1 /************************************************************/
2 /* THIS FILE IS GENERATED DO NOT EDIT */
3 /************************************************************/
8 * If @action is currently enabled.
10 * If the action is disabled then calls to g_action_activate() and
11 * g_action_change_state() have no effect.
20 * The name of the action. This is mostly meaningful for identifying
21 * the action once it has been added to a #GActionGroup.
28 * GAction:parameter-type:
30 * The type of the parameter that must be given when activating the
40 * The state of the action, or %NULL if the action is stateless.
49 * The #GVariantType of the state that the action has, or %NULL if the
50 * action is stateless.
58 * @name: the name of the action
59 * @activate: the callback to connect to the "activate" signal of the action
60 * @parameter_type: the type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or %NULL for no parameter)
61 * @state: the initial state for this action, given in GVariant text format. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary.
62 * @change_state: the callback to connect to the "change-state" signal of the action
64 * This struct defines a single action. It is for use with
65 * g_action_map_add_action_entries().
67 * The order of the items in the structure are intended to reflect
68 * frequency of use. It is permissible to use an incomplete initialiser
69 * in order to leave some of the later values as %NULL. All values
70 * after @name are optional. Additional optional fields may be added in
73 * See g_action_map_add_action_entries() for an example.
78 * GActionGroup::action-added:
79 * @action_group: the #GActionGroup that changed
80 * @action_name: the name of the action in @action_group
82 * Signals that a new action was just added to the group.
83 * This signal is emitted after the action has been added
91 * GActionGroup::action-enabled-changed:
92 * @action_group: the #GActionGroup that changed
93 * @action_name: the name of the action in @action_group
94 * @enabled: whether the action is enabled or not
96 * Signals that the enabled status of the named action has changed.
103 * GActionGroup::action-removed:
104 * @action_group: the #GActionGroup that changed
105 * @action_name: the name of the action in @action_group
107 * Signals that an action is just about to be removed from the group.
108 * This signal is emitted before the action is removed, so the action
109 * is still visible and can be queried from the signal handler.
116 * GActionGroup::action-state-changed:
117 * @action_group: the #GActionGroup that changed
118 * @action_name: the name of the action in @action_group
119 * @value: the new value of the state
121 * Signals that the state of the named action has changed.
128 * GActionGroupInterface:
129 * @has_action: the virtual function pointer for g_action_group_has_action()
130 * @list_actions: the virtual function pointer for g_action_group_list_actions()
131 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
132 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
133 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
134 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
135 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
136 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
137 * @query_action: the virtual function pointer for g_action_group_query_action()
138 * @activate_action: the virtual function pointer for g_action_group_activate_action()
139 * @action_added: the class closure for the #GActionGroup::action-added signal
140 * @action_removed: the class closure for the #GActionGroup::action-removed signal
141 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
142 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
144 * The virtual function table for #GActionGroup.
152 * @get_name: the virtual function pointer for g_action_get_name()
153 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
154 * @get_state_type: the virtual function pointer for g_action_get_state_type()
155 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
156 * @get_enabled: the virtual function pointer for g_action_get_enabled()
157 * @get_state: the virtual function pointer for g_action_get_state()
158 * @change_state: the virtual function pointer for g_action_change_state()
159 * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one.
161 * The virtual function table for #GAction.
168 * GActionMapInterface:
169 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
170 * @add_action: the virtual function pointer for g_action_map_add_action()
171 * @remove_action: the virtual function pointer for g_action_map_remove_action()
173 * The virtual function table for #GActionMap.
180 * GApplication::activate:
181 * @application: the application
183 * The ::activate signal is emitted on the primary instance when an
184 * activation occurs. See g_application_activate().
189 * GApplication::command-line:
190 * @application: the application
191 * @command_line: a #GApplicationCommandLine representing the passed commandline
193 * The ::command-line signal is emitted on the primary instance when
194 * a commandline is not handled locally. See g_application_run() and
195 * the #GApplicationCommandLine documentation for more information.
197 * Returns: An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status().
202 * GApplication::open:
203 * @application: the application
204 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
205 * @n_files: the length of @files
206 * @hint: a hint provided by the calling instance
208 * The ::open signal is emitted on the primary instance when there are
209 * files to open. See g_application_open() for more information.
214 * GApplication::shutdown:
215 * @application: the application
217 * The ::shutdown signal is emitted only on the registered primary instance
218 * immediately after the main loop terminates.
223 * GApplication::startup:
224 * @application: the application
226 * The ::startup signal is emitted on the primary instance immediately
227 * after registration. See g_application_register().
233 * @startup: invoked on the primary instance immediately after registration
234 * @shutdown: invoked only on the registered primary instance immediately after the main loop terminates
235 * @activate: invoked on the primary instance when an activation occurs
236 * @open: invoked on the primary instance when there are files to open
237 * @command_line: invoked on the primary instance when a command-line is not handled locally
238 * @local_command_line: invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information.
239 * @before_emit: invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance
240 * @after_emit: invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance
241 * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions
242 * @quit_mainloop: Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32
243 * @run_mainloop: Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore
244 * @dbus_register: invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the #GDBusConnection to to session bus, and the object path that #GApplication will use to export is D-Bus API. If this function returns %TRUE, registration will proceed; otherwise registration will abort. Since: 2.34
245 * @dbus_unregister: invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the @dbus_register vfunc. Since: 2.34
247 * Virtual function table for #GApplication.
254 * GApplicationCommandLineClass:
256 * The <structname>GApplicationCommandLineClass</structname> structure
257 * contains private data only
264 * GCancellable::cancelled:
265 * @cancellable: a #GCancellable.
267 * Emitted when the operation has been cancelled.
269 * Can be used by implementations of cancellable operations. If the
270 * operation is cancelled from another thread, the signal will be
271 * emitted in the thread that cancelled the operation, not the
272 * thread that is running the operation.
274 * Note that disconnecting from this signal (or any signal) in a
275 * multi-threaded program is prone to race conditions. For instance
276 * it is possible that a signal handler may be invoked even
277 * <emphasis>after</emphasis> a call to
278 * g_signal_handler_disconnect() for that handler has already
281 * There is also a problem when cancellation happen
282 * right before connecting to the signal. If this happens the
283 * signal will unexpectedly not be emitted, and checking before
284 * connecting to the signal leaves a race condition where this is
287 * In order to make it safe and easy to connect handlers there
288 * are two helper functions: g_cancellable_connect() and
289 * g_cancellable_disconnect() which protect against problems
292 * An example of how to us this:
294 * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
295 * if (g_cancellable_set_error_if_cancelled (cancellable))
298 * /<!-- -->* Set up all the data needed to be able to
299 * * handle cancellation of the operation *<!-- -->/
300 * my_data = my_data_new (...);
304 * id = g_cancellable_connect (cancellable,
305 * G_CALLBACK (cancelled_handler)
308 * /<!-- -->* cancellable operation here... *<!-- -->/
310 * g_cancellable_disconnect (cancellable, id);
312 * /<!-- -->* cancelled_handler is never called after this, it
313 * * is now safe to free the data *<!-- -->/
314 * my_data_free (my_data);
317 * Note that the cancelled signal is emitted in the thread that
318 * the user cancelled from, which may be the main thread. So, the
319 * cancellable signal should not do something that can block.
326 * Conversions between character sets.
333 * The #GCredentials structure contains only private data and
334 * should only be accessed using the provided API.
343 * Class structure for #GCredentials.
350 * GDBusAuthMechanism:credentials:
352 * If authenticating as a server, this property contains the
353 * received credentials, if any.
355 * If authenticating as a client, the property contains the
356 * credentials that were sent, if any.
363 * The #GDBusAuthObserver structure contains only private data and
364 * should only be accessed using the provided API.
371 * GDBusAuthObserver::allow-mechanism:
372 * @observer: The #GDBusAuthObserver emitting the signal.
373 * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
375 * Emitted to check if @mechanism is allowed to be used.
377 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
383 * GDBusAuthObserver::authorize-authenticated-peer:
384 * @observer: The #GDBusAuthObserver emitting the signal.
385 * @stream: A #GIOStream for the #GDBusConnection.
386 * @credentials: (allow-none): Credentials received from the peer or %NULL.
388 * Emitted to check if a peer that is successfully authenticated
391 * Returns: %TRUE if the peer is authorized, %FALSE if not.
397 * GDBusAuthObserverClass:
398 * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
400 * Class structure for #GDBusAuthObserverClass.
409 * The #GDBusConnection structure contains only private data and
410 * should only be accessed using the provided API.
417 * GDBusConnection::closed:
418 * @connection: The #GDBusConnection emitting the signal.
419 * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection.
420 * @error: (allow-none): A #GError with more details about the event or %NULL.
422 * Emitted when the connection is closed.
424 * The cause of this event can be
427 * If g_dbus_connection_close() is called. In this case
428 * @remote_peer_vanished is set to %FALSE and @error is %NULL.
431 * If the remote peer closes the connection. In this case
432 * @remote_peer_vanished is set to %TRUE and @error is set.
435 * If the remote peer sends invalid or malformed data. In this
436 * case @remote_peer_vanished is set to %FALSE and @error
441 * Upon receiving this signal, you should give up your reference to
442 * @connection. You are guaranteed that this signal is emitted only
450 * GDBusConnection:address:
452 * A D-Bus address specifying potential endpoints that can be used
453 * when establishing the connection.
460 * GDBusConnection:authentication-observer:
462 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
469 * GDBusConnection:capabilities:
471 * Flags from the #GDBusCapabilityFlags enumeration
472 * representing connection features negotiated with the other peer.
479 * GDBusConnection:closed:
481 * A boolean specifying whether the connection has been closed.
488 * GDBusConnection:exit-on-close:
490 * A boolean specifying whether the process will be terminated (by
491 * calling <literal>raise(SIGTERM)</literal>) if the connection
492 * is closed by the remote peer.
494 * Note that #GDBusConnection objects returned by g_bus_get_finish() and
495 * g_bus_get_sync() will (usually) have this property set to %TRUE.
502 * GDBusConnection:flags:
504 * Flags from the #GDBusConnectionFlags enumeration.
511 * GDBusConnection:guid:
513 * The GUID of the peer performing the role of server when
516 * If you are constructing a #GDBusConnection and pass
517 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
518 * #GDBusConnection:flags property then you MUST also set this
519 * property to a valid guid.
521 * If you are constructing a #GDBusConnection and pass
522 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
523 * #GDBusConnection:flags property you will be able to read the GUID
524 * of the other peer here after the connection has been successfully
532 * GDBusConnection:locked:
534 * A boolean specifying whether the message is locked.
541 * GDBusConnection:stream:
543 * The underlying #GIOStream used for I/O.
545 * If this is passed on construction and is a #GSocketConnection,
546 * then the corresponding #GSocket will be put into non-blocking mode.
548 * While the #GDBusConnection is active, it will interact with this
549 * stream from a worker thread, so it is not safe to interact with
550 * the stream directly.
557 * GDBusConnection:unique-name:
559 * The unique name as assigned by the message bus or %NULL if the
560 * connection is not open or not a message bus connection.
567 * GDBusConnectionClass:
568 * @closed: Signal class handler for the #GDBusConnection::closed signal.
570 * Class structure for #GDBusConnection.
577 * GDBusInterfaceSkeleton::g-authorize-method:
578 * @interface: The #GDBusInterfaceSkeleton emitting the signal.
579 * @invocation: A #GDBusMethodInvocation.
581 * Emitted when a method is invoked by a remote caller and used to
582 * determine if the method call is authorized.
584 * Note that this signal is emitted in a thread dedicated to
585 * handling the method call so handlers are allowed to perform
586 * blocking IO. This means that it is appropriate to call
588 * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</ulink>
590 * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS">POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION</ulink> flag set.
592 * If %FALSE is returned then no further handlers are run and the
593 * signal handler must take a reference to @invocation and finish
594 * handling the call (e.g. return an error via
595 * g_dbus_method_invocation_return_error()).
597 * Otherwise, if %TRUE is returned, signal emission continues. If no
598 * handlers return %FALSE, then the method is dispatched. If
599 * @interface has an enclosing #GDBusObjectSkeleton, then the
600 * #GDBusObjectSkeleton::authorize-method signal handlers run before
601 * the handlers for this signal.
603 * The default class handler just returns %TRUE.
605 * Please note that the common case is optimized: if no signals
606 * handlers are connected and the default class handler isn't
607 * overridden (for both @interface and the enclosing
608 * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
610 * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
611 * flags set, no dedicated thread is ever used and the call will be
612 * handled in the same thread as the object that @interface belongs
613 * to was exported in.
615 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
621 * GDBusInterfaceSkeleton:g-flags:
623 * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
632 * The #GDBusMessage structure contains only private data and should
633 * only be accessed using the provided API.
642 * Class structure for #GDBusMessage.
649 * GDBusMethodInvocation:
651 * The #GDBusMethodInvocation structure contains only private data and
652 * should only be accessed using the provided API.
659 * GDBusMethodInvocationClass:
661 * Class structure for #GDBusMethodInvocation.
668 * GDBusObject::interface-added:
669 * @object: The #GDBusObject emitting the signal.
670 * @interface: The #GDBusInterface that was added.
672 * Emitted when @interface is added to @object.
679 * GDBusObject::interface-removed:
680 * @object: The #GDBusObject emitting the signal.
681 * @interface: The #GDBusInterface that was removed.
683 * Emitted when @interface is removed from @object.
690 * GDBusObjectManager::interface-added:
691 * @manager: The #GDBusObjectManager emitting the signal.
692 * @object: The #GDBusObject on which an interface was added.
693 * @interface: The #GDBusInterface that was added.
695 * Emitted when @interface is added to @object.
697 * This signal exists purely as a convenience to avoid having to
698 * connect signals to all objects managed by @manager.
705 * GDBusObjectManager::interface-removed:
706 * @manager: The #GDBusObjectManager emitting the signal.
707 * @object: The #GDBusObject on which an interface was removed.
708 * @interface: The #GDBusInterface that was removed.
710 * Emitted when @interface has been removed from @object.
712 * This signal exists purely as a convenience to avoid having to
713 * connect signals to all objects managed by @manager.
720 * GDBusObjectManager::object-added:
721 * @manager: The #GDBusObjectManager emitting the signal.
722 * @object: The #GDBusObject that was added.
724 * Emitted when @object is added to @manager.
731 * GDBusObjectManager::object-removed:
732 * @manager: The #GDBusObjectManager emitting the signal.
733 * @object: The #GDBusObject that was removed.
735 * Emitted when @object is removed from @manager.
742 * GDBusObjectManagerClient::interface-proxy-properties-changed:
743 * @manager: The #GDBusObjectManagerClient emitting the signal.
744 * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
745 * @interface_proxy: The #GDBusProxy that has properties that are changing.
746 * @changed_properties: A #GVariant containing the properties that changed.
747 * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
749 * Emitted when one or more D-Bus properties on proxy changes. The
750 * local cache has already been updated when this signal fires. Note
751 * that both @changed_properties and @invalidated_properties are
752 * guaranteed to never be %NULL (either may be empty though).
754 * This signal exists purely as a convenience to avoid having to
755 * connect signals to all interface proxies managed by @manager.
757 * This signal is emitted in the
758 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
759 * that @manager was constructed in.
766 * GDBusObjectManagerClient::interface-proxy-signal:
767 * @manager: The #GDBusObjectManagerClient emitting the signal.
768 * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
769 * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
770 * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
771 * @signal_name: The signal name.
772 * @parameters: A #GVariant tuple with parameters for the signal.
774 * Emitted when a D-Bus signal is received on @interface_proxy.
776 * This signal exists purely as a convenience to avoid having to
777 * connect signals to all interface proxies managed by @manager.
779 * This signal is emitted in the
780 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
781 * that @manager was constructed in.
788 * GDBusObjectManagerClient:bus-type:
790 * If this property is not %G_BUS_TYPE_NONE, then
791 * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
792 * #GDBusConnection obtained by calling g_bus_get() with the value
800 * GDBusObjectManagerClient:connection:
802 * The #GDBusConnection to use.
809 * GDBusObjectManagerClient:flags:
811 * Flags from the #GDBusObjectManagerClientFlags enumeration.
818 * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
820 * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
827 * GDBusObjectManagerClient:get-proxy-type-func:
829 * The #GDBusProxyTypeFunc to use when determining what #GType to
830 * use for interface proxies or %NULL.
837 * GDBusObjectManagerClient:get-proxy-type-user-data:
839 * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
846 * GDBusObjectManagerClient:name:
848 * The well-known name or unique name that the manager is for.
855 * GDBusObjectManagerClient:name-owner:
857 * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
858 * no-one is currently owning the name. Connect to the
859 * #GObject::notify signal to track changes to this property.
866 * GDBusObjectManagerClient:object-path:
868 * The object path the manager is for.
875 * GDBusObjectManagerServer:connection:
877 * The #GDBusConnection to export objects on.
884 * GDBusObjectManagerServer:object-path:
886 * The object path to register the manager object at.
893 * GDBusObjectProxy:g-connection:
895 * The connection of the proxy.
902 * GDBusObjectProxy:g-object-path:
904 * The object path of the proxy.
911 * GDBusObjectSkeleton::authorize-method:
912 * @object: The #GDBusObjectSkeleton emitting the signal.
913 * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
914 * @invocation: A #GDBusMethodInvocation.
916 * Emitted when a method is invoked by a remote caller and used to
917 * determine if the method call is authorized.
919 * This signal is like #GDBusInterfaceSkeleton<!-- -->'s
920 * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
921 * for the enclosing object.
923 * The default class handler just returns %TRUE.
925 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
931 * GDBusObjectSkeleton:g-object-path:
933 * The object path where the object is exported.
940 * GDBusProxy::g-properties-changed:
941 * @proxy: The #GDBusProxy emitting the signal.
942 * @changed_properties: A #GVariant containing the properties that changed
943 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
945 * Emitted when one or more D-Bus properties on @proxy changes. The
946 * local cache has already been updated when this signal fires. Note
947 * that both @changed_properties and @invalidated_properties are
948 * guaranteed to never be %NULL (either may be empty though).
950 * If the proxy has the flag
951 * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
952 * @invalidated_properties will always be empty.
954 * This signal corresponds to the
955 * <literal>PropertiesChanged</literal> D-Bus signal on the
956 * <literal>org.freedesktop.DBus.Properties</literal> interface.
963 * GDBusProxy::g-signal:
964 * @proxy: The #GDBusProxy emitting the signal.
965 * @sender_name: (allow-none): The sender of the signal or %NULL if the connection is not a bus connection.
966 * @signal_name: The name of the signal.
967 * @parameters: A #GVariant tuple with parameters for the signal.
969 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
976 * GDBusProxy:g-bus-type:
978 * If this property is not %G_BUS_TYPE_NONE, then
979 * #GDBusProxy:g-connection must be %NULL and will be set to the
980 * #GDBusConnection obtained by calling g_bus_get() with the value
988 * GDBusProxy:g-connection:
990 * The #GDBusConnection the proxy is for.
997 * GDBusProxy:g-default-timeout:
999 * The timeout to use if -1 (specifying default timeout) is passed
1000 * as @timeout_msec in the g_dbus_proxy_call() and
1001 * g_dbus_proxy_call_sync() functions.
1003 * This allows applications to set a proxy-wide timeout for all
1004 * remote method invocations on the proxy. If this property is -1,
1005 * the default timeout (typically 25 seconds) is used. If set to
1006 * %G_MAXINT, then no timeout is used.
1013 * GDBusProxy:g-flags:
1015 * Flags from the #GDBusProxyFlags enumeration.
1022 * GDBusProxy:g-interface-info:
1024 * Ensure that interactions with this proxy conform to the given
1025 * interface. This is mainly to ensure that malformed data received
1026 * from the other peer is ignored. The given #GDBusInterfaceInfo is
1027 * said to be the <emphasis>expected interface</emphasis>.
1029 * The checks performed are:
1032 * When completing a method call, if the type signature of
1033 * the reply message isn't what's expected, the reply is
1034 * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
1035 * </para></listitem>
1037 * Received signals that have a type signature mismatch are dropped and
1038 * a warning is logged via g_warning().
1039 * </para></listitem>
1041 * Properties received via the initial <literal>GetAll()</literal> call
1042 * or via the <literal>::PropertiesChanged</literal> signal (on the
1043 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface) or
1044 * set using g_dbus_proxy_set_cached_property() with a type signature
1045 * mismatch are ignored and a warning is logged via g_warning().
1046 * </para></listitem>
1048 * Note that these checks are never done on methods, signals and
1049 * properties that are not referenced in the given
1050 * #GDBusInterfaceInfo, since extending a D-Bus interface on the
1051 * service-side is not considered an ABI break.
1058 * GDBusProxy:g-interface-name:
1060 * The D-Bus interface name the proxy is for.
1067 * GDBusProxy:g-name:
1069 * The well-known or unique name that the proxy is for.
1076 * GDBusProxy:g-name-owner:
1078 * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
1079 * currently owns that name. You may connect to #GObject::notify signal to
1080 * track changes to this property.
1087 * GDBusProxy:g-object-path:
1089 * The object path the proxy is for.
1098 * The #GDBusServer structure contains only private data and
1099 * should only be accessed using the provided API.
1106 * GDBusServer::new-connection:
1107 * @server: The #GDBusServer emitting the signal.
1108 * @connection: A #GDBusConnection for the new connection.
1110 * Emitted when a new authenticated connection has been made. Use
1111 * g_dbus_connection_get_peer_credentials() to figure out what
1112 * identity (if any), was authenticated.
1114 * If you want to accept the connection, take a reference to the
1115 * @connection object and return %TRUE. When you are done with the
1116 * connection call g_dbus_connection_close() and give up your
1117 * reference. Note that the other peer may disconnect at any time -
1118 * a typical thing to do when accepting a connection is to listen to
1119 * the #GDBusConnection::closed signal.
1121 * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
1122 * then the signal is emitted in a new thread dedicated to the
1123 * connection. Otherwise the signal is emitted in the <link
1124 * linkend="g-main-context-push-thread-default">thread-default main
1125 * loop</link> of the thread that @server was constructed in.
1127 * You are guaranteed that signal handlers for this signal runs
1128 * before incoming messages on @connection are processed. This means
1129 * that it's suitable to call g_dbus_connection_register_object() or
1130 * similar from the signal handler.
1132 * Returns: %TRUE to claim @connection, %FALSE to let other handlers run.
1138 * GDBusServer:active:
1140 * Whether the server is currently active.
1147 * GDBusServer:address:
1149 * The D-Bus address to listen on.
1156 * GDBusServer:authentication-observer:
1158 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
1165 * GDBusServer:client-address:
1167 * The D-Bus address that clients can use.
1174 * GDBusServer:flags:
1176 * Flags from the #GDBusServerFlags enumeration.
1185 * The guid of the server.
1193 * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
1195 * Class structure for #GDBusServer.
1202 * GDataOutputStream:byte-order:
1204 * Determines the byte ordering that is used when writing
1205 * multi-byte entities (such as integers) to the stream.
1210 * GDataStream:byte-order:
1212 * The ::byte-order property determines the byte ordering that
1213 * is used when reading multi-byte entities (such as integers)
1219 * GDataStream:newline-type:
1221 * The :newline-type property determines what is considered
1222 * as a line ending when reading complete lines from the stream.
1229 * Information about an installed application from a desktop file.
1234 * GDesktopAppInfo:filename:
1236 * The origin filename of this #GDesktopAppInfo
1242 * @drive: a #GDrive.
1244 * Emitted when the drive's state has changed.
1249 * GDrive::disconnected:
1250 * @drive: a #GDrive.
1252 * This signal is emitted when the #GDrive have been
1253 * disconnected. If the recipient is holding references to the
1254 * object they should release them so the object can be
1260 * GDrive::eject-button:
1261 * @drive: a #GDrive.
1263 * Emitted when the physical eject button (if any) of a drive has
1269 * GDrive::stop-button:
1270 * @drive: a #GDrive.
1272 * Emitted when the physical stop button (if any) of a drive has
1282 * The file containing the icon.
1287 * GFileMonitor::changed:
1288 * @monitor: a #GFileMonitor.
1290 * @other_file: (allow-none): a #GFile or #NULL.
1291 * @event_type: a #GFileMonitorEvent.
1293 * Emitted when @file has been changed.
1295 * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
1296 * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
1297 * old path, and @other_file will be set to a #GFile containing the new path.
1299 * In all the other cases, @other_file will be set to #NULL.
1304 * GFilenameCompleter::got-completion-data:
1306 * Emitted when the file name completion information comes available.
1313 * Represents a scope for loading IO modules. A scope can be used for blocking
1314 * duplicate modules, or blocking a module you don't want to load.
1316 * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
1317 * or g_io_modules_scan_all_in_directory_with_scope().
1326 * An IPv4 or IPv6 internet address.
1331 * GInetAddress:is-any:
1333 * Whether this is the "any" address for its family.
1334 * See g_inet_address_get_is_any().
1341 * GInetAddress:is-link-local:
1343 * Whether this is a link-local address.
1344 * See g_inet_address_get_is_link_local().
1351 * GInetAddress:is-loopback:
1353 * Whether this is the loopback address for its family.
1354 * See g_inet_address_get_is_loopback().
1361 * GInetAddress:is-mc-global:
1363 * Whether this is a global multicast address.
1364 * See g_inet_address_get_is_mc_global().
1371 * GInetAddress:is-mc-link-local:
1373 * Whether this is a link-local multicast address.
1374 * See g_inet_address_get_is_mc_link_local().
1381 * GInetAddress:is-mc-node-local:
1383 * Whether this is a node-local multicast address.
1384 * See g_inet_address_get_is_mc_node_local().
1391 * GInetAddress:is-mc-org-local:
1393 * Whether this is an organization-local multicast address.
1394 * See g_inet_address_get_is_mc_org_local().
1401 * GInetAddress:is-mc-site-local:
1403 * Whether this is a site-local multicast address.
1404 * See g_inet_address_get_is_mc_site_local().
1411 * GInetAddress:is-multicast:
1413 * Whether this is a multicast address.
1414 * See g_inet_address_get_is_multicast().
1421 * GInetAddress:is-site-local:
1423 * Whether this is a site-local address.
1424 * See g_inet_address_get_is_loopback().
1433 * A combination of an IPv4 or IPv6 base address and a length,
1434 * representing a range of IP addresses.
1441 * GInetSocketAddress:
1443 * An IPv4 or IPv6 socket address, corresponding to a <type>struct
1444 * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
1449 * GInetSocketAddress:flowinfo:
1451 * The <literal>sin6_flowinfo</literal> field, for IPv6 addresses.
1458 * GInetSocketAddress:scope_id:
1460 * The <literal>sin6_scope_id</literal> field, for IPv6 addresses.
1467 * GMemoryOutputStream:data:
1469 * Pointer to buffer where data will be written.
1476 * GMemoryOutputStream:data-size:
1478 * Size of data written to the buffer.
1485 * GMemoryOutputStream:destroy-function: (skip)
1487 * Function called with the buffer as argument when the stream is destroyed.
1494 * GMemoryOutputStream:realloc-function: (skip)
1496 * Function with realloc semantics called to enlarge the buffer.
1503 * GMemoryOutputStream:size:
1505 * Current size of the data buffer.
1514 * #GMenu is an opaque structure type. You must access it using the
1522 * GMenuAttributeIter:
1524 * #GMenuAttributeIter is an opaque structure type. You must access it
1525 * using the functions below.
1534 * #GMenuItem is an opaque structure type. You must access it using the
1544 * #GMenuLinkIter is an opaque structure type. You must access it using
1545 * the functions below.
1554 * #GMenuModel is an opaque structure type. You must access it using the
1562 * GMenuModel::items-changed:
1563 * @model: the #GMenuModel that is changing
1564 * @position: the position of the change
1565 * @removed: the number of items removed
1566 * @added: the number of items added
1568 * Emitted when a change has occured to the menu.
1570 * The only changes that can occur to a menu is that items are removed
1571 * or added. Items may not change (except by being removed and added
1572 * back in the same location). This signal is capable of describing
1573 * both of those changes (at the same time).
1575 * The signal means that starting at the index @position, @removed
1576 * items were removed and @added items were added in their place. If
1577 * @removed is zero then only items were added. If @added is zero
1578 * then only items were removed.
1580 * As an example, if the menu contains items a, b, c, d (in that
1581 * order) and the signal (2, 1, 3) occurs then the new composition of
1582 * the menu will be a, b, _, _, _, d (with each _ representing some
1585 * Signal handlers may query the model (particularly the added items)
1586 * and expect to see the results of the modification that is being
1587 * reported. The signal is emitted after the modification.
1593 * @mount: the object on which the signal is emitted
1595 * Emitted when the mount has been changed.
1600 * GMount::pre-unmount:
1601 * @mount: the object on which the signal is emitted
1603 * This signal is emitted when the #GMount is about to be
1611 * GMount::unmounted:
1612 * @mount: the object on which the signal is emitted
1614 * This signal is emitted when the #GMount have been
1615 * unmounted. If the recipient is holding references to the
1616 * object they should release them so the object can be
1622 * GMountOperation::aborted:
1624 * Emitted by the backend when e.g. a device becomes unavailable
1625 * while a mount operation is in progress.
1627 * Implementations of GMountOperation should handle this signal
1628 * by dismissing open password dialogs.
1635 * GMountOperation::ask-password:
1636 * @op: a #GMountOperation requesting a password.
1637 * @message: string containing a message to display to the user.
1638 * @default_user: string containing the default user name.
1639 * @default_domain: string containing the default domain.
1640 * @flags: a set of #GAskPasswordFlags.
1642 * Emitted when a mount operation asks the user for a password.
1644 * If the message contains a line break, the first line should be
1645 * presented as a heading. For example, it may be used as the
1646 * primary text in a #GtkMessageDialog.
1651 * GMountOperation::ask-question:
1652 * @op: a #GMountOperation asking a question.
1653 * @message: string containing a message to display to the user.
1654 * @choices: an array of strings for each possible choice.
1656 * Emitted when asking the user a question and gives a list of
1657 * choices for the user to choose from.
1659 * If the message contains a line break, the first line should be
1660 * presented as a heading. For example, it may be used as the
1661 * primary text in a #GtkMessageDialog.
1666 * GMountOperation::reply:
1667 * @op: a #GMountOperation.
1668 * @result: a #GMountOperationResult indicating how the request was handled
1670 * Emitted when the user has replied to the mount operation.
1675 * GMountOperation::show-processes:
1676 * @op: a #GMountOperation.
1677 * @message: string containing a message to display to the user.
1678 * @processes: (element-type GPid): an array of #GPid for processes blocking the operation.
1679 * @choices: an array of strings for each possible choice.
1681 * Emitted when one or more processes are blocking an operation
1682 * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
1684 * Note that this signal may be emitted several times to update the
1685 * list of blocking processes as processes close files. The
1686 * application should only respond with g_mount_operation_reply() to
1687 * the latest signal (setting #GMountOperation:choice to the choice
1690 * If the message contains a line break, the first line should be
1691 * presented as a heading. For example, it may be used as the
1692 * primary text in a #GtkMessageDialog.
1699 * GMountOperation::show-unmount-progress:
1700 * @op: a #GMountOperation:
1701 * @message: string containing a mesage to display to the user
1702 * @time_left: the estimated time left before the operation completes, in microseconds, or -1
1703 * @bytes_left: the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed
1705 * Emitted when an unmount operation has been busy for more than some time
1706 * (typically 1.5 seconds).
1708 * When unmounting or ejecting a volume, the kernel might need to flush
1709 * pending data in its buffers to the volume stable storage, and this operation
1710 * can take a considerable amount of time. This signal may be emitted several
1711 * times as long as the unmount operation is outstanding, and then one
1712 * last time when the operation is completed, with @bytes_left set to zero.
1714 * Implementations of GMountOperation should handle this signal by
1715 * showing an UI notification, and then dismiss it, or show another notification
1716 * of completion, when @bytes_left reaches zero.
1718 * If the message contains a line break, the first line should be
1719 * presented as a heading. For example, it may be used as the
1720 * primary text in a #GtkMessageDialog.
1727 * GMountOperation:anonymous:
1729 * Whether to use an anonymous user when authenticating.
1734 * GMountOperation:choice:
1736 * The index of the user's choice when a question is asked during the
1737 * mount operation. See the #GMountOperation::ask-question signal.
1742 * GMountOperation:domain:
1744 * The domain to use for the mount operation.
1749 * GMountOperation:password:
1751 * The password that is used for authentication when carrying out
1752 * the mount operation.
1757 * GMountOperation:password-save:
1759 * Determines if and how the password information should be saved.
1764 * GMountOperation:username:
1766 * The user name that is used for authentication when carrying out
1767 * the mount operation.
1774 * A #GSocketConnectable for resolving a hostname and connecting to
1782 * #GNetworkMonitor monitors the status of network connections and
1783 * indicates when a possibly-user-visible change has occurred.
1790 * GNetworkMonitor::network-changed:
1791 * @monitor: a #GNetworkMonitor
1792 * @available: the current value of #GNetworkMonitor:network-available
1794 * Emitted when the network configuration changes. If @available is
1795 * %TRUE, then some hosts may be reachable that were not reachable
1796 * before, while others that were reachable before may no longer be
1797 * reachable. If @available is %FALSE, then no remote hosts are
1805 * GNetworkMonitor:network-available:
1807 * Whether the network is considered available. That is, whether the
1808 * system has a default route for at least one of IPv4 or IPv6.
1810 * Real-world networks are of course much more complicated than
1811 * this; the machine may be connected to a wifi hotspot that
1812 * requires payment before allowing traffic through, or may be
1813 * connected to a functioning router that has lost its own upstream
1814 * connectivity. Some hosts might only be accessible when a VPN is
1815 * active. Other hosts might only be accessible when the VPN is
1816 * <emphasis>not</emphasis> active. Thus, it is best to use
1817 * g_network_monitor_can_reach() or
1818 * g_network_monitor_can_reach_async() to test for reachability on a
1819 * host-by-host basis. (On the other hand, when the property is
1820 * %FALSE, the application can reasonably expect that no remote
1821 * hosts at all are reachable, and should indicate this to the user
1824 * See also #GNetworkMonitor::network-changed.
1833 * A #GSocketConnectable for resolving a SRV record and connecting to
1841 * #GPermission is an opaque data structure and can only be accessed
1842 * using the following functions.
1847 * GPermission:allowed:
1849 * %TRUE if the caller currently has permission to perform the action that
1850 * @permission represents the permission to perform.
1855 * GPermission:can-acquire:
1857 * %TRUE if it is generally possible to acquire the permission by calling
1858 * g_permission_acquire().
1863 * GPermission:can-release:
1865 * %TRUE if it is generally possible to release the permission by calling
1866 * g_permission_release().
1873 * A #GInetSocketAddress representing a connection via a proxy server
1880 * GProxyAddress:destination-protocol:
1882 * The protocol being spoke to the destination host, or %NULL if
1883 * the #GProxyAddress doesn't know.
1890 * GProxyAddress:uri:
1892 * The URI string that the proxy was constructed from (or %NULL
1893 * if the creator didn't specify this).
1900 * GRemoteActionGroupInterface:
1901 * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
1902 * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
1904 * The virtual function table for #GRemoteActionGroup.
1913 * The object that handles DNS resolution. Use g_resolver_get_default()
1914 * to get the default resolver.
1919 * GResolver::reload:
1920 * @resolver: a #GResolver
1922 * Emitted when the resolver notices that the system resolver
1923 * configuration has changed.
1928 * GSettings::change-event:
1929 * @settings: the object on which the signal was emitted
1930 * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL
1931 * @n_keys: the length of the @keys array, or 0
1933 * The "change-event" signal is emitted once per change event that
1934 * affects this settings object. You should connect to this signal
1935 * only if you are interested in viewing groups of changes before they
1936 * are split out into multiple emissions of the "changed" signal.
1937 * For most use cases it is more appropriate to use the "changed" signal.
1939 * In the event that the change event applies to one or more specified
1940 * keys, @keys will be an array of #GQuark of length @n_keys. In the
1941 * event that the change event applies to the #GSettings object as a
1942 * whole (ie: potentially every key has been changed) then @keys will
1943 * be %NULL and @n_keys will be 0.
1945 * The default handler for this signal invokes the "changed" signal
1946 * for each affected key. If any other connected handler returns
1947 * %TRUE then this default functionality will be suppressed.
1949 * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
1954 * GSettings::changed:
1955 * @settings: the object on which the signal was emitted
1956 * @key: the name of the key that changed
1958 * The "changed" signal is emitted when a key has potentially changed.
1959 * You should call one of the g_settings_get() calls to check the new
1962 * This signal supports detailed connections. You can connect to the
1963 * detailed signal "changed::x" in order to only receive callbacks
1964 * when key "x" changes.
1969 * GSettings::writable-change-event:
1970 * @settings: the object on which the signal was emitted
1971 * @key: the quark of the key, or 0
1973 * The "writable-change-event" signal is emitted once per writability
1974 * change event that affects this settings object. You should connect
1975 * to this signal if you are interested in viewing groups of changes
1976 * before they are split out into multiple emissions of the
1977 * "writable-changed" signal. For most use cases it is more
1978 * appropriate to use the "writable-changed" signal.
1980 * In the event that the writability change applies only to a single
1981 * key, @key will be set to the #GQuark for that key. In the event
1982 * that the writability change affects the entire settings object,
1985 * The default handler for this signal invokes the "writable-changed"
1986 * and "changed" signals for each affected key. This is done because
1987 * changes in writability might also imply changes in value (if for
1988 * example, a new mandatory setting is introduced). If any other
1989 * connected handler returns %TRUE then this default functionality
1990 * will be suppressed.
1992 * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
1997 * GSettings::writable-changed:
1998 * @settings: the object on which the signal was emitted
2001 * The "writable-changed" signal is emitted when the writability of a
2002 * key has potentially changed. You should call
2003 * g_settings_is_writable() in order to determine the new status.
2005 * This signal supports detailed connections. You can connect to the
2006 * detailed signal "writable-changed::x" in order to only receive
2007 * callbacks when the writability of "x" changes.
2012 * GSettings:context:
2014 * The name of the context that the settings are stored in.
2019 * GSettings:delay-apply:
2021 * Whether the #GSettings object is in 'delay-apply' mode. See
2022 * g_settings_delay() for details.
2029 * GSettings:has-unapplied:
2031 * If this property is %TRUE, the #GSettings object has outstanding
2032 * changes that will be applied when g_settings_apply() is called.
2039 * The path within the backend where the settings are stored.
2046 * The name of the schema that describes the types of keys
2047 * for this #GSettings object.
2049 * The type of this property is *not* #GSettingsSchema.
2050 * #GSettingsSchema has only existed since version 2.32 and
2051 * unfortunately this name was used in previous versions to refer to
2052 * the schema ID rather than the schema itself. Take care to use the
2053 * 'settings-schema' property if you wish to pass in a
2056 * Deprecated: 2.32:Use the 'schema-id' property instead. In a future version, this property may instead refer to a #GSettingsSchema.
2061 * GSettings:schema-id:
2063 * The name of the schema that describes the types of keys
2064 * for this #GSettings object.
2069 * GSettings:settings-schema:
2071 * The #GSettingsSchema describing the types of keys for this
2072 * #GSettings object.
2074 * Ideally, this property would be called 'schema'. #GSettingsSchema
2075 * has only existed since version 2.32, however, and before then the
2076 * 'schema' property was used to refer to the ID of the schema rather
2077 * than the schema itself. Take care.
2084 * This is an opaque structure type. You may not access it directly.
2091 * GSettingsSchemaSource:
2093 * This is an opaque structure type. You may not access it directly.
2100 * GSimpleAction::activate:
2101 * @simple: the #GSimpleAction
2102 * @parameter: (allow-none): the parameter to the activation
2104 * Indicates that the action was just activated.
2106 * @parameter will always be of the expected type. In the event that
2107 * an incorrect type was given, no signal will be emitted.
2114 * GSimpleAction::change-state:
2115 * @simple: the #GSimpleAction
2116 * @value: (allow-none): the requested value for the state
2118 * Indicates that the action just received a request to change its
2121 * @value will always be of the correct state type. In the event that
2122 * an incorrect type was given, no signal will be emitted.
2124 * If no handler is connected to this signal then the default
2125 * behaviour is to call g_simple_action_set_state() to set the state
2126 * to the requested value. If you connect a signal handler then no
2127 * default action is taken. If the state should change then you must
2128 * call g_simple_action_set_state() from the handler.
2131 * <title>Example 'change-state' handler</title>
2134 * change_volume_state (GSimpleAction *action,
2136 * gpointer user_data)
2140 * requested = g_variant_get_int32 (value);
2142 * // Volume only goes from 0 to 10
2143 * if (0 <= requested && requested <= 10)
2144 * g_simple_action_set_state (action, value);
2149 * The handler need not set the state to the requested value. It
2150 * could set it to any value at all, or take some other action.
2157 * GSimpleAction:enabled:
2159 * If @action is currently enabled.
2161 * If the action is disabled then calls to g_action_activate() and
2162 * g_action_change_state() have no effect.
2169 * GSimpleAction:name:
2171 * The name of the action. This is mostly meaningful for identifying
2172 * the action once it has been added to a #GSimpleActionGroup.
2179 * GSimpleAction:parameter-type:
2181 * The type of the parameter that must be given when activating the
2189 * GSimpleAction:state:
2191 * The state of the action, or %NULL if the action is stateless.
2198 * GSimpleAction:state-type:
2200 * The #GVariantType of the state that the action has, or %NULL if the
2201 * action is stateless.
2208 * GSimplePermission:
2210 * #GSimplePermission is an opaque data structure. There are no methods
2211 * except for those defined by #GPermission.
2216 * GSocket:broadcast:
2218 * Whether the socket should allow sending to and receiving from broadcast addresses.
2225 * GSocket:multicast-loopback:
2227 * Whether outgoing multicast packets loop back to the local host.
2234 * GSocket:multicast-ttl:
2236 * Time-to-live out outgoing multicast packets
2245 * The timeout in seconds on socket I/O
2254 * Time-to-live for outgoing unicast packets
2263 * A socket endpoint address, corresponding to <type>struct sockaddr</type>
2264 * or one of its subtypes.
2269 * GSocketClient::event:
2270 * @client: the #GSocketClient
2271 * @event: the event that is occurring
2272 * @connectable: the #GSocketConnectable that @event is occurring on
2273 * @connection: the current representation of the connection
2275 * Emitted when @client's activity on @connectable changes state.
2276 * Among other things, this can be used to provide progress
2277 * information about a network connection in the UI. The meanings of
2278 * the different @event values are as follows:
2282 * <term>%G_SOCKET_CLIENT_RESOLVING:</term>
2284 * @client is about to look up @connectable in DNS.
2285 * @connection will be %NULL.
2286 * </para></listitem>
2289 * <term>%G_SOCKET_CLIENT_RESOLVED:</term>
2291 * @client has successfully resolved @connectable in DNS.
2292 * @connection will be %NULL.
2293 * </para></listitem>
2296 * <term>%G_SOCKET_CLIENT_CONNECTING:</term>
2298 * @client is about to make a connection to a remote host;
2299 * either a proxy server or the destination server itself.
2300 * @connection is the #GSocketConnection, which is not yet
2302 * </para></listitem>
2305 * <term>%G_SOCKET_CLIENT_CONNECTED:</term>
2307 * @client has successfully connected to a remote host.
2308 * @connection is the connected #GSocketConnection.
2309 * </para></listitem>
2312 * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
2314 * @client is about to negotiate with a proxy to get it to
2315 * connect to @connectable. @connection is the
2316 * #GSocketConnection to the proxy server.
2317 * </para></listitem>
2320 * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
2322 * @client has negotiated a connection to @connectable through
2323 * a proxy server. @connection is the stream returned from
2324 * g_proxy_connect(), which may or may not be a
2325 * #GSocketConnection.
2326 * </para></listitem>
2329 * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
2331 * @client is about to begin a TLS handshake. @connection is a
2332 * #GTlsClientConnection.
2333 * </para></listitem>
2336 * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
2338 * @client has successfully completed the TLS handshake.
2339 * @connection is a #GTlsClientConnection.
2340 * </para></listitem>
2343 * <term>%G_SOCKET_CLIENT_COMPLETE:</term>
2345 * @client has either successfully connected to @connectable
2346 * (in which case @connection is the #GSocketConnection that
2347 * it will be returning to the caller) or has failed (in which
2348 * case @connection is %NULL and the client is about to return
2350 * </para></listitem>
2354 * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
2355 * multiple times (or not at all) for a given connectable (in
2356 * particular, if @client ends up attempting to connect to more than
2357 * one address). However, if @client emits the #GSocketClient::event
2358 * signal at all for a given connectable, that it will always emit
2359 * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
2361 * Note that there may be additional #GSocketClientEvent values in
2362 * the future; unrecognized @event values should be ignored.
2369 * GSocketService::incoming:
2370 * @service: the #GSocketService
2371 * @connection: a new #GSocketConnection object
2372 * @source_object: (allow-none): the source_object passed to g_socket_listener_add_address()
2374 * The ::incoming signal is emitted when a new incoming connection
2375 * to @service needs to be handled. The handler must initiate the
2376 * handling of @connection, but may not block; in essence,
2377 * asynchronous operations must be used.
2379 * @connection will be unreffed once the signal handler returns,
2380 * so you need to ref it yourself if you are planning to use it.
2382 * Returns: %TRUE to stop other handlers from being called
2390 * A single target host/port that a network service is running on.
2397 * The opaque object representing a synchronous or asynchronous task
2405 * @source_object: @task's source object
2406 * @task_data: @task's task data
2407 * @cancellable: @task's #GCancellable, or %NULL
2409 * The prototype for a task function to be run in a thread via
2410 * g_task_run_in_thread() or g_task_run_in_thread_sync().
2412 * If the return-on-cancel flag is set on @task, and @cancellable gets
2413 * cancelled, then the #GTask will be completed immediately (as though
2414 * g_task_return_error_if_cancelled() had been called), without
2415 * waiting for the task function to complete. However, the task
2416 * function will continue running in its thread in the background. The
2417 * function therefore needs to be careful about how it uses
2418 * externally-visible state in this case. See
2419 * g_task_set_return_on_cancel() for more details.
2421 * Other than in that case, @task will be completed when the
2422 * #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls
2423 * a <literal>g_task_return_</literal> function.
2432 * The #GTestDBus structure contains only private data and
2433 * should only be accessed using the provided API.
2442 * #GTestDBusFlags specifying the behaviour of the dbus session
2456 * GThemedIcon:names:
2458 * A %NULL-terminated array of icon names.
2463 * GThemedIcon:use-default-fallbacks:
2465 * Whether to use the default fallbacks found by shortening the icon name
2466 * at '-' characters. If the "names" array has more than one element,
2467 * ignores any past the first.
2469 * For example, if the icon name was "gnome-dev-cdrom-audio", the array
2473 * "gnome-dev-cdrom-audio",
2474 * "gnome-dev-cdrom",
2484 * GThreadedSocketService::run:
2485 * @service: the #GThreadedSocketService.
2486 * @connection: a new #GSocketConnection object.
2487 * @source_object: the source_object passed to g_socket_listener_add_address().
2489 * The ::run signal is emitted in a worker thread in response to an
2490 * incoming connection. This thread is dedicated to handling
2491 * @connection and may perform blocking IO. The signal handler need
2492 * not return until the connection is closed.
2494 * Returns: %TRUE to stop further signal handlers from being called
2501 * TLS (Transport Layer Security, aka SSL) backend. This is an
2502 * internal type used to coordinate the different classes implemented
2512 * Abstract base class for TLS certificate types.
2519 * GTlsCertificate:certificate:
2521 * The DER (binary) encoded representation of the certificate.
2522 * This property and the #GTlsCertificate:certificate-pem property
2523 * represent the same data, just in different forms.
2530 * GTlsCertificate:certificate-pem:
2532 * The PEM (ASCII) encoded representation of the certificate.
2533 * This property and the #GTlsCertificate:certificate
2534 * property represent the same data, just in different forms.
2541 * GTlsCertificate:issuer:
2543 * A #GTlsCertificate representing the entity that issued this
2544 * certificate. If %NULL, this means that the certificate is either
2545 * self-signed, or else the certificate of the issuer is not
2553 * GTlsCertificate:private-key:
2555 * The DER (binary) encoded representation of the certificate's
2556 * private key, in either PKCS#1 format or unencrypted PKCS#8
2557 * format. This property (or the #GTlsCertificate:private-key-pem
2558 * property) can be set when constructing a key (eg, from a file),
2559 * but cannot be read.
2561 * PKCS#8 format is supported since 2.32; earlier releases only
2562 * support PKCS#1. You can use the <literal>openssl rsa</literal>
2563 * tool to convert PKCS#8 keys to PKCS#1.
2570 * GTlsCertificate:private-key-pem:
2572 * The PEM (ASCII) encoded representation of the certificate's
2573 * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE
2574 * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN
2575 * PRIVATE KEY</literal>"). This property (or the
2576 * #GTlsCertificate:private-key property) can be set when
2577 * constructing a key (eg, from a file), but cannot be read.
2579 * PKCS#8 format is supported since 2.32; earlier releases only
2580 * support PKCS#1. You can use the <literal>openssl rsa</literal>
2581 * tool to convert PKCS#8 keys to PKCS#1.
2588 * GTlsClientConnection:
2590 * Abstract base class for the backend-specific client connection
2598 * GTlsClientConnection:accepted-cas:
2600 * A list of the distinguished names of the Certificate Authorities
2601 * that the server will accept client certificates signed by. If the
2602 * server requests a client certificate during the handshake, then
2603 * this property will be set after the handshake completes.
2605 * Each item in the list is a #GByteArray which contains the complete
2606 * subject DN of the certificate authority.
2613 * GTlsClientConnection:server-identity:
2615 * A #GSocketConnectable describing the identity of the server that
2616 * is expected on the other end of the connection.
2618 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
2619 * #GTlsClientConnection:validation-flags, this object will be used
2620 * to determine the expected identify of the remote end of the
2621 * connection; if #GTlsClientConnection:server-identity is not set,
2622 * or does not match the identity presented by the server, then the
2623 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
2625 * In addition to its use in verifying the server certificate,
2626 * this is also used to give a hint to the server about what
2627 * certificate we expect, which is useful for servers that serve
2635 * GTlsClientConnection:use-ssl3:
2637 * If %TRUE, tells the connection to use SSL 3.0 rather than trying
2638 * to negotiate the best version of TLS or SSL to use. This can be
2639 * used when talking to servers that don't implement version
2640 * negotiation correctly and therefore refuse to handshake at all with
2641 * a "modern" TLS handshake.
2648 * GTlsClientConnection:validation-flags:
2650 * What steps to perform when validating a certificate received from
2651 * a server. Server certificates that fail to validate in all of the
2652 * ways indicated here will be rejected unless the application
2653 * overrides the default via #GTlsConnection::accept-certificate.
2662 * Abstract base class for the backend-specific #GTlsClientConnection
2663 * and #GTlsServerConnection types.
2670 * GTlsConnection::accept-certificate:
2671 * @conn: a #GTlsConnection
2672 * @peer_cert: the peer's #GTlsCertificate
2673 * @errors: the problems with @peer_cert.
2675 * Emitted during the TLS handshake after the peer certificate has
2676 * been received. You can examine @peer_cert's certification path by
2677 * calling g_tls_certificate_get_issuer() on it.
2679 * For a client-side connection, @peer_cert is the server's
2680 * certificate, and the signal will only be emitted if the
2681 * certificate was not acceptable according to @conn's
2682 * #GTlsClientConnection:validation_flags. If you would like the
2683 * certificate to be accepted despite @errors, return %TRUE from the
2684 * signal handler. Otherwise, if no handler accepts the certificate,
2685 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
2687 * For a server-side connection, @peer_cert is the certificate
2688 * presented by the client, if this was requested via the server's
2689 * #GTlsServerConnection:authentication_mode. On the server side,
2690 * the signal is always emitted when the client presents a
2691 * certificate, and the certificate will only be accepted if a
2692 * handler returns %TRUE.
2694 * Note that if this signal is emitted as part of asynchronous I/O
2695 * in the main thread, then you should not attempt to interact with
2696 * the user before returning from the signal handler. If you want to
2697 * let the user decide whether or not to accept the certificate, you
2698 * would have to return %FALSE from the signal handler on the first
2699 * attempt, and then after the connection attempt returns a
2700 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
2701 * the user decides to accept the certificate, remember that fact,
2702 * create a new connection, and return %TRUE from the signal handler
2705 * If you are doing I/O in another thread, you do not
2706 * need to worry about this, and can simply block in the signal
2707 * handler until the UI thread returns an answer.
2709 * Returns: %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it.
2715 * GTlsConnection:base-io-stream:
2717 * The #GIOStream that the connection wraps
2724 * GTlsConnection:certificate:
2726 * The connection's certificate; see
2727 * g_tls_connection_set_certificate().
2734 * GTlsConnection:database:
2736 * The certificate database to use when verifying this TLS connection.
2737 * If no cerificate database is set, then the default database will be
2738 * used. See g_tls_backend_get_default_database().
2745 * GTlsConnection:interaction:
2747 * A #GTlsInteraction object to be used when the connection or certificate
2748 * database need to interact with the user. This will be used to prompt the
2749 * user for passwords where necessary.
2756 * GTlsConnection:peer-certificate:
2758 * The connection's peer's certificate, after the TLS handshake has
2759 * completed and the certificate has been accepted. Note in
2760 * particular that this is not yet set during the emission of
2761 * #GTlsConnection::accept-certificate.
2763 * (You can watch for a #GObject::notify signal on this property to
2764 * detect when a handshake has occurred.)
2771 * GTlsConnection:peer-certificate-errors:
2773 * The errors noticed-and-ignored while verifying
2774 * #GTlsConnection:peer-certificate. Normally this should be 0, but
2775 * it may not be if #GTlsClientConnection:validation-flags is not
2776 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
2777 * #GTlsConnection::accept-certificate overrode the default
2785 * GTlsConnection:rehandshake-mode:
2787 * The rehandshaking mode. See
2788 * g_tls_connection_set_rehandshake_mode().
2795 * GTlsConnection:require-close-notify:
2797 * Whether or not proper TLS close notification is required.
2798 * See g_tls_connection_set_require_close_notify().
2805 * GTlsConnection:use-system-certdb:
2807 * Whether or not the system certificate database will be used to
2808 * verify peer certificates. See
2809 * g_tls_connection_set_use_system_certdb().
2811 * Deprecated: 2.30: Use GTlsConnection:database instead
2818 * Abstract base class for the backend-specific database types.
2827 * Implemented by a #GTlsDatabase which allows you to load certificates
2835 * GTlsFileDatabase:anchors:
2837 * The path to a file containing PEM encoded certificate authority
2838 * root anchors. The certificates in this file will be treated as
2839 * root authorities for the purpose of verifying other certificates
2840 * via the g_tls_database_verify_chain() operation.
2849 * An object representing interaction that the TLS connection and database
2850 * might have with the user.
2857 * GTlsInteractionClass:
2858 * @ask_password: ask for a password synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument should have been filled in by using g_tls_password_set_value() or a similar function.
2859 * @ask_password_async: ask for a password asynchronously.
2860 * @ask_password_finish: complete operation to ask for a password asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument of the async method should have been filled in by using g_tls_password_set_value() or a similar function.
2862 * The class for #GTlsInteraction. Derived classes implement the various
2863 * virtual interaction methods to handle TLS interactions.
2865 * Derived classes can choose to implement whichever interactions methods they'd
2866 * like to support by overriding those virtual methods in their class
2867 * initialization function. If a derived class implements an async method,
2868 * it must also implement the corresponding finish method.
2870 * The synchronous interaction methods should implement to display modal dialogs,
2871 * and the asynchronous methods to display modeless dialogs.
2873 * If the user cancels an interaction, then the result should be
2874 * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
2875 * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
2884 * An abstract interface representing a password used in TLS. Often used in
2885 * user interaction such as unlocking a key storage token.
2892 * GTlsServerConnection:authentication-mode:
2894 * The #GTlsAuthenticationMode for the server. This can be changed
2895 * before calling g_tls_connection_handshake() if you want to
2896 * rehandshake with a different mode from the initial handshake.
2903 * GUnixCredentialsMessage:credentials:
2905 * The credentials stored in the message.
2912 * GUnixInputStream:close-fd:
2914 * Whether to close the file descriptor when the stream is closed.
2921 * GUnixInputStream:fd:
2923 * The file descriptor that the stream reads from.
2930 * GUnixMountMonitor::mountpoints-changed:
2931 * @monitor: the object on which the signal is emitted
2933 * Emitted when the unix mount points have changed.
2938 * GUnixMountMonitor::mounts-changed:
2939 * @monitor: the object on which the signal is emitted
2941 * Emitted when the unix mounts have changed.
2946 * GUnixOutputStream:close-fd:
2948 * Whether to close the file descriptor when the stream is closed.
2955 * GUnixOutputStream:fd:
2957 * The file descriptor that the stream writes to.
2964 * GUnixSocketAddress:
2966 * A UNIX-domain (local) socket address, corresponding to a
2967 * <type>struct sockaddr_un</type>.
2972 * GUnixSocketAddress:abstract:
2974 * Whether or not this is an abstract address
2976 * Deprecated: Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses.
2983 * Emitted when the volume has been changed.
2990 * This signal is emitted when the #GVolume have been removed. If
2991 * the recipient is holding references to the object they should
2992 * release them so the object can be finalized.
2997 * GVolumeMonitor::drive-changed:
2998 * @volume_monitor: The volume monitor emitting the signal.
2999 * @drive: the drive that changed
3001 * Emitted when a drive changes.
3006 * GVolumeMonitor::drive-connected:
3007 * @volume_monitor: The volume monitor emitting the signal.
3008 * @drive: a #GDrive that was connected.
3010 * Emitted when a drive is connected to the system.
3015 * GVolumeMonitor::drive-disconnected:
3016 * @volume_monitor: The volume monitor emitting the signal.
3017 * @drive: a #GDrive that was disconnected.
3019 * Emitted when a drive is disconnected from the system.
3024 * GVolumeMonitor::drive-eject-button:
3025 * @volume_monitor: The volume monitor emitting the signal.
3026 * @drive: the drive where the eject button was pressed
3028 * Emitted when the eject button is pressed on @drive.
3035 * GVolumeMonitor::drive-stop-button:
3036 * @volume_monitor: The volume monitor emitting the signal.
3037 * @drive: the drive where the stop button was pressed
3039 * Emitted when the stop button is pressed on @drive.
3046 * GVolumeMonitor::mount-added:
3047 * @volume_monitor: The volume monitor emitting the signal.
3048 * @mount: a #GMount that was added.
3050 * Emitted when a mount is added.
3055 * GVolumeMonitor::mount-changed:
3056 * @volume_monitor: The volume monitor emitting the signal.
3057 * @mount: a #GMount that changed.
3059 * Emitted when a mount changes.
3064 * GVolumeMonitor::mount-pre-unmount:
3065 * @volume_monitor: The volume monitor emitting the signal.
3066 * @mount: a #GMount that is being unmounted.
3068 * Emitted when a mount is about to be removed.
3073 * GVolumeMonitor::mount-removed:
3074 * @volume_monitor: The volume monitor emitting the signal.
3075 * @mount: a #GMount that was removed.
3077 * Emitted when a mount is removed.
3082 * GVolumeMonitor::volume-added:
3083 * @volume_monitor: The volume monitor emitting the signal.
3084 * @volume: a #GVolume that was added.
3086 * Emitted when a mountable volume is added to the system.
3091 * GVolumeMonitor::volume-changed:
3092 * @volume_monitor: The volume monitor emitting the signal.
3093 * @volume: a #GVolume that changed.
3095 * Emitted when mountable volume is changed.
3100 * GVolumeMonitor::volume-removed:
3101 * @volume_monitor: The volume monitor emitting the signal.
3102 * @volume: a #GVolume that was removed.
3104 * Emitted when a mountable volume is removed from the system.
3109 * GWin32InputStream:close-handle:
3111 * Whether to close the file handle when the stream is closed.
3118 * GWin32InputStream:handle:
3120 * The handle that the stream reads from.
3127 * GWin32OutputStream:close-handle:
3129 * Whether to close the file handle when the stream is closed.
3136 * GWin32OutputStream:handle:
3138 * The file handle that the stream writes to.
3147 * Zlib decompression
3152 * GZlibCompressor:file-info:
3154 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
3155 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
3156 * and modification time from the file info to the GZIP header.
3163 * GZlibDecompressor:
3165 * Zlib decompression
3170 * GZlibDecompressor:file-info:
3172 * A #GFileInfo containing the information found in the GZIP header
3173 * of the data stream processed, or %NULL if the header was not yet
3174 * fully processed, is not present at all, or the compressor's
3175 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
3182 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
3184 * The purpose used to verify the client certificate in a TLS connection.
3185 * Used by TLS servers.
3190 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
3192 * The purpose used to verify the server certificate in a TLS connection. This
3193 * is the most common purpose in use. Used by TLS clients.
3198 * G_TYPE_SETTINGS_SCHEMA:
3200 * A boxed #GType corresponding to #GSettingsSchema.
3207 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
3209 * A boxed #GType corresponding to #GSettingsSchemaSource.
3216 * SECTION:_GFreedesktopDBus
3217 * @title: _GFreedesktopDBus
3218 * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface
3220 * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface in C.
3225 * SECTION:extensionpoints
3226 * @short_description: Extension Points
3228 * @see_also: <link linkend="extending-gio">Extending GIO</link>
3230 * #GIOExtensionPoint provides a mechanism for modules to extend the
3231 * functionality of the library or application that loaded it in an
3232 * organized fashion.
3234 * An extension point is identified by a name, and it may optionally
3235 * require that any implementation must by of a certain type (or derived
3236 * thereof). Use g_io_extension_point_register() to register an
3237 * extension point, and g_io_extension_point_set_required_type() to
3238 * set a required type.
3240 * A module can implement an extension point by specifying the #GType
3241 * that implements the functionality. Additionally, each implementation
3242 * of an extension point has a name, and a priority. Use
3243 * g_io_extension_point_implement() to implement an extension point.
3246 * GIOExtensionPoint *ep;
3248 * /* Register an extension point */
3249 * ep = g_io_extension_point_register ("my-extension-point");
3250 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
3254 * /* Implement an extension point */
3255 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
3256 * g_io_extension_point_implement ("my-extension-point",
3257 * my_example_impl_get_type (),
3262 * It is up to the code that registered the extension point how
3263 * it uses the implementations that have been associated with it.
3264 * Depending on the use case, it may use all implementations, or
3265 * only the one with the highest priority, or pick a specific
3268 * To avoid opening all modules just to find out what extension
3269 * points they implement, GIO makes use of a caching mechanism,
3270 * see <link linkend="gio-querymodules">gio-querymodules</link>.
3271 * You are expected to run this command after installing a
3274 * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be
3275 * used to specify additional directories to automatically load modules
3276 * from. This environment variable has the same syntax as the
3277 * <envar>PATH</envar>. If two modules have the same base name in different
3278 * directories, then the latter one will be ignored. If additional
3279 * directories are specified GIO will load modules from the built-in
3287 * @short_description: An action interface
3289 * #GAction represents a single named action.
3291 * The main interface to an action is that it can be activated with
3292 * g_action_activate(). This results in the 'activate' signal being
3293 * emitted. An activation has a #GVariant parameter (which may be
3294 * %NULL). The correct type for the parameter is determined by a static
3295 * parameter type (which is given at construction time).
3297 * An action may optionally have a state, in which case the state may be
3298 * set with g_action_change_state(). This call takes a #GVariant. The
3299 * correct type for the state is determined by a static state type
3300 * (which is given at construction time).
3302 * The state may have a hint associated with it, specifying its valid
3305 * #GAction is merely the interface to the concept of an action, as
3306 * described above. Various implementations of actions exist, including
3307 * #GSimpleAction and #GtkAction.
3309 * In all cases, the implementing class is responsible for storing the
3310 * name of the action, the parameter type, the enabled state, the
3311 * optional state type and the state and emitting the appropriate
3312 * signals when these change. The implementor responsible for filtering
3313 * calls to g_action_activate() and g_action_change_state() for type
3314 * safety and for the state being enabled.
3316 * Probably the only useful thing to do with a #GAction is to put it
3317 * inside of a #GSimpleActionGroup.
3322 * SECTION:gactiongroup
3323 * @title: GActionGroup
3324 * @short_description: A group of actions
3325 * @see_also: #GAction
3327 * #GActionGroup represents a group of actions. Actions can be used to
3328 * expose functionality in a structured way, either from one part of a
3329 * program to another, or to the outside world. Action groups are often
3330 * used together with a #GMenuModel that provides additional
3331 * representation data for displaying the actions to the user, e.g. in
3334 * The main way to interact with the actions in a GActionGroup is to
3335 * activate them with g_action_group_activate_action(). Activating an
3336 * action may require a #GVariant parameter. The required type of the
3337 * parameter can be inquired with g_action_group_get_action_parameter_type().
3338 * Actions may be disabled, see g_action_group_get_action_enabled().
3339 * Activating a disabled action has no effect.
3341 * Actions may optionally have a state in the form of a #GVariant. The
3342 * current state of an action can be inquired with
3343 * g_action_group_get_action_state(). Activating a stateful action may
3344 * change its state, but it is also possible to set the state by calling
3345 * g_action_group_change_action_state().
3347 * As typical example, consider a text editing application which has an
3348 * option to change the current font to 'bold'. A good way to represent
3349 * this would be a stateful action, with a boolean state. Activating the
3350 * action would toggle the state.
3352 * Each action in the group has a unique name (which is a string). All
3353 * method calls, except g_action_group_list_actions() take the name of
3354 * an action as an argument.
3356 * The #GActionGroup API is meant to be the 'public' API to the action
3357 * group. The calls here are exactly the interaction that 'external
3358 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
3359 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
3360 * the action group implementation) are found on subclasses. This is
3361 * why you will find - for example - g_action_group_get_action_enabled()
3362 * but not an equivalent <function>set()</function> call.
3364 * Signals are emitted on the action group in response to state changes
3365 * on individual actions.
3367 * Implementations of #GActionGroup should provide implementations for
3368 * the virtual functions g_action_group_list_actions() and
3369 * g_action_group_query_action(). The other virtual functions should
3370 * not be implemented - their "wrappers" are actually implemented with
3371 * calls to g_action_group_query_action().
3376 * SECTION:gactiongroupexporter
3377 * @title: GActionGroup exporter
3378 * @short_description: Export GActionGroups on D-Bus
3379 * @see_also: #GActionGroup, #GDBusActionGroup
3381 * These functions support exporting a #GActionGroup on D-Bus.
3382 * The D-Bus interface that is used is a private implementation
3385 * To access an exported #GActionGroup remotely, use
3386 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
3391 * SECTION:gactionmap
3392 * @title: GActionMap
3393 * @short_description: Interface for action containers
3395 * The GActionMap interface is implemented by #GActionGroup
3396 * implementations that operate by containing a number of
3397 * named #GAction instances, such as #GSimpleActionGroup.
3399 * One useful application of this interface is to map the
3400 * names of actions from various action groups to unique,
3401 * prefixed names (e.g. by prepending "app." or "win.").
3402 * This is the motivation for the 'Map' part of the interface
3411 * @short_description: Application information and launch contexts
3412 * @include: gio/gio.h
3414 * #GAppInfo and #GAppLaunchContext are used for describing and launching
3415 * applications installed on the system.
3417 * As of GLib 2.20, URIs will always be converted to POSIX paths
3418 * (using g_file_get_path()) when using g_app_info_launch() even if
3419 * the application requested an URI and not a POSIX path. For example
3420 * for an desktop-file based application with Exec key <literal>totem
3421 * %U</literal> and a single URI,
3422 * <literal>sftp://foo/file.avi</literal>, then
3423 * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
3424 * passed. This will only work if a set of suitable GIO extensions
3425 * (such as gvfs 2.26 compiled with FUSE support), is available and
3426 * operational; if this is not the case, the URI will be passed
3427 * unmodified to the application. Some URIs, such as
3428 * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
3429 * path (in gvfs there's no FUSE mount for it); such URIs will be
3430 * passed unmodified to the application.
3432 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
3433 * back to the GIO URI in the #GFile constructors (since gvfs
3434 * implements the #GVfs extension point). As such, if the application
3435 * needs to examine the URI, it needs to use g_file_get_uri() or
3436 * similar on #GFile. In other words, an application cannot assume
3437 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
3438 * equal to the result of g_file_get_uri(). The following snippet
3445 * file = g_file_new_for_commandline_arg (uri_from_commandline);
3447 * uri = g_file_get_uri (file);
3448 * strcmp (uri, uri_from_commandline) == 0; // FALSE
3451 * if (g_file_has_uri_scheme (file, "cdda"))
3453 * // do something special with uri
3455 * g_object_unref (file);
3458 * This code will work when both <literal>cdda://sr0/Track
3459 * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
3460 * 1.wav</literal> is passed to the application. It should be noted
3461 * that it's generally not safe for applications to rely on the format
3462 * of a particular URIs. Different launcher applications (e.g. file
3463 * managers) may have different ideas of what a given URI means.
3468 * SECTION:gapplication
3469 * @title: GApplication
3470 * @short_description: Core application class
3472 * A #GApplication is the foundation of an application. It wraps some
3473 * low-level platform-specific services and is intended to act as the
3474 * foundation for higher-level application classes such as
3475 * #GtkApplication or #MxApplication. In general, you should not use
3476 * this class outside of a higher level framework.
3478 * GApplication provides convenient life cycle management by maintaining
3479 * a <firstterm>use count</firstterm> for the primary application instance.
3480 * The use count can be changed using g_application_hold() and
3481 * g_application_release(). If it drops to zero, the application exits.
3482 * Higher-level classes such as #GtkApplication employ the use count to
3483 * ensure that the application stays alive as long as it has any opened
3486 * Another feature that GApplication (optionally) provides is process
3487 * uniqueness. Applications can make use of this functionality by
3488 * providing a unique application ID. If given, only one application
3489 * with this ID can be running at a time per session. The session
3490 * concept is platform-dependent, but corresponds roughly to a graphical
3491 * desktop login. When your application is launched again, its
3492 * arguments are passed through platform communication to the already
3493 * running program. The already running instance of the program is
3494 * called the <firstterm>primary instance</firstterm>; for non-unique
3495 * applications this is the always the current instance.
3496 * On Linux, the D-Bus session bus is used for communication.
3498 * The use of #GApplication differs from some other commonly-used
3499 * uniqueness libraries (such as libunique) in important ways. The
3500 * application is not expected to manually register itself and check if
3501 * it is the primary instance. Instead, the <code>main()</code>
3502 * function of a #GApplication should do very little more than
3503 * instantiating the application instance, possibly connecting signal
3504 * handlers, then calling g_application_run(). All checks for
3505 * uniqueness are done internally. If the application is the primary
3506 * instance then the startup signal is emitted and the mainloop runs.
3507 * If the application is not the primary instance then a signal is sent
3508 * to the primary instance and g_application_run() promptly returns.
3509 * See the code examples below.
3511 * If used, the expected form of an application identifier is very close
3513 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
3514 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
3515 * For details on valid application identifiers, see g_application_id_is_valid().
3517 * On Linux, the application identifier is claimed as a well-known bus name
3518 * on the user's session bus. This means that the uniqueness of your
3519 * application is scoped to the current session. It also means that your
3520 * application may provide additional services (through registration of other
3521 * object paths) at that bus name. The registration of these object paths
3522 * should be done with the shared GDBus session bus. Note that due to the
3523 * internal architecture of GDBus, method calls can be dispatched at any time
3524 * (even if a main loop is not running). For this reason, you must ensure that
3525 * any object paths that you wish to register are registered before #GApplication
3526 * attempts to acquire the bus name of your application (which happens in
3527 * g_application_register()). Unfortunately, this means that you cannot use
3528 * g_application_get_is_remote() to decide if you want to register object paths.
3530 * GApplication also implements the #GActionGroup and #GActionMap
3531 * interfaces and lets you easily export actions by adding them with
3532 * g_action_map_add_action(). When invoking an action by calling
3533 * g_action_group_activate_action() on the application, it is always
3534 * invoked in the primary instance. The actions are also exported on
3535 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
3536 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
3537 * for remote access to exported #GMenuModels.
3539 * There is a number of different entry points into a GApplication:
3541 * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
3542 * <listitem>via 'Open' (i.e. opening some files)</listitem>
3543 * <listitem>by handling a command-line</listitem>
3544 * <listitem>via activating an action</listitem>
3546 * The #GApplication::startup signal lets you handle the application
3547 * initialization for all of these in a single place.
3549 * Regardless of which of these entry points is used to start the application,
3550 * GApplication passes some <firstterm id="platform-data">platform
3551 * data</firstterm> from the launching instance to the primary instance,
3552 * in the form of a #GVariant dictionary mapping strings to variants.
3553 * To use platform data, override the @before_emit or @after_emit virtual
3554 * functions in your #GApplication subclass. When dealing with
3555 * #GApplicationCommandLine objects, the platform data is directly
3556 * available via g_application_command_line_get_cwd(),
3557 * g_application_command_line_get_environ() and
3558 * g_application_command_line_get_platform_data().
3560 * As the name indicates, the platform data may vary depending on the
3561 * operating system, but it always includes the current directory (key
3562 * "cwd"), and optionally the environment (ie the set of environment
3563 * variables and their values) of the calling process (key "environ").
3564 * The environment is only added to the platform data if the
3565 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
3566 * can add their own platform data by overriding the @add_platform_data
3567 * virtual function. For instance, #GtkApplication adds startup notification
3570 * To parse commandline arguments you may handle the
3571 * #GApplication::command-line signal or override the local_command_line()
3572 * vfunc, to parse them in either the primary instance or the local instance,
3575 * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
3577 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c">
3578 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3583 * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
3585 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
3586 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3591 * <example id="gapplication-example-menu"><title>A GApplication with menus</title>
3593 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c">
3594 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3599 * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title>
3601 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-dbushooks.c">
3602 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3610 * SECTION:gapplicationcommandline
3611 * @title: GApplicationCommandLine
3612 * @short_description: A command-line invocation of an application
3613 * @see_also: #GApplication
3615 * #GApplicationCommandLine represents a command-line invocation of
3616 * an application. It is created by #GApplication and emitted
3617 * in the #GApplication::command-line signal and virtual function.
3619 * The class contains the list of arguments that the program was invoked
3620 * with. It is also possible to query if the commandline invocation was
3621 * local (ie: the current process is running in direct response to the
3622 * invocation) or remote (ie: some other process forwarded the
3623 * commandline to this process).
3625 * The GApplicationCommandLine object can provide the @argc and @argv
3626 * parameters for use with the #GOptionContext command-line parsing API,
3627 * with the g_application_command_line_get_arguments() function. See
3628 * <xref linkend="gapplication-example-cmdline3"/> for an example.
3630 * The exit status of the originally-invoked process may be set and
3631 * messages can be printed to stdout or stderr of that process. The
3632 * lifecycle of the originally-invoked process is tied to the lifecycle
3633 * of this object (ie: the process exits when the last reference is
3636 * The main use for #GApplicationCommandLine (and the
3637 * #GApplication::command-line signal) is 'Emacs server' like use cases:
3638 * You can set the <envar>EDITOR</envar> environment variable to have
3639 * e.g. git use your favourite editor to edit commit messages, and if you
3640 * already have an instance of the editor running, the editing will happen
3641 * in the running instance, instead of opening a new one. An important
3642 * aspect of this use case is that the process that gets started by git
3643 * does not return until the editing is done.
3645 * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
3647 * A simple example where the commandline is completely handled
3648 * in the #GApplication::command-line handler. The launching instance exits
3649 * once the signal handler in the primary instance has returned, and the
3650 * return value of the signal handler becomes the exit status of the launching
3654 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
3655 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3660 * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
3662 * An example of split commandline handling. Options that start with
3663 * <literal>--local-</literal> are handled locally, all other options are
3664 * passed to the #GApplication::command-line handler which runs in the primary
3668 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
3669 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3674 * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
3676 * An example of deferred commandline handling. Here, the commandline is
3677 * not completely handled before the #GApplication::command-line handler
3678 * returns. Instead, we keep a reference to the GApplicationCommandLine
3679 * object and handle it later(in this example, in an idle). Note that it
3680 * is necessary to hold the application until you are done with the
3684 * This example also shows how to use #GOptionContext for parsing the
3685 * commandline arguments. Note that it is necessary to disable the
3686 * built-in help-handling of #GOptionContext, since it calls exit()
3687 * after printing help, which is not what you want to happen in
3688 * the primary instance.
3691 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
3692 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3700 * SECTION:gasyncinitable
3701 * @short_description: Asynchronously failable object initialization interface
3702 * @include: gio/gio.h
3703 * @see_also: #GInitable
3705 * This is the asynchronous version of #GInitable; it behaves the same
3706 * in all ways except that initialization is asynchronous. For more details
3707 * see the descriptions on #GInitable.
3709 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
3711 * Users of objects implementing this are not intended to use the interface
3712 * method directly; instead it will be used automatically in various ways.
3713 * For C applications you generally just call g_async_initable_new_async()
3714 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
3715 * g_async_initable_init_async() under the cover, calling back with %NULL and
3716 * a set %GError on failure.
3718 * A typical implementation might look something like this:
3728 * _foo_ready_cb (Foo *self)
3732 * self->priv->state = INITIALIZED;
3734 * for (l = self->priv->init_results; l != NULL; l = l->next)
3736 * GTask *task = l->data;
3738 * if (self->priv->success)
3739 * g_task_return_boolean (task, TRUE);
3741 * g_task_return_new_error (task, ...);
3742 * g_object_unref (task);
3745 * g_list_free (self->priv->init_results);
3746 * self->priv->init_results = NULL;
3750 * foo_init_async (GAsyncInitable *initable,
3752 * GCancellable *cancellable,
3753 * GAsyncReadyCallback callback,
3754 * gpointer user_data)
3756 * Foo *self = FOO (initable);
3759 * task = g_task_new (initable, cancellable, callback, user_data);
3761 * switch (self->priv->state)
3763 * case NOT_INITIALIZED:
3764 * _foo_get_ready (self);
3765 * self->priv->init_results = g_list_append (self->priv->init_results,
3767 * self->priv->state = INITIALIZING;
3769 * case INITIALIZING:
3770 * self->priv->init_results = g_list_append (self->priv->init_results,
3774 * if (!self->priv->success)
3775 * g_task_return_new_error (task, ...);
3777 * g_task_return_boolean (task, TRUE);
3778 * g_object_unref (task);
3784 * foo_init_finish (GAsyncInitable *initable,
3785 * GAsyncResult *result,
3788 * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
3790 * return g_task_propagate_boolean (G_TASK (result), error);
3794 * foo_async_initable_iface_init (gpointer g_iface,
3797 * GAsyncInitableIface *iface = g_iface;
3799 * iface->init_async = foo_init_async;
3800 * iface->init_finish = foo_init_finish;
3807 * SECTION:gasyncresult
3808 * @short_description: Asynchronous Function Results
3809 * @include: gio/gio.h
3812 * Provides a base class for implementing asynchronous function results.
3814 * Asynchronous operations are broken up into two separate operations
3815 * which are chained together by a #GAsyncReadyCallback. To begin
3816 * an asynchronous operation, provide a #GAsyncReadyCallback to the
3817 * asynchronous function. This callback will be triggered when the
3818 * operation has completed, and will be passed a #GAsyncResult instance
3819 * filled with the details of the operation's success or failure, the
3820 * object the asynchronous function was started for and any error codes
3821 * returned. The asynchronous callback function is then expected to call
3822 * the corresponding "_finish()" function, passing the object the
3823 * function was called for, the #GAsyncResult instance, and (optionally)
3824 * an @error to grab any error conditions that may have occurred.
3826 * The "_finish()" function for an operation takes the generic result
3827 * (of type #GAsyncResult) and returns the specific result that the
3828 * operation in question yields (e.g. a #GFileEnumerator for a
3829 * "enumerate children" operation). If the result or error status of the
3830 * operation is not needed, there is no need to call the "_finish()"
3831 * function; GIO will take care of cleaning up the result and error
3832 * information after the #GAsyncReadyCallback returns. You can pass
3833 * %NULL for the #GAsyncReadyCallback if you don't need to take any
3834 * action at all after the operation completes. Applications may also
3835 * take a reference to the #GAsyncResult and call "_finish()" later;
3836 * however, the "_finish()" function may be called at most once.
3838 * Example of a typical asynchronous operation flow:
3840 * void _theoretical_frobnitz_async (Theoretical *t,
3842 * GAsyncReadyCallback *cb,
3845 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
3846 * GAsyncResult *res,
3850 * frobnitz_result_func (GObject *source_object,
3851 * GAsyncResult *res,
3852 * gpointer user_data)
3854 * gboolean success = FALSE;
3856 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
3859 * g_printf ("Hurray!\n");
3861 * g_printf ("Uh oh!\n");
3863 * /<!-- -->* ... *<!-- -->/
3867 * int main (int argc, void *argv[])
3869 * /<!-- -->* ... *<!-- -->/
3871 * _theoretical_frobnitz_async (theoretical_data,
3873 * frobnitz_result_func,
3876 * /<!-- -->* ... *<!-- -->/
3880 * The callback for an asynchronous operation is called only once, and is
3881 * always called, even in the case of a cancelled operation. On cancellation
3882 * the result is a %G_IO_ERROR_CANCELLED error.
3884 * <para id="io-priority"><indexterm><primary>I/O
3885 * priority</primary></indexterm> Many I/O-related asynchronous
3886 * operations have a priority parameter, which is used in certain
3887 * cases to determine the order in which operations are executed. They
3888 * are <emphasis>not</emphasis> used to determine system-wide I/O
3889 * scheduling. Priorities are integers, with lower numbers indicating
3890 * higher priority. It is recommended to choose priorities between
3891 * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a
3897 * SECTION:gbufferedinputstream
3898 * @short_description: Buffered Input Stream
3899 * @include: gio/gio.h
3900 * @see_also: #GFilterInputStream, #GInputStream
3902 * Buffered input stream implements #GFilterInputStream and provides
3903 * for buffered reads.
3905 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
3907 * To create a buffered input stream, use g_buffered_input_stream_new(),
3908 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
3911 * To get the size of a buffer within a buffered input stream, use
3912 * g_buffered_input_stream_get_buffer_size(). To change the size of a
3913 * buffered input stream's buffer, use
3914 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
3915 * cannot be reduced below the size of the data within the buffer.
3920 * SECTION:gbufferedoutputstream
3921 * @short_description: Buffered Output Stream
3922 * @include: gio/gio.h
3923 * @see_also: #GFilterOutputStream, #GOutputStream
3925 * Buffered output stream implements #GFilterOutputStream and provides
3926 * for buffered writes.
3928 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
3930 * To create a buffered output stream, use g_buffered_output_stream_new(),
3931 * or g_buffered_output_stream_new_sized() to specify the buffer's size
3934 * To get the size of a buffer within a buffered input stream, use
3935 * g_buffered_output_stream_get_buffer_size(). To change the size of a
3936 * buffered output stream's buffer, use
3937 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
3938 * size cannot be reduced below the size of the data within the buffer.
3943 * SECTION:gcancellable
3944 * @short_description: Thread-safe Operation Cancellation Stack
3945 * @include: gio/gio.h
3947 * GCancellable is a thread-safe operation cancellation stack used
3948 * throughout GIO to allow for cancellation of synchronous and
3949 * asynchronous operations.
3954 * SECTION:gcharsetconverter
3955 * @short_description: Convert between charsets
3956 * @include: gio/gio.h
3958 * #GCharsetConverter is an implementation of #GConverter based on
3964 * SECTION:gcontenttype
3965 * @short_description: Platform-specific content typing
3966 * @include: gio/gio.h
3968 * A content type is a platform specific string that defines the type
3969 * of a file. On UNIX it is a <ulink url="http://www.wikipedia.org/wiki/Internet_media_type">mime type</ulink> like "text/plain" or "image/png".
3970 * On Win32 it is an extension string like ".doc", ".txt" or a perceived
3971 * string like "audio". Such strings can be looked up in the registry at
3972 * HKEY_CLASSES_ROOT.
3977 * SECTION:gconverter
3978 * @short_description: Data conversion interface
3979 * @include: gio/gio.h
3980 * @see_also: #GInputStream, #GOutputStream
3982 * #GConverter is implemented by objects that convert
3983 * binary data in various ways. The conversion can be
3984 * stateful and may fail at any place.
3986 * Some example conversions are: character set conversion,
3987 * compression, decompression and regular expression
3995 * SECTION:gconverterinputstream
3996 * @short_description: Converter Input Stream
3997 * @include: gio/gio.h
3998 * @see_also: #GInputStream, #GConverter
4000 * Converter input stream implements #GInputStream and allows
4001 * conversion of data of various types during reading.
4003 * As of GLib 2.34, #GConverterInputStream implements
4004 * #GPollableInputStream.
4009 * SECTION:gconverteroutputstream
4010 * @short_description: Converter Output Stream
4011 * @include: gio/gio.h
4012 * @see_also: #GOutputStream, #GConverter
4014 * Converter output stream implements #GOutputStream and allows
4015 * conversion of data of various types during reading.
4017 * As of GLib 2.34, #GConverterOutputStream implements
4018 * #GPollableOutputStream.
4023 * SECTION:gcredentials
4024 * @short_description: An object containing credentials
4025 * @include: gio/gio.h
4027 * The #GCredentials type is a reference-counted wrapper for native
4028 * credentials. This information is typically used for identifying,
4029 * authenticating and authorizing other processes.
4031 * Some operating systems supports looking up the credentials of the
4032 * remote peer of a communication endpoint - see e.g.
4033 * g_socket_get_credentials().
4035 * Some operating systems supports securely sending and receiving
4036 * credentials over a Unix Domain Socket, see
4037 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
4038 * g_unix_connection_receive_credentials() for details.
4040 * On Linux, the native credential type is a <type>struct ucred</type>
4042 * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
4043 * man page for details. This corresponds to
4044 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
4046 * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>.
4047 * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
4049 * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
4050 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
4055 * SECTION:gdatainputstream
4056 * @short_description: Data Input Stream
4057 * @include: gio/gio.h
4058 * @see_also: #GInputStream
4060 * Data input stream implements #GInputStream and includes functions for
4061 * reading structured data directly from a binary input stream.
4066 * SECTION:gdataoutputstream
4067 * @short_description: Data Output Stream
4068 * @include: gio/gio.h
4069 * @see_also: #GOutputStream
4071 * Data output stream implements #GOutputStream and includes functions for
4072 * writing data directly to an output stream.
4077 * SECTION:gdbusactiongroup
4078 * @title: GDBusActionGroup
4079 * @short_description: A D-Bus GActionGroup implementation
4080 * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
4082 * #GDBusActionGroup is an implementation of the #GActionGroup
4083 * interface that can be used as a proxy for an action group
4084 * that is exported over D-Bus with g_dbus_connection_export_action_group().
4089 * SECTION:gdbusaddress
4090 * @title: D-Bus Addresses
4091 * @short_description: D-Bus connection endpoints
4092 * @include: gio/gio.h
4094 * Routines for working with D-Bus addresses. A D-Bus address is a string
4095 * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
4096 * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>.
4101 * SECTION:gdbusauthobserver
4102 * @short_description: Object used for authenticating connections
4103 * @include: gio/gio.h
4105 * The #GDBusAuthObserver type provides a mechanism for participating
4106 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
4107 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
4108 * signals you are interested in. Note that new signals may be added
4111 * For example, if you only want to allow D-Bus connections from
4112 * processes owned by the same uid as the server, you would use a
4113 * signal handler like the following:
4114 * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
4116 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
4117 * GIOStream *stream,
4118 * GCredentials *credentials,
4119 * gpointer user_data)
4121 * gboolean authorized;
4123 * authorized = FALSE;
4124 * if (credentials != NULL)
4126 * GCredentials *own_credentials;
4127 * own_credentials = g_credentials_new ();
4128 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
4129 * authorized = TRUE;
4130 * g_object_unref (own_credentials);
4133 * return authorized;
4135 * </programlisting></example>
4140 * SECTION:gdbusconnection
4141 * @short_description: D-Bus Connections
4142 * @include: gio/gio.h
4144 * The #GDBusConnection type is used for D-Bus connections to remote
4145 * peers such as a message buses. It is a low-level API that offers a
4146 * lot of flexibility. For instance, it lets you establish a connection
4147 * over any transport that can by represented as an #GIOStream.
4149 * This class is rarely used directly in D-Bus clients. If you are writing
4150 * an D-Bus client, it is often easier to use the g_bus_own_name(),
4151 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
4153 * As an exception to the usual GLib rule that a particular object must not be
4154 * used by two threads at the same time, #GDBusConnection's methods may be
4155 * called from any thread<footnote>
4157 * This is so that g_bus_get() and g_bus_get_sync() can safely return the
4158 * same #GDBusConnection when called from any thread.
4162 * Most of the ways to obtain a #GDBusConnection automatically initialize it
4163 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
4164 * g_bus_get(), and the synchronous versions of those methods, give you an
4165 * initialized connection. Language bindings for GIO should use
4166 * g_initable_new() or g_async_initable_new_async(), which also initialize the
4169 * If you construct an uninitialized #GDBusConnection, such as via
4170 * g_object_new(), you must initialize it via g_initable_init() or
4171 * g_async_initable_init_async() before using its methods or properties.
4172 * Calling methods or accessing properties on a #GDBusConnection that has not
4173 * completed initialization successfully is considered to be invalid, and leads
4174 * to undefined behaviour. In particular, if initialization fails with a
4175 * #GError, the only valid thing you can do with that #GDBusConnection is to
4176 * free it with g_object_unref().
4178 * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4180 * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4182 * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4184 * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4189 * SECTION:gdbuserror
4190 * @title: GDBusError
4191 * @short_description: Mapping D-Bus errors to and from GError
4192 * @include: gio/gio.h
4194 * All facilities that return errors from remote methods (such as
4195 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
4196 * errors (e.g. errors returned from the other peer) and locally
4197 * in-process generated errors.
4199 * To check if a returned #GError is an error from a remote peer, use
4200 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
4201 * use g_dbus_error_get_remote_error(). Before presenting an error,
4202 * always use g_dbus_error_strip_remote_error().
4204 * In addition, facilities used to return errors to a remote peer also
4205 * use #GError. See g_dbus_method_invocation_return_error() for
4206 * discussion about how the D-Bus error name is set.
4208 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
4209 * automatically map from D-Bus errors to #GError and back. This
4210 * is typically done in the function returning the #GQuark for the
4212 * <example id="error-registration"><title>Error Registration</title><programlisting>
4213 * /<!-- -->* foo-bar-error.h: *<!-- -->/
4215 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
4216 * GQuark foo_bar_error_quark (void);
4220 * FOO_BAR_ERROR_FAILED,
4221 * FOO_BAR_ERROR_ANOTHER_ERROR,
4222 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
4223 * FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/
4226 * /<!-- -->* foo-bar-error.c: *<!-- -->/
4228 * static const GDBusErrorEntry foo_bar_error_entries[] =
4230 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
4231 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
4232 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
4235 * /<!-- -->* Ensure that every error code has an associated D-Bus error name *<!-- -->/
4236 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
4239 * foo_bar_error_quark (void)
4241 * static volatile gsize quark_volatile = 0;
4242 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
4244 * foo_bar_error_entries,
4245 * G_N_ELEMENTS (foo_bar_error_entries));
4246 * return (GQuark) quark_volatile;
4248 * </programlisting></example>
4249 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
4250 * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>.
4252 * If the other peer is using GDBus, and has registered the association with
4253 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
4254 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
4255 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
4256 * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
4258 * Note that errors in the %G_DBUS_ERROR error domain is intended only
4259 * for returning errors from a remote message bus process. Errors
4260 * generated locally in-process by e.g. #GDBusConnection is from the
4261 * %G_IO_ERROR domain.
4266 * SECTION:gdbusinterface
4267 * @short_description: Base type for D-Bus interfaces
4268 * @include: gio/gio.h
4270 * The #GDBusInterface type is the base type for D-Bus interfaces both
4271 * on the service side (see #GDBusInterfaceSkeleton) and client side
4272 * (see #GDBusProxy).
4277 * SECTION:gdbusinterfaceskeleton
4278 * @short_description: Service-side D-Bus interface
4279 * @include: gio/gio.h
4281 * Abstract base class for D-Bus interfaces on the service side.
4286 * SECTION:gdbusintrospection
4287 * @title: D-Bus Introspection Data
4288 * @short_description: Node and interface description data structures
4289 * @include: gio/gio.h
4291 * Various data structures and convenience routines to parse and
4292 * generate D-Bus introspection XML. Introspection information is
4293 * used when registering objects with g_dbus_connection_register_object().
4295 * The format of D-Bus introspection XML is specified in the
4296 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>.
4301 * SECTION:gdbusmenumodel
4302 * @title: GDBusMenuModel
4303 * @short_description: A D-Bus GMenuModel implementation
4304 * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
4306 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
4307 * as a proxy for a menu model that is exported over D-Bus with
4308 * g_dbus_connection_export_menu_model().
4313 * SECTION:gdbusmessage
4314 * @short_description: D-Bus Message
4315 * @include: gio/gio.h
4317 * A type for representing D-Bus messages that can be sent or received
4318 * on a #GDBusConnection.
4323 * SECTION:gdbusmethodinvocation
4324 * @short_description: Object for handling remote calls
4325 * @include: gio/gio.h
4327 * Instances of the #GDBusMethodInvocation class are used when
4328 * handling D-Bus method calls. It provides a way to asynchronously
4329 * return results and errors.
4331 * The normal way to obtain a #GDBusMethodInvocation object is to receive
4332 * it as an argument to the handle_method_call() function in a
4333 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
4338 * SECTION:gdbusnameowning
4339 * @title: Owning Bus Names
4340 * @short_description: Simple API for owning bus names
4341 * @include: gio/gio.h
4343 * Convenience API for owning bus names.
4345 * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4350 * SECTION:gdbusnamewatching
4351 * @title: Watching Bus Names
4352 * @short_description: Simple API for watching bus names
4353 * @include: gio/gio.h
4355 * Convenience API for watching bus names.
4357 * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4362 * SECTION:gdbusobject
4363 * @short_description: Base type for D-Bus objects
4364 * @include: gio/gio.h
4366 * The #GDBusObject type is the base type for D-Bus objects on both
4367 * the service side (see #GDBusObjectSkeleton) and the client side
4368 * (see #GDBusObjectProxy). It is essentially just a container of
4374 * SECTION:gdbusobjectmanager
4375 * @short_description: Base type for D-Bus object managers
4376 * @include: gio/gio.h
4378 * The #GDBusObjectManager type is the base type for service- and
4379 * client-side implementations of the standardized <ulink
4380 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
4383 * See #GDBusObjectManagerClient for the client-side implementation
4384 * and #GDBusObjectManagerServer for the service-side implementation.
4389 * SECTION:gdbusobjectmanagerclient
4390 * @short_description: Client-side object manager
4391 * @include: gio/gio.h
4393 * #GDBusObjectManagerClient is used to create, monitor and delete object
4394 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
4395 * code implementing the <ulink
4396 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
4399 * Once an instance of this type has been created, you can connect to
4400 * the #GDBusObjectManager::object-added and
4401 * #GDBusObjectManager::object-removed signals and inspect the
4402 * #GDBusObjectProxy objects returned by
4403 * g_dbus_object_manager_get_objects().
4405 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
4406 * object construction time, the default behavior is to request the
4407 * message bus to launch an owner for the name. This behavior can be
4408 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
4409 * flag. It's also worth noting that this only works if the name of
4410 * interest is activatable in the first place. E.g. in some cases it
4411 * is not possible to launch an owner for the requested name. In this
4412 * case, #GDBusObjectManagerClient object construction still succeeds but
4413 * there will be no object proxies
4414 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
4415 * the #GDBusObjectManagerClient:name-owner property is %NULL.
4417 * The owner of the requested name can come and go (for example
4418 * consider a system service being restarted) – #GDBusObjectManagerClient
4419 * handles this case too; simply connect to the #GObject::notify
4420 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
4421 * property. When the name owner vanishes, the behavior is that
4422 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
4423 * emission of the #GObject::notify signal) and then
4424 * #GDBusObjectManager::object-removed signals are synthesized
4425 * for all currently existing object proxies. Since
4426 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
4427 * use this information to disambiguate a synthesized signal from a
4428 * genuine signal caused by object removal on the remote
4429 * #GDBusObjectManager. Similarly, when a new name owner appears,
4430 * #GDBusObjectManager::object-added signals are synthesized
4431 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
4432 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
4433 * is set to the new name owner (this includes emission of the
4434 * #GObject::notify signal). Furthermore, you are guaranteed that
4435 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
4436 * (e.g. <literal>:1.42</literal>) and %NULL even in the case where
4437 * the name of interest is atomically replaced
4439 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
4440 * instances. All signals (including the
4441 * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
4442 * signal) delivered to #GDBusProxy instances are guaranteed to
4443 * originate from the name owner. This guarantee along with the
4444 * behavior described above, means that certain race conditions
4445 * including the <emphasis><quote>half the proxy is from the old owner
4446 * and the other half is from the new owner</quote></emphasis> problem
4449 * To avoid having the application connect to signals on the returned
4450 * #GDBusObjectProxy and #GDBusProxy objects, the
4451 * #GDBusObject::interface-added,
4452 * #GDBusObject::interface-removed,
4453 * #GDBusProxy::g-properties-changed and
4454 * #GDBusProxy::g-signal signals
4455 * are also emitted on the #GDBusObjectManagerClient instance managing these
4456 * objects. The signals emitted are
4457 * #GDBusObjectManager::interface-added,
4458 * #GDBusObjectManager::interface-removed,
4459 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
4460 * #GDBusObjectManagerClient::interface-proxy-signal.
4462 * Note that all callbacks and signals are emitted in the
4463 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
4464 * that the #GDBusObjectManagerClient object was constructed
4465 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
4466 * originating from the #GDBusObjectManagerClient object will be created in
4467 * the same context and, consequently, will deliver signals in the
4473 * SECTION:gdbusobjectmanagerserver
4474 * @short_description: Service-side object manager
4475 * @include: gio/gio.h
4477 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
4478 * the standardized <ulink
4479 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
4480 * interface. For example, remote D-Bus clients can get all objects
4481 * and properties in a single call. Additionally, any change in the
4482 * object hierarchy is broadcast using signals. This means that D-Bus
4483 * clients can keep caches up to date by only listening to D-Bus
4486 * See #GDBusObjectManagerClient for the client-side code that is
4487 * intended to be used with #GDBusObjectManagerServer or any D-Bus
4488 * object implementing the org.freedesktop.DBus.ObjectManager
4494 * SECTION:gdbusobjectproxy
4495 * @short_description: Client-side D-Bus object
4496 * @include: gio/gio.h
4498 * A #GDBusObjectProxy is an object used to represent a remote object
4499 * with one or more D-Bus interfaces. Normally, you don't instantiate
4500 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
4501 * is used to obtain it.
4508 * SECTION:gdbusobjectskeleton
4509 * @short_description: Service-side D-Bus object
4510 * @include: gio/gio.h
4512 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
4513 * interfaces. The set of exported interfaces on the object may be
4514 * dynamic and change at runtime.
4516 * This type is intended to be used with #GDBusObjectManager.
4521 * SECTION:gdbusproxy
4522 * @short_description: Client-side D-Bus interface proxy
4523 * @include: gio/gio.h
4525 * #GDBusProxy is a base class used for proxies to access a D-Bus
4526 * interface on a remote object. A #GDBusProxy can be constructed for
4527 * both well-known and unique names.
4529 * By default, #GDBusProxy will cache all properties (and listen to
4530 * changes) of the remote object, and proxy all signals that gets
4531 * emitted. This behaviour can be changed by passing suitable
4532 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
4533 * well-known name, the property cache is flushed when the name owner
4534 * vanishes and reloaded when a name owner appears.
4536 * If a #GDBusProxy is used for a well-known name, the owner of the
4537 * name is tracked and can be read from
4538 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
4539 * get notified of changes. Additionally, only signals and property
4540 * changes emitted from the current name owner are considered and
4541 * calls are always sent to the current name owner. This avoids a
4542 * number of race conditions when the name is lost by one owner and
4543 * claimed by another. However, if no name owner currently exists,
4544 * then calls will be sent to the well-known name which may result in
4545 * the message bus launching an owner (unless
4546 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
4548 * The generic #GDBusProxy::g-properties-changed and
4549 * #GDBusProxy::g-signal signals are not very convenient to work
4550 * with. Therefore, the recommended way of working with proxies is to
4551 * subclass #GDBusProxy, and have more natural properties and signals
4552 * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/>
4553 * for how this can easily be done using the
4554 * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command>
4557 * A #GDBusProxy instance can be used from multiple threads but note
4558 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
4559 * and #GObject::notify) are emitted in the
4560 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
4561 * of the thread where the instance was constructed.
4563 * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4568 * SECTION:gdbusserver
4569 * @short_description: Helper for accepting connections
4570 * @include: gio/gio.h
4572 * #GDBusServer is a helper for listening to and accepting D-Bus
4573 * connections. This can be used to create a new D-Bus server, allowing two
4574 * peers to use the D-Bus protocol for their own specialized communication.
4575 * A server instance provided in this way will not perform message routing or
4576 * implement the org.freedesktop.DBus interface.
4578 * To just export an object on a well-known name on a message bus, such as the
4579 * session or system bus, you should instead use g_bus_own_name().
4581 * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
4586 * SECTION:gdbusutils
4587 * @title: D-Bus Utilities
4588 * @short_description: Various utilities related to D-Bus.
4589 * @include: gio/gio.h
4591 * Various utility routines related to D-Bus.
4596 * SECTION:gdesktopappinfo
4597 * @title: GDesktopAppInfo
4598 * @short_description: Application information from desktop files
4599 * @include: gio/gdesktopappinfo.h
4601 * #GDesktopAppInfo is an implementation of #GAppInfo based on
4604 * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to
4605 * the UNIX-specific GIO interfaces, thus you have to use the
4606 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
4612 * @short_description: Drive management
4613 * @include: gio/gio.h
4615 * #GDrive - this represent a piece of hardware connected to the machine.
4616 * It's generally only created for removable hardware or hardware with
4619 * #GDrive is a container class for #GVolume objects that stem from
4620 * the same piece of media. As such, #GDrive abstracts a drive with
4621 * (or without) removable media and provides operations for querying
4622 * whether media is available, determining whether media change is
4623 * automatically detected and ejecting the media.
4625 * If the #GDrive reports that media isn't automatically detected, one
4626 * can poll for media; typically one should not do this periodically
4627 * as a poll for media operation is potententially expensive and may
4628 * spin up the drive creating noise.
4630 * #GDrive supports starting and stopping drives with authentication
4631 * support for the former. This can be used to support a diverse set
4632 * of use cases including connecting/disconnecting iSCSI devices,
4633 * powering down external disk enclosures and starting/stopping
4634 * multi-disk devices such as RAID devices. Note that the actual
4635 * semantics and side-effects of starting/stopping a #GDrive may vary
4636 * according to implementation. To choose the correct verbs in e.g. a
4637 * file manager, use g_drive_get_start_stop_type().
4639 * For porting from GnomeVFS note that there is no equivalent of
4640 * #GDrive in that API.
4646 * @short_description: An object for emblems
4647 * @include: gio/gio.h
4648 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
4650 * #GEmblem is an implementation of #GIcon that supports
4651 * having an emblem, which is an icon with additional properties.
4652 * It can than be added to a #GEmblemedIcon.
4654 * Currently, only metainformation about the emblem's origin is
4655 * supported. More may be added in the future.
4660 * SECTION:gemblemedicon
4661 * @short_description: Icon with emblems
4662 * @include: gio/gio.h
4663 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
4665 * #GEmblemedIcon is an implementation of #GIcon that supports
4666 * adding an emblem to an icon. Adding multiple emblems to an
4667 * icon is ensured via g_emblemed_icon_add_emblem().
4669 * Note that #GEmblemedIcon allows no control over the position
4670 * of the emblems. See also #GEmblem for more information.
4676 * @short_description: File and Directory Handling
4677 * @include: gio/gio.h
4678 * @see_also: #GFileInfo, #GFileEnumerator
4680 * #GFile is a high level abstraction for manipulating files on a
4681 * virtual file system. #GFiles are lightweight, immutable objects
4682 * that do no I/O upon creation. It is necessary to understand that
4683 * #GFile objects do not represent files, merely an identifier for a
4684 * file. All file content I/O is implemented as streaming operations
4685 * (see #GInputStream and #GOutputStream).
4687 * To construct a #GFile, you can use:
4689 * <member>g_file_new_for_path() if you have a path.</member>
4690 * <member>g_file_new_for_uri() if you have a URI.</member>
4691 * <member>g_file_new_for_commandline_arg() for a command line argument.</member>
4692 * <member>g_file_new_tmp() to create a temporary file from a template.</member>
4693 * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member>
4696 * One way to think of a #GFile is as an abstraction of a pathname. For
4697 * normal files the system pathname is what is stored internally, but as
4698 * #GFiles are extensible it could also be something else that corresponds
4699 * to a pathname in a userspace implementation of a filesystem.
4701 * #GFiles make up hierarchies of directories and files that correspond to
4702 * the files on a filesystem. You can move through the file system with
4703 * #GFile using g_file_get_parent() to get an identifier for the parent
4704 * directory, g_file_get_child() to get a child within a directory,
4705 * g_file_resolve_relative_path() to resolve a relative path between two
4706 * #GFiles. There can be multiple hierarchies, so you may not end up at
4707 * the same root if you repeatedly call g_file_get_parent() on two different
4710 * All #GFiles have a basename (get with g_file_get_basename()). These names
4711 * are byte strings that are used to identify the file on the filesystem
4712 * (relative to its parent directory) and there is no guarantees that they
4713 * have any particular charset encoding or even make any sense at all. If
4714 * you want to use filenames in a user interface you should use the display
4715 * name that you can get by requesting the
4716 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
4717 * This is guaranteed to be in UTF-8 and can be used in a user interface.
4718 * But always store the real basename or the #GFile to use to actually
4719 * access the file, because there is no way to go from a display name to
4722 * Using #GFile as an identifier has the same weaknesses as using a path
4723 * in that there may be multiple aliases for the same file. For instance,
4724 * hard or soft links may cause two different #GFiles to refer to the same
4725 * file. Other possible causes for aliases are: case insensitive filesystems,
4726 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
4727 * check if two #GFiles point to the same file you can query for the
4728 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
4729 * canonicalization of pathnames passed in, so that trivial differences in
4730 * the path string used at creation (duplicated slashes, slash at end of
4731 * path, "." or ".." path segments, etc) does not create different #GFiles.
4733 * Many #GFile operations have both synchronous and asynchronous versions
4734 * to suit your application. Asynchronous versions of synchronous functions
4735 * simply have _async() appended to their function names. The asynchronous
4736 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
4737 * the operation, producing a GAsyncResult which is then passed to the
4738 * function's matching _finish() operation.
4740 * Some #GFile operations do not have synchronous analogs, as they may
4741 * take a very long time to finish, and blocking may leave an application
4742 * unusable. Notable cases include:
4744 * <member>g_file_mount_mountable() to mount a mountable file.</member>
4745 * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member>
4746 * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
4749 * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
4750 * One notable feature of #GFiles are entity tags, or "etags" for
4751 * short. Entity tags are somewhat like a more abstract version of the
4752 * traditional mtime, and can be used to quickly determine if the file has
4753 * been modified from the version on the file system. See the HTTP 1.1
4754 * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
4755 * for HTTP Etag headers, which are a very similar concept.
4761 * SECTION:gfileattribute
4762 * @short_description: Key-Value Paired File Attributes
4763 * @include: gio/gio.h
4764 * @see_also: #GFile, #GFileInfo
4766 * File attributes in GIO consist of a list of key-value pairs.
4768 * Keys are strings that contain a key namespace and a key name, separated
4769 * by a colon, e.g. "namespace:keyname". Namespaces are included to sort
4770 * key-value pairs by namespaces for relevance. Keys can be retrived
4771 * using wildcards, e.g. "standard::*" will return all of the keys in the
4772 * "standard" namespace.
4774 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
4775 * available as a #GFileAttributeInfoList. This list is queryable by key names
4776 * as indicated earlier.
4778 * Information is stored within the list in #GFileAttributeInfo structures.
4779 * The info structure can store different types, listed in the enum
4780 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
4781 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
4783 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
4784 * install default keys and values for their given file system, architecture,
4785 * and other possible implementation details (e.g., on a UNIX system, a file
4786 * attribute key will be registered for the user id for a given file).
4790 * <title>GFileAttributes Default Namespaces</title>
4791 * <tgroup cols='2' align='left'><thead>
4792 * <row><entry>Namspace</entry><entry>Description</entry></row>
4795 * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file
4796 * information that any application may need should be put in this namespace.
4797 * Examples include the file's name, type, and size.</entry></row>
4798 * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link>
4799 * namespace. Currently, the only key in this namespace is "value", which contains
4800 * the value of the current entity tag.</entry></row>
4801 * <row><entry>"id"</entry><entry>The "Identification" namespace. This
4802 * namespace is used by file managers and applications that list directories
4803 * to check for loops and to uniquely identify files.</entry></row>
4804 * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check
4805 * if a user has the proper privilidges to access files and perform
4806 * file operations. Keys in this namespace are made to be generic
4807 * and easily understood, e.g. the "can_read" key is %TRUE if
4808 * the current user has permission to read the file. UNIX permissions and
4809 * NTFS ACLs in Windows should be mapped to these values.</entry></row>
4810 * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
4811 * simple boolean keys for checking if a file or path supports mount operations, e.g.
4812 * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row>
4813 * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
4814 * access, changed, created times. </entry></row>
4815 * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
4816 * information and may not be available for all files. Examples include
4817 * the UNIX "UID", "GID", etc.</entry></row>
4818 * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific
4819 * information and may not be available for all files. Examples include
4820 * "is_system" for checking if a file is marked as a system file, and "is_archive"
4821 * for checking if a file is marked as an archive file.</entry></row>
4822 * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
4823 * about who owns a file. May not be available for all file systems. Examples include
4824 * "user" for getting the user name of the file owner. This information is often mapped from
4825 * some backend specific data such as a unix UID.</entry></row>
4826 * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
4827 * information about file thumbnails and their location within the file system. Examples of
4828 * keys in this namespace include "path" to get the location of a thumbnail, and "failed"
4829 * to check if thumbnailing of the file failed.</entry></row>
4830 * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information
4831 * about the file system where a file is located, such as its type, how much
4832 * space is left available, and the overall size of the file system.</entry></row>
4833 * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
4834 * contain information about the current GVFS backend in use. </entry></row>
4835 * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information
4836 * about extended user attributes. See attr(5). The "user." prefix of the
4837 * extended user attribute name is stripped away when constructing keys in
4838 * this namespace, e.g. "xattr::mime_type" for the extended attribute with
4839 * the name "user.mime_type". Note that this information is only available
4840 * if GLib has been built with extended attribute support.</entry></row>
4841 * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace.
4842 * Gets information about extended attributes which are not user-specific.
4843 * See attr(5). Note that this information is only available if GLib
4844 * has been built with extended attribute support.</entry></row>
4845 * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes
4846 * information about the SELinux context of files. Note that this information
4847 * is only available if GLib has been built with SELinux support.</entry></row>
4853 * Please note that these are not all of the possible namespaces.
4854 * More namespaces can be added from GIO modules or by individual applications.
4855 * For more information about writing GIO modules, see #GIOModule.
4857 * <!-- TODO: Implementation note about using extended attributes on supported
4861 * <title>GFileAttributes Built-in Keys and Value Types</title>
4862 * <tgroup cols='3' align='left'><thead>
4863 * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row>
4865 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row>
4866 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row>
4867 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row>
4868 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row>
4869 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row>
4870 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row>
4871 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row>
4872 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row>
4873 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row>
4874 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row>
4875 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row>
4876 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row>
4877 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row>
4878 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row>
4879 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row>
4880 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row>
4881 * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row>
4882 * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row>
4883 * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row>
4884 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row>
4885 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row>
4886 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row>
4887 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row>
4888 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row>
4889 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row>
4890 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row>
4891 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row>
4892 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row>
4893 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row>
4894 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row>
4895 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row>
4896 * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row>
4897 * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row>
4898 * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row>
4899 * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row>
4900 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row>
4901 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row>
4902 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row>
4903 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row>
4904 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row>
4905 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row>
4906 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row>
4907 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row>
4908 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row>
4909 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row>
4910 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row>
4911 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row>
4912 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row>
4913 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row>
4914 * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row>
4915 * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row>
4916 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row>
4917 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row>
4918 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row>
4919 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row>
4920 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row>
4921 * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row>
4922 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row>
4923 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row>
4924 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_USED</entry><entry>filesystem::used</entry><entry>uint64</entry></row>
4925 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row>
4926 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row>
4927 * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
4928 * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
4929 * </tbody></tgroup></table></para>
4931 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
4932 * namespaces. Keys for the "xattr" namespace are constructed by stripping
4933 * away the "user." prefix from the extended user attribute, and prepending
4934 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
4935 * concatenating "xattr-sys::" with the extended attribute name. All extended
4936 * attribute values are returned as hex-encoded strings in which bytes outside
4937 * the ASCII range are encoded as hexadecimal escape sequences of the form
4938 * \x<replaceable>nn</replaceable>.
4943 * SECTION:gfiledescriptorbased
4944 * @short_description: Interface for file descriptor based IO
4945 * @include: gio/gfiledescriptorbased.h
4946 * @see_also: #GInputStream, #GOutputStream
4948 * #GFileDescriptorBased is implemented by streams (implementations of
4949 * #GInputStream or #GOutputStream) that are based on file descriptors.
4951 * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to
4952 * the UNIX-specific GIO interfaces, thus you have to use the
4953 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
4960 * SECTION:gfileenumerator
4961 * @short_description: Enumerated Files Routines
4962 * @include: gio/gio.h
4964 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
4965 * returning a #GFileInfo structure for each file enumerated (e.g.
4966 * g_file_enumerate_children() will return a #GFileEnumerator for each
4967 * of the children within a directory).
4969 * To get the next file's information from a #GFileEnumerator, use
4970 * g_file_enumerator_next_file() or its asynchronous version,
4971 * g_file_enumerator_next_files_async(). Note that the asynchronous
4972 * version will return a list of #GFileInfo<!---->s, whereas the
4973 * synchronous will only return the next file in the enumerator.
4975 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
4976 * its asynchronous version, g_file_enumerator_close_async(). Once
4977 * a #GFileEnumerator is closed, no further actions may be performed
4978 * on it, and it should be freed with g_object_unref().
4984 * @short_description: Icons pointing to an image file
4985 * @include: gio/gio.h
4986 * @see_also: #GIcon, #GLoadableIcon
4988 * #GFileIcon specifies an icon by pointing to an image file
4989 * to be used as icon.
4995 * @short_description: File Information and Attributes
4996 * @include: gio/gio.h
4997 * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
4999 * Functionality for manipulating basic metadata for files. #GFileInfo
5000 * implements methods for getting information that all files should
5001 * contain, and allows for manipulation of extended attributes.
5003 * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
5004 * information on how GIO handles file attributes.
5006 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
5007 * async variant). To obtain a #GFileInfo for a file input or output
5008 * stream, use g_file_input_stream_query_info() or
5009 * g_file_output_stream_query_info() (or their async variants).
5011 * To change the actual attributes of a file, you should then set the
5012 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
5013 * or g_file_set_attributes_async() on a GFile.
5015 * However, not all attributes can be changed in the file. For instance,
5016 * the actual size of a file cannot be changed via g_file_info_set_size().
5017 * You may call g_file_query_settable_attributes() and
5018 * g_file_query_writable_namespaces() to discover the settable attributes
5019 * of a particular file at runtime.
5021 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
5027 * SECTION:gfileinputstream
5028 * @short_description: File input streaming operations
5029 * @include: gio/gio.h
5030 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
5032 * GFileInputStream provides input streams that take their
5033 * content from a file.
5035 * GFileInputStream implements #GSeekable, which allows the input
5036 * stream to jump to arbitrary positions in the file, provided the
5037 * filesystem of the file allows it. To find the position of a file
5038 * input stream, use g_seekable_tell(). To find out if a file input
5039 * stream supports seeking, use g_seekable_can_seek().
5040 * To position a file input stream, use g_seekable_seek().
5045 * SECTION:gfileiostream
5046 * @short_description: File read and write streaming operations
5047 * @include: gio/gio.h
5048 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
5050 * GFileIOStream provides io streams that both read and write to the same
5053 * GFileIOStream implements #GSeekable, which allows the io
5054 * stream to jump to arbitrary positions in the file and to truncate
5055 * the file, provided the filesystem of the file supports these
5058 * To find the position of a file io stream, use
5059 * g_seekable_tell().
5061 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
5062 * To position a file io stream, use g_seekable_seek().
5063 * To find out if a file io stream supports truncating, use
5064 * g_seekable_can_truncate(). To truncate a file io
5065 * stream, use g_seekable_truncate().
5067 * The default implementation of all the #GFileIOStream operations
5068 * and the implementation of #GSeekable just call into the same operations
5069 * on the output stream.
5076 * SECTION:gfilemonitor
5077 * @short_description: File Monitor
5078 * @include: gio/gio.h
5080 * Monitors a file or directory for changes.
5082 * To obtain a #GFileMonitor for a file or directory, use
5083 * g_file_monitor(), g_file_monitor_file(), or
5084 * g_file_monitor_directory().
5086 * To get informed about changes to the file or directory you are
5087 * monitoring, connect to the #GFileMonitor::changed signal. The
5088 * signal will be emitted in the <link
5089 * linkend="g-main-context-push-thread-default">thread-default main
5090 * context</link> of the thread that the monitor was created in
5091 * (though if the global default main context is blocked, this may
5092 * cause notifications to be blocked even if the thread-default
5093 * context is still running).
5098 * SECTION:gfilenamecompleter
5099 * @short_description: Filename Completer
5100 * @include: gio/gio.h
5102 * Completes partial file and directory names given a partial string by
5103 * looking in the file system for clues. Can return a list of possible
5104 * completion strings for widget implementations.
5109 * SECTION:gfileoutputstream
5110 * @short_description: File output streaming operations
5111 * @include: gio/gio.h
5112 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
5114 * GFileOutputStream provides output streams that write their
5115 * content to a file.
5117 * GFileOutputStream implements #GSeekable, which allows the output
5118 * stream to jump to arbitrary positions in the file and to truncate
5119 * the file, provided the filesystem of the file supports these
5122 * To find the position of a file output stream, use g_seekable_tell().
5123 * To find out if a file output stream supports seeking, use
5124 * g_seekable_can_seek().To position a file output stream, use
5125 * g_seekable_seek(). To find out if a file output stream supports
5126 * truncating, use g_seekable_can_truncate(). To truncate a file output
5127 * stream, use g_seekable_truncate().
5132 * SECTION:gfilterinputstream
5133 * @short_description: Filter Input Stream
5134 * @include: gio/gio.h
5136 * Base class for input stream implementations that perform some
5137 * kind of filtering operation on a base stream. Typical examples
5138 * of filtering operations are character set conversion, compression
5139 * and byte order flipping.
5144 * SECTION:gfilteroutputstream
5145 * @short_description: Filter Output Stream
5146 * @include: gio/gio.h
5148 * Base class for output stream implementations that perform some
5149 * kind of filtering operation on a base stream. Typical examples
5150 * of filtering operations are character set conversion, compression
5151 * and byte order flipping.
5157 * @short_description: Interface for icons
5158 * @include: gio/gio.h
5160 * #GIcon is a very minimal interface for icons. It provides functions
5161 * for checking the equality of two icons, hashing of icons and
5162 * serializing an icon to and from strings.
5164 * #GIcon does not provide the actual pixmap for the icon as this is out
5165 * of GIO's scope, however implementations of #GIcon may contain the name
5166 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
5168 * To obtain a hash of a #GIcon, see g_icon_hash().
5170 * To check if two #GIcons are equal, see g_icon_equal().
5172 * For serializing a #GIcon, use g_icon_to_string() and
5173 * g_icon_new_for_string().
5175 * If your application or library provides one or more #GIcon
5176 * implementations you need to ensure that each #GType is registered
5177 * with the type system prior to calling g_icon_new_for_string().
5182 * SECTION:ginetaddress
5183 * @short_description: An IPv4/IPv6 address
5185 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
5186 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
5187 * look up the #GInetAddress for a hostname. Use
5188 * g_resolver_lookup_by_address() or
5189 * g_resolver_lookup_by_address_async() to look up the hostname for a
5192 * To actually connect to a remote host, you will need a
5193 * #GInetSocketAddress (which includes a #GInetAddress as well as a
5199 * SECTION:ginetaddressmask
5200 * @short_description: An IPv4/IPv6 address mask
5202 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
5203 * described by a base address and a length indicating how many bits
5204 * of the base address are relevant for matching purposes. These are
5205 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
5210 * SECTION:ginetsocketaddress
5211 * @short_description: Internet GSocketAddress
5213 * An IPv4 or IPv6 socket address; that is, the combination of a
5214 * #GInetAddress and a port number.
5220 * @short_description: Failable object initialization interface
5221 * @include: gio/gio.h
5222 * @see_also: #GAsyncInitable
5224 * #GInitable is implemented by objects that can fail during
5225 * initialization. If an object implements this interface then
5226 * it must be initialized as the first thing after construction,
5227 * either via g_initable_init() or g_async_initable_init_async()
5228 * (the latter is only available if it also implements #GAsyncInitable).
5230 * If the object is not initialized, or initialization returns with an
5231 * error, then all operations on the object except g_object_ref() and
5232 * g_object_unref() are considered to be invalid, and have undefined
5233 * behaviour. They will often fail with g_critical() or g_warning(), but
5234 * this must not be relied on.
5236 * Users of objects implementing this are not intended to use
5237 * the interface method directly, instead it will be used automatically
5238 * in various ways. For C applications you generally just call
5239 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
5240 * This will call g_initable_init() under the cover, returning %NULL and
5241 * setting a #GError on failure (at which point the instance is
5244 * For bindings in languages where the native constructor supports
5245 * exceptions the binding could check for objects implemention %GInitable
5246 * during normal construction and automatically initialize them, throwing
5247 * an exception on failure.
5252 * SECTION:ginputstream
5253 * @short_description: Base class for implementing streaming input
5254 * @include: gio/gio.h
5256 * #GInputStream has functions to read from a stream (g_input_stream_read()),
5257 * to close a stream (g_input_stream_close()) and to skip some content
5258 * (g_input_stream_skip()).
5260 * To copy the content of an input stream to an output stream without
5261 * manually handling the reads and writes, use g_output_stream_splice().
5263 * All of these functions have async variants too.
5269 * @short_description: Error helper functions
5270 * @include: gio/gio.h
5272 * Contains helper functions for reporting errors to the user.
5278 * @short_description: Loadable GIO Modules
5279 * @include: gio/gio.h
5281 * Provides an interface and default functions for loading and unloading
5282 * modules. This is used internally to make GIO extensible, but can also
5283 * be used by others to implement module loading.
5288 * SECTION:gioscheduler
5289 * @short_description: I/O Scheduler
5290 * @include: gio/gio.h
5293 * As of GLib 2.36, the <literal>g_io_scheduler</literal> methods
5294 * are deprecated in favor of #GThreadPool and #GTask.
5297 * Schedules asynchronous I/O operations. #GIOScheduler integrates
5298 * into the main event loop (#GMainLoop) and uses threads.
5304 * @short_description: Base class for implementing read/write streams
5305 * @include: gio/gio.h
5306 * @see_also: #GInputStream, #GOutputStream
5308 * GIOStream represents an object that has both read and write streams.
5309 * Generally the two streams acts as separate input and output streams,
5310 * but they share some common resources and state. For instance, for
5311 * seekable streams they may use the same position in both streams.
5313 * Examples of #GIOStream objects are #GSocketConnection which represents
5314 * a two-way network connection, and #GFileIOStream which represent a
5315 * file handle opened in read-write mode.
5317 * To do the actual reading and writing you need to get the substreams
5318 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
5320 * The #GIOStream object owns the input and the output streams, not the other
5321 * way around, so keeping the substreams alive will not keep the #GIOStream
5322 * object alive. If the #GIOStream object is freed it will be closed, thus
5323 * closing the substream, so even if the substreams stay alive they will
5324 * always just return a %G_IO_ERROR_CLOSED for all operations.
5326 * To close a stream use g_io_stream_close() which will close the common
5327 * stream object and also the individual substreams. You can also close
5328 * the substreams themselves. In most cases this only marks the
5329 * substream as closed, so further I/O on it fails. However, some streams
5330 * may support "half-closed" states where one direction of the stream
5331 * is actually shut down.
5338 * SECTION:gloadableicon
5339 * @short_description: Loadable Icons
5340 * @include: gio/gio.h
5341 * @see_also: #GIcon, #GThemedIcon
5343 * Extends the #GIcon interface and adds the ability to
5344 * load icons from streams.
5349 * SECTION:gmemoryinputstream
5350 * @short_description: Streaming input operations on memory chunks
5351 * @include: gio/gio.h
5352 * @see_also: #GMemoryOutputStream
5354 * #GMemoryInputStream is a class for using arbitrary
5355 * memory chunks as input for GIO streaming input operations.
5357 * As of GLib 2.34, #GMemoryInputStream implements
5358 * #GPollableInputStream.
5363 * SECTION:gmemoryoutputstream
5364 * @short_description: Streaming output operations on memory chunks
5365 * @include: gio/gio.h
5366 * @see_also: #GMemoryInputStream
5368 * #GMemoryOutputStream is a class for using arbitrary
5369 * memory chunks as output for GIO streaming output operations.
5371 * As of GLib 2.34, #GMemoryOutputStream implements
5372 * #GPollableOutputStream.
5379 * @short_description: A simple implementation of GMenuModel
5381 * #GMenu is a simple implementation of #GMenuModel.
5382 * You populate a #GMenu by adding #GMenuItem instances to it.
5384 * There are some convenience functions to allow you to directly
5385 * add items (avoiding #GMenuItem) for the common cases. To add
5386 * a regular item, use g_menu_insert(). To add a section, use
5387 * g_menu_insert_section(). To add a submenu, use
5388 * g_menu_insert_submenu().
5393 * SECTION:gmenuexporter
5394 * @title: GMenuModel exporter
5395 * @short_description: Export GMenuModels on D-Bus
5396 * @see_also: #GMenuModel, #GDBusMenuModel
5398 * These functions support exporting a #GMenuModel on D-Bus.
5399 * The D-Bus interface that is used is a private implementation
5402 * To access an exported #GMenuModel remotely, use
5403 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
5408 * SECTION:gmenumodel
5409 * @title: GMenuModel
5410 * @short_description: An abstract class representing the contents of a menu
5411 * @see_also: #GActionGroup
5413 * #GMenuModel represents the contents of a menu -- an ordered list of
5414 * menu items. The items are associated with actions, which can be
5415 * activated through them. Items can be grouped in sections, and may
5416 * have submenus associated with them. Both items and sections usually
5417 * have some representation data, such as labels or icons. The type of
5418 * the associated action (ie whether it is stateful, and what kind of
5419 * state it has) can influence the representation of the item.
5421 * The conceptual model of menus in #GMenuModel is hierarchical:
5422 * sections and submenus are again represented by #GMenuModels.
5423 * Menus themselves do not define their own roles. Rather, the role
5424 * of a particular #GMenuModel is defined by the item that references
5425 * it (or, in the case of the 'root' menu, is defined by the context
5426 * in which it is used).
5428 * As an example, consider the visible portions of the menu in
5429 * <xref linkend="menu-example"/>.
5431 * <figure id="menu-example">
5432 * <title>An example menu</title>
5433 * <graphic fileref="menu-example.png" format="PNG"></graphic>
5436 * There are 8 "menus" visible in the screenshot: one menubar, two
5437 * submenus and 5 sections:
5439 * <listitem>the toplevel menubar (containing 4 items)</listitem>
5440 * <listitem>the View submenu (containing 3 sections)</listitem>
5441 * <listitem>the first section of the View submenu (containing 2 items)</listitem>
5442 * <listitem>the second section of the View submenu (containing 1 item)</listitem>
5443 * <listitem>the final section of the View submenu (containing 1 item)</listitem>
5444 * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
5445 * <listitem>the Sources section (containing 2 items)</listitem>
5446 * <listitem>the Markup section (containing 2 items)</listitem>
5449 * <xref linkend="menu-model"/> illustrates the conceptual connection between
5450 * these 8 menus. Each large block in the figure represents a menu and the
5451 * smaller blocks within the large block represent items in that menu. Some
5452 * items contain references to other menus.
5454 * <figure id="menu-model">
5455 * <title>A menu model</title>
5456 * <graphic fileref="menu-model.png" format="PNG"></graphic>
5459 * Notice that the separators visible in <xref linkend="menu-example"/>
5460 * appear nowhere in <xref linkend="menu-model"/>. This is because
5461 * separators are not explicitly represented in the menu model. Instead,
5462 * a separator is inserted between any two non-empty sections of a menu.
5463 * Section items can have labels just like any other item. In that case,
5464 * a display system may show a section header instead of a separator.
5466 * The motivation for this abstract model of application controls is
5467 * that modern user interfaces tend to make these controls available
5468 * outside the application. Examples include global menus, jumplists,
5469 * dash boards, etc. To support such uses, it is necessary to 'export'
5470 * information about actions and their representation in menus, which
5471 * is exactly what the
5472 * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
5474 * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
5475 * do for #GActionGroup and #GMenuModel. The client-side counterparts
5476 * to make use of the exported information are #GDBusActionGroup and
5479 * The API of #GMenuModel is very generic, with iterators for the
5480 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
5481 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
5482 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
5483 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
5484 * and %G_MENU_LINK_SUBMENU.
5486 * Items in a #GMenuModel represent active controls if they refer to
5487 * an action that can get activated when the user interacts with the
5488 * menu item. The reference to the action is encoded by the string id
5489 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
5490 * identifies an action in an action group. Which action group(s) provide
5491 * actions depends on the context in which the menu model is used.
5492 * E.g. when the model is exported as the application menu of a
5493 * #GtkApplication, actions can be application-wide or window-specific
5494 * (and thus come from two different action groups). By convention, the
5495 * application-wide actions have names that start with "app.", while the
5496 * names of window-specific actions start with "win.".
5498 * While a wide variety of stateful actions is possible, the following
5499 * is the minimum that is expected to be supported by all users of exported
5502 * <listitem>an action with no parameter type and no state</listitem>
5503 * <listitem>an action with no parameter type and boolean state</listitem>
5504 * <listitem>an action with string parameter type and string state</listitem>
5507 * <formalpara><title>Stateless</title>
5509 * A stateless action typically corresponds to an ordinary menu item.
5512 * Selecting such a menu item will activate the action (with no parameter).
5516 * <formalpara><title>Boolean State</title>
5518 * An action with a boolean state will most typically be used with a "toggle"
5519 * or "switch" menu item. The state can be set directly, but activating the
5520 * action (with no parameter) results in the state being toggled.
5523 * Selecting a toggle menu item will activate the action. The menu item should
5524 * be rendered as "checked" when the state is true.
5528 * <formalpara><title>String Parameter and State</title>
5530 * Actions with string parameters and state will most typically be used to
5531 * represent an enumerated choice over the items available for a group of
5532 * radio menu items. Activating the action with a string parameter is
5533 * equivalent to setting that parameter as the state.
5536 * Radio menu items, in addition to being associated with the action, will
5537 * have a target value. Selecting that menu item will result in activation
5538 * of the action with the target value as the parameter. The menu item should
5539 * be rendered as "selected" when the state of the action is equal to the
5540 * target value of the menu item.
5548 * @short_description: Mount management
5549 * @include: gio/gio.h
5550 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
5552 * The #GMount interface represents user-visible mounts. Note, when
5553 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
5555 * #GMount is a "mounted" filesystem that you can access. Mounted is in
5556 * quotes because it's not the same as a unix mount, it might be a gvfs
5557 * mount, but you can still access the files on it if you use GIO. Might or
5558 * might not be related to a volume object.
5560 * Unmounting a #GMount instance is an asynchronous operation. For
5561 * more information about asynchronous operations, see #GAsyncResult
5562 * and #GSimpleAsyncResult. To unmount a #GMount instance, first call
5563 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
5564 * #GAsyncReadyCallback. The callback will be fired when the
5565 * operation has resolved (either with success or failure), and a
5566 * #GAsyncReady structure will be passed to the callback. That
5567 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
5568 * and the #GAsyncReady data to see if the operation was completed
5569 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
5570 * is called, then it will be filled with any error information.
5575 * SECTION:gmountoperation
5576 * @short_description: Object used for authentication and user interaction
5577 * @include: gio/gio.h
5579 * #GMountOperation provides a mechanism for interacting with the user.
5580 * It can be used for authenticating mountable operations, such as loop
5581 * mounting files, hard drive partitions or server locations. It can
5582 * also be used to ask the user questions or show a list of applications
5583 * preventing unmount or eject operations from completing.
5585 * Note that #GMountOperation is used for more than just #GMount
5586 * objects – for example it is also used in g_drive_start() and
5589 * Users should instantiate a subclass of this that implements all the
5590 * various callbacks to show the required dialogs, such as
5591 * #GtkMountOperation. If no user interaction is desired (for example
5592 * when automounting filesystems at login time), usually %NULL can be
5593 * passed, see each method taking a #GMountOperation for details.
5598 * SECTION:gnetworkaddress
5599 * @short_description: A GSocketConnectable for resolving hostnames
5600 * @include: gio/gio.h
5602 * #GNetworkAddress provides an easy way to resolve a hostname and
5603 * then attempt to connect to that host, handling the possibility of
5604 * multiple IP addresses and multiple address families.
5606 * See #GSocketConnectable for and example of using the connectable
5612 * SECTION:gnetworkmonitor
5613 * @title: GNetworkMonitor
5614 * @short_description: Network status monitor
5615 * @include: gio/gio.h
5617 * #GNetworkMonitor provides an easy-to-use cross-platform API
5618 * for monitoring network connectivity. On Linux, the implementation
5619 * is based on the kernel's netlink interface.
5624 * SECTION:gnetworkservice
5625 * @short_description: A GSocketConnectable for resolving SRV records
5626 * @include: gio/gio.h
5628 * Like #GNetworkAddress does with hostnames, #GNetworkService
5629 * provides an easy way to resolve a SRV record, and then attempt to
5630 * connect to one of the hosts that implements that service, handling
5631 * service priority/weighting, multiple IP addresses, and multiple
5634 * See #GSrvTarget for more information about SRV records, and see
5635 * #GSocketConnectable for and example of using the connectable
5641 * SECTION:goutputstream
5642 * @short_description: Base class for implementing streaming output
5643 * @include: gio/gio.h
5645 * #GOutputStream has functions to write to a stream (g_output_stream_write()),
5646 * to close a stream (g_output_stream_close()) and to flush pending writes
5647 * (g_output_stream_flush()).
5649 * To copy the content of an input stream to an output stream without
5650 * manually handling the reads and writes, use g_output_stream_splice().
5652 * All of these functions have async variants too.
5657 * SECTION:gpermission
5658 * @title: GPermission
5659 * @short_description: An object representing the permission to perform a certain action
5661 * A #GPermission represents the status of the caller's permission to
5662 * perform a certain action.
5664 * You can query if the action is currently allowed and if it is
5665 * possible to acquire the permission so that the action will be allowed
5668 * There is also an API to actually acquire the permission and one to
5671 * As an example, a #GPermission might represent the ability for the
5672 * user to write to a #GSettings object. This #GPermission object could
5673 * then be used to decide if it is appropriate to show a "Click here to
5674 * unlock" button in a dialog and to provide the mechanism to invoke
5675 * when that button is clicked.
5680 * SECTION:gpollableinputstream
5681 * @short_description: Interface for pollable input streams
5682 * @include: gio/gio.h
5683 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
5685 * #GPollableInputStream is implemented by #GInputStreams that
5686 * can be polled for readiness to read. This can be used when
5687 * interfacing with a non-GIO API that expects
5688 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
5695 * SECTION:gpollableoutputstream
5696 * @short_description: Interface for pollable output streams
5697 * @include: gio/gio.h
5698 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
5700 * #GPollableOutputStream is implemented by #GOutputStreams that
5701 * can be polled for readiness to write. This can be used when
5702 * interfacing with a non-GIO API that expects
5703 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
5710 * SECTION:gpollableutils
5711 * @short_description: #GPollableInputStream / #GPollableOutputStream utilities
5712 * @include: gio/gio.h
5714 * Utility functions for #GPollableInputStream and
5715 * #GPollableOutputStream implementations.
5721 * @short_description: Interface for proxy handling
5723 * A #GProxy handles connecting to a remote host via a given type of
5724 * proxy server. It is implemented by the 'gio-proxy' extension point.
5725 * The extensions are named after their proxy protocol name. As an
5726 * example, a SOCKS5 proxy implementation can be retrieved with the
5727 * name 'socks5' using the function
5728 * g_io_extension_point_get_extension_by_name().
5735 * SECTION:gproxyaddress
5736 * @short_description: An internet address with proxy information
5738 * Support for proxied #GInetSocketAddress.
5743 * SECTION:gproxyresolver
5744 * @short_description: Asynchronous and cancellable network proxy resolver
5745 * @include: gio/gio.h
5747 * #GProxyResolver provides synchronous and asynchronous network proxy
5748 * resolution. #GProxyResolver is used within #GSocketClient through
5749 * the method g_socket_connectable_proxy_enumerate().
5754 * SECTION:gremoteactiongroup
5755 * @title: GRemoteActionGroup
5756 * @short_description: a #GActionGroup that interacts with other processes
5758 * The GRemoteActionGroup interface is implemented by #GActionGroup
5759 * instances that either transmit action invocations to other processes
5760 * or receive action invocations in the local process from other
5763 * The interface has <literal>_full</literal> variants of the two
5764 * methods on #GActionGroup used to activate actions:
5765 * g_action_group_activate_action() and
5766 * g_action_group_change_action_state(). These variants allow a
5767 * "platform data" #GVariant to be specified: a dictionary providing
5768 * context for the action invocation (for example: timestamps, startup
5769 * notification IDs, etc).
5771 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
5772 * mechanism to send platform data for action invocations over D-Bus.
5774 * Additionally, g_dbus_connection_export_action_group() will check if
5775 * the exported #GActionGroup implements #GRemoteActionGroup and use the
5776 * <literal>_full</literal> variants of the calls if available. This
5777 * provides a mechanism by which to receive platform data for action
5778 * invocations that arrive by way of D-Bus.
5786 * @short_description: Asynchronous and cancellable DNS resolver
5787 * @include: gio/gio.h
5789 * #GResolver provides cancellable synchronous and asynchronous DNS
5790 * resolution, for hostnames (g_resolver_lookup_by_address(),
5791 * g_resolver_lookup_by_name() and their async variants) and SRV
5792 * (service) records (g_resolver_lookup_service()).
5794 * #GNetworkAddress and #GNetworkService provide wrappers around
5795 * #GResolver functionality that also implement #GSocketConnectable,
5796 * making it easy to connect to a remote host/service.
5802 * @short_description: Resource framework
5803 * @include: gio/gio.h
5805 * Applications and libraries often contain binary or textual data that is really part of the
5806 * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
5807 * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
5808 * manually included as literal strings in the code.
5810 * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program
5811 * provide a convenient and efficient alternative to this which has some nice properties. You
5812 * maintain the files as normal files, so its easy to edit them, but during the build the files
5813 * are combined into a binary bundle that is linked into the executable. This means that loading
5814 * the resource files are efficient (as they are already in memory, shared with other instances) and
5815 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
5816 * also makes it easier to create relocatable applications.
5818 * Resource files can also be marked as compressed. Such files will be included in the resource bundle
5819 * in a compressed form, but will be automatically uncompressed when the resource is used. This
5820 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
5822 * Resource files can also be marked to be preprocessed, by setting the value of the
5823 * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
5824 * The only options currently supported are:
5826 * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip
5827 * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
5828 * environment variable must be set to the full path to the xmllint executable, or xmllint
5829 * must be in the PATH; otherwise the preprocessing step is skipped.
5831 * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert
5832 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
5833 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
5834 * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be
5835 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
5838 * Resource bundles are created by the <link linkend="glib-compile-resources">glib-compile-resources</link> program
5839 * which takes an xml file that describes the bundle, and a set of files that the xml references. These
5840 * are combined into a binary resource bundle.
5842 * <example id="resource-example"><title>Example resource description</title>
5843 * <programlisting><![CDATA[
5844 * <?xml version="1.0" encoding="UTF-8"?>
5846 * <gresource prefix="/org/gtk/Example">
5847 * <file>data/splashscreen.png</file>
5848 * <file compressed="true">dialog.ui</file>
5849 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
5852 * ]]></programlisting></example>
5854 * This will create a resource bundle with the following files:
5855 * <programlisting><![CDATA[
5856 * /org/gtk/Example/data/splashscreen.png
5857 * /org/gtk/Example/dialog.ui
5858 * /org/gtk/Example/menumarkup.xml
5859 * ]]></programlisting>
5861 * Note that all resources in the process share the same namespace, so use java-style
5862 * path prefixes (like in the above example) to avoid conflicts.
5864 * You can then use <link linkend="glib-compile-resources">glib-compile-resources</link> to compile the xml to a
5865 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
5866 * --generate-header arguments to create a source file and header to link directly into your application.
5868 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
5869 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
5870 * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
5871 * the resource data.
5873 * There are two forms of the generated source, the default version uses the compiler support for constructor
5874 * and destructor functions (where available) to automatically create and register the #GResource on startup
5875 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
5876 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
5877 * even on the minor ones where this is not available. (Constructor support is available for at least Win32, MacOS and Linux.)
5879 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
5880 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
5881 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
5882 * is for your own resources, and resource data is often used once, during parsing, and then released.
5890 * @short_description: Stream seeking interface
5891 * @include: gio/gio.h
5892 * @see_also: #GInputStream, #GOutputStream
5894 * #GSeekable is implemented by streams (implementations of
5895 * #GInputStream or #GOutputStream) that support seeking.
5901 * @short_description: High-level API for application settings
5903 * The #GSettings class provides a convenient API for storing and retrieving
5904 * application settings.
5906 * Reads and writes can be considered to be non-blocking. Reading
5907 * settings with #GSettings is typically extremely fast: on
5908 * approximately the same order of magnitude (but slower than) a
5909 * #GHashTable lookup. Writing settings is also extremely fast in terms
5910 * of time to return to your application, but can be extremely expensive
5911 * for other threads and other processes. Many settings backends
5912 * (including dconf) have lazy initialisation which means in the common
5913 * case of the user using their computer without modifying any settings
5914 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
5915 * even need to be started in this case. For this reason, you should
5916 * only ever modify #GSettings keys in response to explicit user action.
5917 * Particular care should be paid to ensure that modifications are not
5918 * made during startup -- for example, when setting the initial value
5919 * of preferences widgets. The built-in g_settings_bind() functionality
5920 * is careful not to write settings in response to notify signals as a
5921 * result of modifications that it makes to widgets.
5923 * When creating a GSettings instance, you have to specify a schema
5924 * that describes the keys in your settings and their types and default
5925 * values, as well as some other information.
5927 * Normally, a schema has as fixed path that determines where the settings
5928 * are stored in the conceptual global tree of settings. However, schemas
5929 * can also be 'relocatable', i.e. not equipped with a fixed path. This is
5930 * useful e.g. when the schema describes an 'account', and you want to be
5931 * able to store a arbitrary number of accounts.
5933 * Paths must start with and end with a forward slash character ('/')
5934 * and must not contain two sequential slash characters. Paths should
5935 * be chosen based on a domain name associated with the program or
5936 * library to which the settings belong. Examples of paths are
5937 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
5938 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
5939 * they often did in GConf.
5941 * Unlike other configuration systems (like GConf), GSettings does not
5942 * restrict keys to basic types like strings and numbers. GSettings stores
5943 * values as #GVariant, and allows any #GVariantType for keys. Key names
5944 * are restricted to lowercase characters, numbers and '-'. Furthermore,
5945 * the names must begin with a lowercase character, must not end
5946 * with a '-', and must not contain consecutive dashes.
5948 * Similar to GConf, the default values in GSettings schemas can be
5949 * localized, but the localized values are stored in gettext catalogs
5950 * and looked up with the domain that is specified in the
5951 * <tag class="attribute">gettext-domain</tag> attribute of the
5952 * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
5953 * elements and the category that is specified in the l10n attribute of the
5954 * <tag class="starttag">key</tag> element.
5956 * GSettings uses schemas in a compact binary form that is created
5957 * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
5958 * utility. The input is a schema description in an XML format that can be
5959 * described by the following DTD:
5960 * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
5962 * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
5964 * At runtime, schemas are identified by their id (as specified
5965 * in the <tag class="attribute">id</tag> attribute of the
5966 * <tag class="starttag">schema</tag> element). The
5967 * convention for schema ids is to use a dotted name, similar in
5968 * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
5969 * if the settings are for a specific service that owns a D-Bus bus name,
5970 * the D-Bus bus name and schema id should match. For schemas which deal
5971 * with settings not associated with one named application, the id should
5972 * not use StudlyCaps, e.g. "org.gnome.font-rendering".
5974 * In addition to #GVariant types, keys can have types that have enumerated
5975 * types. These can be described by a <tag class="starttag">choice</tag>,
5976 * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
5977 * <xref linkend="schema-enumerated"/>. The underlying type of
5978 * such a key is string, but you can use g_settings_get_enum(),
5979 * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
5980 * access the numeric values corresponding to the string value of enum
5983 * <example id="schema-default-values"><title>Default values</title>
5984 * <programlisting><![CDATA[
5986 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
5988 * <key name="greeting" type="s">
5989 * <default l10n="messages">"Hello, earthlings"</default>
5990 * <summary>A greeting</summary>
5992 * Greeting of the invading martians
5996 * <key name="box" type="(ii)">
5997 * <default>(20,30)</default>
6002 * ]]></programlisting></example>
6004 * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
6005 * <programlisting><![CDATA[
6008 * <enum id="org.gtk.Test.myenum">
6009 * <value nick="first" value="1"/>
6010 * <value nick="second" value="2"/>
6013 * <flags id="org.gtk.Test.myflags">
6014 * <value nick="flag1" value="1"/>
6015 * <value nick="flag2" value="2"/>
6016 * <value nick="flag3" value="4"/>
6019 * <schema id="org.gtk.Test">
6021 * <key name="key-with-range" type="i">
6022 * <range min="1" max="100"/>
6023 * <default>10</default>
6026 * <key name="key-with-choices" type="s">
6028 * <choice value='Elisabeth'/>
6029 * <choice value='Annabeth'/>
6030 * <choice value='Joe'/>
6033 * <alias value='Anna' target='Annabeth'/>
6034 * <alias value='Beth' target='Elisabeth'/>
6036 * <default>'Joe'</default>
6039 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
6040 * <default>'first'</default>
6043 * <key name='flags-key' flags='org.gtk.Test.myflags'>
6044 * <default>["flag1",flag2"]</default>
6048 * ]]></programlisting></example>
6051 * <title>Vendor overrides</title>
6053 * Default values are defined in the schemas that get installed by
6054 * an application. Sometimes, it is necessary for a vendor or distributor
6055 * to adjust these defaults. Since patching the XML source for the schema
6056 * is inconvenient and error-prone,
6057 * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
6058 * so-called 'vendor override' files. These are keyfiles in the same
6059 * directory as the XML schema sources which can override default values.
6060 * The schema id serves as the group name in the key file, and the values
6061 * are expected in serialized GVariant form, as in the following example:
6062 * <informalexample><programlisting>
6066 * </programlisting></informalexample>
6069 * glib-compile-schemas expects schema files to have the extension
6070 * <filename>.gschema.override</filename>
6075 * <title>Binding</title>
6077 * A very convenient feature of GSettings lets you bind #GObject properties
6078 * directly to settings, using g_settings_bind(). Once a GObject property
6079 * has been bound to a setting, changes on either side are automatically
6080 * propagated to the other side. GSettings handles details like
6081 * mapping between GObject and GVariant types, and preventing infinite
6085 * This makes it very easy to hook up a preferences dialog to the
6086 * underlying settings. To make this even more convenient, GSettings
6087 * looks for a boolean property with the name "sensitivity" and
6088 * automatically binds it to the writability of the bound setting.
6089 * If this 'magic' gets in the way, it can be suppressed with the
6090 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
6097 * SECTION:gsettingsbackend
6098 * @title: GSettingsBackend
6099 * @short_description: Interface for settings backend implementations
6100 * @include: gio/gsettingsbackend.h
6101 * @see_also: #GSettings, #GIOExtensionPoint
6103 * The #GSettingsBackend interface defines a generic interface for
6104 * non-strictly-typed data that is stored in a hierarchy. To implement
6105 * an alternative storage backend for #GSettings, you need to implement
6106 * the #GSettingsBackend interface and then make it implement the
6107 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
6109 * The interface defines methods for reading and writing values, a
6110 * method for determining if writing of certain values will fail
6111 * (lockdown) and a change notification mechanism.
6113 * The semantics of the interface are very precisely defined and
6114 * implementations must carefully adhere to the expectations of
6115 * callers that are documented on each of the interface methods.
6117 * Some of the GSettingsBackend functions accept or return a #GTree.
6118 * These trees always have strings as keys and #GVariant as values.
6119 * g_settings_backend_create_tree() is a convenience function to create
6123 * The #GSettingsBackend API is exported to allow third-party
6124 * implementations, but does not carry the same stability guarantees
6125 * as the public GIO API. For this reason, you have to define the
6126 * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
6127 * <filename>gio/gsettingsbackend.h</filename>
6133 * SECTION:gsettingsschema
6134 * @short_description: introspecting and controlling the loading of GSettings schemas
6136 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
6137 * mechanism for advanced control over the loading of schemas and a
6138 * mechanism for introspecting their content.
6140 * Plugin loading systems that wish to provide plugins a way to access
6141 * settings face the problem of how to make the schemas for these
6142 * settings visible to GSettings. Typically, a plugin will want to ship
6143 * the schema along with itself and it won't be installed into the
6144 * standard system directories for schemas.
6146 * #GSettingsSchemaSource provides a mechanism for dealing with this by
6147 * allowing the creation of a new 'schema source' from which schemas can
6148 * be acquired. This schema source can then become part of the metadata
6149 * associated with the plugin and queried whenever the plugin requires
6150 * access to some settings.
6152 * Consider the following example:
6158 * GSettingsSchemaSource *schema_source;
6163 * initialise_plugin (const gchar *dir)
6169 * plugin->schema_source =
6170 * g_settings_new_schema_source_from_directory (dir,
6171 * g_settings_schema_source_get_default (), FALSE, NULL);
6181 * plugin_get_settings (Plugin *plugin,
6182 * const gchar *schema_id)
6184 * GSettingsSchema *schema;
6186 * if (schema_id == NULL)
6187 * schema_id = plugin->identifier;
6189 * schema = g_settings_schema_source_lookup (plugin->schema_source,
6190 * schema_id, FALSE);
6192 * if (schema == NULL)
6194 * ... disable the plugin or abort, etc ...
6197 * return g_settings_new_full (schema, NULL, NULL);
6201 * The code above shows how hooks should be added to the code that
6202 * initialises (or enables) the plugin to create the schema source and
6203 * how an API can be added to the plugin system to provide a convenient
6204 * way for the plugin to access its settings, using the schemas that it
6207 * From the standpoint of the plugin, it would need to ensure that it
6208 * ships a gschemas.compiled file as part of itself, and then simply do
6213 * GSettings *settings;
6216 * settings = plugin_get_settings (self, NULL);
6217 * some_value = g_settings_get_int (settings, "some-value");
6222 * It's also possible that the plugin system expects the schema source
6223 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
6224 * In that case, the plugin loading system must compile the schemas for
6225 * itself before attempting to create the settings source.
6232 * SECTION:gsimpleaction
6233 * @title: GSimpleAction
6234 * @short_description: A simple GAction implementation
6236 * A #GSimpleAction is the obvious simple implementation of the #GAction
6237 * interface. This is the easiest way to create an action for purposes of
6238 * adding it to a #GSimpleActionGroup.
6240 * See also #GtkAction.
6245 * SECTION:gsimpleactiongroup
6246 * @title: GSimpleActionGroup
6247 * @short_description: A simple GActionGroup implementation
6249 * #GSimpleActionGroup is a hash table filled with #GAction objects,
6250 * implementing the #GActionGroup and #GActionMap interfaces.
6255 * SECTION:gsimpleasyncresult
6256 * @short_description: Simple asynchronous results implementation
6257 * @include: gio/gio.h
6258 * @see_also: #GAsyncResult
6261 * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
6262 * #GTask, which provides a simpler API.
6265 * #GSimpleAsyncResult implements #GAsyncResult.
6267 * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
6268 * reporting, operation cancellation and the final state of an operation,
6269 * completely transparent to the application. Results can be returned
6270 * as a pointer e.g. for functions that return data that is collected
6271 * asynchronously, a boolean value for checking the success or failure
6272 * of an operation, or a #gssize for operations which return the number
6273 * of bytes modified by the operation; all of the simple return cases
6276 * Most of the time, an application will not need to know of the details
6277 * of this API; it is handled transparently, and any necessary operations
6278 * are handled by #GAsyncResult's interface. However, if implementing a
6279 * new GIO module, for writing language bindings, or for complex
6280 * applications that need better control of how asynchronous operations
6281 * are completed, it is important to understand this functionality.
6283 * GSimpleAsyncResults are tagged with the calling function to ensure
6284 * that asynchronous functions and their finishing functions are used
6285 * together correctly.
6287 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
6288 * If the result needs to be created for a #GError, use
6289 * g_simple_async_result_new_from_error() or
6290 * g_simple_async_result_new_take_error(). If a #GError is not available
6291 * (e.g. the asynchronous operation's doesn't take a #GError argument),
6292 * but the result still needs to be created for an error condition, use
6293 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
6294 * if your application or binding requires passing a variable argument list
6295 * directly), and the error can then be propagated through the use of
6296 * g_simple_async_result_propagate_error().
6298 * An asynchronous operation can be made to ignore a cancellation event by
6299 * calling g_simple_async_result_set_handle_cancellation() with a
6300 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
6301 * operations that are dangerous to cancel, such as close (which would
6302 * cause a leak if cancelled before being run).
6304 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
6305 * or it can use #GThread<!-- -->s.
6306 * g_simple_async_result_complete() will finish an I/O task directly
6307 * from the point where it is called. g_simple_async_result_complete_in_idle()
6308 * will finish it from an idle handler in the <link
6309 * linkend="g-main-context-push-thread-default">thread-default main
6310 * context</link>. g_simple_async_result_run_in_thread() will run the
6311 * job in a separate thread and then deliver the result to the
6312 * thread-default main context.
6314 * To set the results of an asynchronous function,
6315 * g_simple_async_result_set_op_res_gpointer(),
6316 * g_simple_async_result_set_op_res_gboolean(), and
6317 * g_simple_async_result_set_op_res_gssize()
6318 * are provided, setting the operation's result to a gpointer, gboolean, or
6319 * gssize, respectively.
6321 * Likewise, to get the result of an asynchronous function,
6322 * g_simple_async_result_get_op_res_gpointer(),
6323 * g_simple_async_result_get_op_res_gboolean(), and
6324 * g_simple_async_result_get_op_res_gssize() are
6325 * provided, getting the operation's result as a gpointer, gboolean, and
6326 * gssize, respectively.
6328 * For the details of the requirements implementations must respect, see
6329 * #GAsyncResult. A typical implementation of an asynchronous operation
6330 * using GSimpleAsyncResult looks something like this:
6334 * baked_cb (Cake *cake,
6335 * gpointer user_data)
6337 * /* In this example, this callback is not given a reference to the cake, so
6338 * * the GSimpleAsyncResult has to take a reference to it.
6340 * GSimpleAsyncResult *result = user_data;
6343 * g_simple_async_result_set_error (result,
6345 * BAKER_ERROR_NO_FLOUR,
6346 * "Go to the supermarket");
6348 * g_simple_async_result_set_op_res_gpointer (result,
6349 * g_object_ref (cake),
6353 * /* In this example, we assume that baked_cb is called as a callback from
6354 * * the mainloop, so it's safe to complete the operation synchronously here.
6355 * * If, however, _baker_prepare_cake () might call its callback without
6356 * * first returning to the mainloop — inadvisable, but some APIs do so —
6357 * * we would need to use g_simple_async_result_complete_in_idle().
6359 * g_simple_async_result_complete (result);
6360 * g_object_unref (result);
6364 * baker_bake_cake_async (Baker *self,
6366 * GAsyncReadyCallback callback,
6367 * gpointer user_data)
6369 * GSimpleAsyncResult *simple;
6374 * g_simple_async_report_error_in_idle (G_OBJECT (self),
6378 * BAKER_ERROR_TOO_SMALL,
6379 * "%ucm radius cakes are silly",
6384 * simple = g_simple_async_result_new (G_OBJECT (self),
6387 * baker_bake_cake_async);
6388 * cake = _baker_get_cached_cake (self, radius);
6392 * g_simple_async_result_set_op_res_gpointer (simple,
6393 * g_object_ref (cake),
6395 * g_simple_async_result_complete_in_idle (simple);
6396 * g_object_unref (simple);
6397 * /* Drop the reference returned by _baker_get_cached_cake(); the
6398 * * GSimpleAsyncResult has taken its own reference.
6400 * g_object_unref (cake);
6404 * _baker_prepare_cake (self, radius, baked_cb, simple);
6408 * baker_bake_cake_finish (Baker *self,
6409 * GAsyncResult *result,
6412 * GSimpleAsyncResult *simple;
6415 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
6417 * baker_bake_cake_async),
6420 * simple = (GSimpleAsyncResult *) result;
6422 * if (g_simple_async_result_propagate_error (simple, error))
6425 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
6426 * return g_object_ref (cake);
6433 * SECTION:gsimplepermission
6434 * @title: GSimplePermission
6435 * @short_description: A GPermission that doesn't change value
6437 * #GSimplePermission is a trivial implementation of #GPermission that
6438 * represents a permission that is either always or never allowed. The
6439 * value is given at construction and doesn't change.
6441 * Calling request or release will result in errors.
6447 * @short_description: Low-level socket object
6448 * @include: gio/gio.h
6449 * @see_also: #GInitable
6451 * A #GSocket is a low-level networking primitive. It is a more or less
6452 * direct mapping of the BSD socket API in a portable GObject based API.
6453 * It supports both the UNIX socket implementations and winsock2 on Windows.
6455 * #GSocket is the platform independent base upon which the higher level
6456 * network primitives are based. Applications are not typically meant to
6457 * use it directly, but rather through classes like #GSocketClient,
6458 * #GSocketService and #GSocketConnection. However there may be cases where
6459 * direct use of #GSocket is useful.
6461 * #GSocket implements the #GInitable interface, so if it is manually constructed
6462 * by e.g. g_object_new() you must call g_initable_init() and check the
6463 * results before using the object. This is done automatically in
6464 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
6467 * Sockets operate in two general modes, blocking or non-blocking. When
6468 * in blocking mode all operations block until the requested operation
6469 * is finished or there is an error. In non-blocking mode all calls that
6470 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
6471 * To know when a call would successfully run you can call g_socket_condition_check(),
6472 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
6473 * attach it to a #GMainContext to get callbacks when I/O is possible.
6474 * Note that all sockets are always set to non blocking mode in the system, and
6475 * blocking mode is emulated in GSocket.
6477 * When working in non-blocking mode applications should always be able to
6478 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
6479 * function said that I/O was possible. This can easily happen in case
6480 * of a race condition in the application, but it can also happen for other
6481 * reasons. For instance, on Windows a socket is always seen as writable
6482 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
6484 * #GSocket<!-- -->s can be either connection oriented or datagram based.
6485 * For connection oriented types you must first establish a connection by
6486 * either connecting to an address or accepting a connection from another
6487 * address. For connectionless socket types the target/source address is
6488 * specified or received in each I/O operation.
6490 * All socket file descriptors are set to be close-on-exec.
6492 * Note that creating a #GSocket causes the signal %SIGPIPE to be
6493 * ignored for the remainder of the program. If you are writing a
6494 * command-line utility that uses #GSocket, you may need to take into
6495 * account the fact that your program will not automatically be killed
6496 * if it tries to write to %stdout after it has been closed.
6503 * SECTION:gsocketaddress
6504 * @short_description: Abstract base class representing endpoints for socket communication
6506 * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
6507 * in the BSD sockets API. This is an abstract class; use
6508 * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
6509 * for UNIX domain sockets.
6514 * SECTION:gsocketclient
6515 * @short_description: Helper for connecting to a network service
6516 * @include: gio/gio.h
6517 * @see_also: #GSocketConnection, #GSocketListener
6519 * #GSocketClient is a lightweight high-level utility class for connecting to
6520 * a network host using a connection oriented socket type.
6522 * You create a #GSocketClient object, set any options you want, and then
6523 * call a sync or async connect operation, which returns a #GSocketConnection
6524 * subclass on success.
6526 * The type of the #GSocketConnection object returned depends on the type of
6527 * the underlying socket that is in use. For instance, for a TCP/IP connection
6528 * it will be a #GTcpConnection.
6530 * As #GSocketClient is a lightweight object, you don't need to cache it. You
6531 * can just create a new one any time you need one.
6538 * SECTION:gsocketconnectable
6539 * @short_description: Interface for potential socket endpoints
6541 * Objects that describe one or more potential socket endpoints
6542 * implement #GSocketConnectable. Callers can then use
6543 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
6544 * to try out each socket address in turn until one succeeds, as shown
6545 * in the sample code below.
6548 * MyConnectionType *
6549 * connect_to_host (const char *hostname,
6551 * GCancellable *cancellable,
6554 * MyConnection *conn = NULL;
6555 * GSocketConnectable *addr;
6556 * GSocketAddressEnumerator *enumerator;
6557 * GSocketAddress *sockaddr;
6558 * GError *conn_error = NULL;
6560 * addr = g_network_address_new ("www.gnome.org", 80);
6561 * enumerator = g_socket_connectable_enumerate (addr);
6562 * g_object_unref (addr);
6564 * /<!-- -->* Try each sockaddr until we succeed. Record the first
6565 * * connection error, but not any further ones (since they'll probably
6566 * * be basically the same as the first).
6568 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
6570 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
6571 * g_object_unref (sockaddr);
6573 * g_object_unref (enumerator);
6579 * /<!-- -->* We couldn't connect to the first address, but we succeeded
6580 * * in connecting to a later address.
6582 * g_error_free (conn_error);
6588 * /<!-- -->* Either the initial lookup failed, or else the caller
6592 * g_error_free (conn_error);
6597 * g_error_propagate (error, conn_error);
6606 * SECTION:gsocketconnection
6607 * @short_description: A socket connection
6608 * @include: gio/gio.h
6609 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
6611 * #GSocketConnection is a #GIOStream for a connected socket. They
6612 * can be created either by #GSocketClient when connecting to a host,
6613 * or by #GSocketListener when accepting a new client.
6615 * The type of the #GSocketConnection object returned from these calls
6616 * depends on the type of the underlying socket that is in use. For
6617 * instance, for a TCP/IP connection it will be a #GTcpConnection.
6619 * Choosing what type of object to construct is done with the socket
6620 * connection factory, and it is possible for 3rd parties to register
6621 * custom socket connection types for specific combination of socket
6622 * family/type/protocol using g_socket_connection_factory_register_type().
6629 * SECTION:gsocketcontrolmessage
6630 * @title: GSocketControlMessage
6631 * @short_description: A GSocket control message
6632 * @see_also: #GSocket.
6634 * A #GSocketControlMessage is a special-purpose utility message that
6635 * can be sent to or received from a #GSocket. These types of
6636 * messages are often called "ancillary data".
6638 * The message can represent some sort of special instruction to or
6639 * information from the socket or can represent a special kind of
6640 * transfer to the peer (for example, sending a file description over
6643 * These messages are sent with g_socket_send_message() and received
6644 * with g_socket_receive_message().
6646 * To extend the set of control message that can be sent, subclass this
6647 * class and override the get_size, get_level, get_type and serialize
6650 * To extend the set of control messages that can be received, subclass
6651 * this class and implement the deserialize method. Also, make sure your
6652 * class is registered with the GType typesystem before calling
6653 * g_socket_receive_message() to read such a message.
6660 * SECTION:gsocketlistener
6661 * @title: GSocketListener
6662 * @short_description: Helper for accepting network client connections
6663 * @see_also: #GThreadedSocketService, #GSocketService.
6665 * A #GSocketListener is an object that keeps track of a set
6666 * of server sockets and helps you accept sockets from any of the
6667 * socket, either sync or async.
6669 * If you want to implement a network server, also look at #GSocketService
6670 * and #GThreadedSocketService which are subclass of #GSocketListener
6671 * that makes this even easier.
6678 * SECTION:gsocketservice
6679 * @title: GSocketService
6680 * @short_description: Make it easy to implement a network service
6681 * @see_also: #GThreadedSocketService, #GSocketListener.
6683 * A #GSocketService is an object that represents a service that
6684 * is provided to the network or over local sockets. When a new
6685 * connection is made to the service the #GSocketService::incoming
6686 * signal is emitted.
6688 * A #GSocketService is a subclass of #GSocketListener and you need
6689 * to add the addresses you want to accept connections on with the
6690 * #GSocketListener APIs.
6692 * There are two options for implementing a network service based on
6693 * #GSocketService. The first is to create the service using
6694 * g_socket_service_new() and to connect to the #GSocketService::incoming
6695 * signal. The second is to subclass #GSocketService and override the
6696 * default signal handler implementation.
6698 * In either case, the handler must immediately return, or else it
6699 * will block additional incoming connections from being serviced.
6700 * If you are interested in writing connection handlers that contain
6701 * blocking code then see #GThreadedSocketService.
6703 * The socket service runs on the main loop of the <link
6704 * linkend="g-main-context-push-thread-default-context">thread-default
6705 * context</link> of the thread it is created in, and is not
6706 * threadsafe in general. However, the calls to start and stop the
6707 * service are thread-safe so these can be used from threads that
6708 * handle incoming clients.
6715 * SECTION:gsrvtarget
6716 * @short_description: DNS SRV record target
6717 * @include: gio/gio.h
6719 * SRV (service) records are used by some network protocols to provide
6720 * service-specific aliasing and load-balancing. For example, XMPP
6721 * (Jabber) uses SRV records to locate the XMPP server for a domain;
6722 * rather than connecting directly to "example.com" or assuming a
6723 * specific server hostname like "xmpp.example.com", an XMPP client
6724 * would look up the "xmpp-client" SRV record for "example.com", and
6725 * then connect to whatever host was pointed to by that record.
6727 * You can use g_resolver_lookup_service() or
6728 * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
6729 * for a given service. However, if you are simply planning to connect
6730 * to the remote service, you can use #GNetworkService's
6731 * #GSocketConnectable interface and not need to worry about
6732 * #GSrvTarget at all.
6738 * @short_description: Cancellable synchronous or asynchronous task and result
6739 * @include: gio/gio.h
6740 * @see_also: #GAsyncResult
6743 * A #GTask represents and manages a cancellable "task".
6746 * <title>Asynchronous operations</title>
6748 * The most common usage of #GTask is as a #GAsyncResult, to
6749 * manage data during an asynchronous operation. You call
6750 * g_task_new() in the "start" method, followed by
6751 * g_task_set_task_data() and the like if you need to keep some
6752 * additional data associated with the task, and then pass the
6753 * task object around through your asynchronous operation.
6754 * Eventually, you will call a method such as
6755 * g_task_return_pointer() or g_task_return_error(), which will
6756 * save the value you give it and then invoke the task's callback
6757 * function (waiting until the next next iteration of the main
6758 * loop first, if necessary). The caller will pass the #GTask back
6759 * to the operation's finish function (as a #GAsyncResult), and
6760 * you can use g_task_propagate_pointer() or the like to extract
6763 * <example id="gtask-async"><title>GTask as a GAsyncResult</title>
6766 * CakeFrostingType frosting;
6771 * decoration_data_free (DecorationData *decoration)
6773 * g_free (decoration->message);
6774 * g_slice_free (DecorationData, decoration);
6778 * baked_cb (Cake *cake,
6779 * gpointer user_data)
6781 * GTask *task = user_data;
6782 * DecorationData *decoration = g_task_get_task_data (task);
6783 * GError *error = NULL;
6787 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
6788 * "Go to the supermarket");
6789 * g_object_unref (task);
6793 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
6795 * g_object_unref (cake);
6796 * /* g_task_return_error() takes ownership of error */
6797 * g_task_return_error (task, error);
6798 * g_object_unref (task);
6802 * g_task_return_pointer (result, cake, g_object_unref);
6803 * g_object_unref (task);
6807 * baker_bake_cake_async (Baker *self,
6809 * CakeFlavor flavor,
6810 * CakeFrostingType frosting,
6811 * const char *message,
6812 * GCancellable *cancellable,
6813 * GAsyncReadyCallback callback,
6814 * gpointer user_data)
6817 * DecorationData *decoration;
6820 * task = g_task_new (self, cancellable, callback, user_data);
6823 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
6824 * "%ucm radius cakes are silly",
6826 * g_object_unref (task);
6830 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
6833 * /* _baker_get_cached_cake() returns a reffed cake */
6834 * g_task_return_pointer (task, cake, g_object_unref);
6835 * g_object_unref (task);
6839 * decoration = g_slice_new (DecorationData);
6840 * decoration->frosting = frosting;
6841 * decoration->message = g_strdup (message);
6842 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
6844 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
6848 * baker_bake_cake_finish (Baker *self,
6849 * GAsyncResult *result,
6852 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
6854 * return g_task_propagate_pointer (G_TASK (result), error);
6860 * <title>Chained asynchronous operations</title>
6862 * #GTask also tries to simplify asynchronous operations that
6863 * internally chain together several smaller asynchronous
6864 * operations. g_task_get_cancellable(), g_task_get_context(), and
6865 * g_task_get_priority() allow you to get back the task's
6866 * #GCancellable, #GMainContext, and <link
6867 * linkend="io-priority">I/O priority</link> when starting a new
6868 * subtask, so you don't have to keep track of them yourself.
6869 * g_task_attach_source() simplifies the case of waiting for a
6870 * source to fire (automatically using the correct #GMainContext
6873 * <example id="gtask-chained"><title>Chained asynchronous operations</title>
6877 * CakeFrostingType frosting;
6882 * decoration_data_free (BakingData *bd)
6885 * g_object_unref (bd->cake);
6886 * g_free (bd->message);
6887 * g_slice_free (BakingData, bd);
6891 * decorated_cb (Cake *cake,
6892 * GAsyncResult *result,
6893 * gpointer user_data)
6895 * GTask *task = user_data;
6896 * GError *error = NULL;
6898 * if (!cake_decorate_finish (cake, result, &error))
6900 * g_object_unref (cake);
6901 * g_task_return_error (task, error);
6902 * g_object_unref (task);
6906 * /* baking_data_free() will drop its ref on the cake, so
6907 * * we have to take another here to give to the caller.
6909 * g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
6910 * g_object_unref (task);
6914 * decorator_ready (gpointer user_data)
6916 * GTask *task = user_data;
6917 * BakingData *bd = g_task_get_task_data (task);
6919 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
6920 * g_task_get_cancellable (task),
6921 * decorated_cb, task);
6925 * baked_cb (Cake *cake,
6926 * gpointer user_data)
6928 * GTask *task = user_data;
6929 * BakingData *bd = g_task_get_task_data (task);
6930 * GError *error = NULL;
6934 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
6935 * "Go to the supermarket");
6936 * g_object_unref (task);
6942 * /* Bail out now if the user has already cancelled */
6943 * if (g_task_return_error_if_cancelled (g_task_get_cancellable (task)))
6945 * g_object_unref (task);
6949 * if (cake_decorator_available (cake))
6950 * decorator_ready (task);
6955 * source = cake_decorator_wait_source_new (cake);
6956 * /* Attach @source to @task's GMainContext and have it call
6957 * * decorator_ready() when it is ready.
6959 * g_task_attach_source (task, source,
6960 * G_CALLBACK (decorator_ready));
6961 * g_source_unref (source);
6966 * baker_bake_cake_async (Baker *self,
6968 * CakeFlavor flavor,
6969 * CakeFrostingType frosting,
6970 * const char *message,
6972 * GCancellable *cancellable,
6973 * GAsyncReadyCallback callback,
6974 * gpointer user_data)
6979 * task = g_task_new (self, cancellable, callback, user_data);
6980 * g_task_set_priority (task, priority);
6982 * bd = g_slice_new0 (BakingData);
6983 * bd->frosting = frosting;
6984 * bd->message = g_strdup (message);
6985 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
6987 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
6991 * baker_bake_cake_finish (Baker *self,
6992 * GAsyncResult *result,
6995 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
6997 * return g_task_propagate_pointer (G_TASK (result), error);
7003 * <title>Asynchronous operations from synchronous ones</title>
7005 * You can use g_task_run_in_thread() to turn a synchronous
7006 * operation into an asynchronous one, by running it in a thread
7007 * which will then dispatch the result back to the caller's
7008 * #GMainContext when it completes.
7010 * <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title>
7014 * CakeFlavor flavor;
7015 * CakeFrostingType frosting;
7020 * cake_data_free (CakeData *cake_data)
7022 * g_free (cake_data->message);
7023 * g_slice_free (CakeData, cake_data);
7027 * bake_cake_thread (GTask *task,
7028 * gpointer source_object,
7029 * gpointer task_data,
7030 * GCancellable *cancellable)
7032 * Baker *self = source_object;
7033 * CakeData *cake_data = task_data;
7035 * GError *error = NULL;
7037 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7038 * cake_data->frosting, cake_data->message,
7039 * cancellable, &error);
7041 * g_task_return_pointer (task, cake, g_object_unref);
7043 * g_task_return_error (task, error);
7047 * baker_bake_cake_async (Baker *self,
7049 * CakeFlavor flavor,
7050 * CakeFrostingType frosting,
7051 * const char *message,
7052 * GCancellable *cancellable,
7053 * GAsyncReadyCallback callback,
7054 * gpointer user_data)
7056 * CakeData *cake_data;
7059 * cake_data = g_slice_new (CakeData);
7060 * cake_data->radius = radius;
7061 * cake_data->flavor = flavor;
7062 * cake_data->frosting = frosting;
7063 * cake_data->message = g_strdup (message);
7064 * task = g_task_new (self, cancellable, callback, user_data);
7065 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7066 * g_task_run_in_thread (task, bake_cake_thread);
7070 * baker_bake_cake_finish (Baker *self,
7071 * GAsyncResult *result,
7074 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7076 * return g_task_propagate_pointer (G_TASK (result), error);
7082 * <title>Adding cancellability to uncancellable tasks</title>
7084 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
7085 * can be used to turn an uncancellable operation into a
7086 * cancellable one. If you call g_task_set_return_on_cancel(),
7087 * passing %TRUE, then if the task's #GCancellable is cancelled,
7088 * it will return control back to the caller immediately, while
7089 * allowing the task thread to continue running in the background
7090 * (and simply discarding its result when it finally does finish).
7091 * Provided that the task thread is careful about how it uses
7092 * locks and other externally-visible resources, this allows you
7093 * to make "GLib-friendly" asynchronous and cancellable
7094 * synchronous variants of blocking APIs.
7096 * <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title>
7099 * bake_cake_thread (GTask *task,
7100 * gpointer source_object,
7101 * gpointer task_data,
7102 * GCancellable *cancellable)
7104 * Baker *self = source_object;
7105 * CakeData *cake_data = task_data;
7107 * GError *error = NULL;
7109 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7110 * cake_data->frosting, cake_data->message,
7114 * g_task_return_error (task, error);
7118 * /* If the task has already been cancelled, then we don't
7119 * * want to add the cake to the cake cache. Likewise, we don't
7120 * * want to have the task get cancelled in the middle of
7121 * * updating the cache. g_task_set_return_on_cancel() will
7122 * * return %TRUE here if it managed to disable return-on-cancel,
7123 * * or %FALSE if the task was cancelled before it could.
7125 * if (g_task_set_return_on_cancel (task, FALSE))
7127 * /* If the caller cancels at this point, their
7128 * * GAsyncReadyCallback won't be invoked until we return,
7129 * * so we don't have to worry that this code will run at
7130 * * the same time as that code does. But if there were
7131 * * other functions that might look at the cake cache,
7132 * * then we'd probably need a GMutex here as well.
7134 * baker_add_cake_to_cache (baker, cake);
7135 * g_task_return_pointer (task, cake, g_object_unref);
7140 * baker_bake_cake_async (Baker *self,
7142 * CakeFlavor flavor,
7143 * CakeFrostingType frosting,
7144 * const char *message,
7145 * GCancellable *cancellable,
7146 * GAsyncReadyCallback callback,
7147 * gpointer user_data)
7149 * CakeData *cake_data;
7152 * cake_data = g_slice_new (CakeData);
7155 * task = g_task_new (self, cancellable, callback, user_data);
7156 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7157 * g_task_set_return_on_cancel (task, TRUE);
7158 * g_task_run_in_thread (task, bake_cake_thread);
7162 * baker_bake_cake_sync (Baker *self,
7164 * CakeFlavor flavor,
7165 * CakeFrostingType frosting,
7166 * const char *message,
7167 * GCancellable *cancellable,
7170 * CakeData *cake_data;
7174 * cake_data = g_slice_new (CakeData);
7177 * task = g_task_new (self, cancellable, NULL, NULL);
7178 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7179 * g_task_set_return_on_cancel (task, TRUE);
7180 * g_task_run_in_thread_sync (task, bake_cake_thread);
7182 * cake = g_task_propagate_pointer (task, error);
7183 * g_object_unref (task);
7190 * <title>Porting from <literal>GSimpleAsyncResult</literal></title>
7192 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
7197 * You can save task-specific data with g_task_set_task_data(), and
7198 * retrieve it later with g_task_get_task_data(). This replaces the
7199 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
7200 * purpose with #GSimpleAsyncResult.
7201 * </para></listitem>
7203 * In addition to the task data, #GTask also keeps track of the
7204 * <link linkend="io-priority">priority</link>, #GCancellable, and
7205 * #GMainContext associated with the task, so tasks that consist of
7206 * a chain of simpler asynchronous operations will have easy access
7207 * to those values when starting each sub-task.
7208 * </para></listitem>
7210 * g_task_return_error_if_cancelled() provides simplified
7211 * handling for cancellation. In addition, cancellation
7212 * overrides any other #GTask return value by default, like
7213 * #GSimpleAsyncResult does when
7214 * g_simple_async_result_set_check_cancellable() is called.
7215 * (You can use g_task_set_check_cancellable() to turn off that
7216 * behavior.) On the other hand, g_task_run_in_thread()
7217 * guarantees that it will always run your
7218 * <literal>task_func</literal>, even if the task's #GCancellable
7219 * is already cancelled before the task gets a chance to run;
7220 * you can start your <literal>task_func</literal> with a
7221 * g_task_return_error_if_cancelled() check if you need the
7223 * </para></listitem>
7225 * The "return" methods (eg, g_task_return_pointer())
7226 * automatically cause the task to be "completed" as well, and
7227 * there is no need to worry about the "complete" vs "complete
7228 * in idle" distinction. (#GTask automatically figures out
7229 * whether the task's callback can be invoked directly, or
7230 * if it needs to be sent to another #GMainContext, or delayed
7231 * until the next iteration of the current #GMainContext.)
7232 * </para></listitem>
7234 * The "finish" functions for #GTask-based operations are generally
7235 * much simpler than #GSimpleAsyncResult ones, normally consisting
7236 * of only a single call to g_task_propagate_pointer() or the like.
7237 * Since g_task_propagate_pointer() "steals" the return value from
7238 * the #GTask, it is not necessary to juggle pointers around to
7239 * prevent it from being freed twice.
7240 * </para></listitem>
7242 * With #GSimpleAsyncResult, it was common to call
7243 * g_simple_async_result_propagate_error() from the
7244 * <literal>_finish()</literal> wrapper function, and have
7245 * virtual method implementations only deal with successful
7246 * returns. This behavior is deprecated, because it makes it
7247 * difficult for a subclass to chain to a parent class's async
7248 * methods. Instead, the wrapper function should just be a
7249 * simple wrapper, and the virtual method should call an
7250 * appropriate <literal>g_task_propagate_</literal> function.
7251 * Note that wrapper methods can now use
7252 * g_async_result_legacy_propagate_error() to do old-style
7253 * #GSimpleAsyncResult error-returning behavior, and
7254 * g_async_result_is_tagged() to check if a result is tagged as
7255 * having come from the <literal>_async()</literal> wrapper
7256 * function (for "short-circuit" results, such as when passing
7257 * 0 to g_input_stream_read_async()).
7258 * </para></listitem>
7265 * SECTION:gtcpconnection
7266 * @title: GTcpConnection
7267 * @short_description: A TCP GSocketConnection
7268 * @see_also: #GSocketConnection.
7270 * This is the subclass of #GSocketConnection that is created
7271 * for TCP/IP sockets.
7278 * SECTION:gtcpwrapperconnection
7279 * @title: GTcpWrapperConnection
7280 * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
7281 * @see_also: #GSocketConnection.
7283 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
7284 * based on a #GSocket, but which is not actually a
7285 * #GSocketConnection. This is used by #GSocketClient so that it can
7286 * always return a #GSocketConnection, even when the connection it has
7287 * actually created is not directly a #GSocketConnection.
7295 * @short_description: D-Bus testing helper
7296 * @include: gio/gio.h
7298 * A helper class for testing code which uses D-Bus without touching the user's
7304 * SECTION:gthemedicon
7305 * @short_description: Icon theming support
7306 * @include: gio/gio.h
7307 * @see_also: #GIcon, #GLoadableIcon
7309 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
7310 * #GThemedIcon contains a list of all of the icons present in an icon
7311 * theme, so that icons can be looked up quickly. #GThemedIcon does
7312 * not provide actual pixmaps for icons, just the icon names.
7313 * Ideally something like gtk_icon_theme_choose_icon() should be used to
7314 * resolve the list of names so that fallback icons work nicely with
7315 * themes that inherit other themes.
7320 * SECTION:gthreadedsocketservice
7321 * @title: GThreadedSocketService
7322 * @short_description: A threaded GSocketService
7323 * @see_also: #GSocketService.
7325 * A #GThreadedSocketService is a simple subclass of #GSocketService
7326 * that handles incoming connections by creating a worker thread and
7327 * dispatching the connection to it by emitting the
7328 * #GThreadedSocketService::run signal in the new thread.
7330 * The signal handler may perform blocking IO and need not return
7331 * until the connection is closed.
7333 * The service is implemented using a thread pool, so there is a
7334 * limited amount of threads available to serve incoming requests.
7335 * The service automatically stops the #GSocketService from accepting
7336 * new connections when all threads are busy.
7338 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
7339 * or subclass and override the default handler.
7345 * @title: TLS Overview
7346 * @short_description: TLS (aka SSL) support for GSocketConnection
7347 * @include: gio/gio.h
7349 * #GTlsConnection and related classes provide TLS (Transport Layer
7350 * Security, previously known as SSL, Secure Sockets Layer) support for
7351 * gio-based network streams.
7353 * In the simplest case, for a client connection, you can just set the
7354 * #GSocketClient:tls flag on a #GSocketClient, and then any
7355 * connections created by that client will have TLS negotiated
7356 * automatically, using appropriate default settings, and rejecting
7357 * any invalid or self-signed certificates (unless you change that
7358 * default by setting the #GSocketClient:tls-validation-flags
7359 * property). The returned object will be a #GTcpWrapperConnection,
7360 * which wraps the underlying #GTlsClientConnection.
7362 * For greater control, you can create your own #GTlsClientConnection,
7363 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
7364 * pollable input and output streams) and then connect to its signals,
7365 * such as #GTlsConnection::accept-certificate, before starting the
7368 * Server-side TLS is similar, using #GTlsServerConnection. At the
7369 * moment, there is no support for automatically wrapping server-side
7370 * connections in the way #GSocketClient does for client-side
7376 * SECTION:gtlsbackend
7377 * @title: GTlsBackend
7378 * @short_description: TLS backend implementation
7379 * @include: gio/gio.h
7386 * SECTION:gtlscertificate
7387 * @title: GTlsCertificate
7388 * @short_description: TLS certificate
7389 * @see_also: #GTlsConnection
7391 * A certificate used for TLS authentication and encryption.
7392 * This can represent either a certificate only (eg, the certificate
7393 * received by a client from a server), or the combination of
7394 * a certificate and a private key (which is needed when acting as a
7395 * #GTlsServerConnection).
7402 * SECTION:gtlsclientconnection
7403 * @short_description: TLS client-side connection
7404 * @include: gio/gio.h
7406 * #GTlsClientConnection is the client-side subclass of
7407 * #GTlsConnection, representing a client-side TLS connection.
7412 * SECTION:gtlsconnection
7413 * @short_description: TLS connection type
7414 * @include: gio/gio.h
7416 * #GTlsConnection is the base TLS connection class type, which wraps
7417 * a #GIOStream and provides TLS encryption on top of it. Its
7418 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
7419 * implement client-side and server-side TLS, respectively.
7426 * SECTION:gtlsdatabase
7427 * @short_description: TLS database type
7428 * @include: gio/gio.h
7430 * #GTlsDatabase is used to lookup certificates and other information
7431 * from a certificate or key store. It is an abstract base class which
7432 * TLS library specific subtypes override.
7434 * Most common client applications will not directly interact with
7435 * #GTlsDatabase. It is used internally by #GTlsConnection.
7442 * SECTION:gtlsfiledatabase
7443 * @short_description: TLS file based database type
7444 * @include: gio/gio.h
7446 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
7447 * their certificate information from a file. It is in interface which
7448 * TLS library specific subtypes implement.
7455 * SECTION:gtlsinteraction
7456 * @short_description: Interaction with the user during TLS operations.
7457 * @include: gio/gio.h
7459 * #GTlsInteraction provides a mechanism for the TLS connection and database
7460 * code to interact with the user. It can be used to ask the user for passwords.
7462 * To use a #GTlsInteraction with a TLS connection use
7463 * g_tls_connection_set_interaction().
7465 * Callers should instantiate a derived class that implements the various
7466 * interaction methods to show the required dialogs.
7468 * Callers should use the 'invoke' functions like
7469 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
7470 * functions make sure that the interaction is invoked in the main loop
7471 * and not in the current thread, if the current thread is not running the
7474 * Derived classes can choose to implement whichever interactions methods they'd
7475 * like to support by overriding those virtual methods in their class
7476 * initialization function. Any interactions not implemented will return
7477 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
7478 * it must also implement the corresponding finish method.
7483 * SECTION:gtlspassword
7484 * @title: GTlsPassword
7485 * @short_description: TLS Passwords for prompting
7486 * @include: gio/gio.h
7488 * Holds a password used in TLS.
7493 * SECTION:gtlsserverconnection
7494 * @short_description: TLS server-side connection
7495 * @include: gio/gio.h
7497 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
7498 * representing a server-side TLS connection.
7505 * SECTION:gunixconnection
7506 * @title: GUnixConnection
7507 * @short_description: A UNIX domain GSocketConnection
7508 * @include: gio/gunixconnection.h
7509 * @see_also: #GSocketConnection.
7511 * This is the subclass of #GSocketConnection that is created
7512 * for UNIX domain sockets.
7514 * It contains functions to do some of the UNIX socket specific
7515 * functionality like passing file descriptors.
7517 * Note that <filename><gio/gunixconnection.h></filename> belongs to
7518 * the UNIX-specific GIO interfaces, thus you have to use the
7519 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7526 * SECTION:gunixcredentialsmessage
7527 * @title: GUnixCredentialsMessage
7528 * @short_description: A GSocketControlMessage containing credentials
7529 * @include: gio/gunixcredentialsmessage.h
7530 * @see_also: #GUnixConnection, #GSocketControlMessage
7532 * This #GSocketControlMessage contains a #GCredentials instance. It
7533 * may be sent using g_socket_send_message() and received using
7534 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
7535 * %G_SOCKET_FAMILY_UNIX family).
7537 * For an easier way to send and receive credentials over
7538 * stream-oriented UNIX sockets, see
7539 * g_unix_connection_send_credentials() and
7540 * g_unix_connection_receive_credentials(). To receive credentials of
7541 * a foreign process connected to a socket, use
7542 * g_socket_get_credentials().
7547 * SECTION:gunixfdlist
7548 * @title: GUnixFDList
7549 * @short_description: An object containing a set of UNIX file descriptors
7550 * @include: gio/gunixfdlist.h
7551 * @see_also: #GUnixFDMessage
7553 * A #GUnixFDList contains a list of file descriptors. It owns the file
7554 * descriptors that it contains, closing them when finalized.
7556 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
7557 * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
7558 * and received using g_socket_receive_message().
7560 * Note that <filename><gio/gunixfdlist.h></filename> belongs to
7561 * the UNIX-specific GIO interfaces, thus you have to use the
7562 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7567 * SECTION:gunixfdmessage
7568 * @title: GUnixFDMessage
7569 * @short_description: A GSocketControlMessage containing a GUnixFDList
7570 * @include: gio/gunixfdmessage.h
7571 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
7573 * This #GSocketControlMessage contains a #GUnixFDList.
7574 * It may be sent using g_socket_send_message() and received using
7575 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
7576 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
7577 * between processes by the kernel.
7579 * For an easier way to send and receive file descriptors over
7580 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
7581 * g_unix_connection_receive_fd().
7583 * Note that <filename><gio/gunixfdmessage.h></filename> belongs to
7584 * the UNIX-specific GIO interfaces, thus you have to use the
7585 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7590 * SECTION:gunixinputstream
7591 * @short_description: Streaming input operations for UNIX file descriptors
7592 * @include: gio/gunixinputstream.h
7593 * @see_also: #GInputStream
7595 * #GUnixInputStream implements #GInputStream for reading from a UNIX
7596 * file descriptor, including asynchronous operations. (If the file
7597 * descriptor refers to a socket or pipe, this will use poll() to do
7598 * asynchronous I/O. If it refers to a regular file, it will fall back
7599 * to doing asynchronous I/O in another thread.)
7601 * Note that <filename><gio/gunixinputstream.h></filename> belongs
7602 * to the UNIX-specific GIO interfaces, thus you have to use the
7603 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7608 * SECTION:gunixmounts
7609 * @include: gio/gunixmounts.h
7610 * @short_description: UNIX mounts
7612 * Routines for managing mounted UNIX mount points and paths.
7614 * Note that <filename><gio/gunixmounts.h></filename> belongs to the
7615 * UNIX-specific GIO interfaces, thus you have to use the
7616 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7621 * SECTION:gunixoutputstream
7622 * @short_description: Streaming output operations for UNIX file descriptors
7623 * @include: gio/gunixoutputstream.h
7624 * @see_also: #GOutputStream
7626 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
7627 * file descriptor, including asynchronous operations. (If the file
7628 * descriptor refers to a socket or pipe, this will use poll() to do
7629 * asynchronous I/O. If it refers to a regular file, it will fall back
7630 * to doing asynchronous I/O in another thread.)
7632 * Note that <filename><gio/gunixoutputstream.h></filename> belongs
7633 * to the UNIX-specific GIO interfaces, thus you have to use the
7634 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7639 * SECTION:gunixsocketaddress
7640 * @short_description: UNIX GSocketAddress
7641 * @include: gio/gunixsocketaddress.h
7643 * Support for UNIX-domain (also known as local) sockets.
7645 * UNIX domain sockets are generally visible in the filesystem.
7646 * However, some systems support abstract socket names which are not
7647 * visible in the filesystem and not affected by the filesystem
7648 * permissions, visibility, etc. Currently this is only supported
7649 * under Linux. If you attempt to use abstract sockets on other
7650 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
7651 * errors. You can use g_unix_socket_address_abstract_names_supported()
7652 * to see if abstract names are supported.
7654 * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to
7655 * the UNIX-specific GIO interfaces, thus you have to use the
7656 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
7662 * @short_description: Virtual File System
7663 * @include: gio/gio.h
7665 * Entry point for using GIO functionality.
7671 * @short_description: Volume management
7672 * @include: gio/gio.h
7674 * The #GVolume interface represents user-visible objects that can be
7675 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
7676 * equivalent of #GnomeVFSDrive.
7678 * Mounting a #GVolume instance is an asynchronous operation. For more
7679 * information about asynchronous operations, see #GAsyncResult and
7680 * #GSimpleAsyncResult. To mount a #GVolume, first call
7681 * g_volume_mount() with (at least) the #GVolume instance, optionally
7682 * a #GMountOperation object and a #GAsyncReadyCallback.
7684 * Typically, one will only want to pass %NULL for the
7685 * #GMountOperation if automounting all volumes when a desktop session
7686 * starts since it's not desirable to put up a lot of dialogs asking
7689 * The callback will be fired when the operation has resolved (either
7690 * with success or failure), and a #GAsyncReady structure will be
7691 * passed to the callback. That callback should then call
7692 * g_volume_mount_finish() with the #GVolume instance and the
7693 * #GAsyncReady data to see if the operation was completed
7694 * successfully. If an @error is present when g_volume_mount_finish()
7695 * is called, then it will be filled with any error information.
7697 * <para id="volume-identifier">
7698 * It is sometimes necessary to directly access the underlying
7699 * operating system object behind a volume (e.g. for passing a volume
7700 * to an application via the commandline). For this purpose, GIO
7701 * allows to obtain an 'identifier' for the volume. There can be
7702 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
7703 * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
7704 * uuids. GIO uses predefind strings as names for the different kinds
7705 * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
7706 * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
7707 * to obtain an identifier for a volume.
7710 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
7711 * when the gvfs hal volume monitor is in use. Other volume monitors
7712 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
7713 * identifier, which can be used to obtain a hal device by means of
7714 * libhal_manager_find_device_string_match().
7719 * SECTION:gvolumemonitor
7720 * @short_description: Volume Monitor
7721 * @include: gio/gio.h
7722 * @see_also: #GFileMonitor
7724 * #GVolumeMonitor is for listing the user interesting devices and volumes
7725 * on the computer. In other words, what a file selector or file manager
7726 * would show in a sidebar.
7728 * #GVolumeMonitor is not <link
7729 * linkend="g-main-context-push-thread-default">thread-default-context
7730 * aware</link>, and so should not be used other than from the main
7731 * thread, with no thread-default-context active.
7736 * SECTION:gwin32inputstream
7737 * @short_description: Streaming input operations for Windows file handles
7738 * @include: gio/gwin32inputstream.h
7739 * @see_also: #GInputStream
7741 * #GWin32InputStream implements #GInputStream for reading from a
7742 * Windows file handle.
7744 * Note that <filename><gio/gwin32inputstream.h></filename> belongs
7745 * to the Windows-specific GIO interfaces, thus you have to use the
7746 * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
7751 * SECTION:gwin32outputstream
7752 * @short_description: Streaming output operations for Windows file handles
7753 * @include: gio/gwin32outputstream.h
7754 * @see_also: #GOutputStream
7756 * #GWin32OutputStream implements #GOutputStream for writing to a
7757 * Windows file handle.
7759 * Note that <filename><gio/gwin32outputstream.h></filename> belongs
7760 * to the Windows-specific GIO interfaces, thus you have to use the
7761 * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
7766 * SECTION:gzcompressor
7767 * @short_description: Zlib compressor
7768 * @include: gio/gio.h
7770 * #GZlibCompressor is an implementation of #GConverter that
7771 * compresses data using zlib.
7776 * SECTION:gzdecompressor
7777 * @short_description: Zlib decompressor
7778 * @include: gio/gio.h
7780 * #GZlibDecompressor is an implementation of #GConverter that
7781 * decompresses data compressed with zlib.
7786 * _GFreedesktopDBus:
7788 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
7793 * _GFreedesktopDBus::handle-add-match:
7794 * @object: A #_GFreedesktopDBus.
7795 * @invocation: A #GDBusMethodInvocation.
7796 * @arg_rule: Argument passed by remote caller.
7798 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method.
7800 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_add_match() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7802 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7807 * _GFreedesktopDBus::handle-get-connection-selinux-security-context:
7808 * @object: A #_GFreedesktopDBus.
7809 * @invocation: A #GDBusMethodInvocation.
7810 * @arg_name: Argument passed by remote caller.
7812 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method.
7814 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_selinux_security_context() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7816 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7821 * _GFreedesktopDBus::handle-get-connection-unix-process-id:
7822 * @object: A #_GFreedesktopDBus.
7823 * @invocation: A #GDBusMethodInvocation.
7824 * @arg_name: Argument passed by remote caller.
7826 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method.
7828 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_unix_process_id() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7830 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7835 * _GFreedesktopDBus::handle-get-connection-unix-user:
7836 * @object: A #_GFreedesktopDBus.
7837 * @invocation: A #GDBusMethodInvocation.
7838 * @arg_name: Argument passed by remote caller.
7840 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method.
7842 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_unix_user() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7844 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7849 * _GFreedesktopDBus::handle-get-id:
7850 * @object: A #_GFreedesktopDBus.
7851 * @invocation: A #GDBusMethodInvocation.
7853 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method.
7855 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_id() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7857 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7862 * _GFreedesktopDBus::handle-get-name-owner:
7863 * @object: A #_GFreedesktopDBus.
7864 * @invocation: A #GDBusMethodInvocation.
7865 * @arg_name: Argument passed by remote caller.
7867 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method.
7869 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_name_owner() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7871 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7876 * _GFreedesktopDBus::handle-hello:
7877 * @object: A #_GFreedesktopDBus.
7878 * @invocation: A #GDBusMethodInvocation.
7880 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method.
7882 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_hello() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7884 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7889 * _GFreedesktopDBus::handle-list-activatable-names:
7890 * @object: A #_GFreedesktopDBus.
7891 * @invocation: A #GDBusMethodInvocation.
7893 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method.
7895 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_activatable_names() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7897 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7902 * _GFreedesktopDBus::handle-list-names:
7903 * @object: A #_GFreedesktopDBus.
7904 * @invocation: A #GDBusMethodInvocation.
7906 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method.
7908 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_names() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7910 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7915 * _GFreedesktopDBus::handle-list-queued-owners:
7916 * @object: A #_GFreedesktopDBus.
7917 * @invocation: A #GDBusMethodInvocation.
7918 * @arg_name: Argument passed by remote caller.
7920 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method.
7922 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_queued_owners() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7924 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7929 * _GFreedesktopDBus::handle-name-has-owner:
7930 * @object: A #_GFreedesktopDBus.
7931 * @invocation: A #GDBusMethodInvocation.
7932 * @arg_name: Argument passed by remote caller.
7934 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method.
7936 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_name_has_owner() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7938 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7943 * _GFreedesktopDBus::handle-release-name:
7944 * @object: A #_GFreedesktopDBus.
7945 * @invocation: A #GDBusMethodInvocation.
7946 * @arg_name: Argument passed by remote caller.
7948 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method.
7950 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_release_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7952 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7957 * _GFreedesktopDBus::handle-reload-config:
7958 * @object: A #_GFreedesktopDBus.
7959 * @invocation: A #GDBusMethodInvocation.
7961 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method.
7963 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_reload_config() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7965 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7970 * _GFreedesktopDBus::handle-remove-match:
7971 * @object: A #_GFreedesktopDBus.
7972 * @invocation: A #GDBusMethodInvocation.
7973 * @arg_rule: Argument passed by remote caller.
7975 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method.
7977 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_remove_match() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7979 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7984 * _GFreedesktopDBus::handle-request-name:
7985 * @object: A #_GFreedesktopDBus.
7986 * @invocation: A #GDBusMethodInvocation.
7987 * @arg_name: Argument passed by remote caller.
7988 * @arg_flags: Argument passed by remote caller.
7990 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method.
7992 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_request_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
7994 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
7999 * _GFreedesktopDBus::handle-start-service-by-name:
8000 * @object: A #_GFreedesktopDBus.
8001 * @invocation: A #GDBusMethodInvocation.
8002 * @arg_name: Argument passed by remote caller.
8003 * @arg_flags: Argument passed by remote caller.
8005 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method.
8007 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_start_service_by_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
8009 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8014 * _GFreedesktopDBus::handle-update-activation-environment:
8015 * @object: A #_GFreedesktopDBus.
8016 * @invocation: A #GDBusMethodInvocation.
8017 * @arg_environment: Argument passed by remote caller.
8019 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method.
8021 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_update_activation_environment() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
8023 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8028 * _GFreedesktopDBus::name-acquired:
8029 * @object: A #_GFreedesktopDBus.
8030 * @arg_name: Argument.
8032 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> is received.
8034 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
8039 * _GFreedesktopDBus::name-lost:
8040 * @object: A #_GFreedesktopDBus.
8041 * @arg_name: Argument.
8043 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> is received.
8045 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
8050 * _GFreedesktopDBus::name-owner-changed:
8051 * @object: A #_GFreedesktopDBus.
8052 * @arg_name: Argument.
8053 * @arg_old_owner: Argument.
8054 * @arg_new_owner: Argument.
8056 * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> is received.
8058 * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
8063 * _GFreedesktopDBusIface:
8064 * @parent_iface: The parent interface.
8065 * @handle_add_match: Handler for the #_GFreedesktopDBus::handle-add-match signal.
8066 * @handle_get_connection_selinux_security_context: Handler for the #_GFreedesktopDBus::handle-get-connection-selinux-security-context signal.
8067 * @handle_get_connection_unix_process_id: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-process-id signal.
8068 * @handle_get_connection_unix_user: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-user signal.
8069 * @handle_get_id: Handler for the #_GFreedesktopDBus::handle-get-id signal.
8070 * @handle_get_name_owner: Handler for the #_GFreedesktopDBus::handle-get-name-owner signal.
8071 * @handle_hello: Handler for the #_GFreedesktopDBus::handle-hello signal.
8072 * @handle_list_activatable_names: Handler for the #_GFreedesktopDBus::handle-list-activatable-names signal.
8073 * @handle_list_names: Handler for the #_GFreedesktopDBus::handle-list-names signal.
8074 * @handle_list_queued_owners: Handler for the #_GFreedesktopDBus::handle-list-queued-owners signal.
8075 * @handle_name_has_owner: Handler for the #_GFreedesktopDBus::handle-name-has-owner signal.
8076 * @handle_release_name: Handler for the #_GFreedesktopDBus::handle-release-name signal.
8077 * @handle_reload_config: Handler for the #_GFreedesktopDBus::handle-reload-config signal.
8078 * @handle_remove_match: Handler for the #_GFreedesktopDBus::handle-remove-match signal.
8079 * @handle_request_name: Handler for the #_GFreedesktopDBus::handle-request-name signal.
8080 * @handle_start_service_by_name: Handler for the #_GFreedesktopDBus::handle-start-service-by-name signal.
8081 * @handle_update_activation_environment: Handler for the #_GFreedesktopDBus::handle-update-activation-environment signal.
8082 * @name_acquired: Handler for the #_GFreedesktopDBus::name-acquired signal.
8083 * @name_lost: Handler for the #_GFreedesktopDBus::name-lost signal.
8084 * @name_owner_changed: Handler for the #_GFreedesktopDBus::name-owner-changed signal.
8086 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8091 * _GFreedesktopDBusProxy:
8093 * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API.
8098 * _GFreedesktopDBusProxyClass:
8099 * @parent_class: The parent class.
8101 * Class structure for #_GFreedesktopDBusProxy.
8106 * _GFreedesktopDBusSkeleton:
8108 * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API.
8113 * _GFreedesktopDBusSkeletonClass:
8114 * @parent_class: The parent class.
8116 * Class structure for #_GFreedesktopDBusSkeleton.
8121 * _g_freedesktop_dbus_call_add_match:
8122 * @proxy: A #_GFreedesktopDBusProxy.
8123 * @arg_rule: Argument to pass with the method invocation.
8124 * @cancellable: (allow-none): A #GCancellable or %NULL.
8125 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8126 * @user_data: User data to pass to @callback.
8128 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
8129 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8130 * You can then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
8132 * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
8137 * _g_freedesktop_dbus_call_add_match_finish:
8138 * @proxy: A #_GFreedesktopDBusProxy.
8139 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
8140 * @error: Return location for error or %NULL.
8142 * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
8144 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8149 * _g_freedesktop_dbus_call_add_match_sync:
8150 * @proxy: A #_GFreedesktopDBusProxy.
8151 * @arg_rule: Argument to pass with the method invocation.
8152 * @cancellable: (allow-none): A #GCancellable or %NULL.
8153 * @error: Return location for error or %NULL.
8155 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8157 * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
8159 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8164 * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
8165 * @proxy: A #_GFreedesktopDBusProxy.
8166 * @arg_name: Argument to pass with the method invocation.
8167 * @cancellable: (allow-none): A #GCancellable or %NULL.
8168 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8169 * @user_data: User data to pass to @callback.
8171 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
8172 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8173 * You can then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
8175 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
8180 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
8181 * @proxy: A #_GFreedesktopDBusProxy.
8182 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
8183 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
8184 * @error: Return location for error or %NULL.
8186 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
8188 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8193 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
8194 * @proxy: A #_GFreedesktopDBusProxy.
8195 * @arg_name: Argument to pass with the method invocation.
8196 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
8197 * @cancellable: (allow-none): A #GCancellable or %NULL.
8198 * @error: Return location for error or %NULL.
8200 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8202 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
8204 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8209 * _g_freedesktop_dbus_call_get_connection_unix_process_id:
8210 * @proxy: A #_GFreedesktopDBusProxy.
8211 * @arg_name: Argument to pass with the method invocation.
8212 * @cancellable: (allow-none): A #GCancellable or %NULL.
8213 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8214 * @user_data: User data to pass to @callback.
8216 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
8217 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8218 * You can then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
8220 * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
8225 * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
8226 * @proxy: A #_GFreedesktopDBusProxy.
8227 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
8228 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
8229 * @error: Return location for error or %NULL.
8231 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
8233 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8238 * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
8239 * @proxy: A #_GFreedesktopDBusProxy.
8240 * @arg_name: Argument to pass with the method invocation.
8241 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
8242 * @cancellable: (allow-none): A #GCancellable or %NULL.
8243 * @error: Return location for error or %NULL.
8245 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8247 * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
8249 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8254 * _g_freedesktop_dbus_call_get_connection_unix_user:
8255 * @proxy: A #_GFreedesktopDBusProxy.
8256 * @arg_name: Argument to pass with the method invocation.
8257 * @cancellable: (allow-none): A #GCancellable or %NULL.
8258 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8259 * @user_data: User data to pass to @callback.
8261 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
8262 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8263 * You can then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
8265 * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
8270 * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
8271 * @proxy: A #_GFreedesktopDBusProxy.
8272 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
8273 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
8274 * @error: Return location for error or %NULL.
8276 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
8278 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8283 * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
8284 * @proxy: A #_GFreedesktopDBusProxy.
8285 * @arg_name: Argument to pass with the method invocation.
8286 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
8287 * @cancellable: (allow-none): A #GCancellable or %NULL.
8288 * @error: Return location for error or %NULL.
8290 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8292 * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
8294 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8299 * _g_freedesktop_dbus_call_get_id:
8300 * @proxy: A #_GFreedesktopDBusProxy.
8301 * @cancellable: (allow-none): A #GCancellable or %NULL.
8302 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8303 * @user_data: User data to pass to @callback.
8305 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy.
8306 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8307 * You can then call _g_freedesktop_dbus_call_get_id_finish() to get the result of the operation.
8309 * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method.
8314 * _g_freedesktop_dbus_call_get_id_finish:
8315 * @proxy: A #_GFreedesktopDBusProxy.
8316 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
8317 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_id().
8318 * @error: Return location for error or %NULL.
8320 * Finishes an operation started with _g_freedesktop_dbus_call_get_id().
8322 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8327 * _g_freedesktop_dbus_call_get_id_sync:
8328 * @proxy: A #_GFreedesktopDBusProxy.
8329 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
8330 * @cancellable: (allow-none): A #GCancellable or %NULL.
8331 * @error: Return location for error or %NULL.
8333 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8335 * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method.
8337 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8342 * _g_freedesktop_dbus_call_get_name_owner:
8343 * @proxy: A #_GFreedesktopDBusProxy.
8344 * @arg_name: Argument to pass with the method invocation.
8345 * @cancellable: (allow-none): A #GCancellable or %NULL.
8346 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8347 * @user_data: User data to pass to @callback.
8349 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy.
8350 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8351 * You can then call _g_freedesktop_dbus_call_get_name_owner_finish() to get the result of the operation.
8353 * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method.
8358 * _g_freedesktop_dbus_call_get_name_owner_finish:
8359 * @proxy: A #_GFreedesktopDBusProxy.
8360 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
8361 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_name_owner().
8362 * @error: Return location for error or %NULL.
8364 * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner().
8366 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8371 * _g_freedesktop_dbus_call_get_name_owner_sync:
8372 * @proxy: A #_GFreedesktopDBusProxy.
8373 * @arg_name: Argument to pass with the method invocation.
8374 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
8375 * @cancellable: (allow-none): A #GCancellable or %NULL.
8376 * @error: Return location for error or %NULL.
8378 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8380 * See _g_freedesktop_dbus_call_get_name_owner() for the asynchronous version of this method.
8382 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8387 * _g_freedesktop_dbus_call_hello:
8388 * @proxy: A #_GFreedesktopDBusProxy.
8389 * @cancellable: (allow-none): A #GCancellable or %NULL.
8390 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8391 * @user_data: User data to pass to @callback.
8393 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy.
8394 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8395 * You can then call _g_freedesktop_dbus_call_hello_finish() to get the result of the operation.
8397 * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method.
8402 * _g_freedesktop_dbus_call_hello_finish:
8403 * @proxy: A #_GFreedesktopDBusProxy.
8404 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
8405 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_hello().
8406 * @error: Return location for error or %NULL.
8408 * Finishes an operation started with _g_freedesktop_dbus_call_hello().
8410 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8415 * _g_freedesktop_dbus_call_hello_sync:
8416 * @proxy: A #_GFreedesktopDBusProxy.
8417 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
8418 * @cancellable: (allow-none): A #GCancellable or %NULL.
8419 * @error: Return location for error or %NULL.
8421 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8423 * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method.
8425 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8430 * _g_freedesktop_dbus_call_list_activatable_names:
8431 * @proxy: A #_GFreedesktopDBusProxy.
8432 * @cancellable: (allow-none): A #GCancellable or %NULL.
8433 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8434 * @user_data: User data to pass to @callback.
8436 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy.
8437 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8438 * You can then call _g_freedesktop_dbus_call_list_activatable_names_finish() to get the result of the operation.
8440 * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method.
8445 * _g_freedesktop_dbus_call_list_activatable_names_finish:
8446 * @proxy: A #_GFreedesktopDBusProxy.
8447 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
8448 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
8449 * @error: Return location for error or %NULL.
8451 * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names().
8453 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8458 * _g_freedesktop_dbus_call_list_activatable_names_sync:
8459 * @proxy: A #_GFreedesktopDBusProxy.
8460 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
8461 * @cancellable: (allow-none): A #GCancellable or %NULL.
8462 * @error: Return location for error or %NULL.
8464 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8466 * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method.
8468 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8473 * _g_freedesktop_dbus_call_list_names:
8474 * @proxy: A #_GFreedesktopDBusProxy.
8475 * @cancellable: (allow-none): A #GCancellable or %NULL.
8476 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8477 * @user_data: User data to pass to @callback.
8479 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy.
8480 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8481 * You can then call _g_freedesktop_dbus_call_list_names_finish() to get the result of the operation.
8483 * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method.
8488 * _g_freedesktop_dbus_call_list_names_finish:
8489 * @proxy: A #_GFreedesktopDBusProxy.
8490 * @out_names: (out): Return location for return parameter or %NULL to ignore.
8491 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
8492 * @error: Return location for error or %NULL.
8494 * Finishes an operation started with _g_freedesktop_dbus_call_list_names().
8496 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8501 * _g_freedesktop_dbus_call_list_names_sync:
8502 * @proxy: A #_GFreedesktopDBusProxy.
8503 * @out_names: (out): Return location for return parameter or %NULL to ignore.
8504 * @cancellable: (allow-none): A #GCancellable or %NULL.
8505 * @error: Return location for error or %NULL.
8507 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8509 * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method.
8511 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8516 * _g_freedesktop_dbus_call_list_queued_owners:
8517 * @proxy: A #_GFreedesktopDBusProxy.
8518 * @arg_name: Argument to pass with the method invocation.
8519 * @cancellable: (allow-none): A #GCancellable or %NULL.
8520 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8521 * @user_data: User data to pass to @callback.
8523 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy.
8524 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8525 * You can then call _g_freedesktop_dbus_call_list_queued_owners_finish() to get the result of the operation.
8527 * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method.
8532 * _g_freedesktop_dbus_call_list_queued_owners_finish:
8533 * @proxy: A #_GFreedesktopDBusProxy.
8534 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
8535 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
8536 * @error: Return location for error or %NULL.
8538 * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners().
8540 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8545 * _g_freedesktop_dbus_call_list_queued_owners_sync:
8546 * @proxy: A #_GFreedesktopDBusProxy.
8547 * @arg_name: Argument to pass with the method invocation.
8548 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
8549 * @cancellable: (allow-none): A #GCancellable or %NULL.
8550 * @error: Return location for error or %NULL.
8552 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8554 * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method.
8556 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8561 * _g_freedesktop_dbus_call_name_has_owner:
8562 * @proxy: A #_GFreedesktopDBusProxy.
8563 * @arg_name: Argument to pass with the method invocation.
8564 * @cancellable: (allow-none): A #GCancellable or %NULL.
8565 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8566 * @user_data: User data to pass to @callback.
8568 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy.
8569 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8570 * You can then call _g_freedesktop_dbus_call_name_has_owner_finish() to get the result of the operation.
8572 * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method.
8577 * _g_freedesktop_dbus_call_name_has_owner_finish:
8578 * @proxy: A #_GFreedesktopDBusProxy.
8579 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
8580 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_name_has_owner().
8581 * @error: Return location for error or %NULL.
8583 * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner().
8585 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8590 * _g_freedesktop_dbus_call_name_has_owner_sync:
8591 * @proxy: A #_GFreedesktopDBusProxy.
8592 * @arg_name: Argument to pass with the method invocation.
8593 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
8594 * @cancellable: (allow-none): A #GCancellable or %NULL.
8595 * @error: Return location for error or %NULL.
8597 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8599 * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method.
8601 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8606 * _g_freedesktop_dbus_call_release_name:
8607 * @proxy: A #_GFreedesktopDBusProxy.
8608 * @arg_name: Argument to pass with the method invocation.
8609 * @cancellable: (allow-none): A #GCancellable or %NULL.
8610 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8611 * @user_data: User data to pass to @callback.
8613 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy.
8614 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8615 * You can then call _g_freedesktop_dbus_call_release_name_finish() to get the result of the operation.
8617 * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method.
8622 * _g_freedesktop_dbus_call_release_name_finish:
8623 * @proxy: A #_GFreedesktopDBusProxy.
8624 * @out_value: (out): Return location for return parameter or %NULL to ignore.
8625 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_release_name().
8626 * @error: Return location for error or %NULL.
8628 * Finishes an operation started with _g_freedesktop_dbus_call_release_name().
8630 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8635 * _g_freedesktop_dbus_call_release_name_sync:
8636 * @proxy: A #_GFreedesktopDBusProxy.
8637 * @arg_name: Argument to pass with the method invocation.
8638 * @out_value: (out): Return location for return parameter or %NULL to ignore.
8639 * @cancellable: (allow-none): A #GCancellable or %NULL.
8640 * @error: Return location for error or %NULL.
8642 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8644 * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method.
8646 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8651 * _g_freedesktop_dbus_call_reload_config:
8652 * @proxy: A #_GFreedesktopDBusProxy.
8653 * @cancellable: (allow-none): A #GCancellable or %NULL.
8654 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8655 * @user_data: User data to pass to @callback.
8657 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy.
8658 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8659 * You can then call _g_freedesktop_dbus_call_reload_config_finish() to get the result of the operation.
8661 * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method.
8666 * _g_freedesktop_dbus_call_reload_config_finish:
8667 * @proxy: A #_GFreedesktopDBusProxy.
8668 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_reload_config().
8669 * @error: Return location for error or %NULL.
8671 * Finishes an operation started with _g_freedesktop_dbus_call_reload_config().
8673 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8678 * _g_freedesktop_dbus_call_reload_config_sync:
8679 * @proxy: A #_GFreedesktopDBusProxy.
8680 * @cancellable: (allow-none): A #GCancellable or %NULL.
8681 * @error: Return location for error or %NULL.
8683 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8685 * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method.
8687 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8692 * _g_freedesktop_dbus_call_remove_match:
8693 * @proxy: A #_GFreedesktopDBusProxy.
8694 * @arg_rule: Argument to pass with the method invocation.
8695 * @cancellable: (allow-none): A #GCancellable or %NULL.
8696 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8697 * @user_data: User data to pass to @callback.
8699 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy.
8700 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8701 * You can then call _g_freedesktop_dbus_call_remove_match_finish() to get the result of the operation.
8703 * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method.
8708 * _g_freedesktop_dbus_call_remove_match_finish:
8709 * @proxy: A #_GFreedesktopDBusProxy.
8710 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_remove_match().
8711 * @error: Return location for error or %NULL.
8713 * Finishes an operation started with _g_freedesktop_dbus_call_remove_match().
8715 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8720 * _g_freedesktop_dbus_call_remove_match_sync:
8721 * @proxy: A #_GFreedesktopDBusProxy.
8722 * @arg_rule: Argument to pass with the method invocation.
8723 * @cancellable: (allow-none): A #GCancellable or %NULL.
8724 * @error: Return location for error or %NULL.
8726 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8728 * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method.
8730 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8735 * _g_freedesktop_dbus_call_request_name:
8736 * @proxy: A #_GFreedesktopDBusProxy.
8737 * @arg_name: Argument to pass with the method invocation.
8738 * @arg_flags: Argument to pass with the method invocation.
8739 * @cancellable: (allow-none): A #GCancellable or %NULL.
8740 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8741 * @user_data: User data to pass to @callback.
8743 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy.
8744 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8745 * You can then call _g_freedesktop_dbus_call_request_name_finish() to get the result of the operation.
8747 * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method.
8752 * _g_freedesktop_dbus_call_request_name_finish:
8753 * @proxy: A #_GFreedesktopDBusProxy.
8754 * @out_value: (out): Return location for return parameter or %NULL to ignore.
8755 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_request_name().
8756 * @error: Return location for error or %NULL.
8758 * Finishes an operation started with _g_freedesktop_dbus_call_request_name().
8760 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8765 * _g_freedesktop_dbus_call_request_name_sync:
8766 * @proxy: A #_GFreedesktopDBusProxy.
8767 * @arg_name: Argument to pass with the method invocation.
8768 * @arg_flags: Argument to pass with the method invocation.
8769 * @out_value: (out): Return location for return parameter or %NULL to ignore.
8770 * @cancellable: (allow-none): A #GCancellable or %NULL.
8771 * @error: Return location for error or %NULL.
8773 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8775 * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method.
8777 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8782 * _g_freedesktop_dbus_call_start_service_by_name:
8783 * @proxy: A #_GFreedesktopDBusProxy.
8784 * @arg_name: Argument to pass with the method invocation.
8785 * @arg_flags: Argument to pass with the method invocation.
8786 * @cancellable: (allow-none): A #GCancellable or %NULL.
8787 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8788 * @user_data: User data to pass to @callback.
8790 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy.
8791 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8792 * You can then call _g_freedesktop_dbus_call_start_service_by_name_finish() to get the result of the operation.
8794 * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method.
8799 * _g_freedesktop_dbus_call_start_service_by_name_finish:
8800 * @proxy: A #_GFreedesktopDBusProxy.
8801 * @out_value: (out): Return location for return parameter or %NULL to ignore.
8802 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_start_service_by_name().
8803 * @error: Return location for error or %NULL.
8805 * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name().
8807 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8812 * _g_freedesktop_dbus_call_start_service_by_name_sync:
8813 * @proxy: A #_GFreedesktopDBusProxy.
8814 * @arg_name: Argument to pass with the method invocation.
8815 * @arg_flags: Argument to pass with the method invocation.
8816 * @out_value: (out): Return location for return parameter or %NULL to ignore.
8817 * @cancellable: (allow-none): A #GCancellable or %NULL.
8818 * @error: Return location for error or %NULL.
8820 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8822 * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method.
8824 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8829 * _g_freedesktop_dbus_call_update_activation_environment:
8830 * @proxy: A #_GFreedesktopDBusProxy.
8831 * @arg_environment: Argument to pass with the method invocation.
8832 * @cancellable: (allow-none): A #GCancellable or %NULL.
8833 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8834 * @user_data: User data to pass to @callback.
8836 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy.
8837 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
8838 * You can then call _g_freedesktop_dbus_call_update_activation_environment_finish() to get the result of the operation.
8840 * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method.
8845 * _g_freedesktop_dbus_call_update_activation_environment_finish:
8846 * @proxy: A #_GFreedesktopDBusProxy.
8847 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_update_activation_environment().
8848 * @error: Return location for error or %NULL.
8850 * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment().
8852 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8857 * _g_freedesktop_dbus_call_update_activation_environment_sync:
8858 * @proxy: A #_GFreedesktopDBusProxy.
8859 * @arg_environment: Argument to pass with the method invocation.
8860 * @cancellable: (allow-none): A #GCancellable or %NULL.
8861 * @error: Return location for error or %NULL.
8863 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
8865 * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method.
8867 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8872 * _g_freedesktop_dbus_complete_add_match:
8873 * @object: A #_GFreedesktopDBus.
8874 * @invocation: (transfer full): A #GDBusMethodInvocation.
8876 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8878 * This method will free @invocation, you cannot use it afterwards.
8883 * _g_freedesktop_dbus_complete_get_connection_selinux_security_context:
8884 * @object: A #_GFreedesktopDBus.
8885 * @invocation: (transfer full): A #GDBusMethodInvocation.
8886 * @security_context: Parameter to return.
8888 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8890 * This method will free @invocation, you cannot use it afterwards.
8895 * _g_freedesktop_dbus_complete_get_connection_unix_process_id:
8896 * @object: A #_GFreedesktopDBus.
8897 * @invocation: (transfer full): A #GDBusMethodInvocation.
8898 * @pid: Parameter to return.
8900 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8902 * This method will free @invocation, you cannot use it afterwards.
8907 * _g_freedesktop_dbus_complete_get_connection_unix_user:
8908 * @object: A #_GFreedesktopDBus.
8909 * @invocation: (transfer full): A #GDBusMethodInvocation.
8910 * @uid: Parameter to return.
8912 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8914 * This method will free @invocation, you cannot use it afterwards.
8919 * _g_freedesktop_dbus_complete_get_id:
8920 * @object: A #_GFreedesktopDBus.
8921 * @invocation: (transfer full): A #GDBusMethodInvocation.
8922 * @unique_id: Parameter to return.
8924 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8926 * This method will free @invocation, you cannot use it afterwards.
8931 * _g_freedesktop_dbus_complete_get_name_owner:
8932 * @object: A #_GFreedesktopDBus.
8933 * @invocation: (transfer full): A #GDBusMethodInvocation.
8934 * @unique_name: Parameter to return.
8936 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8938 * This method will free @invocation, you cannot use it afterwards.
8943 * _g_freedesktop_dbus_complete_hello:
8944 * @object: A #_GFreedesktopDBus.
8945 * @invocation: (transfer full): A #GDBusMethodInvocation.
8946 * @assigned_name: Parameter to return.
8948 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8950 * This method will free @invocation, you cannot use it afterwards.
8955 * _g_freedesktop_dbus_complete_list_activatable_names:
8956 * @object: A #_GFreedesktopDBus.
8957 * @invocation: (transfer full): A #GDBusMethodInvocation.
8958 * @activatable_names: Parameter to return.
8960 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8962 * This method will free @invocation, you cannot use it afterwards.
8967 * _g_freedesktop_dbus_complete_list_names:
8968 * @object: A #_GFreedesktopDBus.
8969 * @invocation: (transfer full): A #GDBusMethodInvocation.
8970 * @names: Parameter to return.
8972 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8974 * This method will free @invocation, you cannot use it afterwards.
8979 * _g_freedesktop_dbus_complete_list_queued_owners:
8980 * @object: A #_GFreedesktopDBus.
8981 * @invocation: (transfer full): A #GDBusMethodInvocation.
8982 * @queued_owners: Parameter to return.
8984 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8986 * This method will free @invocation, you cannot use it afterwards.
8991 * _g_freedesktop_dbus_complete_name_has_owner:
8992 * @object: A #_GFreedesktopDBus.
8993 * @invocation: (transfer full): A #GDBusMethodInvocation.
8994 * @has_owner: Parameter to return.
8996 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
8998 * This method will free @invocation, you cannot use it afterwards.
9003 * _g_freedesktop_dbus_complete_release_name:
9004 * @object: A #_GFreedesktopDBus.
9005 * @invocation: (transfer full): A #GDBusMethodInvocation.
9006 * @value: Parameter to return.
9008 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
9010 * This method will free @invocation, you cannot use it afterwards.
9015 * _g_freedesktop_dbus_complete_reload_config:
9016 * @object: A #_GFreedesktopDBus.
9017 * @invocation: (transfer full): A #GDBusMethodInvocation.
9019 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
9021 * This method will free @invocation, you cannot use it afterwards.
9026 * _g_freedesktop_dbus_complete_remove_match:
9027 * @object: A #_GFreedesktopDBus.
9028 * @invocation: (transfer full): A #GDBusMethodInvocation.
9030 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
9032 * This method will free @invocation, you cannot use it afterwards.
9037 * _g_freedesktop_dbus_complete_request_name:
9038 * @object: A #_GFreedesktopDBus.
9039 * @invocation: (transfer full): A #GDBusMethodInvocation.
9040 * @value: Parameter to return.
9042 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
9044 * This method will free @invocation, you cannot use it afterwards.
9049 * _g_freedesktop_dbus_complete_start_service_by_name:
9050 * @object: A #_GFreedesktopDBus.
9051 * @invocation: (transfer full): A #GDBusMethodInvocation.
9052 * @value: Parameter to return.
9054 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
9056 * This method will free @invocation, you cannot use it afterwards.
9061 * _g_freedesktop_dbus_complete_update_activation_environment:
9062 * @object: A #_GFreedesktopDBus.
9063 * @invocation: (transfer full): A #GDBusMethodInvocation.
9065 * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
9067 * This method will free @invocation, you cannot use it afterwards.
9072 * _g_freedesktop_dbus_emit_name_acquired:
9073 * @object: A #_GFreedesktopDBus.
9074 * @arg_name: Argument to pass with the signal.
9076 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> D-Bus signal.
9081 * _g_freedesktop_dbus_emit_name_lost:
9082 * @object: A #_GFreedesktopDBus.
9083 * @arg_name: Argument to pass with the signal.
9085 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> D-Bus signal.
9090 * _g_freedesktop_dbus_emit_name_owner_changed:
9091 * @object: A #_GFreedesktopDBus.
9092 * @arg_name: Argument to pass with the signal.
9093 * @arg_old_owner: Argument to pass with the signal.
9094 * @arg_new_owner: Argument to pass with the signal.
9096 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> D-Bus signal.
9101 * _g_freedesktop_dbus_interface_info:
9103 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface.
9105 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
9110 * _g_freedesktop_dbus_override_properties:
9111 * @klass: The class structure for a #GObject<!-- -->-derived class.
9112 * @property_id_begin: The property id to assign to the first overridden property.
9114 * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
9115 * The properties are overridden in the order they are defined.
9117 * Returns: The last property id.
9122 * _g_freedesktop_dbus_proxy_new:
9123 * @connection: A #GDBusConnection.
9124 * @flags: Flags from the #GDBusProxyFlags enumeration.
9125 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9126 * @object_path: An object path.
9127 * @cancellable: (allow-none): A #GCancellable or %NULL.
9128 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9129 * @user_data: User data to pass to @callback.
9131 * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new() for more details.
9133 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
9134 * You can then call _g_freedesktop_dbus_proxy_new_finish() to get the result of the operation.
9136 * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor.
9141 * _g_freedesktop_dbus_proxy_new_finish:
9142 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new().
9143 * @error: Return location for error or %NULL
9145 * Finishes an operation started with _g_freedesktop_dbus_proxy_new().
9147 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9152 * _g_freedesktop_dbus_proxy_new_for_bus:
9153 * @bus_type: A #GBusType.
9154 * @flags: Flags from the #GDBusProxyFlags enumeration.
9155 * @name: A bus name (well-known or unique).
9156 * @object_path: An object path.
9157 * @cancellable: (allow-none): A #GCancellable or %NULL.
9158 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9159 * @user_data: User data to pass to @callback.
9161 * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
9163 * When the operation is finished, @callback will be invoked in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> of the thread you are calling this method from.
9164 * You can then call _g_freedesktop_dbus_proxy_new_for_bus_finish() to get the result of the operation.
9166 * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
9171 * _g_freedesktop_dbus_proxy_new_for_bus_finish:
9172 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new_for_bus().
9173 * @error: Return location for error or %NULL
9175 * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus().
9177 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9182 * _g_freedesktop_dbus_proxy_new_for_bus_sync:
9183 * @bus_type: A #GBusType.
9184 * @flags: Flags from the #GDBusProxyFlags enumeration.
9185 * @name: A bus name (well-known or unique).
9186 * @object_path: An object path.
9187 * @cancellable: (allow-none): A #GCancellable or %NULL.
9188 * @error: Return location for error or %NULL
9190 * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
9192 * The calling thread is blocked until a reply is received.
9194 * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor.
9196 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9201 * _g_freedesktop_dbus_proxy_new_sync:
9202 * @connection: A #GDBusConnection.
9203 * @flags: Flags from the #GDBusProxyFlags enumeration.
9204 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9205 * @object_path: An object path.
9206 * @cancellable: (allow-none): A #GCancellable or %NULL.
9207 * @error: Return location for error or %NULL
9209 * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new_sync() for more details.
9211 * The calling thread is blocked until a reply is received.
9213 * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor.
9215 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9220 * _g_freedesktop_dbus_skeleton_new:
9222 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
9224 * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object.
9229 * _g_io_module_get_default:
9230 * @extension_point: the name of an extension point
9231 * @envvar: (allow-none): the name of an environment variable to override the default implementation.
9232 * @verify_func: (allow-none): a function to call to verify that a given implementation is usable in the current environment.
9234 * Retrieves the default object implementing @extension_point.
9236 * If @envvar is not %NULL, and the environment variable with that
9237 * name is set, then the implementation it specifies will be tried
9238 * first. After that, or if @envvar is not set, all other
9239 * implementations will be tried in order of decreasing priority.
9241 * If an extension point implementation implements #GInitable, then
9242 * that implementation will only be used if it initializes
9243 * successfully. Otherwise, if @verify_func is not %NULL, then it will
9244 * be called on each candidate implementation after construction, to
9245 * check if it is actually usable or not.
9247 * The result is cached after it is generated the first time, and
9248 * the function is thread-safe.
9250 * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations.
9255 * g_action_activate:
9256 * @action: a #GAction
9257 * @parameter: (allow-none): the parameter to the activation
9259 * Activates the action.
9261 * @parameter must be the correct type of parameter for the action (ie:
9262 * the parameter type given at construction time). If the parameter
9263 * type was %NULL then @parameter must also be %NULL.
9270 * g_action_change_state:
9271 * @action: a #GAction
9272 * @value: the new state
9274 * Request for the state of @action to be changed to @value.
9276 * The action must be stateful and @value must be of the correct type.
9277 * See g_action_get_state_type().
9279 * This call merely requests a change. The action may refuse to change
9280 * its state or may change its state to something other than @value.
9281 * See g_action_get_state_hint().
9283 * If the @value GVariant is floating, it is consumed.
9290 * g_action_get_enabled:
9291 * @action: a #GAction
9293 * Checks if @action is currently enabled.
9295 * An action must be enabled in order to be activated or in order to
9296 * have its state changed from outside callers.
9298 * Returns: whether the action is enabled
9304 * g_action_get_name:
9305 * @action: a #GAction
9307 * Queries the name of @action.
9309 * Returns: the name of the action
9315 * g_action_get_parameter_type:
9316 * @action: a #GAction
9318 * Queries the type of the parameter that must be given when activating
9321 * When activating the action using g_action_activate(), the #GVariant
9322 * given to that function must be of the type returned by this function.
9324 * In the case that this function returns %NULL, you must not give any
9325 * #GVariant, but %NULL instead.
9327 * Returns: (allow-none): the parameter type
9333 * g_action_get_state:
9334 * @action: a #GAction
9336 * Queries the current state of @action.
9338 * If the action is not stateful then %NULL will be returned. If the
9339 * action is stateful then the type of the return value is the type
9340 * given by g_action_get_state_type().
9342 * The return value (if non-%NULL) should be freed with
9343 * g_variant_unref() when it is no longer required.
9345 * Returns: (transfer full): the current state of the action
9351 * g_action_get_state_hint:
9352 * @action: a #GAction
9354 * Requests a hint about the valid range of values for the state of
9357 * If %NULL is returned it either means that the action is not stateful
9358 * or that there is no hint about the valid range of values for the
9359 * state of the action.
9361 * If a #GVariant array is returned then each item in the array is a
9362 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
9363 * returned then the tuple specifies the inclusive lower and upper bound
9364 * of valid values for the state.
9366 * In any case, the information is merely a hint. It may be possible to
9367 * have a state value outside of the hinted range and setting a value
9368 * within the range may fail.
9370 * The return value (if non-%NULL) should be freed with
9371 * g_variant_unref() when it is no longer required.
9373 * Returns: (transfer full): the state range hint
9379 * g_action_get_state_type:
9380 * @action: a #GAction
9382 * Queries the type of the state of @action.
9384 * If the action is stateful (e.g. created with
9385 * g_simple_action_new_stateful()) then this function returns the
9386 * #GVariantType of the state. This is the type of the initial value
9387 * given as the state. All calls to g_action_change_state() must give a
9388 * #GVariant of this type and g_action_get_state() will return a
9389 * #GVariant of the same type.
9391 * If the action is not stateful (e.g. created with g_simple_action_new())
9392 * then this function will return %NULL. In that case, g_action_get_state()
9393 * will return %NULL and you must not call g_action_change_state().
9395 * Returns: (allow-none): the state type, if the action is stateful
9401 * g_action_group_action_added:
9402 * @action_group: a #GActionGroup
9403 * @action_name: the name of an action in the group
9405 * Emits the #GActionGroup::action-added signal on @action_group.
9407 * This function should only be called by #GActionGroup implementations.
9414 * g_action_group_action_enabled_changed:
9415 * @action_group: a #GActionGroup
9416 * @action_name: the name of an action in the group
9417 * @enabled: whether or not the action is now enabled
9419 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
9421 * This function should only be called by #GActionGroup implementations.
9428 * g_action_group_action_removed:
9429 * @action_group: a #GActionGroup
9430 * @action_name: the name of an action in the group
9432 * Emits the #GActionGroup::action-removed signal on @action_group.
9434 * This function should only be called by #GActionGroup implementations.
9441 * g_action_group_action_state_changed:
9442 * @action_group: a #GActionGroup
9443 * @action_name: the name of an action in the group
9444 * @state: the new state of the named action
9446 * Emits the #GActionGroup::action-state-changed signal on @action_group.
9448 * This function should only be called by #GActionGroup implementations.
9455 * g_action_group_activate_action:
9456 * @action_group: a #GActionGroup
9457 * @action_name: the name of the action to activate
9458 * @parameter: (allow-none): parameters to the activation
9460 * Activate the named action within @action_group.
9462 * If the action is expecting a parameter, then the correct type of
9463 * parameter must be given as @parameter. If the action is expecting no
9464 * parameters then @parameter must be %NULL. See
9465 * g_action_group_get_action_parameter_type().
9472 * g_action_group_change_action_state:
9473 * @action_group: a #GActionGroup
9474 * @action_name: the name of the action to request the change on
9475 * @value: the new state
9477 * Request for the state of the named action within @action_group to be
9478 * changed to @value.
9480 * The action must be stateful and @value must be of the correct type.
9481 * See g_action_group_get_action_state_type().
9483 * This call merely requests a change. The action may refuse to change
9484 * its state or may change its state to something other than @value.
9485 * See g_action_group_get_action_state_hint().
9487 * If the @value GVariant is floating, it is consumed.
9494 * g_action_group_get_action_enabled:
9495 * @action_group: a #GActionGroup
9496 * @action_name: the name of the action to query
9498 * Checks if the named action within @action_group is currently enabled.
9500 * An action must be enabled in order to be activated or in order to
9501 * have its state changed from outside callers.
9503 * Returns: whether or not the action is currently enabled
9509 * g_action_group_get_action_parameter_type:
9510 * @action_group: a #GActionGroup
9511 * @action_name: the name of the action to query
9513 * Queries the type of the parameter that must be given when activating
9514 * the named action within @action_group.
9516 * When activating the action using g_action_group_activate_action(),
9517 * the #GVariant given to that function must be of the type returned
9520 * In the case that this function returns %NULL, you must not give any
9521 * #GVariant, but %NULL instead.
9523 * The parameter type of a particular action will never change but it is
9524 * possible for an action to be removed and for a new action to be added
9525 * with the same name but a different parameter type.
9527 * Returns: the parameter type
9533 * g_action_group_get_action_state:
9534 * @action_group: a #GActionGroup
9535 * @action_name: the name of the action to query
9537 * Queries the current state of the named action within @action_group.
9539 * If the action is not stateful then %NULL will be returned. If the
9540 * action is stateful then the type of the return value is the type
9541 * given by g_action_group_get_action_state_type().
9543 * The return value (if non-%NULL) should be freed with
9544 * g_variant_unref() when it is no longer required.
9546 * Returns: (allow-none): the current state of the action
9552 * g_action_group_get_action_state_hint:
9553 * @action_group: a #GActionGroup
9554 * @action_name: the name of the action to query
9556 * Requests a hint about the valid range of values for the state of the
9557 * named action within @action_group.
9559 * If %NULL is returned it either means that the action is not stateful
9560 * or that there is no hint about the valid range of values for the
9561 * state of the action.
9563 * If a #GVariant array is returned then each item in the array is a
9564 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
9565 * returned then the tuple specifies the inclusive lower and upper bound
9566 * of valid values for the state.
9568 * In any case, the information is merely a hint. It may be possible to
9569 * have a state value outside of the hinted range and setting a value
9570 * within the range may fail.
9572 * The return value (if non-%NULL) should be freed with
9573 * g_variant_unref() when it is no longer required.
9575 * Returns: (transfer full): the state range hint
9581 * g_action_group_get_action_state_type:
9582 * @action_group: a #GActionGroup
9583 * @action_name: the name of the action to query
9585 * Queries the type of the state of the named action within
9588 * If the action is stateful then this function returns the
9589 * #GVariantType of the state. All calls to
9590 * g_action_group_change_action_state() must give a #GVariant of this
9591 * type and g_action_group_get_action_state() will return a #GVariant
9594 * If the action is not stateful then this function will return %NULL.
9595 * In that case, g_action_group_get_action_state() will return %NULL
9596 * and you must not call g_action_group_change_action_state().
9598 * The state type of a particular action will never change but it is
9599 * possible for an action to be removed and for a new action to be added
9600 * with the same name but a different state type.
9602 * Returns: (transfer full): the state type, if the action is stateful
9608 * g_action_group_has_action:
9609 * @action_group: a #GActionGroup
9610 * @action_name: the name of the action to check for
9612 * Checks if the named action exists within @action_group.
9614 * Returns: whether the named action exists
9620 * g_action_group_list_actions:
9621 * @action_group: a #GActionGroup
9623 * Lists the actions contained within @action_group.
9625 * The caller is responsible for freeing the list with g_strfreev() when
9626 * it is no longer required.
9628 * Returns: (transfer full): a %NULL-terminated array of the names of the actions in the groupb
9634 * g_action_group_query_action:
9635 * @action_group: a #GActionGroup
9636 * @action_name: the name of an action in the group
9637 * @enabled: (out): if the action is presently enabled
9638 * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
9639 * @state_type: (out) (allow-none): the state type, or %NULL if stateless
9640 * @state_hint: (out) (allow-none): the state hint, or %NULL if none
9641 * @state: (out) (allow-none): the current state, or %NULL if stateless
9643 * Queries all aspects of the named action within an @action_group.
9645 * This function acquires the information available from
9646 * g_action_group_has_action(), g_action_group_get_action_enabled(),
9647 * g_action_group_get_action_parameter_type(),
9648 * g_action_group_get_action_state_type(),
9649 * g_action_group_get_action_state_hint() and
9650 * g_action_group_get_action_state() with a single function call.
9652 * This provides two main benefits.
9654 * The first is the improvement in efficiency that comes with not having
9655 * to perform repeated lookups of the action in order to discover
9656 * different things about it. The second is that implementing
9657 * #GActionGroup can now be done by only overriding this one virtual
9660 * The interface provides a default implementation of this function that
9661 * calls the individual functions, as required, to fetch the
9662 * information. The interface also provides default implementations of
9663 * those functions that call this function. All implementations,
9664 * therefore, must override either this function or all of the others.
9666 * If the action exists, %TRUE is returned and any of the requested
9667 * fields (as indicated by having a non-%NULL reference passed in) are
9668 * filled. If the action doesn't exist, %FALSE is returned and the
9669 * fields may or may not have been modified.
9671 * Returns: %TRUE if the action exists, else %FALSE
9677 * g_action_map_add_action:
9678 * @action_map: a #GActionMap
9679 * @action: a #GAction
9681 * Adds an action to the @action_map.
9683 * If the action map already contains an action with the same name
9684 * as @action then the old action is dropped from the action map.
9686 * The action map takes its own reference on @action.
9693 * g_action_map_add_action_entries:
9694 * @action_map: a #GActionMap
9695 * @entries: a pointer to the first item in an array of #GActionEntry structs
9696 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
9697 * @user_data: the user data for signal connections
9699 * A convenience function for creating multiple #GSimpleAction instances
9700 * and adding them to a #GActionMap.
9702 * Each action is constructed as per one #GActionEntry.
9705 * <title>Using g_action_map_add_action_entries()</title>
9708 * activate_quit (GSimpleAction *simple,
9709 * GVariant *parameter,
9710 * gpointer user_data)
9716 * activate_print_string (GSimpleAction *simple,
9717 * GVariant *parameter,
9718 * gpointer user_data)
9720 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
9723 * static GActionGroup *
9724 * create_action_group (void)
9726 * const GActionEntry entries[] = {
9727 * { "quit", activate_quit },
9728 * { "print-string", activate_print_string, "s" }
9730 * GSimpleActionGroup *group;
9732 * group = g_simple_action_group_new ();
9733 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
9735 * return G_ACTION_GROUP (group);
9745 * g_action_map_lookup_action:
9746 * @action_map: a #GActionMap
9747 * @action_name: the name of an action
9749 * Looks up the action with the name @action_name in @action_map.
9751 * If no such action exists, returns %NULL.
9753 * Returns: (transfer none): a #GAction, or %NULL
9759 * g_action_map_remove_action:
9760 * @action_map: a #GActionMap
9761 * @action_name: the name of the action
9763 * Removes the named action from the action map.
9765 * If no action of this name is in the map then nothing happens.
9772 * g_app_info_add_supports_type:
9773 * @appinfo: a #GAppInfo.
9774 * @content_type: a string.
9775 * @error: a #GError.
9777 * Adds a content type to the application information to indicate the
9778 * application is capable of opening files with the given content type.
9780 * Returns: %TRUE on success, %FALSE on error.
9785 * g_app_info_can_delete:
9786 * @appinfo: a #GAppInfo
9788 * Obtains the information whether the #GAppInfo can be deleted.
9789 * See g_app_info_delete().
9791 * Returns: %TRUE if @appinfo can be deleted
9797 * g_app_info_can_remove_supports_type:
9798 * @appinfo: a #GAppInfo.
9800 * Checks if a supported content type can be removed from an application.
9802 * Returns: %TRUE if it is possible to remove supported content types from a given @appinfo, %FALSE if not.
9807 * g_app_info_create_from_commandline:
9808 * @commandline: the commandline to use
9809 * @application_name: (allow-none): the application name, or %NULL to use @commandline
9810 * @flags: flags that can specify details of the created #GAppInfo
9811 * @error: a #GError location to store the error occurring, %NULL to ignore.
9813 * Creates a new #GAppInfo from the given information.
9815 * Note that for @commandline, the quoting rules of the Exec key of the
9816 * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">freedesktop.org Desktop
9817 * Entry Specification</ulink> are applied. For example, if the @commandline contains
9818 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
9819 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
9821 * Returns: (transfer full): new #GAppInfo for given command.
9826 * g_app_info_delete:
9827 * @appinfo: a #GAppInfo
9829 * Tries to delete a #GAppInfo.
9831 * On some platforms, there may be a difference between user-defined
9832 * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
9833 * cannot. See g_app_info_can_delete().
9835 * Virtual: do_delete
9836 * Returns: %TRUE if @appinfo has been deleted
9843 * @appinfo: a #GAppInfo.
9845 * Creates a duplicate of a #GAppInfo.
9847 * Returns: (transfer full): a duplicate of @appinfo.
9853 * @appinfo1: the first #GAppInfo.
9854 * @appinfo2: the second #GAppInfo.
9856 * Checks if two #GAppInfo<!-- -->s are equal.
9858 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
9863 * g_app_info_get_all:
9865 * Gets a list of all of the applications currently registered
9868 * For desktop files, this includes applications that have
9869 * <literal>NoDisplay=true</literal> set or are excluded from
9870 * display by means of <literal>OnlyShowIn</literal> or
9871 * <literal>NotShowIn</literal>. See g_app_info_should_show().
9872 * The returned list does not include applications which have
9873 * the <literal>Hidden</literal> key set.
9875 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
9880 * g_app_info_get_all_for_type:
9881 * @content_type: the content type to find a #GAppInfo for
9883 * Gets a list of all #GAppInfos for a given content type,
9884 * including the recommended and fallback #GAppInfos. See
9885 * g_app_info_get_recommended_for_type() and
9886 * g_app_info_get_fallback_for_type().
9888 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error.
9893 * g_app_info_get_commandline:
9894 * @appinfo: a #GAppInfo
9896 * Gets the commandline with which the application will be
9899 * Returns: a string containing the @appinfo's commandline, or %NULL if this information is not available
9905 * g_app_info_get_default_for_type:
9906 * @content_type: the content type to find a #GAppInfo for
9907 * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs
9909 * Gets the default #GAppInfo for a given content type.
9911 * Returns: (transfer full): #GAppInfo for given @content_type or %NULL on error.
9916 * g_app_info_get_default_for_uri_scheme:
9917 * @uri_scheme: a string containing a URI scheme.
9919 * Gets the default application for handling URIs with
9920 * the given URI scheme. A URI scheme is the initial part
9921 * of the URI, up to but not including the ':', e.g. "http",
9924 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
9929 * g_app_info_get_description:
9930 * @appinfo: a #GAppInfo.
9932 * Gets a human-readable description of an installed application.
9934 * Returns: a string containing a description of the application @appinfo, or %NULL if none.
9939 * g_app_info_get_display_name:
9940 * @appinfo: a #GAppInfo.
9942 * Gets the display name of the application. The display name is often more
9943 * descriptive to the user than the name itself.
9945 * Returns: the display name of the application for @appinfo, or the name if no display name is available.
9951 * g_app_info_get_executable:
9952 * @appinfo: a #GAppInfo
9954 * Gets the executable's name for the installed application.
9956 * Returns: a string containing the @appinfo's application binaries name
9961 * g_app_info_get_fallback_for_type:
9962 * @content_type: the content type to find a #GAppInfo for
9964 * Gets a list of fallback #GAppInfos for a given content type, i.e.
9965 * those applications which claim to support the given content type
9966 * by MIME type subclassing and not directly.
9968 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error.
9974 * g_app_info_get_icon:
9975 * @appinfo: a #GAppInfo.
9977 * Gets the icon for the application.
9979 * Returns: (transfer none): the default #GIcon for @appinfo or %NULL if there is no default icon.
9984 * g_app_info_get_id:
9985 * @appinfo: a #GAppInfo.
9987 * Gets the ID of an application. An id is a string that
9988 * identifies the application. The exact format of the id is
9989 * platform dependent. For instance, on Unix this is the
9990 * desktop file id from the xdg menu specification.
9992 * Note that the returned ID may be %NULL, depending on how
9993 * the @appinfo has been constructed.
9995 * Returns: a string containing the application's ID.
10000 * g_app_info_get_name:
10001 * @appinfo: a #GAppInfo.
10003 * Gets the installed name of the application.
10005 * Returns: the name of the application for @appinfo.
10010 * g_app_info_get_recommended_for_type:
10011 * @content_type: the content type to find a #GAppInfo for
10013 * Gets a list of recommended #GAppInfos for a given content type, i.e.
10014 * those applications which claim to support the given content type exactly,
10015 * and not by MIME type subclassing.
10016 * Note that the first application of the list is the last used one, i.e.
10017 * the last one for which g_app_info_set_as_last_used_for_type() has been
10020 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error.
10026 * g_app_info_get_supported_types:
10027 * @appinfo: a #GAppInfo that can handle files
10029 * Retrieves the list of content types that @app_info claims to support.
10030 * If this information is not provided by the environment, this function
10031 * will return %NULL.
10032 * This function does not take in consideration associations added with
10033 * g_app_info_add_supports_type(), but only those exported directly by
10036 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): a list of content types.
10042 * g_app_info_launch:
10043 * @appinfo: a #GAppInfo
10044 * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
10045 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
10046 * @error: a #GError
10048 * Launches the application. Passes @files to the launched application
10049 * as arguments, using the optional @launch_context to get information
10050 * about the details of the launcher (like what screen it is on).
10051 * On error, @error will be set accordingly.
10053 * To launch the application without arguments pass a %NULL @files list.
10055 * Note that even if the launch is successful the application launched
10056 * can fail to start if it runs into problems during startup. There is
10057 * no way to detect this.
10059 * Some URIs can be changed when passed through a GFile (for instance
10060 * unsupported URIs with strange formats like mailto:), so if you have
10061 * a textual URI you want to pass in as argument, consider using
10062 * g_app_info_launch_uris() instead.
10064 * The launched application inherits the environment of the launching
10065 * process, but it can be modified with g_app_launch_context_setenv() and
10066 * g_app_launch_context_unsetenv().
10068 * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
10069 * environment variable with the path of the launched desktop file and
10070 * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
10071 * id of the launched process. This can be used to ignore
10072 * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
10073 * by further processes. The <envar>DISPLAY</envar> and
10074 * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
10075 * set, based on information provided in @launch_context.
10077 * Returns: %TRUE on successful launch, %FALSE otherwise.
10082 * g_app_info_launch_default_for_uri:
10083 * @uri: the uri to show
10084 * @launch_context: (allow-none): an optional #GAppLaunchContext.
10085 * @error: a #GError.
10087 * Utility function that launches the default application
10088 * registered to handle the specified uri. Synchronous I/O
10089 * is done on the uri to detect the type of the file if
10092 * Returns: %TRUE on success, %FALSE on error.
10097 * g_app_info_launch_uris:
10098 * @appinfo: a #GAppInfo
10099 * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
10100 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
10101 * @error: a #GError
10103 * Launches the application. This passes the @uris to the launched application
10104 * as arguments, using the optional @launch_context to get information
10105 * about the details of the launcher (like what screen it is on).
10106 * On error, @error will be set accordingly.
10108 * To launch the application without arguments pass a %NULL @uris list.
10110 * Note that even if the launch is successful the application launched
10111 * can fail to start if it runs into problems during startup. There is
10112 * no way to detect this.
10114 * Returns: %TRUE on successful launch, %FALSE otherwise.
10119 * g_app_info_remove_supports_type:
10120 * @appinfo: a #GAppInfo.
10121 * @content_type: a string.
10122 * @error: a #GError.
10124 * Removes a supported type from an application, if possible.
10126 * Returns: %TRUE on success, %FALSE on error.
10131 * g_app_info_reset_type_associations:
10132 * @content_type: a content type
10134 * Removes all changes to the type associations done by
10135 * g_app_info_set_as_default_for_type(),
10136 * g_app_info_set_as_default_for_extension(),
10137 * g_app_info_add_supports_type() or
10138 * g_app_info_remove_supports_type().
10145 * g_app_info_set_as_default_for_extension:
10146 * @appinfo: a #GAppInfo.
10147 * @extension: a string containing the file extension (without the dot).
10148 * @error: a #GError.
10150 * Sets the application as the default handler for the given file extension.
10152 * Returns: %TRUE on success, %FALSE on error.
10157 * g_app_info_set_as_default_for_type:
10158 * @appinfo: a #GAppInfo.
10159 * @content_type: the content type.
10160 * @error: a #GError.
10162 * Sets the application as the default handler for a given type.
10164 * Returns: %TRUE on success, %FALSE on error.
10169 * g_app_info_set_as_last_used_for_type:
10170 * @appinfo: a #GAppInfo.
10171 * @content_type: the content type.
10172 * @error: a #GError.
10174 * Sets the application as the last used application for a given type.
10175 * This will make the application appear as first in the list returned
10176 * by g_app_info_get_recommended_for_type(), regardless of the default
10177 * application for that content type.
10179 * Returns: %TRUE on success, %FALSE on error.
10184 * g_app_info_should_show:
10185 * @appinfo: a #GAppInfo.
10187 * Checks if the application info should be shown in menus that
10188 * list available applications.
10190 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
10195 * g_app_info_supports_files:
10196 * @appinfo: a #GAppInfo.
10198 * Checks if the application accepts files as arguments.
10200 * Returns: %TRUE if the @appinfo supports files.
10205 * g_app_info_supports_uris:
10206 * @appinfo: a #GAppInfo.
10208 * Checks if the application supports reading files and directories from URIs.
10210 * Returns: %TRUE if the @appinfo supports URIs.
10215 * g_app_launch_context_get_display:
10216 * @context: a #GAppLaunchContext
10217 * @info: a #GAppInfo
10218 * @files: (element-type GFile): a #GList of #GFile objects
10220 * Gets the display string for the @context. This is used to ensure new
10221 * applications are started on the same display as the launching
10222 * application, by setting the <envar>DISPLAY</envar> environment variable.
10224 * Returns: a display string for the display.
10229 * g_app_launch_context_get_environment:
10230 * @context: a #GAppLaunchContext
10232 * Gets the complete environment variable list to be passed to
10233 * the child process when @context is used to launch an application.
10234 * This is a %NULL-terminated array of strings, where each string has
10235 * the form <literal>KEY=VALUE</literal>.
10237 * Returns: (array zero-terminated=1) (transfer full): the child's environment
10243 * g_app_launch_context_get_startup_notify_id:
10244 * @context: a #GAppLaunchContext
10245 * @info: a #GAppInfo
10246 * @files: (element-type GFile): a #GList of of #GFile objects
10248 * Initiates startup notification for the application and returns the
10249 * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
10252 * Startup notification IDs are defined in the <ulink
10253 * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
10254 * FreeDesktop.Org Startup Notifications standard</ulink>.
10256 * Returns: a startup notification ID for the application, or %NULL if not supported.
10261 * g_app_launch_context_launch_failed:
10262 * @context: a #GAppLaunchContext.
10263 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
10265 * Called when an application has failed to launch, so that it can cancel
10266 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
10271 * g_app_launch_context_new:
10273 * Creates a new application launch context. This is not normally used,
10274 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
10276 * Returns: a #GAppLaunchContext.
10281 * g_app_launch_context_setenv:
10282 * @context: a #GAppLaunchContext
10283 * @variable: the environment variable to set
10284 * @value: the value for to set the variable to.
10286 * Arranges for @variable to be set to @value in the child's
10287 * environment when @context is used to launch an application.
10294 * g_app_launch_context_unsetenv:
10295 * @context: a #GAppLaunchContext
10296 * @variable: the environment variable to remove
10298 * Arranges for @variable to be unset in the child's environment
10299 * when @context is used to launch an application.
10306 * g_application_activate:
10307 * @application: a #GApplication
10309 * Activates the application.
10311 * In essence, this results in the #GApplication::activate signal being
10312 * emitted in the primary instance.
10314 * The application must be registered before calling this function.
10321 * g_application_command_line_get_arguments:
10322 * @cmdline: a #GApplicationCommandLine
10323 * @argc: (out) (allow-none): the length of the arguments array, or %NULL
10325 * Gets the list of arguments that was passed on the command line.
10327 * The strings in the array may contain non-utf8 data.
10329 * The return value is %NULL-terminated and should be freed using
10332 * Returns: (array length=argc) (transfer full): the string array containing the arguments (the argv)
10338 * g_application_command_line_get_cwd:
10339 * @cmdline: a #GApplicationCommandLine
10341 * Gets the working directory of the command line invocation.
10342 * The string may contain non-utf8 data.
10344 * It is possible that the remote application did not send a working
10345 * directory, so this may be %NULL.
10347 * The return value should not be modified or freed and is valid for as
10348 * long as @cmdline exists.
10350 * Returns: the current directory, or %NULL
10356 * g_application_command_line_get_environ:
10357 * @cmdline: a #GApplicationCommandLine
10359 * Gets the contents of the 'environ' variable of the command line
10360 * invocation, as would be returned by g_get_environ(), ie as a
10361 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
10362 * The strings may contain non-utf8 data.
10364 * The remote application usually does not send an environment. Use
10365 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
10366 * set it is possible that the environment is still not available (due
10367 * to invocation messages from other applications).
10369 * The return value should not be modified or freed and is valid for as
10370 * long as @cmdline exists.
10372 * See g_application_command_line_getenv() if you are only interested
10373 * in the value of a single environment variable.
10375 * Returns: (array zero-terminated=1) (transfer none): the environment strings, or %NULL if they were not sent
10381 * g_application_command_line_get_exit_status:
10382 * @cmdline: a #GApplicationCommandLine
10384 * Gets the exit status of @cmdline. See
10385 * g_application_command_line_set_exit_status() for more information.
10387 * Returns: the exit status
10393 * g_application_command_line_get_is_remote:
10394 * @cmdline: a #GApplicationCommandLine
10396 * Determines if @cmdline represents a remote invocation.
10398 * Returns: %TRUE if the invocation was remote
10404 * g_application_command_line_get_platform_data:
10405 * @cmdline: #GApplicationCommandLine
10407 * Gets the platform data associated with the invocation of @cmdline.
10409 * This is a #GVariant dictionary containing information about the
10410 * context in which the invocation occurred. It typically contains
10411 * information like the current working directory and the startup
10414 * For local invocation, it will be %NULL.
10416 * Returns: (allow-none): the platform data, or %NULL
10422 * g_application_command_line_getenv:
10423 * @cmdline: a #GApplicationCommandLine
10424 * @name: the environment variable to get
10426 * Gets the value of a particular environment variable of the command
10427 * line invocation, as would be returned by g_getenv(). The strings may
10428 * contain non-utf8 data.
10430 * The remote application usually does not send an environment. Use
10431 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
10432 * set it is possible that the environment is still not available (due
10433 * to invocation messages from other applications).
10435 * The return value should not be modified or freed and is valid for as
10436 * long as @cmdline exists.
10438 * Returns: the value of the variable, or %NULL if unset or unsent
10444 * g_application_command_line_print:
10445 * @cmdline: a #GApplicationCommandLine
10446 * @format: a printf-style format string
10447 * @...: arguments, as per @format
10449 * Formats a message and prints it using the stdout print handler in the
10450 * invoking process.
10452 * If @cmdline is a local invocation then this is exactly equivalent to
10453 * g_print(). If @cmdline is remote then this is equivalent to calling
10454 * g_print() in the invoking process.
10461 * g_application_command_line_printerr:
10462 * @cmdline: a #GApplicationCommandLine
10463 * @format: a printf-style format string
10464 * @...: arguments, as per @format
10466 * Formats a message and prints it using the stderr print handler in the
10467 * invoking process.
10469 * If @cmdline is a local invocation then this is exactly equivalent to
10470 * g_printerr(). If @cmdline is remote then this is equivalent to
10471 * calling g_printerr() in the invoking process.
10478 * g_application_command_line_set_exit_status:
10479 * @cmdline: a #GApplicationCommandLine
10480 * @exit_status: the exit status
10482 * Sets the exit status that will be used when the invoking process
10485 * The return value of the #GApplication::command-line signal is
10486 * passed to this function when the handler returns. This is the usual
10487 * way of setting the exit status.
10489 * In the event that you want the remote invocation to continue running
10490 * and want to decide on the exit status in the future, you can use this
10491 * call. For the case of a remote invocation, the remote process will
10492 * typically exit when the last reference is dropped on @cmdline. The
10493 * exit status of the remote process will be equal to the last value
10494 * that was set with this function.
10496 * In the case that the commandline invocation is local, the situation
10497 * is slightly more complicated. If the commandline invocation results
10498 * in the mainloop running (ie: because the use-count of the application
10499 * increased to a non-zero value) then the application is considered to
10500 * have been 'successful' in a certain sense, and the exit status is
10501 * always zero. If the application use count is zero, though, the exit
10502 * status of the local #GApplicationCommandLine is used.
10509 * g_application_get_application_id:
10510 * @application: a #GApplication
10512 * Gets the unique identifier for @application.
10514 * Returns: the identifier for @application, owned by @application
10520 * g_application_get_dbus_connection:
10521 * @application: a #GApplication
10523 * Gets the #GDBusConnection being used by the application, or %NULL.
10525 * If #GApplication is using its D-Bus backend then this function will
10526 * return the #GDBusConnection being used for uniqueness and
10527 * communication with the desktop environment and other instances of the
10530 * If #GApplication is not using D-Bus then this function will return
10531 * %NULL. This includes the situation where the D-Bus backend would
10532 * normally be in use but we were unable to connect to the bus.
10534 * This function must not be called before the application has been
10535 * registered. See g_application_get_is_registered().
10537 * Returns: (transfer none): a #GDBusConnection, or %NULL
10543 * g_application_get_dbus_object_path:
10544 * @application: a #GApplication
10546 * Gets the D-Bus object path being used by the application, or %NULL.
10548 * If #GApplication is using its D-Bus backend then this function will
10549 * return the D-Bus object path that #GApplication is using. If the
10550 * application is the primary instance then there is an object published
10551 * at this path. If the application is not the primary instance then
10552 * the result of this function is undefined.
10554 * If #GApplication is not using D-Bus then this function will return
10555 * %NULL. This includes the situation where the D-Bus backend would
10556 * normally be in use but we were unable to connect to the bus.
10558 * This function must not be called before the application has been
10559 * registered. See g_application_get_is_registered().
10561 * Returns: the object path, or %NULL
10567 * g_application_get_default:
10569 * Returns the default #GApplication instance for this process.
10571 * Normally there is only one #GApplication per process and it becomes
10572 * the default when it is created. You can exercise more control over
10573 * this by using g_application_set_default().
10575 * If there is no default application then %NULL is returned.
10577 * Returns: (transfer none): the default application for this process, or %NULL
10583 * g_application_get_flags:
10584 * @application: a #GApplication
10586 * Gets the flags for @application.
10588 * See #GApplicationFlags.
10590 * Returns: the flags for @application
10596 * g_application_get_inactivity_timeout:
10597 * @application: a #GApplication
10599 * Gets the current inactivity timeout for the application.
10601 * This is the amount of time (in milliseconds) after the last call to
10602 * g_application_release() before the application stops running.
10604 * Returns: the timeout, in milliseconds
10610 * g_application_get_is_registered:
10611 * @application: a #GApplication
10613 * Checks if @application is registered.
10615 * An application is registered if g_application_register() has been
10616 * successfully called.
10618 * Returns: %TRUE if @application is registered
10624 * g_application_get_is_remote:
10625 * @application: a #GApplication
10627 * Checks if @application is remote.
10629 * If @application is remote then it means that another instance of
10630 * application already exists (the 'primary' instance). Calls to
10631 * perform actions on @application will result in the actions being
10632 * performed by the primary instance.
10634 * The value of this property cannot be accessed before
10635 * g_application_register() has been called. See
10636 * g_application_get_is_registered().
10638 * Returns: %TRUE if @application is remote
10644 * g_application_hold:
10645 * @application: a #GApplication
10647 * Increases the use count of @application.
10649 * Use this function to indicate that the application has a reason to
10650 * continue to run. For example, g_application_hold() is called by GTK+
10651 * when a toplevel window is on the screen.
10653 * To cancel the hold, call g_application_release().
10658 * g_application_id_is_valid:
10659 * @application_id: a potential application identifier
10661 * Checks if @application_id is a valid application identifier.
10663 * A valid ID is required for calls to g_application_new() and
10664 * g_application_set_application_id().
10666 * For convenience, the restrictions on application identifiers are
10669 * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
10670 * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
10671 * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
10672 * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
10673 * <listitem>Application identifiers must not exceed 255 characters.</listitem>
10676 * Returns: %TRUE if @application_id is valid
10681 * g_application_new:
10682 * @application_id: (allow-none): the application id
10683 * @flags: the application flags
10685 * Creates a new #GApplication instance.
10687 * If non-%NULL, the application id must be valid. See
10688 * g_application_id_is_valid().
10690 * If no application ID is given then some features of #GApplication
10691 * (most notably application uniqueness) will be disabled.
10693 * Returns: a new #GApplication instance
10698 * g_application_open:
10699 * @application: a #GApplication
10700 * @files: (array length=n_files): an array of #GFiles to open
10701 * @n_files: the length of the @files array
10702 * @hint: a hint (or ""), but never %NULL
10704 * Opens the given files.
10706 * In essence, this results in the #GApplication::open signal being emitted
10707 * in the primary instance.
10709 * @n_files must be greater than zero.
10711 * @hint is simply passed through to the ::open signal. It is
10712 * intended to be used by applications that have multiple modes for
10713 * opening files (eg: "view" vs "edit", etc). Unless you have a need
10714 * for this functionality, you should use "".
10716 * The application must be registered before calling this function
10717 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
10724 * g_application_quit:
10725 * @application: a #GApplication
10727 * Immediately quits the application.
10729 * Upon return to the mainloop, g_application_run() will return,
10730 * calling only the 'shutdown' function before doing so.
10732 * The hold count is ignored.
10734 * The result of calling g_application_run() again after it returns is
10742 * g_application_register:
10743 * @application: a #GApplication
10744 * @cancellable: (allow-none): a #GCancellable, or %NULL
10745 * @error: a pointer to a NULL #GError, or %NULL
10747 * Attempts registration of the application.
10749 * This is the point at which the application discovers if it is the
10750 * primary instance or merely acting as a remote for an already-existing
10751 * primary instance. This is implemented by attempting to acquire the
10752 * application identifier as a unique bus name on the session bus using
10755 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
10756 * given, then this process will always become the primary instance.
10758 * Due to the internal architecture of GDBus, method calls can be
10759 * dispatched at any time (even if a main loop is not running). For
10760 * this reason, you must ensure that any object paths that you wish to
10761 * register are registered before calling this function.
10763 * If the application has already been registered then %TRUE is
10764 * returned with no work performed.
10766 * The #GApplication::startup signal is emitted if registration succeeds
10767 * and @application is the primary instance (including the non-unique
10770 * In the event of an error (such as @cancellable being cancelled, or a
10771 * failure to connect to the session bus), %FALSE is returned and @error
10772 * is set appropriately.
10774 * Note: the return value of this function is not an indicator that this
10775 * instance is or is not the primary instance of the application. See
10776 * g_application_get_is_remote() for that.
10778 * Returns: %TRUE if registration succeeded
10784 * g_application_release:
10785 * @application: a #GApplication
10787 * Decrease the use count of @application.
10789 * When the use count reaches zero, the application will stop running.
10791 * Never call this function except to cancel the effect of a previous
10792 * call to g_application_hold().
10797 * g_application_run:
10798 * @application: a #GApplication
10799 * @argc: the argc from main() (or 0 if @argv is %NULL)
10800 * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
10802 * Runs the application.
10804 * This function is intended to be run from main() and its return value
10805 * is intended to be returned by main(). Although you are expected to pass
10806 * the @argc, @argv parameters from main() to this function, it is possible
10807 * to pass %NULL if @argv is not available or commandline handling is not
10810 * First, the local_command_line() virtual function is invoked.
10811 * This function always runs on the local instance. It gets passed a pointer
10812 * to a %NULL-terminated copy of @argv and is expected to remove the arguments
10813 * that it handled (shifting up remaining arguments). See
10814 * <xref linkend="gapplication-example-cmdline2"/> for an example of
10815 * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
10816 * after setting <literal>argc = g_strv_length (argv);</literal>.
10818 * The last argument to local_command_line() is a pointer to the @status
10819 * variable which can used to set the exit status that is returned from
10820 * g_application_run().
10822 * If local_command_line() returns %TRUE, the command line is expected
10823 * to be completely handled, including possibly registering as the primary
10824 * instance, calling g_application_activate() or g_application_open(), etc.
10826 * If local_command_line() returns %FALSE then the application is registered
10827 * and the #GApplication::command-line signal is emitted in the primary
10828 * instance (which may or may not be this instance). The signal handler
10829 * gets passed a #GApplicationCommandLine object that (among other things)
10830 * contains the remaining commandline arguments that have not been handled
10831 * by local_command_line().
10833 * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
10834 * flag set then the default implementation of local_command_line()
10835 * always returns %FALSE immediately, resulting in the commandline
10836 * always being handled in the primary instance.
10838 * Otherwise, the default implementation of local_command_line() tries
10839 * to do a couple of things that are probably reasonable for most
10840 * applications. First, g_application_register() is called to attempt
10841 * to register the application. If that works, then the command line
10842 * arguments are inspected. If no commandline arguments are given, then
10843 * g_application_activate() is called. If commandline arguments are
10844 * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
10845 * are assumed to be filenames and g_application_open() is called.
10847 * If you need to handle commandline arguments that are not filenames,
10848 * and you don't mind commandline handling to happen in the primary
10849 * instance, you should set %G_APPLICATION_HANDLES_COMMAND_LINE and
10850 * process the commandline arguments in your #GApplication::command-line
10851 * signal handler, either manually or using the #GOptionContext API.
10853 * If you are interested in doing more complicated local handling of the
10854 * commandline then you should implement your own #GApplication subclass
10855 * and override local_command_line(). In this case, you most likely want
10856 * to return %TRUE from your local_command_line() implementation to
10857 * suppress the default handling. See
10858 * <xref linkend="gapplication-example-cmdline2"/> for an example.
10860 * If, after the above is done, the use count of the application is zero
10861 * then the exit status is returned immediately. If the use count is
10862 * non-zero then the default main context is iterated until the use count
10863 * falls to zero, at which point 0 is returned.
10865 * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
10866 * use count of zero is delayed for a while (ie: the instance stays
10867 * around to provide its <emphasis>service</emphasis> to others).
10869 * Returns: the exit status
10875 * g_application_set_action_group:
10876 * @application: a #GApplication
10877 * @action_group: (allow-none): a #GActionGroup, or %NULL
10879 * This used to be how actions were associated with a #GApplication.
10880 * Now there is #GActionMap for that.
10883 * Deprecated: 2.32:Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead.
10888 * g_application_set_application_id:
10889 * @application: a #GApplication
10890 * @application_id: (allow-none): the identifier for @application
10892 * Sets the unique identifier for @application.
10894 * The application id can only be modified if @application has not yet
10897 * If non-%NULL, the application id must be valid. See
10898 * g_application_id_is_valid().
10905 * g_application_set_default:
10906 * @application: (allow-none): the application to set as default, or %NULL
10908 * Sets or unsets the default application for the process, as returned
10909 * by g_application_get_default().
10911 * This function does not take its own reference on @application. If
10912 * @application is destroyed then the default application will revert
10920 * g_application_set_flags:
10921 * @application: a #GApplication
10922 * @flags: the flags for @application
10924 * Sets the flags for @application.
10926 * The flags can only be modified if @application has not yet been
10929 * See #GApplicationFlags.
10936 * g_application_set_inactivity_timeout:
10937 * @application: a #GApplication
10938 * @inactivity_timeout: the timeout, in milliseconds
10940 * Sets the current inactivity timeout for the application.
10942 * This is the amount of time (in milliseconds) after the last call to
10943 * g_application_release() before the application stops running.
10945 * This call has no side effects of its own. The value set here is only
10946 * used for next time g_application_release() drops the use count to
10947 * zero. Any timeouts currently in progress are not impacted.
10954 * g_async_initable_init_async:
10955 * @initable: a #GAsyncInitable.
10956 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
10957 * @cancellable: optional #GCancellable object, %NULL to ignore.
10958 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
10959 * @user_data: the data to pass to callback function
10961 * Starts asynchronous initialization of the object implementing the
10962 * interface. This must be done before any real use of the object after
10963 * initial construction. If the object also implements #GInitable you can
10964 * optionally call g_initable_init() instead.
10966 * When the initialization is finished, @callback will be called. You can
10967 * then call g_async_initable_init_finish() to get the result of the
10970 * Implementations may also support cancellation. If @cancellable is not
10971 * %NULL, then initialization can be cancelled by triggering the cancellable
10972 * object from another thread. If the operation was cancelled, the error
10973 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
10974 * the object doesn't support cancellable initialization, the error
10975 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
10977 * As with #GInitable, if the object is not initialized, or initialization
10978 * returns with an error, then all operations on the object except
10979 * g_object_ref() and g_object_unref() are considered to be invalid, and
10980 * have undefined behaviour. They will often fail with g_critical() or
10981 * g_warning(), but this must not be relied on.
10983 * Implementations of this method must be idempotent: i.e. multiple calls
10984 * to this function with the same argument should return the same results.
10985 * Only the first call initializes the object; further calls return the result
10986 * of the first call. This is so that it's safe to implement the singleton
10987 * pattern in the GObject constructor function.
10989 * For classes that also support the #GInitable interface, the default
10990 * implementation of this method will run the g_initable_init() function
10991 * in a thread, so if you want to support asynchronous initialization via
10992 * threads, just implement the #GAsyncInitable interface without overriding
10993 * any interface methods.
11000 * g_async_initable_init_finish:
11001 * @initable: a #GAsyncInitable.
11002 * @res: a #GAsyncResult.
11003 * @error: a #GError location to store the error occurring, or %NULL to ignore.
11005 * Finishes asynchronous initialization and returns the result.
11006 * See g_async_initable_init_async().
11008 * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
11014 * g_async_initable_new_async:
11015 * @object_type: a #GType supporting #GAsyncInitable.
11016 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
11017 * @cancellable: optional #GCancellable object, %NULL to ignore.
11018 * @callback: a #GAsyncReadyCallback to call when the initialization is finished
11019 * @user_data: the data to pass to callback function
11020 * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties
11021 * @...: the value of the first property, followed by other property value pairs, and ended by %NULL.
11023 * Helper function for constructing #GAsyncInitable object. This is
11024 * similar to g_object_new() but also initializes the object asynchronously.
11026 * When the initialization is finished, @callback will be called. You can
11027 * then call g_async_initable_new_finish() to get the new object and check
11035 * g_async_initable_new_finish:
11036 * @initable: the #GAsyncInitable from the callback
11037 * @res: the #GAsyncResult from the callback
11038 * @error: return location for errors, or %NULL to ignore
11040 * Finishes the async construction for the various g_async_initable_new
11041 * calls, returning the created object or %NULL on error.
11043 * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref().
11049 * g_async_initable_new_valist_async:
11050 * @object_type: a #GType supporting #GAsyncInitable.
11051 * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL.
11052 * @var_args: The var args list generated from @first_property_name.
11053 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
11054 * @cancellable: optional #GCancellable object, %NULL to ignore.
11055 * @callback: a #GAsyncReadyCallback to call when the initialization is finished
11056 * @user_data: the data to pass to callback function
11058 * Helper function for constructing #GAsyncInitable object. This is
11059 * similar to g_object_new_valist() but also initializes the object
11062 * When the initialization is finished, @callback will be called. You can
11063 * then call g_async_initable_new_finish() to get the new object and check
11071 * g_async_initable_newv_async:
11072 * @object_type: a #GType supporting #GAsyncInitable.
11073 * @n_parameters: the number of parameters in @parameters
11074 * @parameters: the parameters to use to construct the object
11075 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
11076 * @cancellable: optional #GCancellable object, %NULL to ignore.
11077 * @callback: a #GAsyncReadyCallback to call when the initialization is finished
11078 * @user_data: the data to pass to callback function
11080 * Helper function for constructing #GAsyncInitable object. This is
11081 * similar to g_object_newv() but also initializes the object asynchronously.
11083 * When the initialization is finished, @callback will be called. You can
11084 * then call g_async_initable_new_finish() to get the new object and check
11092 * g_async_result_get_source_object:
11093 * @res: a #GAsyncResult
11095 * Gets the source object from a #GAsyncResult.
11097 * Returns: (transfer full): a new reference to the source object for the @res, or %NULL if there is none.
11102 * g_async_result_get_user_data:
11103 * @res: a #GAsyncResult.
11105 * Gets the user data from a #GAsyncResult.
11107 * Returns: (transfer full): the user data for @res.
11112 * g_async_result_is_tagged:
11113 * @res: a #GAsyncResult
11114 * @source_tag: an application-defined tag
11116 * Checks if @res has the given @source_tag (generally a function
11117 * pointer indicating the function @res was created by).
11119 * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if not.
11125 * g_async_result_legacy_propagate_error:
11126 * @res: a #GAsyncResult
11127 * @error: (out): a location to propagate the error to.
11129 * If @res is a #GSimpleAsyncResult, this is equivalent to
11130 * g_simple_async_result_propagate_error(). Otherwise it returns
11133 * This can be used for legacy error handling in async
11134 * <literal>_finish ()</literal> wrapper functions that traditionally
11135 * handled #GSimpleAsyncResult error returns themselves rather than
11136 * calling into the virtual method. This should not be used in new
11137 * code; #GAsyncResult errors that are set by virtual methods should
11138 * also be extracted by virtual methods, to enable subclasses to chain
11141 * Returns: %TRUE if @error is has been filled in with an error from @res, %FALSE if not.
11147 * g_buffered_input_stream_fill:
11148 * @stream: a #GBufferedInputStream
11149 * @count: the number of bytes that will be read from the stream
11150 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
11151 * @error: location to store the error occurring, or %NULL to ignore
11153 * Tries to read @count bytes from the stream into the buffer.
11154 * Will block during this read.
11156 * If @count is zero, returns zero and does nothing. A value of @count
11157 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
11159 * On success, the number of bytes read into the buffer is returned.
11160 * It is not an error if this is not the same as the requested size, as it
11161 * can happen e.g. near the end of a file. Zero is returned on end of file
11162 * (or if @count is zero), but never otherwise.
11164 * If @count is -1 then the attempted read size is equal to the number of
11165 * bytes that are required to fill the buffer.
11167 * If @cancellable is not %NULL, then the operation can be cancelled by
11168 * triggering the cancellable object from another thread. If the operation
11169 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
11170 * operation was partially finished when the operation was cancelled the
11171 * partial result will be returned, without an error.
11173 * On error -1 is returned and @error is set accordingly.
11175 * For the asynchronous, non-blocking, version of this function, see
11176 * g_buffered_input_stream_fill_async().
11178 * Returns: the number of bytes read into @stream's buffer, up to @count, or -1 on error.
11183 * g_buffered_input_stream_fill_async:
11184 * @stream: a #GBufferedInputStream
11185 * @count: the number of bytes that will be read from the stream
11186 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
11187 * @cancellable: (allow-none): optional #GCancellable object
11188 * @callback: (scope async): a #GAsyncReadyCallback
11189 * @user_data: (closure): a #gpointer
11191 * Reads data into @stream's buffer asynchronously, up to @count size.
11192 * @io_priority can be used to prioritize reads. For the synchronous
11193 * version of this function, see g_buffered_input_stream_fill().
11195 * If @count is -1 then the attempted read size is equal to the number
11196 * of bytes that are required to fill the buffer.
11201 * g_buffered_input_stream_fill_finish:
11202 * @stream: a #GBufferedInputStream
11203 * @result: a #GAsyncResult
11204 * @error: a #GError
11206 * Finishes an asynchronous read.
11208 * Returns: a #gssize of the read stream, or %-1 on an error.
11213 * g_buffered_input_stream_get_available:
11214 * @stream: #GBufferedInputStream
11216 * Gets the size of the available data within the stream.
11218 * Returns: size of the available stream.
11223 * g_buffered_input_stream_get_buffer_size:
11224 * @stream: a #GBufferedInputStream
11226 * Gets the size of the input buffer.
11228 * Returns: the current buffer size.
11233 * g_buffered_input_stream_new:
11234 * @base_stream: a #GInputStream
11236 * Creates a new #GInputStream from the given @base_stream, with
11237 * a buffer set to the default size (4 kilobytes).
11239 * Returns: a #GInputStream for the given @base_stream.
11244 * g_buffered_input_stream_new_sized:
11245 * @base_stream: a #GInputStream
11248 * Creates a new #GBufferedInputStream from the given @base_stream,
11249 * with a buffer set to @size.
11251 * Returns: a #GInputStream.
11256 * g_buffered_input_stream_peek:
11257 * @stream: a #GBufferedInputStream
11258 * @buffer: (array length=count) (element-type guint8): a pointer to an allocated chunk of memory
11259 * @offset: a #gsize
11262 * Peeks in the buffer, copying data of size @count into @buffer,
11263 * offset @offset bytes.
11265 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
11270 * g_buffered_input_stream_peek_buffer:
11271 * @stream: a #GBufferedInputStream
11272 * @count: (out): a #gsize to get the number of bytes available in the buffer
11274 * Returns the buffer with the currently available bytes. The returned
11275 * buffer must not be modified and will become invalid when reading from
11276 * the stream or filling the buffer.
11278 * Returns: (array length=count) (element-type guint8) (transfer none): read-only buffer
11283 * g_buffered_input_stream_read_byte:
11284 * @stream: a #GBufferedInputStream
11285 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
11286 * @error: location to store the error occurring, or %NULL to ignore
11288 * Tries to read a single byte from the stream or the buffer. Will block
11289 * during this read.
11291 * On success, the byte read from the stream is returned. On end of stream
11292 * -1 is returned but it's not an exceptional error and @error is not set.
11294 * If @cancellable is not %NULL, then the operation can be cancelled by
11295 * triggering the cancellable object from another thread. If the operation
11296 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
11297 * operation was partially finished when the operation was cancelled the
11298 * partial result will be returned, without an error.
11300 * On error -1 is returned and @error is set accordingly.
11302 * Returns: the byte read from the @stream, or -1 on end of stream or error.
11307 * g_buffered_input_stream_set_buffer_size:
11308 * @stream: a #GBufferedInputStream
11311 * Sets the size of the internal buffer of @stream to @size, or to the
11312 * size of the contents of the buffer. The buffer can never be resized
11313 * smaller than its current contents.
11318 * g_buffered_output_stream_get_auto_grow:
11319 * @stream: a #GBufferedOutputStream.
11321 * Checks if the buffer automatically grows as data is added.
11323 * Returns: %TRUE if the @stream's buffer automatically grows, %FALSE otherwise.
11328 * g_buffered_output_stream_get_buffer_size:
11329 * @stream: a #GBufferedOutputStream.
11331 * Gets the size of the buffer in the @stream.
11333 * Returns: the current size of the buffer.
11338 * g_buffered_output_stream_new:
11339 * @base_stream: a #GOutputStream.
11341 * Creates a new buffered output stream for a base stream.
11343 * Returns: a #GOutputStream for the given @base_stream.
11348 * g_buffered_output_stream_new_sized:
11349 * @base_stream: a #GOutputStream.
11352 * Creates a new buffered output stream with a given buffer size.
11354 * Returns: a #GOutputStream with an internal buffer set to @size.
11359 * g_buffered_output_stream_set_auto_grow:
11360 * @stream: a #GBufferedOutputStream.
11361 * @auto_grow: a #gboolean.
11363 * Sets whether or not the @stream's buffer should automatically grow.
11364 * If @auto_grow is true, then each write will just make the buffer
11365 * larger, and you must manually flush the buffer to actually write out
11366 * the data to the underlying stream.
11371 * g_buffered_output_stream_set_buffer_size:
11372 * @stream: a #GBufferedOutputStream.
11375 * Sets the size of the internal buffer to @size.
11381 * @bus_type: A #GBusType.
11382 * @cancellable: (allow-none): A #GCancellable or %NULL.
11383 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
11384 * @user_data: The data to pass to @callback.
11386 * Asynchronously connects to the message bus specified by @bus_type.
11388 * When the operation is finished, @callback will be invoked. You can
11389 * then call g_bus_get_finish() to get the result of the operation.
11391 * This is a asynchronous failable function. See g_bus_get_sync() for
11392 * the synchronous version.
11399 * g_bus_get_finish:
11400 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
11401 * @error: Return location for error or %NULL.
11403 * Finishes an operation started with g_bus_get().
11405 * The returned object is a singleton, that is, shared with other
11406 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
11407 * event that you need a private message bus connection, use
11408 * g_dbus_address_get_for_bus_sync() and
11409 * g_dbus_connection_new_for_address().
11411 * Note that the returned #GDBusConnection object will (usually) have
11412 * the #GDBusConnection:exit-on-close property set to %TRUE.
11414 * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
11421 * @bus_type: A #GBusType.
11422 * @cancellable: (allow-none): A #GCancellable or %NULL.
11423 * @error: Return location for error or %NULL.
11425 * Synchronously connects to the message bus specified by @bus_type.
11426 * Note that the returned object may shared with other callers,
11427 * e.g. if two separate parts of a process calls this function with
11428 * the same @bus_type, they will share the same object.
11430 * This is a synchronous failable function. See g_bus_get() and
11431 * g_bus_get_finish() for the asynchronous version.
11433 * The returned object is a singleton, that is, shared with other
11434 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
11435 * event that you need a private message bus connection, use
11436 * g_dbus_address_get_for_bus_sync() and
11437 * g_dbus_connection_new_for_address().
11439 * Note that the returned #GDBusConnection object will (usually) have
11440 * the #GDBusConnection:exit-on-close property set to %TRUE.
11442 * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
11449 * @bus_type: The type of bus to own a name on.
11450 * @name: The well-known name to own.
11451 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
11452 * @bus_acquired_handler: (allow-none): Handler to invoke when connected to the bus of type @bus_type or %NULL.
11453 * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL.
11454 * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL.
11455 * @user_data: User data to pass to handlers.
11456 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
11458 * Starts acquiring @name on the bus specified by @bus_type and calls
11459 * @name_acquired_handler and @name_lost_handler when the name is
11460 * acquired respectively lost. Callbacks will be invoked in the <link
11461 * linkend="g-main-context-push-thread-default">thread-default main
11462 * loop</link> of the thread you are calling this function from.
11464 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
11465 * callbacks will be invoked after calling this function - there are three
11469 * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
11470 * </para></listitem>
11472 * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
11473 * </para></listitem>
11475 * @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
11476 * </para></listitem>
11478 * When you are done owning the name, just call g_bus_unown_name()
11479 * with the owner id this function returns.
11481 * If the name is acquired or lost (for example another application
11482 * could acquire the name if you allow replacement or the application
11483 * currently owning the name exits), the handlers are also invoked. If the
11484 * #GDBusConnection that is used for attempting to own the name
11485 * closes, then @name_lost_handler is invoked since it is no
11486 * longer possible for other processes to access the process.
11488 * You cannot use g_bus_own_name() several times for the same name (unless
11489 * interleaved with calls to g_bus_unown_name()) - only the first call
11492 * Another guarantee is that invocations of @name_acquired_handler
11493 * and @name_lost_handler are guaranteed to alternate; that
11494 * is, if @name_acquired_handler is invoked then you are
11495 * guaranteed that the next time one of the handlers is invoked, it
11496 * will be @name_lost_handler. The reverse is also true.
11498 * If you plan on exporting objects (using e.g.
11499 * g_dbus_connection_register_object()), note that it is generally too late
11500 * to export the objects in @name_acquired_handler. Instead, you can do this
11501 * in @bus_acquired_handler since you are guaranteed that this will run
11502 * before @name is requested from the bus.
11504 * This behavior makes it very simple to write applications that wants
11505 * to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
11506 * Simply register objects to be exported in @bus_acquired_handler and
11507 * unregister the objects (if any) in @name_lost_handler.
11509 * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
11515 * g_bus_own_name_on_connection:
11516 * @connection: A #GDBusConnection.
11517 * @name: The well-known name to own.
11518 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
11519 * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL.
11520 * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL.
11521 * @user_data: User data to pass to handlers.
11522 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
11524 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
11527 * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
11533 * g_bus_own_name_on_connection_with_closures:
11534 * @connection: A #GDBusConnection.
11535 * @name: The well-known name to own.
11536 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
11537 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
11538 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
11540 * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
11541 * easier binding in other languages.
11543 * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
11544 * Rename to: g_bus_own_name_on_connection
11550 * g_bus_own_name_with_closures:
11551 * @bus_type: The type of bus to own a name on.
11552 * @name: The well-known name to own.
11553 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
11554 * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL.
11555 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
11556 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
11558 * Version of g_bus_own_name() using closures instead of callbacks for
11559 * easier binding in other languages.
11561 * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
11562 * Rename to: g_bus_own_name
11568 * g_bus_unown_name:
11569 * @owner_id: An identifier obtained from g_bus_own_name()
11571 * Stops owning a name.
11578 * g_bus_unwatch_name:
11579 * @watcher_id: An identifier obtained from g_bus_watch_name()
11581 * Stops watching a name.
11588 * g_bus_watch_name:
11589 * @bus_type: The type of bus to watch a name on.
11590 * @name: The name (well-known or unique) to watch.
11591 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
11592 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
11593 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
11594 * @user_data: User data to pass to handlers.
11595 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
11597 * Starts watching @name on the bus specified by @bus_type and calls
11598 * @name_appeared_handler and @name_vanished_handler when the name is
11599 * known to have a owner respectively known to lose its
11600 * owner. Callbacks will be invoked in the <link
11601 * linkend="g-main-context-push-thread-default">thread-default main
11602 * loop</link> of the thread you are calling this function from.
11604 * You are guaranteed that one of the handlers will be invoked after
11605 * calling this function. When you are done watching the name, just
11606 * call g_bus_unwatch_name() with the watcher id this function
11609 * If the name vanishes or appears (for example the application owning
11610 * the name could restart), the handlers are also invoked. If the
11611 * #GDBusConnection that is used for watching the name disconnects, then
11612 * @name_vanished_handler is invoked since it is no longer
11613 * possible to access the name.
11615 * Another guarantee is that invocations of @name_appeared_handler
11616 * and @name_vanished_handler are guaranteed to alternate; that
11617 * is, if @name_appeared_handler is invoked then you are
11618 * guaranteed that the next time one of the handlers is invoked, it
11619 * will be @name_vanished_handler. The reverse is also true.
11621 * This behavior makes it very simple to write applications that wants
11622 * to take action when a certain name exists, see <xref
11623 * linkend="gdbus-watching-names"/>. Basically, the application
11624 * should create object proxies in @name_appeared_handler and destroy
11625 * them again (if any) in @name_vanished_handler.
11627 * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
11633 * g_bus_watch_name_on_connection:
11634 * @connection: A #GDBusConnection.
11635 * @name: The name (well-known or unique) to watch.
11636 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
11637 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
11638 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
11639 * @user_data: User data to pass to handlers.
11640 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
11642 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
11645 * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
11651 * g_bus_watch_name_on_connection_with_closures:
11652 * @connection: A #GDBusConnection.
11653 * @name: The name (well-known or unique) to watch.
11654 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
11655 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
11656 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
11658 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
11659 * easier binding in other languages.
11661 * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
11662 * Rename to: g_bus_watch_name_on_connection
11668 * g_bus_watch_name_with_closures:
11669 * @bus_type: The type of bus to watch a name on.
11670 * @name: The name (well-known or unique) to watch.
11671 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
11672 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
11673 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
11675 * Version of g_bus_watch_name() using closures instead of callbacks for
11676 * easier binding in other languages.
11678 * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
11679 * Rename to: g_bus_watch_name
11685 * g_cancellable_cancel:
11686 * @cancellable: a #GCancellable object.
11688 * Will set @cancellable to cancelled, and will emit the
11689 * #GCancellable::cancelled signal. (However, see the warning about
11690 * race conditions in the documentation for that signal if you are
11691 * planning to connect to it.)
11693 * This function is thread-safe. In other words, you can safely call
11694 * it from a thread other than the one running the operation that was
11695 * passed the @cancellable.
11697 * The convention within gio is that cancelling an asynchronous
11698 * operation causes it to complete asynchronously. That is, if you
11699 * cancel the operation from the same thread in which it is running,
11700 * then the operation's #GAsyncReadyCallback will not be invoked until
11701 * the application returns to the main loop.
11706 * g_cancellable_connect:
11707 * @cancellable: A #GCancellable.
11708 * @callback: The #GCallback to connect.
11709 * @data: Data to pass to @callback.
11710 * @data_destroy_func: (allow-none): Free function for @data or %NULL.
11712 * Convenience function to connect to the #GCancellable::cancelled
11713 * signal. Also handles the race condition that may happen
11714 * if the cancellable is cancelled right before connecting.
11716 * @callback is called at most once, either directly at the
11717 * time of the connect if @cancellable is already cancelled,
11718 * or when @cancellable is cancelled in some thread.
11720 * @data_destroy_func will be called when the handler is
11721 * disconnected, or immediately if the cancellable is already
11724 * See #GCancellable::cancelled for details on how to use this.
11726 * Returns: The id of the signal handler or 0 if @cancellable has already been cancelled.
11732 * g_cancellable_disconnect:
11733 * @cancellable: (allow-none): A #GCancellable or %NULL.
11734 * @handler_id: Handler id of the handler to be disconnected, or %0.
11736 * Disconnects a handler from a cancellable instance similar to
11737 * g_signal_handler_disconnect(). Additionally, in the event that a
11738 * signal handler is currently running, this call will block until the
11739 * handler has finished. Calling this function from a
11740 * #GCancellable::cancelled signal handler will therefore result in a
11743 * This avoids a race condition where a thread cancels at the
11744 * same time as the cancellable operation is finished and the
11745 * signal handler is removed. See #GCancellable::cancelled for
11746 * details on how to use this.
11748 * If @cancellable is %NULL or @handler_id is %0 this function does
11756 * g_cancellable_get_current:
11758 * Gets the top cancellable from the stack.
11760 * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL if the stack is empty.
11765 * g_cancellable_get_fd:
11766 * @cancellable: a #GCancellable.
11768 * Gets the file descriptor for a cancellable job. This can be used to
11769 * implement cancellable operations on Unix systems. The returned fd will
11770 * turn readable when @cancellable is cancelled.
11772 * You are not supposed to read from the fd yourself, just check for
11773 * readable status. Reading to unset the readable status is done
11774 * with g_cancellable_reset().
11776 * After a successful return from this function, you should use
11777 * g_cancellable_release_fd() to free up resources allocated for
11778 * the returned file descriptor.
11780 * See also g_cancellable_make_pollfd().
11782 * Returns: A valid file descriptor. %-1 if the file descriptor is not supported, or on errors.
11787 * g_cancellable_is_cancelled:
11788 * @cancellable: (allow-none): a #GCancellable or %NULL
11790 * Checks if a cancellable job has been cancelled.
11792 * Returns: %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled.
11797 * g_cancellable_make_pollfd:
11798 * @cancellable: (allow-none): a #GCancellable or %NULL
11799 * @pollfd: a pointer to a #GPollFD
11801 * Creates a #GPollFD corresponding to @cancellable; this can be passed
11802 * to g_poll() and used to poll for cancellation. This is useful both
11803 * for unix systems without a native poll and for portability to
11806 * When this function returns %TRUE, you should use
11807 * g_cancellable_release_fd() to free up resources allocated for the
11808 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
11810 * If this function returns %FALSE, either no @cancellable was given or
11811 * resource limits prevent this function from allocating the necessary
11812 * structures for polling. (On Linux, you will likely have reached
11813 * the maximum number of file descriptors.) The suggested way to handle
11814 * these cases is to ignore the @cancellable.
11816 * You are not supposed to read from the fd yourself, just check for
11817 * readable status. Reading to unset the readable status is done
11818 * with g_cancellable_reset().
11820 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable.
11826 * g_cancellable_new:
11828 * Creates a new #GCancellable object.
11830 * Applications that want to start one or more operations
11831 * that should be cancellable should create a #GCancellable
11832 * and pass it to the operations.
11834 * One #GCancellable can be used in multiple consecutive
11835 * operations or in multiple concurrent operations.
11837 * Returns: a #GCancellable.
11842 * g_cancellable_pop_current:
11843 * @cancellable: a #GCancellable object
11845 * Pops @cancellable off the cancellable stack (verifying that @cancellable
11846 * is on the top of the stack).
11851 * g_cancellable_push_current:
11852 * @cancellable: a #GCancellable object
11854 * Pushes @cancellable onto the cancellable stack. The current
11855 * cancellable can then be received using g_cancellable_get_current().
11857 * This is useful when implementing cancellable operations in
11858 * code that does not allow you to pass down the cancellable object.
11860 * This is typically called automatically by e.g. #GFile operations,
11861 * so you rarely have to call this yourself.
11866 * g_cancellable_release_fd:
11867 * @cancellable: a #GCancellable
11869 * Releases a resources previously allocated by g_cancellable_get_fd()
11870 * or g_cancellable_make_pollfd().
11872 * For compatibility reasons with older releases, calling this function
11873 * is not strictly required, the resources will be automatically freed
11874 * when the @cancellable is finalized. However, the @cancellable will
11875 * block scarce file descriptors until it is finalized if this function
11876 * is not called. This can cause the application to run out of file
11877 * descriptors when many #GCancellables are used at the same time.
11884 * g_cancellable_reset:
11885 * @cancellable: a #GCancellable object.
11887 * Resets @cancellable to its uncancelled state.
11889 * If cancellable is currently in use by any cancellable operation
11890 * then the behavior of this function is undefined.
11895 * g_cancellable_set_error_if_cancelled:
11896 * @cancellable: (allow-none): a #GCancellable or %NULL
11897 * @error: #GError to append error state to
11899 * If the @cancellable is cancelled, sets the error to notify
11900 * that the operation was cancelled.
11902 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
11907 * g_cancellable_source_new: (skip)
11908 * @cancellable: (allow-none): a #GCancellable, or %NULL
11910 * Creates a source that triggers if @cancellable is cancelled and
11911 * calls its callback of type #GCancellableSourceFunc. This is
11912 * primarily useful for attaching to another (non-cancellable) source
11913 * with g_source_add_child_source() to add cancellability to it.
11915 * For convenience, you can call this with a %NULL #GCancellable,
11916 * in which case the source will never trigger.
11918 * Returns: (transfer full): the new #GSource.
11924 * g_charset_converter_get_num_fallbacks:
11925 * @converter: a #GCharsetConverter
11927 * Gets the number of fallbacks that @converter has applied so far.
11929 * Returns: the number of fallbacks that @converter has applied
11935 * g_charset_converter_get_use_fallback:
11936 * @converter: a #GCharsetConverter
11938 * Gets the #GCharsetConverter:use-fallback property.
11940 * Returns: %TRUE if fallbacks are used by @converter
11946 * g_charset_converter_new:
11947 * @to_charset: destination charset
11948 * @from_charset: source charset
11949 * @error: #GError for error reporting, or %NULL to ignore.
11951 * Creates a new #GCharsetConverter.
11953 * Returns: a new #GCharsetConverter or %NULL on error.
11959 * g_charset_converter_set_use_fallback:
11960 * @converter: a #GCharsetConverter
11961 * @use_fallback: %TRUE to use fallbacks
11963 * Sets the #GCharsetConverter:use-fallback property.
11970 * g_content_type_can_be_executable:
11971 * @type: a content type string
11973 * Checks if a content type can be executable. Note that for instance
11974 * things like text files can be executables (i.e. scripts and batch files).
11976 * Returns: %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise.
11981 * g_content_type_equals:
11982 * @type1: a content type string
11983 * @type2: a content type string
11985 * Compares two content types for equality.
11987 * Returns: %TRUE if the two strings are identical or equivalent, %FALSE otherwise.
11992 * g_content_type_from_mime_type:
11993 * @mime_type: a mime type string
11995 * Tries to find a content type based on the mime type name.
11997 * Returns: (allow-none): Newly allocated string with content type or %NULL. Free with g_free()
12003 * g_content_type_get_description:
12004 * @type: a content type string
12006 * Gets the human readable description of the content type.
12008 * Returns: a short description of the content type @type. Free the returned string with g_free()
12013 * g_content_type_get_generic_icon_name:
12014 * @type: a content type string
12016 * Gets the generic icon name for a content type.
12018 * See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
12019 * specification for more on the generic icon name.
12021 * Returns: (allow-none): the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free()
12027 * g_content_type_get_icon:
12028 * @type: a content type string
12030 * Gets the icon for a content type.
12032 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned object with g_object_unref()
12037 * g_content_type_get_mime_type:
12038 * @type: a content type string
12040 * Gets the mime type for the content type, if one is registered.
12042 * Returns: (allow-none): the registered mime type for the given @type, or %NULL if unknown.
12047 * g_content_type_get_symbolic_icon:
12048 * @type: a content type string
12050 * Gets the symbolic icon for a content type.
12052 * Returns: (transfer full): symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref()
12058 * g_content_type_guess:
12059 * @filename: (allow-none): a string, or %NULL
12060 * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
12061 * @data_size: the size of @data
12062 * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL
12064 * Guesses the content type based on example data. If the function is
12065 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
12066 * or @data may be %NULL, in which case the guess will be based solely
12067 * on the other argument.
12069 * Returns: a string indicating a guessed content type for the given data. Free with g_free()
12074 * g_content_type_guess_for_tree:
12075 * @root: the root of the tree to guess a type for
12077 * Tries to guess the type of the tree with root @root, by
12078 * looking at the files it contains. The result is an array
12079 * of content types, with the best guess coming first.
12081 * The types returned all have the form x-content/foo, e.g.
12082 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
12083 * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
12084 * specification for more on x-content types.
12086 * This function is useful in the implementation of
12087 * g_mount_guess_content_type().
12089 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated array of zero or more content types. Free with g_strfreev()
12095 * g_content_type_is_a:
12096 * @type: a content type string
12097 * @supertype: a content type string
12099 * Determines if @type is a subset of @supertype.
12101 * Returns: %TRUE if @type is a kind of @supertype, %FALSE otherwise.
12106 * g_content_type_is_unknown:
12107 * @type: a content type string
12109 * Checks if the content type is the generic "unknown" type.
12110 * On UNIX this is the "application/octet-stream" mimetype,
12111 * while on win32 it is "*".
12113 * Returns: %TRUE if the type is the unknown type.
12118 * g_content_types_get_registered:
12120 * Gets a list of strings containing all the registered content types
12121 * known to the system. The list and its data should be freed using
12123 * g_list_free_full (list, g_free);
12124 * </programlisting>
12126 * Returns: (element-type utf8) (transfer full): #GList of the registered content types
12131 * g_converter_convert:
12132 * @converter: a #GConverter.
12133 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert.
12134 * @inbuf_size: the number of bytes in @inbuf
12135 * @outbuf: a buffer to write converted data in.
12136 * @outbuf_size: the number of bytes in @outbuf, must be at least one
12137 * @flags: a #GConverterFlags controlling the conversion details
12138 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
12139 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
12140 * @error: location to store the error occurring, or %NULL to ignore
12142 * This is the main operation used when converting data. It is to be called
12143 * multiple times in a loop, and each time it will do some work, i.e.
12144 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
12145 * both. If its not possible to do any work an error is returned.
12147 * Note that a single call may not consume all input (or any input at all).
12148 * Also a call may produce output even if given no input, due to state stored
12149 * in the converter producing output.
12151 * If any data was either produced or consumed, and then an error happens, then
12152 * only the successful conversion is reported and the error is returned on the
12155 * A full conversion loop involves calling this method repeatedly, each time
12156 * giving it new input and space output space. When there is no more input
12157 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
12158 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
12159 * each time until all data is consumed and all output is produced, then
12160 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
12161 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
12162 * in a decompression converter where the end of data is detectable from the
12163 * data (and there might even be other data after the end of the compressed data).
12165 * When some data has successfully been converted @bytes_read and is set to
12166 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
12167 * how many bytes was written to @outbuf. If there are more data to output
12168 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
12169 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
12170 * then %G_CONVERTER_FINISHED is returned.
12172 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
12173 * Some errors need special handling:
12175 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
12176 * to write the resulting converted data, the application should
12177 * call the function again with a larger @outbuf to continue.
12179 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
12180 * input to fully determine what the conversion should produce,
12181 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
12182 * example with an incomplete multibyte sequence when converting text,
12183 * or when a regexp matches up to the end of the input (and may match
12184 * further input). It may also happen when @inbuf_size is zero and
12185 * there is no more data to produce.
12187 * When this happens the application should read more input and then
12188 * call the function again. If further input shows that there is no
12189 * more data call the function again with the same data but with
12190 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
12191 * to finish as e.g. in the regexp match case (or, to fail again with
12192 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
12193 * input is actually partial).
12195 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
12196 * converter object is in an invalid state where its not allowed
12197 * to call g_converter_convert() anymore. At this time you can only
12198 * free the object or call g_converter_reset() to reset it to the
12201 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
12202 * to try to write out all internal state to the output. The application
12203 * has to call the function multiple times with the flag set, and when
12204 * the available input has been consumed and all internal state has
12205 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
12206 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
12207 * This is somewhat similar to what happens at the end of the input stream,
12208 * but done in the middle of the data.
12210 * This has different meanings for different conversions. For instance
12211 * in a compression converter it would mean that we flush all the
12212 * compression state into output such that if you uncompress the
12213 * compressed data you get back all the input data. Doing this may
12214 * make the final file larger due to padding though. Another example
12215 * is a regexp conversion, where if you at the end of the flushed data
12216 * have a match, but there is also a potential longer match. In the
12217 * non-flushed case we would ask for more input, but when flushing we
12218 * treat this as the end of input and do the match.
12220 * Flushing is not always possible (like if a charset converter flushes
12221 * at a partial multibyte sequence). Converters are supposed to try
12222 * to produce as much output as possible and then return an error
12223 * (typically %G_IO_ERROR_PARTIAL_INPUT).
12225 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
12231 * g_converter_input_stream_get_converter:
12232 * @converter_stream: a #GConverterInputStream
12234 * Gets the #GConverter that is used by @converter_stream.
12236 * Returns: (transfer none): the converter of the converter input stream
12242 * g_converter_input_stream_new:
12243 * @base_stream: a #GInputStream
12244 * @converter: a #GConverter
12246 * Creates a new converter input stream for the @base_stream.
12248 * Returns: a new #GInputStream.
12253 * g_converter_output_stream_get_converter:
12254 * @converter_stream: a #GConverterOutputStream
12256 * Gets the #GConverter that is used by @converter_stream.
12258 * Returns: (transfer none): the converter of the converter output stream
12264 * g_converter_output_stream_new:
12265 * @base_stream: a #GOutputStream
12266 * @converter: a #GConverter
12268 * Creates a new converter output stream for the @base_stream.
12270 * Returns: a new #GOutputStream.
12275 * g_converter_reset:
12276 * @converter: a #GConverter.
12278 * Resets all internal state in the converter, making it behave
12279 * as if it was just created. If the converter has any internal
12280 * state that would produce output then that output is lost.
12287 * g_credentials_get_native: (skip)
12288 * @credentials: A #GCredentials.
12289 * @native_type: The type of native credentials to get.
12291 * Gets a pointer to native credentials of type @native_type from
12294 * It is a programming error (which will cause an warning to be
12295 * logged) to use this method if there is no #GCredentials support for
12296 * the OS or if @native_type isn't supported by the OS.
12298 * Returns: The pointer to native credentials or %NULL if the operation there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Do not free the returned data, it is owned by @credentials.
12304 * g_credentials_get_unix_user:
12305 * @credentials: A #GCredentials
12306 * @error: Return location for error or %NULL.
12308 * Tries to get the UNIX user identifier from @credentials. This
12309 * method is only available on UNIX platforms.
12311 * This operation can fail if #GCredentials is not supported on the
12312 * OS or if the native credentials type does not contain information
12313 * about the UNIX user.
12315 * Returns: The UNIX user identifier or -1 if @error is set.
12321 * g_credentials_is_same_user:
12322 * @credentials: A #GCredentials.
12323 * @other_credentials: A #GCredentials.
12324 * @error: Return location for error or %NULL.
12326 * Checks if @credentials and @other_credentials is the same user.
12328 * This operation can fail if #GCredentials is not supported on the
12331 * Returns: %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set.
12337 * g_credentials_new:
12339 * Creates a new #GCredentials object with credentials matching the
12340 * the current process.
12342 * Returns: A #GCredentials. Free with g_object_unref().
12348 * g_credentials_set_native:
12349 * @credentials: A #GCredentials.
12350 * @native_type: The type of native credentials to set.
12351 * @native: A pointer to native credentials.
12353 * Copies the native credentials of type @native_type from @native
12354 * into @credentials.
12356 * It is a programming error (which will cause an warning to be
12357 * logged) to use this method if there is no #GCredentials support for
12358 * the OS or if @native_type isn't supported by the OS.
12365 * g_credentials_set_unix_user:
12366 * @credentials: A #GCredentials.
12367 * @uid: The UNIX user identifier to set.
12368 * @error: Return location for error or %NULL.
12370 * Tries to set the UNIX user identifier on @credentials. This method
12371 * is only available on UNIX platforms.
12373 * This operation can fail if #GCredentials is not supported on the
12374 * OS or if the native credentials type does not contain information
12375 * about the UNIX user.
12377 * Returns: %TRUE if @uid was set, %FALSE if error is set.
12383 * g_credentials_to_string:
12384 * @credentials: A #GCredentials object.
12386 * Creates a human-readable textual representation of @credentials
12387 * that can be used in logging and debug messages. The format of the
12388 * returned string may change in future GLib release.
12390 * Returns: A string that should be freed with g_free().
12396 * g_data_input_stream_get_byte_order:
12397 * @stream: a given #GDataInputStream.
12399 * Gets the byte order for the data input stream.
12401 * Returns: the @stream's current #GDataStreamByteOrder.
12406 * g_data_input_stream_get_newline_type:
12407 * @stream: a given #GDataInputStream.
12409 * Gets the current newline type for the @stream.
12411 * Returns: #GDataStreamNewlineType for the given @stream.
12416 * g_data_input_stream_new:
12417 * @base_stream: a #GInputStream.
12419 * Creates a new data input stream for the @base_stream.
12421 * Returns: a new #GDataInputStream.
12426 * g_data_input_stream_read_byte:
12427 * @stream: a given #GDataInputStream.
12428 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12429 * @error: #GError for error reporting.
12431 * Reads an unsigned 8-bit/1-byte value from @stream.
12433 * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 if an error occurred.
12438 * g_data_input_stream_read_int16:
12439 * @stream: a given #GDataInputStream.
12440 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12441 * @error: #GError for error reporting.
12443 * Reads a 16-bit/2-byte value from @stream.
12445 * In order to get the correct byte order for this read operation,
12446 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
12448 * Returns: a signed 16-bit/2-byte value read from @stream or %0 if an error occurred.
12453 * g_data_input_stream_read_int32:
12454 * @stream: a given #GDataInputStream.
12455 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12456 * @error: #GError for error reporting.
12458 * Reads a signed 32-bit/4-byte value from @stream.
12460 * In order to get the correct byte order for this read operation,
12461 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
12463 * If @cancellable is not %NULL, then the operation can be cancelled by
12464 * triggering the cancellable object from another thread. If the operation
12465 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
12467 * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if an error occurred.
12472 * g_data_input_stream_read_int64:
12473 * @stream: a given #GDataInputStream.
12474 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12475 * @error: #GError for error reporting.
12477 * Reads a 64-bit/8-byte value from @stream.
12479 * In order to get the correct byte order for this read operation,
12480 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
12482 * If @cancellable is not %NULL, then the operation can be cancelled by
12483 * triggering the cancellable object from another thread. If the operation
12484 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
12486 * Returns: a signed 64-bit/8-byte value read from @stream or %0 if an error occurred.
12491 * g_data_input_stream_read_line:
12492 * @stream: a given #GDataInputStream.
12493 * @length: (out): a #gsize to get the length of the data read in.
12494 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12495 * @error: #GError for error reporting.
12497 * Reads a line from the data input stream. Note that no encoding
12498 * checks or conversion is performed; the input is not guaranteed to
12499 * be UTF-8, and may in fact have embedded NUL characters.
12501 * If @cancellable is not %NULL, then the operation can be cancelled by
12502 * triggering the cancellable object from another thread. If the operation
12503 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
12505 * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set.
12510 * g_data_input_stream_read_line_async:
12511 * @stream: a given #GDataInputStream.
12512 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
12513 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12514 * @callback: (scope async): callback to call when the request is satisfied.
12515 * @user_data: (closure): the data to pass to callback function.
12517 * The asynchronous version of g_data_input_stream_read_line(). It is
12518 * an error to have two outstanding calls to this function.
12520 * When the operation is finished, @callback will be called. You
12521 * can then call g_data_input_stream_read_line_finish() to get
12522 * the result of the operation.
12529 * g_data_input_stream_read_line_finish:
12530 * @stream: a given #GDataInputStream.
12531 * @result: the #GAsyncResult that was provided to the callback.
12532 * @length: (out): a #gsize to get the length of the data read in.
12533 * @error: #GError for error reporting.
12535 * Finish an asynchronous call started by
12536 * g_data_input_stream_read_line_async(). Note the warning about
12537 * string encoding in g_data_input_stream_read_line() applies here as
12540 * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL-terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set.
12546 * g_data_input_stream_read_line_finish_utf8:
12547 * @stream: a given #GDataInputStream.
12548 * @result: the #GAsyncResult that was provided to the callback.
12549 * @length: (out): a #gsize to get the length of the data read in.
12550 * @error: #GError for error reporting.
12552 * Finish an asynchronous call started by
12553 * g_data_input_stream_read_line_async().
12555 * Returns: (transfer full): a string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set.
12561 * g_data_input_stream_read_line_utf8:
12562 * @stream: a given #GDataInputStream.
12563 * @length: (out): a #gsize to get the length of the data read in.
12564 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12565 * @error: #GError for error reporting.
12567 * Reads a UTF-8 encoded line from the data input stream.
12569 * If @cancellable is not %NULL, then the operation can be cancelled by
12570 * triggering the cancellable object from another thread. If the operation
12571 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
12573 * Returns: (transfer full): a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set.
12579 * g_data_input_stream_read_uint16:
12580 * @stream: a given #GDataInputStream.
12581 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12582 * @error: #GError for error reporting.
12584 * Reads an unsigned 16-bit/2-byte value from @stream.
12586 * In order to get the correct byte order for this read operation,
12587 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
12589 * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if an error occurred.
12594 * g_data_input_stream_read_uint32:
12595 * @stream: a given #GDataInputStream.
12596 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12597 * @error: #GError for error reporting.
12599 * Reads an unsigned 32-bit/4-byte value from @stream.
12601 * In order to get the correct byte order for this read operation,
12602 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
12604 * If @cancellable is not %NULL, then the operation can be cancelled by
12605 * triggering the cancellable object from another thread. If the operation
12606 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
12608 * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if an error occurred.
12613 * g_data_input_stream_read_uint64:
12614 * @stream: a given #GDataInputStream.
12615 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12616 * @error: #GError for error reporting.
12618 * Reads an unsigned 64-bit/8-byte value from @stream.
12620 * In order to get the correct byte order for this read operation,
12621 * see g_data_input_stream_get_byte_order().
12623 * If @cancellable is not %NULL, then the operation can be cancelled by
12624 * triggering the cancellable object from another thread. If the operation
12625 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
12627 * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if an error occurred.
12632 * g_data_input_stream_read_until:
12633 * @stream: a given #GDataInputStream.
12634 * @stop_chars: characters to terminate the read.
12635 * @length: (out): a #gsize to get the length of the data read in.
12636 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12637 * @error: #GError for error reporting.
12639 * Reads a string from the data input stream, up to the first
12640 * occurrence of any of the stop characters.
12642 * Note that, in contrast to g_data_input_stream_read_until_async(),
12643 * this function consumes the stop character that it finds.
12645 * Don't use this function in new code. Its functionality is
12646 * inconsistent with g_data_input_stream_read_until_async(). Both
12647 * functions will be marked as deprecated in a future release. Use
12648 * g_data_input_stream_read_upto() instead, but note that that function
12649 * does not consume the stop character.
12651 * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.
12656 * g_data_input_stream_read_until_async:
12657 * @stream: a given #GDataInputStream.
12658 * @stop_chars: characters to terminate the read.
12659 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
12660 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12661 * @callback: (scope async): callback to call when the request is satisfied.
12662 * @user_data: (closure): the data to pass to callback function.
12664 * The asynchronous version of g_data_input_stream_read_until().
12665 * It is an error to have two outstanding calls to this function.
12667 * Note that, in contrast to g_data_input_stream_read_until(),
12668 * this function does not consume the stop character that it finds. You
12669 * must read it for yourself.
12671 * When the operation is finished, @callback will be called. You
12672 * can then call g_data_input_stream_read_until_finish() to get
12673 * the result of the operation.
12675 * Don't use this function in new code. Its functionality is
12676 * inconsistent with g_data_input_stream_read_until(). Both functions
12677 * will be marked as deprecated in a future release. Use
12678 * g_data_input_stream_read_upto_async() instead.
12685 * g_data_input_stream_read_until_finish:
12686 * @stream: a given #GDataInputStream.
12687 * @result: the #GAsyncResult that was provided to the callback.
12688 * @length: (out): a #gsize to get the length of the data read in.
12689 * @error: #GError for error reporting.
12691 * Finish an asynchronous call started by
12692 * g_data_input_stream_read_until_async().
12695 * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.
12700 * g_data_input_stream_read_upto:
12701 * @stream: a #GDataInputStream
12702 * @stop_chars: characters to terminate the read
12703 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
12704 * @length: (out): a #gsize to get the length of the data read in
12705 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12706 * @error: #GError for error reporting
12708 * Reads a string from the data input stream, up to the first
12709 * occurrence of any of the stop characters.
12711 * In contrast to g_data_input_stream_read_until(), this function
12712 * does <emphasis>not</emphasis> consume the stop character. You have
12713 * to use g_data_input_stream_read_byte() to get it before calling
12714 * g_data_input_stream_read_upto() again.
12716 * Note that @stop_chars may contain '\0' if @stop_chars_len is
12719 * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error
12725 * g_data_input_stream_read_upto_async:
12726 * @stream: a #GDataInputStream
12727 * @stop_chars: characters to terminate the read
12728 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
12729 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
12730 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12731 * @callback: (scope async): callback to call when the request is satisfied
12732 * @user_data: (closure): the data to pass to callback function
12734 * The asynchronous version of g_data_input_stream_read_upto().
12735 * It is an error to have two outstanding calls to this function.
12737 * In contrast to g_data_input_stream_read_until(), this function
12738 * does <emphasis>not</emphasis> consume the stop character. You have
12739 * to use g_data_input_stream_read_byte() to get it before calling
12740 * g_data_input_stream_read_upto() again.
12742 * Note that @stop_chars may contain '\0' if @stop_chars_len is
12745 * When the operation is finished, @callback will be called. You
12746 * can then call g_data_input_stream_read_upto_finish() to get
12747 * the result of the operation.
12754 * g_data_input_stream_read_upto_finish:
12755 * @stream: a #GDataInputStream
12756 * @result: the #GAsyncResult that was provided to the callback
12757 * @length: (out): a #gsize to get the length of the data read in
12758 * @error: #GError for error reporting
12760 * Finish an asynchronous call started by
12761 * g_data_input_stream_read_upto_async().
12763 * Note that this function does <emphasis>not</emphasis> consume the
12764 * stop character. You have to use g_data_input_stream_read_byte() to
12765 * get it before calling g_data_input_stream_read_upto_async() again.
12767 * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.
12773 * g_data_input_stream_set_byte_order:
12774 * @stream: a given #GDataInputStream.
12775 * @order: a #GDataStreamByteOrder to set.
12777 * This function sets the byte order for the given @stream. All subsequent
12778 * reads from the @stream will be read in the given @order.
12783 * g_data_input_stream_set_newline_type:
12784 * @stream: a #GDataInputStream.
12785 * @type: the type of new line return as #GDataStreamNewlineType.
12787 * Sets the newline type for the @stream.
12789 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
12790 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
12791 * "CR LF", and this might block if there is no more data available.
12796 * g_data_output_stream_get_byte_order:
12797 * @stream: a #GDataOutputStream.
12799 * Gets the byte order for the stream.
12801 * Returns: the #GDataStreamByteOrder for the @stream.
12806 * g_data_output_stream_new:
12807 * @base_stream: a #GOutputStream.
12809 * Creates a new data output stream for @base_stream.
12811 * Returns: #GDataOutputStream.
12816 * g_data_output_stream_put_byte:
12817 * @stream: a #GDataOutputStream.
12818 * @data: a #guchar.
12819 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12820 * @error: a #GError, %NULL to ignore.
12822 * Puts a byte into the output stream.
12824 * Returns: %TRUE if @data was successfully added to the @stream.
12829 * g_data_output_stream_put_int16:
12830 * @stream: a #GDataOutputStream.
12831 * @data: a #gint16.
12832 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12833 * @error: a #GError, %NULL to ignore.
12835 * Puts a signed 16-bit integer into the output stream.
12837 * Returns: %TRUE if @data was successfully added to the @stream.
12842 * g_data_output_stream_put_int32:
12843 * @stream: a #GDataOutputStream.
12844 * @data: a #gint32.
12845 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12846 * @error: a #GError, %NULL to ignore.
12848 * Puts a signed 32-bit integer into the output stream.
12850 * Returns: %TRUE if @data was successfully added to the @stream.
12855 * g_data_output_stream_put_int64:
12856 * @stream: a #GDataOutputStream.
12857 * @data: a #gint64.
12858 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12859 * @error: a #GError, %NULL to ignore.
12861 * Puts a signed 64-bit integer into the stream.
12863 * Returns: %TRUE if @data was successfully added to the @stream.
12868 * g_data_output_stream_put_string:
12869 * @stream: a #GDataOutputStream.
12871 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12872 * @error: a #GError, %NULL to ignore.
12874 * Puts a string into the output stream.
12876 * Returns: %TRUE if @string was successfully added to the @stream.
12881 * g_data_output_stream_put_uint16:
12882 * @stream: a #GDataOutputStream.
12883 * @data: a #guint16.
12884 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12885 * @error: a #GError, %NULL to ignore.
12887 * Puts an unsigned 16-bit integer into the output stream.
12889 * Returns: %TRUE if @data was successfully added to the @stream.
12894 * g_data_output_stream_put_uint32:
12895 * @stream: a #GDataOutputStream.
12896 * @data: a #guint32.
12897 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12898 * @error: a #GError, %NULL to ignore.
12900 * Puts an unsigned 32-bit integer into the stream.
12902 * Returns: %TRUE if @data was successfully added to the @stream.
12907 * g_data_output_stream_put_uint64:
12908 * @stream: a #GDataOutputStream.
12909 * @data: a #guint64.
12910 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
12911 * @error: a #GError, %NULL to ignore.
12913 * Puts an unsigned 64-bit integer into the stream.
12915 * Returns: %TRUE if @data was successfully added to the @stream.
12920 * g_data_output_stream_set_byte_order:
12921 * @stream: a #GDataOutputStream.
12922 * @order: a %GDataStreamByteOrder.
12924 * Sets the byte order of the data output stream to @order.
12929 * g_dbus_action_group_get:
12930 * @connection: A #GDBusConnection
12931 * @bus_name: the bus name which exports the action group
12932 * @object_path: the object path at which the action group is exported
12934 * Obtains a #GDBusActionGroup for the action group which is exported at
12935 * the given @bus_name and @object_path.
12937 * The thread default main context is taken at the time of this call.
12938 * All signals on the menu model (and any linked models) are reported
12939 * with respect to this context. All calls on the returned menu model
12940 * (and linked models) must also originate from this same context, with
12941 * the thread default main context unchanged.
12943 * This call is non-blocking. The returned action group may or may not
12944 * already be filled in. The correct thing to do is connect the signals
12945 * for the action group to monitor for changes and then to call
12946 * g_action_group_list_actions() to get the initial list.
12948 * Returns: (transfer full): a #GDBusActionGroup
12954 * g_dbus_address_get_for_bus_sync:
12955 * @bus_type: A #GBusType.
12956 * @cancellable: (allow-none): A #GCancellable or %NULL.
12957 * @error: Return location for error or %NULL.
12959 * Synchronously looks up the D-Bus address for the well-known message
12960 * bus instance specified by @bus_type. This may involve using various
12961 * platform specific mechanisms.
12963 * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
12969 * g_dbus_address_get_stream:
12970 * @address: A valid D-Bus address.
12971 * @cancellable: (allow-none): A #GCancellable or %NULL.
12972 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
12973 * @user_data: Data to pass to @callback.
12975 * Asynchronously connects to an endpoint specified by @address and
12976 * sets up the connection so it is in a state to run the client-side
12977 * of the D-Bus authentication conversation.
12979 * When the operation is finished, @callback will be invoked. You can
12980 * then call g_dbus_address_get_stream_finish() to get the result of
12983 * This is an asynchronous failable function. See
12984 * g_dbus_address_get_stream_sync() for the synchronous version.
12991 * g_dbus_address_get_stream_finish:
12992 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
12993 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
12994 * @error: Return location for error or %NULL.
12996 * Finishes an operation started with g_dbus_address_get_stream().
12998 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
13004 * g_dbus_address_get_stream_sync:
13005 * @address: A valid D-Bus address.
13006 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
13007 * @cancellable: (allow-none): A #GCancellable or %NULL.
13008 * @error: Return location for error or %NULL.
13010 * Synchronously connects to an endpoint specified by @address and
13011 * sets up the connection so it is in a state to run the client-side
13012 * of the D-Bus authentication conversation.
13014 * This is a synchronous failable function. See
13015 * g_dbus_address_get_stream() for the asynchronous version.
13017 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
13023 * g_dbus_annotation_info_lookup:
13024 * @annotations: (array zero-terminated=1) (allow-none): A %NULL-terminated array of annotations or %NULL.
13025 * @name: The name of the annotation to look up.
13027 * Looks up the value of an annotation.
13029 * The cost of this function is O(n) in number of annotations.
13031 * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
13037 * g_dbus_annotation_info_ref:
13038 * @info: A #GDBusNodeInfo
13040 * If @info is statically allocated does nothing. Otherwise increases
13041 * the reference count.
13043 * Returns: The same @info.
13049 * g_dbus_annotation_info_unref:
13050 * @info: A #GDBusAnnotationInfo.
13052 * If @info is statically allocated, does nothing. Otherwise decreases
13053 * the reference count of @info. When its reference count drops to 0,
13054 * the memory used is freed.
13061 * g_dbus_arg_info_ref:
13062 * @info: A #GDBusArgInfo
13064 * If @info is statically allocated does nothing. Otherwise increases
13065 * the reference count.
13067 * Returns: The same @info.
13073 * g_dbus_arg_info_unref:
13074 * @info: A #GDBusArgInfo.
13076 * If @info is statically allocated, does nothing. Otherwise decreases
13077 * the reference count of @info. When its reference count drops to 0,
13078 * the memory used is freed.
13085 * g_dbus_auth_observer_allow_mechanism:
13086 * @observer: A #GDBusAuthObserver.
13087 * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
13089 * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
13091 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
13097 * g_dbus_auth_observer_authorize_authenticated_peer:
13098 * @observer: A #GDBusAuthObserver.
13099 * @stream: A #GIOStream for the #GDBusConnection.
13100 * @credentials: (allow-none): Credentials received from the peer or %NULL.
13102 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
13104 * Returns: %TRUE if the peer is authorized, %FALSE if not.
13110 * g_dbus_auth_observer_new:
13112 * Creates a new #GDBusAuthObserver object.
13114 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
13120 * g_dbus_connection_add_filter:
13121 * @connection: A #GDBusConnection.
13122 * @filter_function: A filter function.
13123 * @user_data: User data to pass to @filter_function.
13124 * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL.
13126 * Adds a message filter. Filters are handlers that are run on all
13127 * incoming and outgoing messages, prior to standard dispatch. Filters
13128 * are run in the order that they were added. The same handler can be
13129 * added as a filter more than once, in which case it will be run more
13130 * than once. Filters added during a filter callback won't be run on
13131 * the message being processed. Filter functions are allowed to modify
13132 * and even drop messages.
13134 * Note that filters are run in a dedicated message handling thread so
13135 * they can't block and, generally, can't do anything but signal a
13136 * worker thread. Also note that filters are rarely needed - use API
13137 * such as g_dbus_connection_send_message_with_reply(),
13138 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
13140 * If a filter consumes an incoming message the message is not
13141 * dispatched anywhere else - not even the standard dispatch machinery
13142 * (that API such as g_dbus_connection_signal_subscribe() and
13143 * g_dbus_connection_send_message_with_reply() relies on) will see the
13144 * message. Similary, if a filter consumes an outgoing message, the
13145 * message will not be sent to the other peer.
13147 * Returns: A filter identifier that can be used with g_dbus_connection_remove_filter().
13153 * g_dbus_connection_call:
13154 * @connection: A #GDBusConnection.
13155 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
13156 * @object_path: Path of remote object.
13157 * @interface_name: D-Bus interface to invoke method on.
13158 * @method_name: The name of the method to invoke.
13159 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
13160 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
13161 * @flags: Flags from the #GDBusCallFlags enumeration.
13162 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
13163 * @cancellable: (allow-none): A #GCancellable or %NULL.
13164 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
13165 * @user_data: The data to pass to @callback.
13167 * Asynchronously invokes the @method_name method on the
13168 * @interface_name D-Bus interface on the remote object at
13169 * @object_path owned by @bus_name.
13171 * If @connection is closed then the operation will fail with
13172 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
13173 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
13174 * not compatible with the D-Bus protocol, the operation fails with
13175 * %G_IO_ERROR_INVALID_ARGUMENT.
13177 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
13178 * error will be raised if it does not match. Said another way, if you give a @reply_type
13179 * then any non-%NULL return value will be of this type.
13181 * If the @parameters #GVariant is floating, it is consumed. This allows
13182 * convenient 'inline' use of g_variant_new(), e.g.:
13184 * g_dbus_connection_call (connection,
13185 * "org.freedesktop.StringThings",
13186 * "/org/freedesktop/StringThings",
13187 * "org.freedesktop.StringThings",
13189 * g_variant_new ("(ss)",
13193 * G_DBUS_CALL_FLAGS_NONE,
13196 * (GAsyncReadyCallback) two_strings_done,
13200 * This is an asynchronous method. When the operation is finished, @callback will be invoked
13201 * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
13202 * of the thread you are calling this method from. You can then call
13203 * g_dbus_connection_call_finish() to get the result of the operation.
13204 * See g_dbus_connection_call_sync() for the synchronous version of this
13207 * If @callback is %NULL then the D-Bus method call message will be sent with
13208 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
13215 * g_dbus_connection_call_finish:
13216 * @connection: A #GDBusConnection.
13217 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call().
13218 * @error: Return location for error or %NULL.
13220 * Finishes an operation started with g_dbus_connection_call().
13222 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
13228 * g_dbus_connection_call_sync:
13229 * @connection: A #GDBusConnection.
13230 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
13231 * @object_path: Path of remote object.
13232 * @interface_name: D-Bus interface to invoke method on.
13233 * @method_name: The name of the method to invoke.
13234 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
13235 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
13236 * @flags: Flags from the #GDBusCallFlags enumeration.
13237 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
13238 * @cancellable: (allow-none): A #GCancellable or %NULL.
13239 * @error: Return location for error or %NULL.
13241 * Synchronously invokes the @method_name method on the
13242 * @interface_name D-Bus interface on the remote object at
13243 * @object_path owned by @bus_name.
13245 * If @connection is closed then the operation will fail with
13246 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
13247 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
13248 * contains a value not compatible with the D-Bus protocol, the operation
13249 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
13251 * If @reply_type is non-%NULL then the reply will be checked for having
13252 * this type and an error will be raised if it does not match. Said
13253 * another way, if you give a @reply_type then any non-%NULL return
13254 * value will be of this type.
13256 * If the @parameters #GVariant is floating, it is consumed.
13257 * This allows convenient 'inline' use of g_variant_new(), e.g.:
13259 * g_dbus_connection_call_sync (connection,
13260 * "org.freedesktop.StringThings",
13261 * "/org/freedesktop/StringThings",
13262 * "org.freedesktop.StringThings",
13264 * g_variant_new ("(ss)",
13268 * G_DBUS_CALL_FLAGS_NONE,
13274 * The calling thread is blocked until a reply is received. See
13275 * g_dbus_connection_call() for the asynchronous version of
13278 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
13284 * g_dbus_connection_call_with_unix_fd_list:
13285 * @connection: A #GDBusConnection.
13286 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
13287 * @object_path: Path of remote object.
13288 * @interface_name: D-Bus interface to invoke method on.
13289 * @method_name: The name of the method to invoke.
13290 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
13291 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
13292 * @flags: Flags from the #GDBusCallFlags enumeration.
13293 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
13294 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
13295 * @cancellable: (allow-none): A #GCancellable or %NULL.
13296 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation.
13297 * @user_data: The data to pass to @callback.
13299 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
13301 * This method is only available on UNIX.
13308 * g_dbus_connection_call_with_unix_fd_list_finish:
13309 * @connection: A #GDBusConnection.
13310 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
13311 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list().
13312 * @error: Return location for error or %NULL.
13314 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
13316 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
13322 * g_dbus_connection_call_with_unix_fd_list_sync:
13323 * @connection: A #GDBusConnection.
13324 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
13325 * @object_path: Path of remote object.
13326 * @interface_name: D-Bus interface to invoke method on.
13327 * @method_name: The name of the method to invoke.
13328 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
13329 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
13330 * @flags: Flags from the #GDBusCallFlags enumeration.
13331 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
13332 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
13333 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
13334 * @cancellable: (allow-none): A #GCancellable or %NULL.
13335 * @error: Return location for error or %NULL.
13337 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
13339 * This method is only available on UNIX.
13341 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
13347 * g_dbus_connection_close:
13348 * @connection: A #GDBusConnection.
13349 * @cancellable: (allow-none): A #GCancellable or %NULL.
13350 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
13351 * @user_data: The data to pass to @callback.
13353 * Closes @connection. Note that this never causes the process to
13354 * exit (this might only happen if the other end of a shared message
13355 * bus connection disconnects, see #GDBusConnection:exit-on-close).
13357 * Once the connection is closed, operations such as sending a message
13358 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
13359 * will not automatically flush the connection so queued messages may
13360 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
13362 * If @connection is already closed, this method fails with
13363 * %G_IO_ERROR_CLOSED.
13365 * When @connection has been closed, the #GDBusConnection::closed
13366 * signal is emitted in the <link
13367 * linkend="g-main-context-push-thread-default">thread-default main
13368 * loop</link> of the thread that @connection was constructed in.
13370 * This is an asynchronous method. When the operation is finished,
13371 * @callback will be invoked in the <link
13372 * linkend="g-main-context-push-thread-default">thread-default main
13373 * loop</link> of the thread you are calling this method from. You can
13374 * then call g_dbus_connection_close_finish() to get the result of the
13375 * operation. See g_dbus_connection_close_sync() for the synchronous
13383 * g_dbus_connection_close_finish:
13384 * @connection: A #GDBusConnection.
13385 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close().
13386 * @error: Return location for error or %NULL.
13388 * Finishes an operation started with g_dbus_connection_close().
13390 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
13396 * g_dbus_connection_close_sync:
13397 * @connection: A #GDBusConnection.
13398 * @cancellable: (allow-none): A #GCancellable or %NULL.
13399 * @error: Return location for error or %NULL.
13401 * Synchronously closees @connection. The calling thread is blocked
13402 * until this is done. See g_dbus_connection_close() for the
13403 * asynchronous version of this method and more details about what it
13406 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
13412 * g_dbus_connection_emit_signal:
13413 * @connection: A #GDBusConnection.
13414 * @destination_bus_name: (allow-none): The unique bus name for the destination for the signal or %NULL to emit to all listeners.
13415 * @object_path: Path of remote object.
13416 * @interface_name: D-Bus interface to emit a signal on.
13417 * @signal_name: The name of the signal to emit.
13418 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
13419 * @error: Return location for error or %NULL.
13423 * If the parameters GVariant is floating, it is consumed.
13425 * This can only fail if @parameters is not compatible with the D-Bus protocol.
13427 * Returns: %TRUE unless @error is set.
13433 * g_dbus_connection_export_action_group:
13434 * @connection: a #GDBusConnection
13435 * @object_path: a D-Bus object path
13436 * @action_group: a #GActionGroup
13437 * @error: a pointer to a %NULL #GError, or %NULL
13439 * Exports @action_group on @connection at @object_path.
13441 * The implemented D-Bus API should be considered private. It is
13442 * subject to change in the future.
13444 * A given object path can only have one action group exported on it.
13445 * If this constraint is violated, the export will fail and 0 will be
13446 * returned (with @error set accordingly).
13448 * You can unexport the action group using
13449 * g_dbus_connection_unexport_action_group() with the return value of
13452 * The thread default main context is taken at the time of this call.
13453 * All incoming action activations and state change requests are
13454 * reported from this context. Any changes on the action group that
13455 * cause it to emit signals must also come from this same context.
13456 * Since incoming action activations and state change requests are
13457 * rather likely to cause changes on the action group, this effectively
13458 * limits a given action group to being exported from only one main
13461 * Returns: the ID of the export (never zero), or 0 in case of failure
13467 * g_dbus_connection_export_menu_model:
13468 * @connection: a #GDBusConnection
13469 * @object_path: a D-Bus object path
13470 * @menu: a #GMenuModel
13471 * @error: return location for an error, or %NULL
13473 * Exports @menu on @connection at @object_path.
13475 * The implemented D-Bus API should be considered private.
13476 * It is subject to change in the future.
13478 * An object path can only have one action group exported on it. If this
13479 * constraint is violated, the export will fail and 0 will be
13480 * returned (with @error set accordingly).
13482 * You can unexport the menu model using
13483 * g_dbus_connection_unexport_menu_model() with the return value of
13486 * Returns: the ID of the export (never zero), or 0 in case of failure
13492 * g_dbus_connection_flush:
13493 * @connection: A #GDBusConnection.
13494 * @cancellable: (allow-none): A #GCancellable or %NULL.
13495 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
13496 * @user_data: The data to pass to @callback.
13498 * Asynchronously flushes @connection, that is, writes all queued
13499 * outgoing message to the transport and then flushes the transport
13500 * (using g_output_stream_flush_async()). This is useful in programs
13501 * that wants to emit a D-Bus signal and then exit
13502 * immediately. Without flushing the connection, there is no guarantee
13503 * that the message has been sent to the networking buffers in the OS
13506 * This is an asynchronous method. When the operation is finished,
13507 * @callback will be invoked in the <link
13508 * linkend="g-main-context-push-thread-default">thread-default main
13509 * loop</link> of the thread you are calling this method from. You can
13510 * then call g_dbus_connection_flush_finish() to get the result of the
13511 * operation. See g_dbus_connection_flush_sync() for the synchronous
13519 * g_dbus_connection_flush_finish:
13520 * @connection: A #GDBusConnection.
13521 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush().
13522 * @error: Return location for error or %NULL.
13524 * Finishes an operation started with g_dbus_connection_flush().
13526 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
13532 * g_dbus_connection_flush_sync:
13533 * @connection: A #GDBusConnection.
13534 * @cancellable: (allow-none): A #GCancellable or %NULL.
13535 * @error: Return location for error or %NULL.
13537 * Synchronously flushes @connection. The calling thread is blocked
13538 * until this is done. See g_dbus_connection_flush() for the
13539 * asynchronous version of this method and more details about what it
13542 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
13548 * g_dbus_connection_get_capabilities:
13549 * @connection: A #GDBusConnection.
13551 * Gets the capabilities negotiated with the remote peer
13553 * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
13559 * g_dbus_connection_get_exit_on_close:
13560 * @connection: A #GDBusConnection.
13562 * Gets whether the process is terminated when @connection is
13563 * closed by the remote peer. See
13564 * #GDBusConnection:exit-on-close for more details.
13566 * Returns: Whether the process is terminated when @connection is closed by the remote peer.
13572 * g_dbus_connection_get_guid:
13573 * @connection: A #GDBusConnection.
13575 * The GUID of the peer performing the role of server when
13576 * authenticating. See #GDBusConnection:guid for more details.
13578 * Returns: The GUID. Do not free this string, it is owned by @connection.
13584 * g_dbus_connection_get_last_serial:
13585 * @connection: A #GDBusConnection.
13587 * Retrieves the last serial number assigned to a #GDBusMessage on
13588 * the current thread. This includes messages sent via both low-level
13589 * API such as g_dbus_connection_send_message() as well as
13590 * high-level API such as g_dbus_connection_emit_signal(),
13591 * g_dbus_connection_call() or g_dbus_proxy_call().
13593 * Returns: the last used serial or zero when no message has been sent within the current thread.
13599 * g_dbus_connection_get_peer_credentials:
13600 * @connection: A #GDBusConnection.
13602 * Gets the credentials of the authenticated peer. This will always
13603 * return %NULL unless @connection acted as a server
13604 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
13605 * when set up and the client passed credentials as part of the
13606 * authentication process.
13608 * In a message bus setup, the message bus is always the server and
13609 * each application is a client. So this method will always return
13610 * %NULL for message bus clients.
13612 * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection.
13618 * g_dbus_connection_get_stream:
13619 * @connection: a #GDBusConnection
13621 * Gets the underlying stream used for IO.
13623 * While the #GDBusConnection is active, it will interact with this
13624 * stream from a worker thread, so it is not safe to interact with
13625 * the stream directly.
13627 * Returns: (transfer none): the stream used for IO
13633 * g_dbus_connection_get_unique_name:
13634 * @connection: A #GDBusConnection.
13636 * Gets the unique name of @connection as assigned by the message
13637 * bus. This can also be used to figure out if @connection is a
13638 * message bus connection.
13640 * Returns: The unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection.
13646 * g_dbus_connection_is_closed:
13647 * @connection: A #GDBusConnection.
13649 * Gets whether @connection is closed.
13651 * Returns: %TRUE if the connection is closed, %FALSE otherwise.
13657 * g_dbus_connection_new:
13658 * @stream: A #GIOStream.
13659 * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
13660 * @flags: Flags describing how to make the connection.
13661 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
13662 * @cancellable: (allow-none): A #GCancellable or %NULL.
13663 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
13664 * @user_data: The data to pass to @callback.
13666 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
13667 * with the end represented by @stream.
13669 * If @stream is a #GSocketConnection, then the corresponding #GSocket
13670 * will be put into non-blocking mode.
13672 * The D-Bus connection will interact with @stream from a worker thread.
13673 * As a result, the caller should not interact with @stream after this
13674 * method has been called, except by calling g_object_unref() on it.
13676 * If @observer is not %NULL it may be used to control the
13677 * authentication process.
13679 * When the operation is finished, @callback will be invoked. You can
13680 * then call g_dbus_connection_new_finish() to get the result of the
13683 * This is a asynchronous failable constructor. See
13684 * g_dbus_connection_new_sync() for the synchronous
13692 * g_dbus_connection_new_finish:
13693 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
13694 * @error: Return location for error or %NULL.
13696 * Finishes an operation started with g_dbus_connection_new().
13698 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
13704 * g_dbus_connection_new_for_address:
13705 * @address: A D-Bus address.
13706 * @flags: Flags describing how to make the connection.
13707 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
13708 * @cancellable: (allow-none): A #GCancellable or %NULL.
13709 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
13710 * @user_data: The data to pass to @callback.
13712 * Asynchronously connects and sets up a D-Bus client connection for
13713 * exchanging D-Bus messages with an endpoint specified by @address
13714 * which must be in the D-Bus address format.
13716 * This constructor can only be used to initiate client-side
13717 * connections - use g_dbus_connection_new() if you need to act as the
13718 * server. In particular, @flags cannot contain the
13719 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
13720 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
13722 * When the operation is finished, @callback will be invoked. You can
13723 * then call g_dbus_connection_new_finish() to get the result of the
13726 * If @observer is not %NULL it may be used to control the
13727 * authentication process.
13729 * This is a asynchronous failable constructor. See
13730 * g_dbus_connection_new_for_address_sync() for the synchronous
13738 * g_dbus_connection_new_for_address_finish:
13739 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
13740 * @error: Return location for error or %NULL.
13742 * Finishes an operation started with g_dbus_connection_new_for_address().
13744 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
13750 * g_dbus_connection_new_for_address_sync:
13751 * @address: A D-Bus address.
13752 * @flags: Flags describing how to make the connection.
13753 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
13754 * @cancellable: (allow-none): A #GCancellable or %NULL.
13755 * @error: Return location for error or %NULL.
13757 * Synchronously connects and sets up a D-Bus client connection for
13758 * exchanging D-Bus messages with an endpoint specified by @address
13759 * which must be in the D-Bus address format.
13761 * This constructor can only be used to initiate client-side
13762 * connections - use g_dbus_connection_new_sync() if you need to act
13763 * as the server. In particular, @flags cannot contain the
13764 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
13765 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
13767 * This is a synchronous failable constructor. See
13768 * g_dbus_connection_new_for_address() for the asynchronous version.
13770 * If @observer is not %NULL it may be used to control the
13771 * authentication process.
13773 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
13779 * g_dbus_connection_new_sync:
13780 * @stream: A #GIOStream.
13781 * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
13782 * @flags: Flags describing how to make the connection.
13783 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
13784 * @cancellable: (allow-none): A #GCancellable or %NULL.
13785 * @error: Return location for error or %NULL.
13787 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
13788 * with the end represented by @stream.
13790 * If @stream is a #GSocketConnection, then the corresponding #GSocket
13791 * will be put into non-blocking mode.
13793 * The D-Bus connection will interact with @stream from a worker thread.
13794 * As a result, the caller should not interact with @stream after this
13795 * method has been called, except by calling g_object_unref() on it.
13797 * If @observer is not %NULL it may be used to control the
13798 * authentication process.
13800 * This is a synchronous failable constructor. See
13801 * g_dbus_connection_new() for the asynchronous version.
13803 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
13809 * g_dbus_connection_register_object:
13810 * @connection: A #GDBusConnection.
13811 * @object_path: The object path to register at.
13812 * @interface_info: Introspection data for the interface.
13813 * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL.
13814 * @user_data: (allow-none): Data to pass to functions in @vtable.
13815 * @user_data_free_func: Function to call when the object path is unregistered.
13816 * @error: Return location for error or %NULL.
13818 * Registers callbacks for exported objects at @object_path with the
13819 * D-Bus interface that is described in @interface_info.
13821 * Calls to functions in @vtable (and @user_data_free_func) will
13822 * happen in the <link linkend="g-main-context-push-thread-default">thread-default main
13823 * loop</link> of the thread you are calling this method from.
13825 * Note that all #GVariant values passed to functions in @vtable will match
13826 * the signature given in @interface_info - if a remote caller passes
13827 * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
13828 * is returned to the remote caller.
13830 * Additionally, if the remote caller attempts to invoke methods or
13831 * access properties not mentioned in @interface_info the
13832 * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
13833 * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
13834 * are returned to the caller.
13836 * It is considered a programming error if the
13837 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
13838 * #GVariant of incorrect type.
13840 * If an existing callback is already registered at @object_path and
13841 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
13843 * GDBus automatically implements the standard D-Bus interfaces
13844 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
13845 * and org.freedesktop.Peer, so you don't have to implement those for
13846 * the objects you export. You <emphasis>can</emphasis> implement
13847 * org.freedesktop.DBus.Properties yourself, e.g. to handle getting
13848 * and setting of properties asynchronously.
13850 * Note that the reference count on @interface_info will be
13851 * incremented by 1 (unless allocated statically, e.g. if the
13852 * reference count is -1, see g_dbus_interface_info_ref()) for as long
13853 * as the object is exported. Also note that @vtable will be copied.
13855 * See <xref linkend="gdbus-server"/> for an example of how to use this method.
13857 * Returns: 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() .
13863 * g_dbus_connection_register_subtree:
13864 * @connection: A #GDBusConnection.
13865 * @object_path: The object path to register the subtree at.
13866 * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
13867 * @flags: Flags used to fine tune the behavior of the subtree.
13868 * @user_data: Data to pass to functions in @vtable.
13869 * @user_data_free_func: Function to call when the subtree is unregistered.
13870 * @error: Return location for error or %NULL.
13872 * Registers a whole subtree of <quote>dynamic</quote> objects.
13874 * The @enumerate and @introspection functions in @vtable are used to
13875 * convey, to remote callers, what nodes exist in the subtree rooted
13878 * When handling remote calls into any node in the subtree, first the
13879 * @enumerate function is used to check if the node exists. If the node exists
13880 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
13881 * the @introspection function is used to check if the node supports the
13882 * requested method. If so, the @dispatch function is used to determine
13883 * where to dispatch the call. The collected #GDBusInterfaceVTable and
13884 * #gpointer will be used to call into the interface vtable for processing
13887 * All calls into user-provided code will be invoked in the <link
13888 * linkend="g-main-context-push-thread-default">thread-default main
13889 * loop</link> of the thread you are calling this method from.
13891 * If an existing subtree is already registered at @object_path or
13892 * then @error is set to #G_IO_ERROR_EXISTS.
13894 * Note that it is valid to register regular objects (using
13895 * g_dbus_connection_register_object()) in a subtree registered with
13896 * g_dbus_connection_register_subtree() - if so, the subtree handler
13897 * is tried as the last resort. One way to think about a subtree
13898 * handler is to consider it a <quote>fallback handler</quote>
13899 * for object paths not registered via g_dbus_connection_register_object()
13900 * or other bindings.
13902 * Note that @vtable will be copied so you cannot change it after
13905 * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
13907 * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) that can be used with g_dbus_connection_unregister_subtree() .
13913 * g_dbus_connection_remove_filter:
13914 * @connection: a #GDBusConnection
13915 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
13917 * Removes a filter.
13924 * g_dbus_connection_send_message:
13925 * @connection: A #GDBusConnection.
13926 * @message: A #GDBusMessage
13927 * @flags: Flags affecting how the message is sent.
13928 * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
13929 * @error: Return location for error or %NULL.
13931 * Asynchronously sends @message to the peer represented by @connection.
13933 * Unless @flags contain the
13934 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
13935 * will be assigned by @connection and set on @message via
13936 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
13937 * serial number used will be written to this location prior to
13938 * submitting the message to the underlying transport.
13940 * If @connection is closed then the operation will fail with
13941 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
13942 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
13944 * See <xref linkend="gdbus-server"/> and <xref
13945 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
13946 * low-level API to send and receive UNIX file descriptors.
13948 * Note that @message must be unlocked, unless @flags contain the
13949 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
13951 * Returns: %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set.
13957 * g_dbus_connection_send_message_with_reply:
13958 * @connection: A #GDBusConnection.
13959 * @message: A #GDBusMessage.
13960 * @flags: Flags affecting how the message is sent.
13961 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
13962 * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
13963 * @cancellable: (allow-none): A #GCancellable or %NULL.
13964 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
13965 * @user_data: The data to pass to @callback.
13967 * Asynchronously sends @message to the peer represented by @connection.
13969 * Unless @flags contain the
13970 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
13971 * will be assigned by @connection and set on @message via
13972 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
13973 * serial number used will be written to this location prior to
13974 * submitting the message to the underlying transport.
13976 * If @connection is closed then the operation will fail with
13977 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
13978 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
13979 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
13981 * This is an asynchronous method. When the operation is finished, @callback will be invoked
13982 * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
13983 * of the thread you are calling this method from. You can then call
13984 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
13985 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
13987 * Note that @message must be unlocked, unless @flags contain the
13988 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
13990 * See <xref linkend="gdbus-server"/> and <xref
13991 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
13992 * low-level API to send and receive UNIX file descriptors.
13999 * g_dbus_connection_send_message_with_reply_finish:
14000 * @connection: a #GDBusConnection
14001 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
14002 * @error: Return location for error or %NULL.
14004 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
14006 * Note that @error is only set if a local in-process error
14007 * occurred. That is to say that the returned #GDBusMessage object may
14008 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
14009 * g_dbus_message_to_gerror() to transcode this to a #GError.
14011 * See <xref linkend="gdbus-server"/> and <xref
14012 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
14013 * low-level API to send and receive UNIX file descriptors.
14015 * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
14021 * g_dbus_connection_send_message_with_reply_sync:
14022 * @connection: A #GDBusConnection.
14023 * @message: A #GDBusMessage.
14024 * @flags: Flags affecting how the message is sent.
14025 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
14026 * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
14027 * @cancellable: (allow-none): A #GCancellable or %NULL.
14028 * @error: Return location for error or %NULL.
14030 * Synchronously sends @message to the peer represented by @connection
14031 * and blocks the calling thread until a reply is received or the
14032 * timeout is reached. See g_dbus_connection_send_message_with_reply()
14033 * for the asynchronous version of this method.
14035 * Unless @flags contain the
14036 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
14037 * will be assigned by @connection and set on @message via
14038 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
14039 * serial number used will be written to this location prior to
14040 * submitting the message to the underlying transport.
14042 * If @connection is closed then the operation will fail with
14043 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
14044 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
14045 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
14047 * Note that @error is only set if a local in-process error
14048 * occurred. That is to say that the returned #GDBusMessage object may
14049 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
14050 * g_dbus_message_to_gerror() to transcode this to a #GError.
14052 * See <xref linkend="gdbus-server"/> and <xref
14053 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
14054 * low-level API to send and receive UNIX file descriptors.
14056 * Note that @message must be unlocked, unless @flags contain the
14057 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
14059 * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
14065 * g_dbus_connection_set_exit_on_close:
14066 * @connection: A #GDBusConnection.
14067 * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer.
14069 * Sets whether the process should be terminated when @connection is
14070 * closed by the remote peer. See #GDBusConnection:exit-on-close for
14073 * Note that this function should be used with care. Most modern UNIX
14074 * desktops tie the notion of a user session the session bus, and expect
14075 * all of a users applications to quit when their bus connection goes away.
14076 * If you are setting @exit_on_close to %FALSE for the shared session
14077 * bus connection, you should make sure that your application exits
14078 * when the user session ends.
14085 * g_dbus_connection_signal_subscribe:
14086 * @connection: A #GDBusConnection.
14087 * @sender: (allow-none): Sender name to match on (unique or well-known name) or %NULL to listen from all senders.
14088 * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to match on all interfaces.
14089 * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals.
14090 * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths.
14091 * @arg0: (allow-none): Contents of first string argument to match on or %NULL to match on all kinds of arguments.
14092 * @flags: Flags describing how to subscribe to the signal (currently unused).
14093 * @callback: Callback to invoke when there is a signal matching the requested data.
14094 * @user_data: User data to pass to @callback.
14095 * @user_data_free_func: (allow-none): Function to free @user_data with when subscription is removed or %NULL.
14097 * Subscribes to signals on @connection and invokes @callback with a
14098 * whenever the signal is received. Note that @callback
14099 * will be invoked in the <link
14100 * linkend="g-main-context-push-thread-default">thread-default main
14101 * loop</link> of the thread you are calling this method from.
14103 * If @connection is not a message bus connection, @sender must be
14106 * If @sender is a well-known name note that @callback is invoked with
14107 * the unique name for the owner of @sender, not the well-known name
14108 * as one would expect. This is because the message bus rewrites the
14109 * name. As such, to avoid certain race conditions, users should be
14110 * tracking the name owner of the well-known name and use that when
14111 * processing the received signal.
14113 * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
14119 * g_dbus_connection_signal_unsubscribe:
14120 * @connection: A #GDBusConnection.
14121 * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
14123 * Unsubscribes from signals.
14130 * g_dbus_connection_start_message_processing:
14131 * @connection: A #GDBusConnection.
14133 * If @connection was created with
14134 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
14135 * starts processing messages. Does nothing on if @connection wasn't
14136 * created with this flag or if the method has already been called.
14143 * g_dbus_connection_unexport_action_group:
14144 * @connection: a #GDBusConnection
14145 * @export_id: the ID from g_dbus_connection_export_action_group()
14147 * Reverses the effect of a previous call to
14148 * g_dbus_connection_export_action_group().
14150 * It is an error to call this function with an ID that wasn't returned
14151 * from g_dbus_connection_export_action_group() or to call it with the
14152 * same ID more than once.
14159 * g_dbus_connection_unexport_menu_model:
14160 * @connection: a #GDBusConnection
14161 * @export_id: the ID from g_dbus_connection_export_menu_model()
14163 * Reverses the effect of a previous call to
14164 * g_dbus_connection_export_menu_model().
14166 * It is an error to call this function with an ID that wasn't returned
14167 * from g_dbus_connection_export_menu_model() or to call it with the
14168 * same ID more than once.
14175 * g_dbus_connection_unregister_object:
14176 * @connection: A #GDBusConnection.
14177 * @registration_id: A registration id obtained from g_dbus_connection_register_object().
14179 * Unregisters an object.
14181 * Returns: %TRUE if the object was unregistered, %FALSE otherwise.
14187 * g_dbus_connection_unregister_subtree:
14188 * @connection: A #GDBusConnection.
14189 * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree().
14191 * Unregisters a subtree.
14193 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
14199 * g_dbus_error_encode_gerror:
14200 * @error: A #GError.
14202 * Creates a D-Bus error name to use for @error. If @error matches
14203 * a registered error (cf. g_dbus_error_register_error()), the corresponding
14204 * D-Bus error name will be returned.
14206 * Otherwise the a name of the form
14207 * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
14208 * will be used. This allows other GDBus applications to map the error
14209 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
14211 * This function is typically only used in object mappings to put a
14212 * #GError on the wire. Regular applications should not use it.
14214 * Returns: A D-Bus error name (never %NULL). Free with g_free().
14220 * g_dbus_error_get_remote_error:
14221 * @error: A #GError.
14223 * Gets the D-Bus error name used for @error, if any.
14225 * This function is guaranteed to return a D-Bus error name for all
14226 * #GError<!-- -->s returned from functions handling remote method
14227 * calls (e.g. g_dbus_connection_call_finish()) unless
14228 * g_dbus_error_strip_remote_error() has been used on @error.
14230 * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
14236 * g_dbus_error_is_remote_error:
14237 * @error: A #GError.
14239 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
14240 * use g_dbus_error_get_remote_error() to get the name of the error.
14242 * Returns: %TRUE if @error represents an error from a remote peer, %FALSE otherwise.
14248 * g_dbus_error_new_for_dbus_error:
14249 * @dbus_error_name: D-Bus error name.
14250 * @dbus_error_message: D-Bus error message.
14252 * Creates a #GError based on the contents of @dbus_error_name and
14253 * @dbus_error_message.
14255 * Errors registered with g_dbus_error_register_error() will be looked
14256 * up using @dbus_error_name and if a match is found, the error domain
14257 * and code is used. Applications can use g_dbus_error_get_remote_error()
14258 * to recover @dbus_error_name.
14260 * If a match against a registered error is not found and the D-Bus
14261 * error name is in a form as returned by g_dbus_error_encode_gerror()
14262 * the error domain and code encoded in the name is used to
14263 * create the #GError. Also, @dbus_error_name is added to the error message
14264 * such that it can be recovered with g_dbus_error_get_remote_error().
14266 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
14267 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
14268 * added to the error message such that it can be recovered with
14269 * g_dbus_error_get_remote_error().
14271 * In all three cases, @dbus_error_name can always be recovered from the
14272 * returned #GError using the g_dbus_error_get_remote_error() function
14273 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
14275 * This function is typically only used in object mappings to prepare
14276 * #GError instances for applications. Regular applications should not use
14279 * Returns: An allocated #GError. Free with g_error_free().
14285 * g_dbus_error_register_error:
14286 * @error_domain: A #GQuark for a error domain.
14287 * @error_code: An error code.
14288 * @dbus_error_name: A D-Bus error name.
14290 * Creates an association to map between @dbus_error_name and
14291 * #GError<!-- -->s specified by @error_domain and @error_code.
14293 * This is typically done in the routine that returns the #GQuark for
14296 * Returns: %TRUE if the association was created, %FALSE if it already exists.
14302 * g_dbus_error_register_error_domain:
14303 * @error_domain_quark_name: The error domain name.
14304 * @quark_volatile: A pointer where to store the #GQuark.
14305 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
14306 * @num_entries: Number of items to register.
14308 * Helper function for associating a #GError error domain with D-Bus error names.
14315 * g_dbus_error_set_dbus_error:
14316 * @error: A pointer to a #GError or %NULL.
14317 * @dbus_error_name: D-Bus error name.
14318 * @dbus_error_message: D-Bus error message.
14319 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
14320 * @...: Arguments for @format.
14322 * Does nothing if @error is %NULL. Otherwise sets *@error to
14323 * a new #GError created with g_dbus_error_new_for_dbus_error()
14324 * with @dbus_error_message prepend with @format (unless %NULL).
14331 * g_dbus_error_set_dbus_error_valist:
14332 * @error: A pointer to a #GError or %NULL.
14333 * @dbus_error_name: D-Bus error name.
14334 * @dbus_error_message: D-Bus error message.
14335 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
14336 * @var_args: Arguments for @format.
14338 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
14345 * g_dbus_error_strip_remote_error:
14346 * @error: A #GError.
14348 * Looks for extra information in the error message used to recover
14349 * the D-Bus error name and strips it if found. If stripped, the
14350 * message field in @error will correspond exactly to what was
14351 * received on the wire.
14353 * This is typically used when presenting errors to the end user.
14355 * Returns: %TRUE if information was stripped, %FALSE otherwise.
14361 * g_dbus_error_unregister_error:
14362 * @error_domain: A #GQuark for a error domain.
14363 * @error_code: An error code.
14364 * @dbus_error_name: A D-Bus error name.
14366 * Destroys an association previously set up with g_dbus_error_register_error().
14368 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
14374 * g_dbus_generate_guid:
14376 * Generate a D-Bus GUID that can be used with
14377 * e.g. g_dbus_connection_new().
14379 * See the D-Bus specification regarding what strings are valid D-Bus
14380 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
14382 * Returns: A valid D-Bus GUID. Free with g_free().
14388 * g_dbus_gvalue_to_gvariant:
14389 * @gvalue: A #GValue to convert to a #GVariant.
14390 * @type: A #GVariantType.
14392 * Converts a #GValue to a #GVariant of the type indicated by the @type parameter.
14394 * The conversion is using the following rules:
14395 * <table frame='all'>
14396 * <title>#GValue / #GVariant conversion rules</title>
14397 * <tgroup cols='2' align='left' colsep='1' rowsep='1'>
14400 * <entry>If the #GType for @gvalue is...</entry>
14401 * <entry>... then @type must be</entry>
14406 * <entry>#G_TYPE_STRING</entry>
14407 * <entry><link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link>, <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link> or <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link></entry>
14410 * <entry>#G_TYPE_STRV</entry>
14411 * <entry><link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>, <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> or <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link></entry>
14414 * <entry>#G_TYPE_BOOLEAN</entry>
14415 * <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
14418 * <entry>#G_TYPE_UCHAR</entry>
14419 * <entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry>
14422 * <entry>#G_TYPE_INT</entry>
14423 * <entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry>
14426 * <entry>#G_TYPE_UINT</entry>
14427 * <entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry>
14430 * <entry>#G_TYPE_INT64</entry>
14431 * <entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry>
14434 * <entry>#G_TYPE_UINT64</entry>
14435 * <entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry>
14438 * <entry>#G_TYPE_DOUBLE</entry>
14439 * <entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry>
14442 * <entry>#G_TYPE_VARIANT</entry>
14443 * <entry>Any #GVariantType</entry>
14448 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
14449 * is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will
14450 * also fail for any #GType (including e.g. #G_TYPE_OBJECT and
14451 * #G_TYPE_BOXED derived-types) not in the table above.
14453 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
14454 * %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
14455 * %NULL) for @type is returned (e.g. 0 for scalar types, the empty
14456 * string for string types, <literal>'/'</literal> for object path
14457 * types, the empty array for any array type and so on).
14459 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
14460 * #GVariant to a #GValue.
14462 * Returns: A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or %NULL in case of failure. Free with g_variant_unref().
14468 * g_dbus_gvariant_to_gvalue:
14469 * @value: A #GVariant.
14470 * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
14472 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
14474 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
14475 * used - this function is essentially its reverse form.
14477 * The conversion never fails - a valid #GValue is always returned in
14485 * g_dbus_interface_dup_object:
14486 * @interface_: An exported D-Bus interface.
14488 * Gets the #GDBusObject that @interface_ belongs to, if any.
14490 * Returns: (transfer full): A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref().
14492 * Rename to: g_dbus_interface_get_object
14497 * g_dbus_interface_get_info:
14498 * @interface_: An exported D-Bus interface.
14500 * Gets D-Bus introspection information for the D-Bus interface
14501 * implemented by @interface_.
14503 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
14509 * g_dbus_interface_get_object: (skip)
14510 * @interface_: An exported D-Bus interface.
14512 * Gets the #GDBusObject that @interface_ belongs to, if any.
14514 * <warning>It is not safe to use the returned object if @interface_
14515 * or the returned object is being used from other threads. See
14516 * g_dbus_interface_dup_object() for a thread-safe
14517 * alternative.</warning>
14519 * Returns: (transfer none): A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed.
14525 * g_dbus_interface_info_cache_build:
14526 * @info: A #GDBusInterfaceInfo.
14528 * Builds a lookup-cache to speed up
14529 * g_dbus_interface_info_lookup_method(),
14530 * g_dbus_interface_info_lookup_signal() and
14531 * g_dbus_interface_info_lookup_property().
14533 * If this has already been called with @info, the existing cache is
14534 * used and its use count is increased.
14536 * Note that @info cannot be modified until
14537 * g_dbus_interface_info_cache_release() is called.
14544 * g_dbus_interface_info_cache_release:
14545 * @info: A GDBusInterfaceInfo
14547 * Decrements the usage count for the cache for @info built by
14548 * g_dbus_interface_info_cache_build() (if any) and frees the
14549 * resources used by the cache if the usage count drops to zero.
14556 * g_dbus_interface_info_generate_xml:
14557 * @info: A #GDBusNodeInfo
14558 * @indent: Indentation level.
14559 * @string_builder: (out): A #GString to to append XML data to.
14561 * Appends an XML representation of @info (and its children) to @string_builder.
14563 * This function is typically used for generating introspection XML
14564 * documents at run-time for handling the
14565 * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
14573 * g_dbus_interface_info_lookup_method:
14574 * @info: A #GDBusInterfaceInfo.
14575 * @name: A D-Bus method name (typically in CamelCase)
14577 * Looks up information about a method.
14579 * The cost of this function is O(n) in number of methods unless
14580 * g_dbus_interface_info_cache_build() has been used on @info.
14582 * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
14588 * g_dbus_interface_info_lookup_property:
14589 * @info: A #GDBusInterfaceInfo.
14590 * @name: A D-Bus property name (typically in CamelCase).
14592 * Looks up information about a property.
14594 * The cost of this function is O(n) in number of properties unless
14595 * g_dbus_interface_info_cache_build() has been used on @info.
14597 * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
14603 * g_dbus_interface_info_lookup_signal:
14604 * @info: A #GDBusInterfaceInfo.
14605 * @name: A D-Bus signal name (typically in CamelCase)
14607 * Looks up information about a signal.
14609 * The cost of this function is O(n) in number of signals unless
14610 * g_dbus_interface_info_cache_build() has been used on @info.
14612 * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
14618 * g_dbus_interface_info_ref:
14619 * @info: A #GDBusInterfaceInfo
14621 * If @info is statically allocated does nothing. Otherwise increases
14622 * the reference count.
14624 * Returns: The same @info.
14630 * g_dbus_interface_info_unref:
14631 * @info: A #GDBusInterfaceInfo.
14633 * If @info is statically allocated, does nothing. Otherwise decreases
14634 * the reference count of @info. When its reference count drops to 0,
14635 * the memory used is freed.
14642 * g_dbus_interface_set_object:
14643 * @interface_: An exported D-Bus interface.
14644 * @object: (allow-none): A #GDBusObject or %NULL.
14646 * Sets the #GDBusObject for @interface_ to @object.
14648 * Note that @interface_ will hold a weak reference to @object.
14655 * g_dbus_interface_skeleton_export:
14656 * @interface_: The D-Bus interface to export.
14657 * @connection: A #GDBusConnection to export @interface_ on.
14658 * @object_path: The path to export the interface at.
14659 * @error: Return location for error or %NULL.
14661 * Exports @interface_ at @object_path on @connection.
14663 * This can be called multiple times to export the same @interface_
14664 * onto multiple connections however the @object_path provided must be
14665 * the same for all connections.
14667 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
14669 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set.
14675 * g_dbus_interface_skeleton_flush:
14676 * @interface_: A #GDBusInterfaceSkeleton.
14678 * If @interface_ has outstanding changes, request for these changes to be
14679 * emitted immediately.
14681 * For example, an exported D-Bus interface may queue up property
14682 * changes and emit the
14683 * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
14684 * signal later (e.g. in an idle handler). This technique is useful
14685 * for collapsing multiple property changes into one.
14692 * g_dbus_interface_skeleton_get_connection:
14693 * @interface_: A #GDBusInterfaceSkeleton.
14695 * Gets the first connection that @interface_ is exported on, if any.
14697 * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_.
14703 * g_dbus_interface_skeleton_get_connections:
14704 * @interface_: A #GDBusInterfaceSkeleton.
14706 * Gets a list of the connections that @interface_ is exported on.
14708 * Returns: (element-type GDBusConnection) (transfer full): A list of all the connections that @interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().
14714 * g_dbus_interface_skeleton_get_flags:
14715 * @interface_: A #GDBusInterfaceSkeleton.
14717 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
14720 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
14726 * g_dbus_interface_skeleton_get_info:
14727 * @interface_: A #GDBusInterfaceSkeleton.
14729 * Gets D-Bus introspection information for the D-Bus interface
14730 * implemented by @interface_.
14732 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
14738 * g_dbus_interface_skeleton_get_object_path:
14739 * @interface_: A #GDBusInterfaceSkeleton.
14741 * Gets the object path that @interface_ is exported on, if any.
14743 * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_.
14749 * g_dbus_interface_skeleton_get_properties:
14750 * @interface_: A #GDBusInterfaceSkeleton.
14752 * Gets all D-Bus properties for @interface_.
14754 * Returns: (transfer full): A #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref().
14760 * g_dbus_interface_skeleton_get_vtable: (skip)
14761 * @interface_: A #GDBusInterfaceSkeleton.
14763 * Gets the interface vtable for the D-Bus interface implemented by
14764 * @interface_. The returned function pointers should expect @interface_
14765 * itself to be passed as @user_data.
14767 * Returns: A #GDBusInterfaceVTable (never %NULL).
14773 * g_dbus_interface_skeleton_has_connection:
14774 * @interface_: A #GDBusInterfaceSkeleton.
14775 * @connection: A #GDBusConnection.
14777 * Checks if @interface_ is exported on @connection.
14779 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
14785 * g_dbus_interface_skeleton_set_flags:
14786 * @interface_: A #GDBusInterfaceSkeleton.
14787 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
14789 * Sets flags describing what the behavior of @skeleton should be.
14796 * g_dbus_interface_skeleton_unexport:
14797 * @interface_: A #GDBusInterfaceSkeleton.
14799 * Stops exporting @interface_ on all connections it is exported on.
14801 * To unexport @interface_ from only a single connection, use
14802 * g_dbus_interface_skeleton_unexport_from_connection()
14809 * g_dbus_interface_skeleton_unexport_from_connection:
14810 * @interface_: A #GDBusInterfaceSkeleton.
14811 * @connection: A #GDBusConnection.
14813 * Stops exporting @interface_ on @connection.
14815 * To stop exporting on all connections the interface is exported on,
14816 * use g_dbus_interface_skeleton_unexport().
14823 * g_dbus_is_address:
14824 * @string: A string.
14826 * Checks if @string is a D-Bus address.
14828 * This doesn't check if @string is actually supported by #GDBusServer
14829 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
14832 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
14839 * @string: The string to check.
14841 * Checks if @string is a D-Bus GUID.
14843 * See the D-Bus specification regarding what strings are valid D-Bus
14844 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
14846 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
14852 * g_dbus_is_interface_name:
14853 * @string: The string to check.
14855 * Checks if @string is a valid D-Bus interface name.
14857 * Returns: %TRUE if valid, %FALSE otherwise.
14863 * g_dbus_is_member_name:
14864 * @string: The string to check.
14866 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
14868 * Returns: %TRUE if valid, %FALSE otherwise.
14875 * @string: The string to check.
14877 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
14879 * Returns: %TRUE if valid, %FALSE otherwise.
14885 * g_dbus_is_supported_address:
14886 * @string: A string.
14887 * @error: Return location for error or %NULL.
14889 * Like g_dbus_is_address() but also checks if the library suppors the
14890 * transports in @string and that key/value pairs for each transport
14893 * Returns: %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set.
14899 * g_dbus_is_unique_name:
14900 * @string: The string to check.
14902 * Checks if @string is a valid D-Bus unique bus name.
14904 * Returns: %TRUE if valid, %FALSE otherwise.
14910 * g_dbus_menu_model_get:
14911 * @connection: a #GDBusConnection
14912 * @bus_name: the bus name which exports the menu model
14913 * @object_path: the object path at which the menu model is exported
14915 * Obtains a #GDBusMenuModel for the menu model which is exported
14916 * at the given @bus_name and @object_path.
14918 * The thread default main context is taken at the time of this call.
14919 * All signals on the menu model (and any linked models) are reported
14920 * with respect to this context. All calls on the returned menu model
14921 * (and linked models) must also originate from this same context, with
14922 * the thread default main context unchanged.
14924 * Returns: (transfer full): a #GDBusMenuModel object. Free with g_object_unref().
14930 * g_dbus_message_bytes_needed:
14931 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
14932 * @blob_len: The length of @blob (must be at least 16).
14933 * @error: Return location for error or %NULL.
14935 * Utility function to calculate how many bytes are needed to
14936 * completely deserialize the D-Bus message stored at @blob.
14938 * Returns: Number of bytes needed or -1 if @error is set (e.g. if @blob contains invalid data or not enough data is available to determine the size).
14944 * g_dbus_message_copy:
14945 * @message: A #GDBusMessage.
14946 * @error: Return location for error or %NULL.
14948 * Copies @message. The copy is a deep copy and the returned
14949 * #GDBusMessage is completely identical except that it is guaranteed
14950 * to not be locked.
14952 * This operation can fail if e.g. @message contains file descriptors
14953 * and the per-process or system-wide open files limit is reached.
14955 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref().
14961 * g_dbus_message_get_arg0:
14962 * @message: A #GDBusMessage.
14964 * Convenience to get the first item in the body of @message.
14966 * Returns: The string item or %NULL if the first item in the body of @message is not a string.
14972 * g_dbus_message_get_body:
14973 * @message: A #GDBusMessage.
14975 * Gets the body of a message.
14977 * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
14983 * g_dbus_message_get_byte_order:
14984 * @message: A #GDBusMessage.
14986 * Gets the byte order of @message.
14988 * Returns: The byte order.
14993 * g_dbus_message_get_destination:
14994 * @message: A #GDBusMessage.
14996 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
14998 * Returns: The value.
15004 * g_dbus_message_get_error_name:
15005 * @message: A #GDBusMessage.
15007 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
15009 * Returns: The value.
15015 * g_dbus_message_get_flags:
15016 * @message: A #GDBusMessage.
15018 * Gets the flags for @message.
15020 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
15026 * g_dbus_message_get_header:
15027 * @message: A #GDBusMessage.
15028 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
15030 * Gets a header field on @message.
15032 * Returns: A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message.
15038 * g_dbus_message_get_header_fields:
15039 * @message: A #GDBusMessage.
15041 * Gets an array of all header fields on @message that are set.
15043 * Returns: (array zero-terminated=1): An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free().
15049 * g_dbus_message_get_interface:
15050 * @message: A #GDBusMessage.
15052 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
15054 * Returns: The value.
15060 * g_dbus_message_get_locked:
15061 * @message: A #GDBusMessage.
15063 * Checks whether @message is locked. To monitor changes to this
15064 * value, conncet to the #GObject::notify signal to listen for changes
15065 * on the #GDBusMessage:locked property.
15067 * Returns: %TRUE if @message is locked, %FALSE otherwise.
15073 * g_dbus_message_get_member:
15074 * @message: A #GDBusMessage.
15076 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
15078 * Returns: The value.
15084 * g_dbus_message_get_message_type:
15085 * @message: A #GDBusMessage.
15087 * Gets the type of @message.
15089 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
15095 * g_dbus_message_get_num_unix_fds:
15096 * @message: A #GDBusMessage.
15098 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
15100 * Returns: The value.
15106 * g_dbus_message_get_path:
15107 * @message: A #GDBusMessage.
15109 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
15111 * Returns: The value.
15117 * g_dbus_message_get_reply_serial:
15118 * @message: A #GDBusMessage.
15120 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
15122 * Returns: The value.
15128 * g_dbus_message_get_sender:
15129 * @message: A #GDBusMessage.
15131 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
15133 * Returns: The value.
15139 * g_dbus_message_get_serial:
15140 * @message: A #GDBusMessage.
15142 * Gets the serial for @message.
15144 * Returns: A #guint32.
15150 * g_dbus_message_get_signature:
15151 * @message: A #GDBusMessage.
15153 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
15155 * Returns: The value.
15161 * g_dbus_message_get_unix_fd_list:
15162 * @message: A #GDBusMessage.
15164 * Gets the UNIX file descriptors associated with @message, if any.
15166 * This method is only available on UNIX.
15168 * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message.
15174 * g_dbus_message_lock:
15175 * @message: A #GDBusMessage.
15177 * If @message is locked, does nothing. Otherwise locks the message.
15184 * g_dbus_message_new:
15186 * Creates a new empty #GDBusMessage.
15188 * Returns: A #GDBusMessage. Free with g_object_unref().
15194 * g_dbus_message_new_from_blob:
15195 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
15196 * @blob_len: The length of @blob.
15197 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
15198 * @error: Return location for error or %NULL.
15200 * Creates a new #GDBusMessage from the data stored at @blob. The byte
15201 * order that the message was in can be retrieved using
15202 * g_dbus_message_get_byte_order().
15204 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref().
15210 * g_dbus_message_new_method_call:
15211 * @name: (allow-none): A valid D-Bus name or %NULL.
15212 * @path: A valid object path.
15213 * @interface_: (allow-none): A valid D-Bus interface name or %NULL.
15214 * @method: A valid method name.
15216 * Creates a new #GDBusMessage for a method call.
15218 * Returns: A #GDBusMessage. Free with g_object_unref().
15224 * g_dbus_message_new_method_error:
15225 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
15226 * @error_name: A valid D-Bus error name.
15227 * @error_message_format: The D-Bus error message in a printf() format.
15228 * @...: Arguments for @error_message_format.
15230 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
15232 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
15238 * g_dbus_message_new_method_error_literal:
15239 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
15240 * @error_name: A valid D-Bus error name.
15241 * @error_message: The D-Bus error message.
15243 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
15245 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
15251 * g_dbus_message_new_method_error_valist:
15252 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
15253 * @error_name: A valid D-Bus error name.
15254 * @error_message_format: The D-Bus error message in a printf() format.
15255 * @var_args: Arguments for @error_message_format.
15257 * Like g_dbus_message_new_method_error() but intended for language bindings.
15259 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
15265 * g_dbus_message_new_method_reply:
15266 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
15268 * Creates a new #GDBusMessage that is a reply to @method_call_message.
15270 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
15276 * g_dbus_message_new_signal:
15277 * @path: A valid object path.
15278 * @interface_: A valid D-Bus interface name.
15279 * @signal: A valid signal name.
15281 * Creates a new #GDBusMessage for a signal emission.
15283 * Returns: A #GDBusMessage. Free with g_object_unref().
15289 * g_dbus_message_print:
15290 * @message: A #GDBusMessage.
15291 * @indent: Indentation level.
15293 * Produces a human-readable multi-line description of @message.
15295 * The contents of the description has no ABI guarantees, the contents
15296 * and formatting is subject to change at any time. Typical output
15297 * looks something like this:
15299 * Type: method-call
15300 * Flags: none
15304 * path -> objectpath '/org/gtk/GDBus/TestObject'
15305 * interface -> 'org.gtk.GDBus.TestInterface'
15306 * member -> 'GimmeStdout'
15307 * destination -> ':1.146'
15309 * UNIX File Descriptors:
15311 * </programlisting>
15314 * Type: method-return
15315 * Flags: no-reply-expected
15317 * Serial: 477
15319 * reply-serial -> uint32 4
15320 * destination -> ':1.159'
15321 * sender -> ':1.146'
15322 * num-unix-fds -> uint32 1
15324 * UNIX File Descriptors:
15325 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
15326 * </programlisting>
15328 * Returns: A string that should be freed with g_free().
15334 * g_dbus_message_set_body:
15335 * @message: A #GDBusMessage.
15336 * @body: Either %NULL or a #GVariant that is a tuple.
15338 * Sets the body @message. As a side-effect the
15339 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
15340 * type string of @body (or cleared if @body is %NULL).
15342 * If @body is floating, @message assumes ownership of @body.
15349 * g_dbus_message_set_byte_order:
15350 * @message: A #GDBusMessage.
15351 * @byte_order: The byte order.
15353 * Sets the byte order of @message.
15358 * g_dbus_message_set_destination:
15359 * @message: A #GDBusMessage.
15360 * @value: The value to set.
15362 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
15369 * g_dbus_message_set_error_name:
15370 * @message: A #GDBusMessage.
15371 * @value: The value to set.
15373 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
15380 * g_dbus_message_set_flags:
15381 * @message: A #GDBusMessage.
15382 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
15384 * Sets the flags to set on @message.
15391 * g_dbus_message_set_header:
15392 * @message: A #GDBusMessage.
15393 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
15394 * @value: (allow-none): A #GVariant to set the header field or %NULL to clear the header field.
15396 * Sets a header field on @message.
15398 * If @value is floating, @message assumes ownership of @value.
15405 * g_dbus_message_set_interface:
15406 * @message: A #GDBusMessage.
15407 * @value: The value to set.
15409 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
15416 * g_dbus_message_set_member:
15417 * @message: A #GDBusMessage.
15418 * @value: The value to set.
15420 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
15427 * g_dbus_message_set_message_type:
15428 * @message: A #GDBusMessage.
15429 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
15431 * Sets @message to be of @type.
15438 * g_dbus_message_set_num_unix_fds:
15439 * @message: A #GDBusMessage.
15440 * @value: The value to set.
15442 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
15449 * g_dbus_message_set_path:
15450 * @message: A #GDBusMessage.
15451 * @value: The value to set.
15453 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
15460 * g_dbus_message_set_reply_serial:
15461 * @message: A #GDBusMessage.
15462 * @value: The value to set.
15464 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
15471 * g_dbus_message_set_sender:
15472 * @message: A #GDBusMessage.
15473 * @value: The value to set.
15475 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
15482 * g_dbus_message_set_serial:
15483 * @message: A #GDBusMessage.
15484 * @serial: A #guint32.
15486 * Sets the serial for @message.
15493 * g_dbus_message_set_signature:
15494 * @message: A #GDBusMessage.
15495 * @value: The value to set.
15497 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
15504 * g_dbus_message_set_unix_fd_list:
15505 * @message: A #GDBusMessage.
15506 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
15508 * Sets the UNIX file descriptors associated with @message. As a
15509 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
15510 * field is set to the number of fds in @fd_list (or cleared if
15511 * @fd_list is %NULL).
15513 * This method is only available on UNIX.
15520 * g_dbus_message_to_blob:
15521 * @message: A #GDBusMessage.
15522 * @out_size: Return location for size of generated blob.
15523 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
15524 * @error: Return location for error.
15526 * Serializes @message to a blob. The byte order returned by
15527 * g_dbus_message_get_byte_order() will be used.
15529 * Returns: (array length=out_size) (transfer full): A pointer to a valid binary D-Bus message of @out_size bytes generated by @message or %NULL if @error is set. Free with g_free().
15535 * g_dbus_message_to_gerror:
15536 * @message: A #GDBusMessage.
15537 * @error: The #GError to set.
15539 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
15540 * nothing and returns %FALSE.
15542 * Otherwise this method encodes the error in @message as a #GError
15543 * using g_dbus_error_set_dbus_error() using the information in the
15544 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
15545 * well as the first string item in @message's body.
15547 * Returns: %TRUE if @error was set, %FALSE otherwise.
15553 * g_dbus_method_info_ref:
15554 * @info: A #GDBusMethodInfo
15556 * If @info is statically allocated does nothing. Otherwise increases
15557 * the reference count.
15559 * Returns: The same @info.
15565 * g_dbus_method_info_unref:
15566 * @info: A #GDBusMethodInfo.
15568 * If @info is statically allocated, does nothing. Otherwise decreases
15569 * the reference count of @info. When its reference count drops to 0,
15570 * the memory used is freed.
15577 * g_dbus_method_invocation_get_connection:
15578 * @invocation: A #GDBusMethodInvocation.
15580 * Gets the #GDBusConnection the method was invoked on.
15582 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
15588 * g_dbus_method_invocation_get_interface_name:
15589 * @invocation: A #GDBusMethodInvocation.
15591 * Gets the name of the D-Bus interface the method was invoked on.
15593 * Returns: A string. Do not free, it is owned by @invocation.
15599 * g_dbus_method_invocation_get_message:
15600 * @invocation: A #GDBusMethodInvocation.
15602 * Gets the #GDBusMessage for the method invocation. This is useful if
15603 * you need to use low-level protocol features, such as UNIX file
15604 * descriptor passing, that cannot be properly expressed in the
15607 * See <xref linkend="gdbus-server"/> and <xref
15608 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
15609 * low-level API to send and receive UNIX file descriptors.
15611 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
15617 * g_dbus_method_invocation_get_method_info:
15618 * @invocation: A #GDBusMethodInvocation.
15620 * Gets information about the method call, if any.
15622 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
15628 * g_dbus_method_invocation_get_method_name:
15629 * @invocation: A #GDBusMethodInvocation.
15631 * Gets the name of the method that was invoked.
15633 * Returns: A string. Do not free, it is owned by @invocation.
15639 * g_dbus_method_invocation_get_object_path:
15640 * @invocation: A #GDBusMethodInvocation.
15642 * Gets the object path the method was invoked on.
15644 * Returns: A string. Do not free, it is owned by @invocation.
15650 * g_dbus_method_invocation_get_parameters:
15651 * @invocation: A #GDBusMethodInvocation.
15653 * Gets the parameters of the method invocation. If there are no input
15654 * parameters then this will return a GVariant with 0 children rather than NULL.
15656 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
15662 * g_dbus_method_invocation_get_sender:
15663 * @invocation: A #GDBusMethodInvocation.
15665 * Gets the bus name that invoked the method.
15667 * Returns: A string. Do not free, it is owned by @invocation.
15673 * g_dbus_method_invocation_get_user_data: (skip)
15674 * @invocation: A #GDBusMethodInvocation.
15676 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
15678 * Returns: A #gpointer.
15684 * g_dbus_method_invocation_return_dbus_error:
15685 * @invocation: (transfer full): A #GDBusMethodInvocation.
15686 * @error_name: A valid D-Bus error name.
15687 * @error_message: A valid D-Bus error message.
15689 * Finishes handling a D-Bus method call by returning an error.
15691 * This method will free @invocation, you cannot use it afterwards.
15698 * g_dbus_method_invocation_return_error:
15699 * @invocation: (transfer full): A #GDBusMethodInvocation.
15700 * @domain: A #GQuark for the #GError error domain.
15701 * @code: The error code.
15702 * @format: printf()-style format.
15703 * @...: Parameters for @format.
15705 * Finishes handling a D-Bus method call by returning an error.
15707 * See g_dbus_error_encode_gerror() for details about what error name
15708 * will be returned on the wire. In a nutshell, if the given error is
15709 * registered using g_dbus_error_register_error() the name given
15710 * during registration is used. Otherwise, a name of the form
15711 * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
15712 * used. This provides transparent mapping of #GError between
15713 * applications using GDBus.
15715 * If you are writing an application intended to be portable,
15716 * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
15717 * or use g_dbus_method_invocation_return_dbus_error().
15719 * This method will free @invocation, you cannot use it afterwards.
15726 * g_dbus_method_invocation_return_error_literal:
15727 * @invocation: (transfer full): A #GDBusMethodInvocation.
15728 * @domain: A #GQuark for the #GError error domain.
15729 * @code: The error code.
15730 * @message: The error message.
15732 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
15734 * This method will free @invocation, you cannot use it afterwards.
15741 * g_dbus_method_invocation_return_error_valist:
15742 * @invocation: (transfer full): A #GDBusMethodInvocation.
15743 * @domain: A #GQuark for the #GError error domain.
15744 * @code: The error code.
15745 * @format: printf()-style format.
15746 * @var_args: #va_list of parameters for @format.
15748 * Like g_dbus_method_invocation_return_error() but intended for
15749 * language bindings.
15751 * This method will free @invocation, you cannot use it afterwards.
15758 * g_dbus_method_invocation_return_gerror:
15759 * @invocation: (transfer full): A #GDBusMethodInvocation.
15760 * @error: A #GError.
15762 * Like g_dbus_method_invocation_return_error() but takes a #GError
15763 * instead of the error domain, error code and message.
15765 * This method will free @invocation, you cannot use it afterwards.
15772 * g_dbus_method_invocation_return_value:
15773 * @invocation: (transfer full): A #GDBusMethodInvocation.
15774 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
15776 * Finishes handling a D-Bus method call by returning @parameters.
15777 * If the @parameters GVariant is floating, it is consumed.
15779 * It is an error if @parameters is not of the right format.
15781 * This method will free @invocation, you cannot use it afterwards.
15788 * g_dbus_method_invocation_return_value_with_unix_fd_list:
15789 * @invocation: (transfer full): A #GDBusMethodInvocation.
15790 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
15791 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
15793 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
15795 * This method is only available on UNIX.
15797 * This method will free @invocation, you cannot use it afterwards.
15804 * g_dbus_method_invocation_take_error: (skip)
15805 * @invocation: (transfer full): A #GDBusMethodInvocation.
15806 * @error: (transfer full): A #GError.
15808 * Like g_dbus_method_invocation_return_gerror() but takes ownership
15809 * of @error so the caller does not need to free it.
15811 * This method will free @invocation, you cannot use it afterwards.
15818 * g_dbus_node_info_generate_xml:
15819 * @info: A #GDBusNodeInfo.
15820 * @indent: Indentation level.
15821 * @string_builder: (out): A #GString to to append XML data to.
15823 * Appends an XML representation of @info (and its children) to @string_builder.
15825 * This function is typically used for generating introspection XML documents at run-time for
15826 * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
15833 * g_dbus_node_info_lookup_interface:
15834 * @info: A #GDBusNodeInfo.
15835 * @name: A D-Bus interface name.
15837 * Looks up information about an interface.
15839 * The cost of this function is O(n) in number of interfaces.
15841 * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
15847 * g_dbus_node_info_new_for_xml:
15848 * @xml_data: Valid D-Bus introspection XML.
15849 * @error: Return location for error.
15851 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
15853 * The introspection XML must contain exactly one top-level
15854 * <tag class="starttag">node</tag> element.
15856 * Note that this routine is using a
15857 * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
15858 * parser that only accepts a subset of valid XML documents.
15860 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref().
15866 * g_dbus_node_info_ref:
15867 * @info: A #GDBusNodeInfo
15869 * If @info is statically allocated does nothing. Otherwise increases
15870 * the reference count.
15872 * Returns: The same @info.
15878 * g_dbus_node_info_unref:
15879 * @info: A #GDBusNodeInfo.
15881 * If @info is statically allocated, does nothing. Otherwise decreases
15882 * the reference count of @info. When its reference count drops to 0,
15883 * the memory used is freed.
15890 * g_dbus_object_get_interface:
15891 * @object: A #GDBusObject.
15892 * @interface_name: A D-Bus interface name.
15894 * Gets the D-Bus interface with name @interface_name associated with
15897 * Returns: (transfer full): %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref().
15903 * g_dbus_object_get_interfaces:
15904 * @object: A #GDBusObject.
15906 * Gets the D-Bus interfaces associated with @object.
15908 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref().
15914 * g_dbus_object_get_object_path:
15915 * @object: A #GDBusObject.
15917 * Gets the object path for @object.
15919 * Returns: A string owned by @object. Do not free.
15925 * g_dbus_object_manager_client_get_connection:
15926 * @manager: A #GDBusObjectManagerClient
15928 * Gets the #GDBusConnection used by @manager.
15930 * Returns: (transfer none): A #GDBusConnection object. Do not free, the object belongs to @manager.
15936 * g_dbus_object_manager_client_get_flags:
15937 * @manager: A #GDBusObjectManagerClient
15939 * Gets the flags that @manager was constructed with.
15941 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags enumeration.
15947 * g_dbus_object_manager_client_get_name:
15948 * @manager: A #GDBusObjectManagerClient
15950 * Gets the name that @manager is for, or %NULL if not a message bus
15953 * Returns: A unique or well-known name. Do not free, the string belongs to @manager.
15959 * g_dbus_object_manager_client_get_name_owner:
15960 * @manager: A #GDBusObjectManagerClient.
15962 * The unique name that owns the name that @manager is for or %NULL if
15963 * no-one currently owns that name. You can connect to the
15964 * #GObject::notify signal to track changes to the
15965 * #GDBusObjectManagerClient:name-owner property.
15967 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
15973 * g_dbus_object_manager_client_new:
15974 * @connection: A #GDBusConnection.
15975 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
15976 * @name: The owner of the control object (unique or well-known name).
15977 * @object_path: The object path of the control object.
15978 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
15979 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
15980 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
15981 * @cancellable: (allow-none): A #GCancellable or %NULL
15982 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
15983 * @user_data: The data to pass to @callback.
15985 * Asynchronously creates a new #GDBusObjectManagerClient object.
15987 * This is an asynchronous failable constructor. When the result is
15988 * ready, @callback will be invoked in the
15989 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
15990 * of the thread you are calling this method from. You can
15991 * then call g_dbus_object_manager_client_new_finish() to get the result. See
15992 * g_dbus_object_manager_client_new_sync() for the synchronous version.
15999 * g_dbus_object_manager_client_new_finish:
16000 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
16001 * @error: Return location for error or %NULL.
16003 * Finishes an operation started with g_dbus_object_manager_client_new().
16005 * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
16011 * g_dbus_object_manager_client_new_for_bus:
16012 * @bus_type: A #GBusType.
16013 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
16014 * @name: The owner of the control object (unique or well-known name).
16015 * @object_path: The object path of the control object.
16016 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
16017 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
16018 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
16019 * @cancellable: (allow-none): A #GCancellable or %NULL
16020 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
16021 * @user_data: The data to pass to @callback.
16023 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
16024 * #GDBusConnection.
16026 * This is an asynchronous failable constructor. When the result is
16027 * ready, @callback will be invoked in the
16028 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
16029 * of the thread you are calling this method from. You can
16030 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
16031 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
16038 * g_dbus_object_manager_client_new_for_bus_finish:
16039 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
16040 * @error: Return location for error or %NULL.
16042 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
16044 * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
16050 * g_dbus_object_manager_client_new_for_bus_sync:
16051 * @bus_type: A #GBusType.
16052 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
16053 * @name: The owner of the control object (unique or well-known name).
16054 * @object_path: The object path of the control object.
16055 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
16056 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
16057 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
16058 * @cancellable: (allow-none): A #GCancellable or %NULL
16059 * @error: Return location for error or %NULL.
16061 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
16062 * of a #GDBusConnection.
16064 * This is a synchronous failable constructor - the calling thread is
16065 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
16066 * for the asynchronous version.
16068 * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
16074 * g_dbus_object_manager_client_new_sync:
16075 * @connection: A #GDBusConnection.
16076 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
16077 * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
16078 * @object_path: The object path of the control object.
16079 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
16080 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
16081 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
16082 * @cancellable: (allow-none): A #GCancellable or %NULL
16083 * @error: Return location for error or %NULL.
16085 * Creates a new #GDBusObjectManagerClient object.
16087 * This is a synchronous failable constructor - the calling thread is
16088 * blocked until a reply is received. See g_dbus_object_manager_client_new()
16089 * for the asynchronous version.
16091 * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
16097 * g_dbus_object_manager_get_interface:
16098 * @manager: A #GDBusObjectManager.
16099 * @object_path: Object path to lookup.
16100 * @interface_name: D-Bus interface name to lookup.
16102 * Gets the interface proxy for @interface_name at @object_path, if
16105 * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free with g_object_unref().
16111 * g_dbus_object_manager_get_object:
16112 * @manager: A #GDBusObjectManager.
16113 * @object_path: Object path to lookup.
16115 * Gets the #GDBusObjectProxy at @object_path, if any.
16117 * Returns: (transfer full): A #GDBusObject or %NULL. Free with g_object_unref().
16123 * g_dbus_object_manager_get_object_path:
16124 * @manager: A #GDBusObjectManager.
16126 * Gets the object path that @manager is for.
16128 * Returns: A string owned by @manager. Do not free.
16134 * g_dbus_object_manager_get_objects:
16135 * @manager: A #GDBusObjectManager.
16137 * Gets all #GDBusObject objects known to @manager.
16139 * Returns: (transfer full) (element-type GDBusObject): A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().
16145 * g_dbus_object_manager_server_export:
16146 * @manager: A #GDBusObjectManagerServer.
16147 * @object: A #GDBusObjectSkeleton.
16149 * Exports @object on @manager.
16151 * If there is already a #GDBusObject exported at the object path,
16152 * then the old object is removed.
16154 * The object path for @object must be in the hierarchy rooted by the
16155 * object path for @manager.
16157 * Note that @manager will take a reference on @object for as long as
16165 * g_dbus_object_manager_server_export_uniquely:
16166 * @manager: A #GDBusObjectManagerServer.
16167 * @object: An object.
16169 * Like g_dbus_object_manager_server_export() but appends a string of
16170 * the form <literal>_N</literal> (with N being a natural number) to
16171 * @object<!-- -->'s object path if an object with the given path
16172 * already exists. As such, the #GDBusObjectProxy:g-object-path property
16173 * of @object may be modified.
16180 * g_dbus_object_manager_server_get_connection:
16181 * @manager: A #GDBusObjectManagerServer
16183 * Gets the #GDBusConnection used by @manager.
16185 * Returns: (transfer full): A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref().
16191 * g_dbus_object_manager_server_is_exported:
16192 * @manager: A #GDBusObjectManagerServer.
16193 * @object: An object.
16195 * Returns whether @object is currently exported on @manager.
16197 * Returns: %TRUE if @object is exported
16203 * g_dbus_object_manager_server_new:
16204 * @object_path: The object path to export the manager object at.
16206 * Creates a new #GDBusObjectManagerServer object.
16208 * The returned server isn't yet exported on any connection. To do so,
16209 * use g_dbus_object_manager_server_set_connection(). Normally you
16210 * want to export all of your objects before doing so to avoid <ulink
16211 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
16212 * signals being emitted.
16214 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
16220 * g_dbus_object_manager_server_set_connection:
16221 * @manager: A #GDBusObjectManagerServer.
16222 * @connection: (allow-none): A #GDBusConnection or %NULL.
16224 * Exports all objects managed by @manager on @connection. If
16225 * @connection is %NULL, stops exporting objects.
16230 * g_dbus_object_manager_server_unexport:
16231 * @manager: A #GDBusObjectManagerServer.
16232 * @object_path: An object path.
16234 * If @manager has an object at @path, removes the object. Otherwise
16237 * Note that @object_path must be in the hierarchy rooted by the
16238 * object path for @manager.
16240 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
16246 * g_dbus_object_proxy_get_connection:
16247 * @proxy: a #GDBusObjectProxy
16249 * Gets the connection that @proxy is for.
16251 * Returns: (transfer none): A #GDBusConnection. Do not free, the object is owned by @proxy.
16257 * g_dbus_object_proxy_new:
16258 * @connection: a #GDBusConnection
16259 * @object_path: the object path
16261 * Creates a new #GDBusObjectProxy for the given connection and
16264 * Returns: a new #GDBusObjectProxy
16270 * g_dbus_object_skeleton_add_interface:
16271 * @object: A #GDBusObjectSkeleton.
16272 * @interface_: A #GDBusInterfaceSkeleton.
16274 * Adds @interface_ to @object.
16276 * If @object already contains a #GDBusInterfaceSkeleton with the same
16277 * interface name, it is removed before @interface_ is added.
16279 * Note that @object takes its own reference on @interface_ and holds
16280 * it until removed.
16287 * g_dbus_object_skeleton_flush:
16288 * @object: A #GDBusObjectSkeleton.
16290 * This method simply calls g_dbus_interface_skeleton_flush() on all
16291 * interfaces belonging to @object. See that method for when flushing
16299 * g_dbus_object_skeleton_new:
16300 * @object_path: An object path.
16302 * Creates a new #GDBusObjectSkeleton.
16304 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
16310 * g_dbus_object_skeleton_remove_interface:
16311 * @object: A #GDBusObjectSkeleton.
16312 * @interface_: A #GDBusInterfaceSkeleton.
16314 * Removes @interface_ from @object.
16321 * g_dbus_object_skeleton_remove_interface_by_name:
16322 * @object: A #GDBusObjectSkeleton.
16323 * @interface_name: A D-Bus interface name.
16325 * Removes the #GDBusInterface with @interface_name from @object.
16327 * If no D-Bus interface of the given interface exists, this function
16335 * g_dbus_object_skeleton_set_object_path:
16336 * @object: A #GDBusObjectSkeleton.
16337 * @object_path: A valid D-Bus object path.
16339 * Sets the object path for @object.
16346 * g_dbus_property_info_ref:
16347 * @info: A #GDBusPropertyInfo
16349 * If @info is statically allocated does nothing. Otherwise increases
16350 * the reference count.
16352 * Returns: The same @info.
16358 * g_dbus_property_info_unref:
16359 * @info: A #GDBusPropertyInfo.
16361 * If @info is statically allocated, does nothing. Otherwise decreases
16362 * the reference count of @info. When its reference count drops to 0,
16363 * the memory used is freed.
16370 * g_dbus_proxy_call:
16371 * @proxy: A #GDBusProxy.
16372 * @method_name: Name of method to invoke.
16373 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
16374 * @flags: Flags from the #GDBusCallFlags enumeration.
16375 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
16376 * @cancellable: (allow-none): A #GCancellable or %NULL.
16377 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
16378 * @user_data: The data to pass to @callback.
16380 * Asynchronously invokes the @method_name method on @proxy.
16382 * If @method_name contains any dots, then @name is split into interface and
16383 * method name parts. This allows using @proxy for invoking methods on
16384 * other interfaces.
16386 * If the #GDBusConnection associated with @proxy is closed then
16387 * the operation will fail with %G_IO_ERROR_CLOSED. If
16388 * @cancellable is canceled, the operation will fail with
16389 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
16390 * compatible with the D-Bus protocol, the operation fails with
16391 * %G_IO_ERROR_INVALID_ARGUMENT.
16393 * If the @parameters #GVariant is floating, it is consumed. This allows
16394 * convenient 'inline' use of g_variant_new(), e.g.:
16396 * g_dbus_proxy_call (proxy,
16398 * g_variant_new ("(ss)",
16401 * G_DBUS_CALL_FLAGS_NONE,
16404 * (GAsyncReadyCallback) two_strings_done,
16408 * If @proxy has an expected interface (see
16409 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
16410 * then the return value is checked against the return type.
16412 * This is an asynchronous method. When the operation is finished,
16413 * @callback will be invoked in the
16414 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
16415 * of the thread you are calling this method from.
16416 * You can then call g_dbus_proxy_call_finish() to get the result of
16417 * the operation. See g_dbus_proxy_call_sync() for the synchronous
16418 * version of this method.
16420 * If @callback is %NULL then the D-Bus method call message will be sent with
16421 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
16428 * g_dbus_proxy_call_finish:
16429 * @proxy: A #GDBusProxy.
16430 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
16431 * @error: Return location for error or %NULL.
16433 * Finishes an operation started with g_dbus_proxy_call().
16435 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
16441 * g_dbus_proxy_call_sync:
16442 * @proxy: A #GDBusProxy.
16443 * @method_name: Name of method to invoke.
16444 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
16445 * @flags: Flags from the #GDBusCallFlags enumeration.
16446 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
16447 * @cancellable: (allow-none): A #GCancellable or %NULL.
16448 * @error: Return location for error or %NULL.
16450 * Synchronously invokes the @method_name method on @proxy.
16452 * If @method_name contains any dots, then @name is split into interface and
16453 * method name parts. This allows using @proxy for invoking methods on
16454 * other interfaces.
16456 * If the #GDBusConnection associated with @proxy is disconnected then
16457 * the operation will fail with %G_IO_ERROR_CLOSED. If
16458 * @cancellable is canceled, the operation will fail with
16459 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
16460 * compatible with the D-Bus protocol, the operation fails with
16461 * %G_IO_ERROR_INVALID_ARGUMENT.
16463 * If the @parameters #GVariant is floating, it is consumed. This allows
16464 * convenient 'inline' use of g_variant_new(), e.g.:
16466 * g_dbus_proxy_call_sync (proxy,
16468 * g_variant_new ("(ss)",
16471 * G_DBUS_CALL_FLAGS_NONE,
16477 * The calling thread is blocked until a reply is received. See
16478 * g_dbus_proxy_call() for the asynchronous version of this
16481 * If @proxy has an expected interface (see
16482 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
16483 * then the return value is checked against the return type.
16485 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
16491 * g_dbus_proxy_call_with_unix_fd_list:
16492 * @proxy: A #GDBusProxy.
16493 * @method_name: Name of method to invoke.
16494 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
16495 * @flags: Flags from the #GDBusCallFlags enumeration.
16496 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
16497 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
16498 * @cancellable: (allow-none): A #GCancellable or %NULL.
16499 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
16500 * @user_data: The data to pass to @callback.
16502 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
16504 * This method is only available on UNIX.
16511 * g_dbus_proxy_call_with_unix_fd_list_finish:
16512 * @proxy: A #GDBusProxy.
16513 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
16514 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
16515 * @error: Return location for error or %NULL.
16517 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
16519 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
16525 * g_dbus_proxy_call_with_unix_fd_list_sync:
16526 * @proxy: A #GDBusProxy.
16527 * @method_name: Name of method to invoke.
16528 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
16529 * @flags: Flags from the #GDBusCallFlags enumeration.
16530 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
16531 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
16532 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
16533 * @cancellable: (allow-none): A #GCancellable or %NULL.
16534 * @error: Return location for error or %NULL.
16536 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
16538 * This method is only available on UNIX.
16540 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
16546 * g_dbus_proxy_get_cached_property:
16547 * @proxy: A #GDBusProxy.
16548 * @property_name: Property name.
16550 * Looks up the value for a property from the cache. This call does no
16553 * If @proxy has an expected interface (see
16554 * #GDBusProxy:g-interface-info) and @property_name is referenced by
16555 * it, then @value is checked against the type of the property.
16557 * Returns: A reference to the #GVariant instance that holds the value for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref().
16563 * g_dbus_proxy_get_cached_property_names:
16564 * @proxy: A #GDBusProxy.
16566 * Gets the names of all cached properties on @proxy.
16568 * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev().
16574 * g_dbus_proxy_get_connection:
16575 * @proxy: A #GDBusProxy.
16577 * Gets the connection @proxy is for.
16579 * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
16585 * g_dbus_proxy_get_default_timeout:
16586 * @proxy: A #GDBusProxy.
16588 * Gets the timeout to use if -1 (specifying default timeout) is
16589 * passed as @timeout_msec in the g_dbus_proxy_call() and
16590 * g_dbus_proxy_call_sync() functions.
16592 * See the #GDBusProxy:g-default-timeout property for more details.
16594 * Returns: Timeout to use for @proxy.
16600 * g_dbus_proxy_get_flags:
16601 * @proxy: A #GDBusProxy.
16603 * Gets the flags that @proxy was constructed with.
16605 * Returns: Flags from the #GDBusProxyFlags enumeration.
16611 * g_dbus_proxy_get_interface_info:
16612 * @proxy: A #GDBusProxy
16614 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
16615 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
16616 * property for more details.
16618 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy.
16624 * g_dbus_proxy_get_interface_name:
16625 * @proxy: A #GDBusProxy.
16627 * Gets the D-Bus interface name @proxy is for.
16629 * Returns: A string owned by @proxy. Do not free.
16635 * g_dbus_proxy_get_name:
16636 * @proxy: A #GDBusProxy.
16638 * Gets the name that @proxy was constructed for.
16640 * Returns: A string owned by @proxy. Do not free.
16646 * g_dbus_proxy_get_name_owner:
16647 * @proxy: A #GDBusProxy.
16649 * The unique name that owns the name that @proxy is for or %NULL if
16650 * no-one currently owns that name. You may connect to the
16651 * #GObject::notify signal to track changes to the
16652 * #GDBusProxy:g-name-owner property.
16654 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
16660 * g_dbus_proxy_get_object_path:
16661 * @proxy: A #GDBusProxy.
16663 * Gets the object path @proxy is for.
16665 * Returns: A string owned by @proxy. Do not free.
16671 * g_dbus_proxy_new:
16672 * @connection: A #GDBusConnection.
16673 * @flags: Flags used when constructing the proxy.
16674 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
16675 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
16676 * @object_path: An object path.
16677 * @interface_name: A D-Bus interface name.
16678 * @cancellable: (allow-none): A #GCancellable or %NULL.
16679 * @callback: Callback function to invoke when the proxy is ready.
16680 * @user_data: User data to pass to @callback.
16682 * Creates a proxy for accessing @interface_name on the remote object
16683 * at @object_path owned by @name at @connection and asynchronously
16684 * loads D-Bus properties unless the
16685 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
16686 * the #GDBusProxy::g-properties-changed signal to get notified about
16687 * property changes.
16689 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
16690 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
16691 * to handle signals from the remote object.
16693 * If @name is a well-known name and the
16694 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name
16695 * owner currently exists, the message bus will be requested to launch
16696 * a name owner for the name.
16698 * This is a failable asynchronous constructor - when the proxy is
16699 * ready, @callback will be invoked and you can use
16700 * g_dbus_proxy_new_finish() to get the result.
16702 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
16704 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
16711 * g_dbus_proxy_new_finish:
16712 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
16713 * @error: Return location for error or %NULL.
16715 * Finishes creating a #GDBusProxy.
16717 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
16723 * g_dbus_proxy_new_for_bus:
16724 * @bus_type: A #GBusType.
16725 * @flags: Flags used when constructing the proxy.
16726 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
16727 * @name: A bus name (well-known or unique).
16728 * @object_path: An object path.
16729 * @interface_name: A D-Bus interface name.
16730 * @cancellable: (allow-none): A #GCancellable or %NULL.
16731 * @callback: Callback function to invoke when the proxy is ready.
16732 * @user_data: User data to pass to @callback.
16734 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
16736 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
16743 * g_dbus_proxy_new_for_bus_finish:
16744 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
16745 * @error: Return location for error or %NULL.
16747 * Finishes creating a #GDBusProxy.
16749 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
16755 * g_dbus_proxy_new_for_bus_sync:
16756 * @bus_type: A #GBusType.
16757 * @flags: Flags used when constructing the proxy.
16758 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
16759 * @name: A bus name (well-known or unique).
16760 * @object_path: An object path.
16761 * @interface_name: A D-Bus interface name.
16762 * @cancellable: (allow-none): A #GCancellable or %NULL.
16763 * @error: Return location for error or %NULL.
16765 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
16767 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
16769 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
16775 * g_dbus_proxy_new_sync:
16776 * @connection: A #GDBusConnection.
16777 * @flags: Flags used when constructing the proxy.
16778 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
16779 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
16780 * @object_path: An object path.
16781 * @interface_name: A D-Bus interface name.
16782 * @cancellable: (allow-none): A #GCancellable or %NULL.
16783 * @error: (allow-none): Return location for error or %NULL.
16785 * Creates a proxy for accessing @interface_name on the remote object
16786 * at @object_path owned by @name at @connection and synchronously
16787 * loads D-Bus properties unless the
16788 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
16790 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
16791 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
16792 * to handle signals from the remote object.
16794 * If @name is a well-known name and the
16795 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name
16796 * owner currently exists, the message bus will be requested to launch
16797 * a name owner for the name.
16799 * This is a synchronous failable constructor. See g_dbus_proxy_new()
16800 * and g_dbus_proxy_new_finish() for the asynchronous version.
16802 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
16804 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
16810 * g_dbus_proxy_set_cached_property:
16811 * @proxy: A #GDBusProxy
16812 * @property_name: Property name.
16813 * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
16815 * If @value is not %NULL, sets the cached value for the property with
16816 * name @property_name to the value in @value.
16818 * If @value is %NULL, then the cached value is removed from the
16821 * If @proxy has an expected interface (see
16822 * #GDBusProxy:g-interface-info) and @property_name is referenced by
16823 * it, then @value is checked against the type of the property.
16825 * If the @value #GVariant is floating, it is consumed. This allows
16826 * convenient 'inline' use of g_variant_new(), e.g.
16828 * g_dbus_proxy_set_cached_property (proxy,
16830 * g_variant_new ("(si)",
16835 * Normally you will not need to use this method since @proxy is
16836 * tracking changes using the
16837 * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
16838 * D-Bus signal. However, for performance reasons an object may decide
16839 * to not use this signal for some properties and instead use a
16840 * proprietary out-of-band mechanism to transmit changes.
16842 * As a concrete example, consider an object with a property
16843 * <literal>ChatroomParticipants</literal> which is an array of
16844 * strings. Instead of transmitting the same (long) array every time
16845 * the property changes, it is more efficient to only transmit the
16846 * delta using e.g. signals <literal>ChatroomParticipantJoined(String
16847 * name)</literal> and <literal>ChatroomParticipantParted(String
16855 * g_dbus_proxy_set_default_timeout:
16856 * @proxy: A #GDBusProxy.
16857 * @timeout_msec: Timeout in milliseconds.
16859 * Sets the timeout to use if -1 (specifying default timeout) is
16860 * passed as @timeout_msec in the g_dbus_proxy_call() and
16861 * g_dbus_proxy_call_sync() functions.
16863 * See the #GDBusProxy:g-default-timeout property for more details.
16870 * g_dbus_proxy_set_interface_info:
16871 * @proxy: A #GDBusProxy
16872 * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
16874 * Ensure that interactions with @proxy conform to the given
16875 * interface. See the #GDBusProxy:g-interface-info property for more
16883 * g_dbus_server_get_client_address:
16884 * @server: A #GDBusServer.
16886 * Gets a D-Bus address string that can be used by clients to connect
16889 * Returns: A D-Bus address string. Do not free, the string is owned by @server.
16895 * g_dbus_server_get_flags:
16896 * @server: A #GDBusServer.
16898 * Gets the flags for @server.
16900 * Returns: A set of flags from the #GDBusServerFlags enumeration.
16906 * g_dbus_server_get_guid:
16907 * @server: A #GDBusServer.
16909 * Gets the GUID for @server.
16911 * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
16917 * g_dbus_server_is_active:
16918 * @server: A #GDBusServer.
16920 * Gets whether @server is active.
16922 * Returns: %TRUE if server is active, %FALSE otherwise.
16928 * g_dbus_server_new_sync:
16929 * @address: A D-Bus address.
16930 * @flags: Flags from the #GDBusServerFlags enumeration.
16931 * @guid: A D-Bus GUID.
16932 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
16933 * @cancellable: (allow-none): A #GCancellable or %NULL.
16934 * @error: Return location for server or %NULL.
16936 * Creates a new D-Bus server that listens on the first address in
16937 * @address that works.
16939 * Once constructed, you can use g_dbus_server_get_client_address() to
16940 * get a D-Bus address string that clients can use to connect.
16942 * Connect to the #GDBusServer::new-connection signal to handle
16943 * incoming connections.
16945 * The returned #GDBusServer isn't active - you have to start it with
16946 * g_dbus_server_start().
16948 * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
16951 * This is a synchronous failable constructor. See
16952 * g_dbus_server_new() for the asynchronous version.
16954 * Returns: A #GDBusServer or %NULL if @error is set. Free with g_object_unref().
16960 * g_dbus_server_start:
16961 * @server: A #GDBusServer.
16970 * g_dbus_server_stop:
16971 * @server: A #GDBusServer.
16980 * g_dbus_signal_info_ref:
16981 * @info: A #GDBusSignalInfo
16983 * If @info is statically allocated does nothing. Otherwise increases
16984 * the reference count.
16986 * Returns: The same @info.
16992 * g_dbus_signal_info_unref:
16993 * @info: A #GDBusSignalInfo.
16995 * If @info is statically allocated, does nothing. Otherwise decreases
16996 * the reference count of @info. When its reference count drops to 0,
16997 * the memory used is freed.
17004 * g_desktop_app_info_get_categories:
17005 * @info: a #GDesktopAppInfo
17007 * Gets the categories from the desktop file.
17009 * Returns: The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it.
17014 * g_desktop_app_info_get_filename:
17015 * @info: a #GDesktopAppInfo
17017 * When @info was created from a known filename, return it. In some
17018 * situations such as the #GDesktopAppInfo returned from
17019 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
17021 * Returns: The full path to the file for @info, or %NULL if not known.
17027 * g_desktop_app_info_get_generic_name:
17028 * @info: a #GDesktopAppInfo
17030 * Gets the generic name from the destkop file.
17032 * Returns: The value of the GenericName key
17037 * g_desktop_app_info_get_is_hidden:
17038 * @info: a #GDesktopAppInfo.
17040 * A desktop file is hidden if the Hidden key in it is
17043 * Returns: %TRUE if hidden, %FALSE otherwise.
17048 * g_desktop_app_info_get_keywords:
17049 * @info: a #GDesktopAppInfo
17051 * Gets the keywords from the desktop file.
17053 * Returns: (transfer none): The value of the Keywords key
17059 * g_desktop_app_info_get_nodisplay:
17060 * @info: a #GDesktopAppInfo
17062 * Gets the value of the NoDisplay key, which helps determine if the
17063 * application info should be shown in menus. See
17064 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
17066 * Returns: The value of the NoDisplay key
17072 * g_desktop_app_info_get_show_in:
17073 * @info: a #GDesktopAppInfo
17074 * @desktop_env: a string specifying a desktop name
17076 * Checks if the application info should be shown in menus that list available
17077 * applications for a specific name of the desktop, based on the
17078 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys.
17080 * If @desktop_env is %NULL, then the name of the desktop set with
17081 * g_desktop_app_info_set_desktop_env() is used.
17083 * Note that g_app_info_should_show() for @info will include this check (with
17084 * %NULL for @desktop_env) as well as additional checks.
17086 * Returns: %TRUE if the @info should be shown in @desktop_env according to the <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE otherwise.
17092 * g_desktop_app_info_get_startup_wm_class:
17093 * @info: a #GDesktopAppInfo that supports startup notify
17095 * Retrieves the StartupWMClass field from @info. This represents the
17096 * WM_CLASS property of the main window of the application, if launched
17099 * Returns: (transfer none): the startup WM class, or %NULL if none is set in the desktop file.
17105 * g_desktop_app_info_launch_uris_as_manager:
17106 * @appinfo: a #GDesktopAppInfo
17107 * @uris: (element-type utf8): List of URIs
17108 * @launch_context: a #GAppLaunchContext
17109 * @spawn_flags: #GSpawnFlags, used for each process
17110 * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process.
17111 * @user_setup_data: (closure user_setup): User data for @user_setup
17112 * @pid_callback: (scope call): Callback for child processes
17113 * @pid_callback_data: (closure pid_callback): User data for @callback
17114 * @error: return location for a #GError, or %NULL
17116 * This function performs the equivalent of g_app_info_launch_uris(),
17117 * but is intended primarily for operating system components that
17118 * launch applications. Ordinary applications should use
17119 * g_app_info_launch_uris().
17121 * In contrast to g_app_info_launch_uris(), all processes created will
17122 * always be run directly as children as if by the UNIX fork()/exec()
17125 * This guarantee allows additional control over the exact environment
17126 * of the child processes, which is provided via a setup function
17127 * @user_setup, as well as the process identifier of each child process
17128 * via @pid_callback. See g_spawn_async() for more information about the
17129 * semantics of the @user_setup function.
17131 * Returns: %TRUE on successful launch, %FALSE otherwise.
17136 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
17137 * @lookup: a #GDesktopAppInfoLookup
17138 * @uri_scheme: a string containing a URI scheme.
17140 * Gets the default application for launching applications
17141 * using this URI scheme for a particular GDesktopAppInfoLookup
17144 * The GDesktopAppInfoLookup interface and this function is used
17145 * to implement g_app_info_get_default_for_uri_scheme() backends
17146 * in a GIO module. There is no reason for applications to use it
17147 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
17149 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
17150 * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
17155 * g_desktop_app_info_new:
17156 * @desktop_id: the desktop file id
17158 * Creates a new #GDesktopAppInfo based on a desktop file id.
17160 * A desktop file id is the basename of the desktop file, including the
17161 * .desktop extension. GIO is looking for a desktop file with this name
17162 * in the <filename>applications</filename> subdirectories of the XDG data
17163 * directories (i.e. the directories specified in the
17164 * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment
17165 * variables). GIO also supports the prefix-to-subdirectory mapping that is
17166 * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink>
17167 * (i.e. a desktop id of kde-foo.desktop will match
17168 * <filename>/usr/share/applications/kde/foo.desktop</filename>).
17170 * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
17175 * g_desktop_app_info_new_from_filename:
17176 * @filename: the path of a desktop file, in the GLib filename encoding
17178 * Creates a new #GDesktopAppInfo.
17180 * Returns: a new #GDesktopAppInfo or %NULL on error.
17185 * g_desktop_app_info_new_from_keyfile:
17186 * @key_file: an opened #GKeyFile
17188 * Creates a new #GDesktopAppInfo.
17190 * Returns: a new #GDesktopAppInfo or %NULL on error.
17196 * g_desktop_app_info_set_desktop_env:
17197 * @desktop_env: a string specifying what desktop this is
17199 * Sets the name of the desktop that the application is running in.
17200 * This is used by g_app_info_should_show() and
17201 * g_desktop_app_info_get_show_in() to evaluate the
17202 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
17203 * desktop entry fields.
17205 * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop
17206 * Menu specification</ulink> recognizes the following:
17208 * <member>GNOME</member>
17209 * <member>KDE</member>
17210 * <member>ROX</member>
17211 * <member>XFCE</member>
17212 * <member>LXDE</member>
17213 * <member>Unity</member>
17214 * <member>Old</member>
17217 * Should be called only once; subsequent calls are ignored.
17222 * g_drive_can_eject:
17223 * @drive: a #GDrive.
17225 * Checks if a drive can be ejected.
17227 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
17232 * g_drive_can_poll_for_media:
17233 * @drive: a #GDrive.
17235 * Checks if a drive can be polled for media changes.
17237 * Returns: %TRUE if the @drive can be polled for media changes, %FALSE otherwise.
17242 * g_drive_can_start:
17243 * @drive: a #GDrive.
17245 * Checks if a drive can be started.
17247 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
17253 * g_drive_can_start_degraded:
17254 * @drive: a #GDrive.
17256 * Checks if a drive can be started degraded.
17258 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
17264 * g_drive_can_stop:
17265 * @drive: a #GDrive.
17267 * Checks if a drive can be stopped.
17269 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
17276 * @drive: a #GDrive.
17277 * @flags: flags affecting the unmount if required for eject
17278 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
17279 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
17280 * @user_data: user data to pass to @callback
17282 * Asynchronously ejects a drive.
17284 * When the operation is finished, @callback will be called.
17285 * You can then call g_drive_eject_finish() to obtain the
17286 * result of the operation.
17288 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
17293 * g_drive_eject_finish:
17294 * @drive: a #GDrive.
17295 * @result: a #GAsyncResult.
17296 * @error: a #GError, or %NULL
17298 * Finishes ejecting a drive.
17300 * Returns: %TRUE if the drive has been ejected successfully, %FALSE otherwise.
17301 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
17306 * g_drive_eject_with_operation:
17307 * @drive: a #GDrive.
17308 * @flags: flags affecting the unmount if required for eject
17309 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
17310 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
17311 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
17312 * @user_data: user data passed to @callback.
17314 * Ejects a drive. This is an asynchronous operation, and is
17315 * finished by calling g_drive_eject_with_operation_finish() with the @drive
17316 * and #GAsyncResult data returned in the @callback.
17323 * g_drive_eject_with_operation_finish:
17324 * @drive: a #GDrive.
17325 * @result: a #GAsyncResult.
17326 * @error: a #GError location to store the error occurring, or %NULL to ignore.
17328 * Finishes ejecting a drive. If any errors occurred during the operation,
17329 * @error will be set to contain the errors and %FALSE will be returned.
17331 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
17337 * g_drive_enumerate_identifiers:
17338 * @drive: a #GDrive
17340 * Gets the kinds of identifiers that @drive has.
17341 * Use g_drive_get_identifier() to obtain the identifiers
17344 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.
17349 * g_drive_get_icon:
17350 * @drive: a #GDrive.
17352 * Gets the icon for @drive.
17354 * Returns: (transfer full): #GIcon for the @drive. Free the returned object with g_object_unref().
17359 * g_drive_get_identifier:
17360 * @drive: a #GDrive
17361 * @kind: the kind of identifier to return
17363 * Gets the identifier of the given kind for @drive.
17365 * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier.
17370 * g_drive_get_name:
17371 * @drive: a #GDrive.
17373 * Gets the name of @drive.
17375 * Returns: a string containing @drive's name. The returned string should be freed when no longer needed.
17380 * g_drive_get_sort_key:
17381 * @drive: A #GDrive.
17383 * Gets the sort key for @drive, if any.
17385 * Returns: Sorting key for @drive or %NULL if no such key is available.
17391 * g_drive_get_start_stop_type:
17392 * @drive: a #GDrive.
17394 * Gets a hint about how a drive can be started/stopped.
17396 * Returns: A value from the #GDriveStartStopType enumeration.
17402 * g_drive_get_symbolic_icon:
17403 * @drive: a #GDrive.
17405 * Gets the icon for @drive.
17407 * Returns: (transfer full): symbolic #GIcon for the @drive. Free the returned object with g_object_unref().
17413 * g_drive_get_volumes:
17414 * @drive: a #GDrive.
17416 * Get a list of mountable volumes for @drive.
17418 * The returned list should be freed with g_list_free(), after
17419 * its elements have been unreffed with g_object_unref().
17421 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
17426 * g_drive_has_media:
17427 * @drive: a #GDrive.
17429 * Checks if the @drive has media. Note that the OS may not be polling
17430 * the drive for media changes; see g_drive_is_media_check_automatic()
17431 * for more details.
17433 * Returns: %TRUE if @drive has media, %FALSE otherwise.
17438 * g_drive_has_volumes:
17439 * @drive: a #GDrive.
17441 * Check if @drive has any mountable volumes.
17443 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
17448 * g_drive_is_media_check_automatic:
17449 * @drive: a #GDrive.
17451 * Checks if @drive is capabable of automatically detecting media changes.
17453 * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise.
17458 * g_drive_is_media_removable:
17459 * @drive: a #GDrive.
17461 * Checks if the @drive supports removable media.
17463 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
17468 * g_drive_poll_for_media:
17469 * @drive: a #GDrive.
17470 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
17471 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
17472 * @user_data: user data to pass to @callback
17474 * Asynchronously polls @drive to see if media has been inserted or removed.
17476 * When the operation is finished, @callback will be called.
17477 * You can then call g_drive_poll_for_media_finish() to obtain the
17478 * result of the operation.
17483 * g_drive_poll_for_media_finish:
17484 * @drive: a #GDrive.
17485 * @result: a #GAsyncResult.
17486 * @error: a #GError, or %NULL
17488 * Finishes an operation started with g_drive_poll_for_media() on a drive.
17490 * Returns: %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise.
17496 * @drive: a #GDrive.
17497 * @flags: flags affecting the start operation.
17498 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
17499 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
17500 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
17501 * @user_data: user data to pass to @callback
17503 * Asynchronously starts a drive.
17505 * When the operation is finished, @callback will be called.
17506 * You can then call g_drive_start_finish() to obtain the
17507 * result of the operation.
17514 * g_drive_start_finish:
17515 * @drive: a #GDrive.
17516 * @result: a #GAsyncResult.
17517 * @error: a #GError, or %NULL
17519 * Finishes starting a drive.
17521 * Returns: %TRUE if the drive has been started successfully, %FALSE otherwise.
17528 * @drive: a #GDrive.
17529 * @flags: flags affecting the unmount if required for stopping.
17530 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
17531 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
17532 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
17533 * @user_data: user data to pass to @callback
17535 * Asynchronously stops a drive.
17537 * When the operation is finished, @callback will be called.
17538 * You can then call g_drive_stop_finish() to obtain the
17539 * result of the operation.
17546 * g_drive_stop_finish:
17547 * @drive: a #GDrive.
17548 * @result: a #GAsyncResult.
17549 * @error: a #GError, or %NULL
17551 * Finishes stopping a drive.
17553 * Returns: %TRUE if the drive has been stopped successfully, %FALSE otherwise.
17559 * g_emblem_get_icon:
17560 * @emblem: a #GEmblem from which the icon should be extracted.
17562 * Gives back the icon from @emblem.
17564 * Returns: (transfer none): a #GIcon. The returned object belongs to the emblem and should not be modified or freed.
17570 * g_emblem_get_origin:
17571 * @emblem: a #GEmblem
17573 * Gets the origin of the emblem.
17575 * Returns: (transfer none): the origin of the emblem
17582 * @icon: a GIcon containing the icon.
17584 * Creates a new emblem for @icon.
17586 * Returns: a new #GEmblem.
17592 * g_emblem_new_with_origin:
17593 * @icon: a GIcon containing the icon.
17594 * @origin: a GEmblemOrigin enum defining the emblem's origin
17596 * Creates a new emblem for @icon.
17598 * Returns: a new #GEmblem.
17604 * g_emblemed_icon_add_emblem:
17605 * @emblemed: a #GEmblemedIcon
17606 * @emblem: a #GEmblem
17608 * Adds @emblem to the #GList of #GEmblem <!-- -->s.
17615 * g_emblemed_icon_clear_emblems:
17616 * @emblemed: a #GEmblemedIcon
17618 * Removes all the emblems from @icon.
17625 * g_emblemed_icon_get_emblems:
17626 * @emblemed: a #GEmblemedIcon
17628 * Gets the list of emblems for the @icon.
17630 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of #GEmblem <!-- -->s that is owned by @emblemed
17636 * g_emblemed_icon_get_icon:
17637 * @emblemed: a #GEmblemedIcon
17639 * Gets the main icon for @emblemed.
17641 * Returns: (transfer none): a #GIcon that is owned by @emblemed
17647 * g_emblemed_icon_new:
17649 * @emblem: (allow-none): a #GEmblem, or %NULL
17651 * Creates a new emblemed icon for @icon with the emblem @emblem.
17653 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
17659 * g_file_append_to:
17660 * @file: input #GFile
17661 * @flags: a set of #GFileCreateFlags
17662 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
17663 * @error: a #GError, or %NULL
17665 * Gets an output stream for appending data to the file.
17666 * If the file doesn't already exist it is created.
17668 * By default files created are generally readable by everyone,
17669 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
17670 * will be made readable only to the current user, to the level that
17671 * is supported on the target filesystem.
17673 * If @cancellable is not %NULL, then the operation can be cancelled
17674 * by triggering the cancellable object from another thread. If the
17675 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
17678 * Some file systems don't allow all file names, and may return an
17679 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
17680 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
17681 * possible too, and depend on what kind of filesystem the file is on.
17683 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref().
17688 * g_file_append_to_async:
17689 * @file: input #GFile
17690 * @flags: a set of #GFileCreateFlags
17691 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
17692 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
17693 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
17694 * @user_data: (closure): the data to pass to callback function
17696 * Asynchronously opens @file for appending.
17698 * For more details, see g_file_append_to() which is
17699 * the synchronous version of this call.
17701 * When the operation is finished, @callback will be called.
17702 * You can then call g_file_append_to_finish() to get the result
17703 * of the operation.
17708 * g_file_append_to_finish:
17709 * @file: input #GFile
17710 * @res: #GAsyncResult
17711 * @error: a #GError, or %NULL
17713 * Finishes an asynchronous file append operation started with
17714 * g_file_append_to_async().
17716 * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref().
17721 * g_file_attribute_info_list_add:
17722 * @list: a #GFileAttributeInfoList.
17723 * @name: the name of the attribute to add.
17724 * @type: the #GFileAttributeType for the attribute.
17725 * @flags: #GFileAttributeInfoFlags for the attribute.
17727 * Adds a new attribute with @name to the @list, setting
17728 * its @type and @flags.
17733 * g_file_attribute_info_list_dup:
17734 * @list: a #GFileAttributeInfoList to duplicate.
17736 * Makes a duplicate of a file attribute info list.
17738 * Returns: a copy of the given @list.
17743 * g_file_attribute_info_list_lookup:
17744 * @list: a #GFileAttributeInfoList.
17745 * @name: the name of the attribute to lookup.
17747 * Gets the file attribute with the name @name from @list.
17749 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found.
17754 * g_file_attribute_info_list_new:
17756 * Creates a new file attribute info list.
17758 * Returns: a #GFileAttributeInfoList.
17763 * g_file_attribute_info_list_ref:
17764 * @list: a #GFileAttributeInfoList to reference.
17766 * References a file attribute info list.
17768 * Returns: #GFileAttributeInfoList or %NULL on error.
17773 * g_file_attribute_info_list_unref:
17774 * @list: The #GFileAttributeInfoList to unreference.
17776 * Removes a reference from the given @list. If the reference count
17777 * falls to zero, the @list is deleted.
17782 * g_file_attribute_matcher_enumerate_namespace:
17783 * @matcher: a #GFileAttributeMatcher.
17784 * @ns: a string containing a file attribute namespace.
17786 * Checks if the matcher will match all of the keys in a given namespace.
17787 * This will always return %TRUE if a wildcard character is in use (e.g. if
17788 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
17789 * using "*" and namespace is anything.)
17791 * TODO: this is awkwardly worded.
17793 * Returns: %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise.
17798 * g_file_attribute_matcher_enumerate_next:
17799 * @matcher: a #GFileAttributeMatcher.
17801 * Gets the next matched attribute from a #GFileAttributeMatcher.
17803 * Returns: a string containing the next attribute or %NULL if no more attribute exist.
17808 * g_file_attribute_matcher_matches:
17809 * @matcher: a #GFileAttributeMatcher.
17810 * @attribute: a file attribute key.
17812 * Checks if an attribute will be matched by an attribute matcher. If
17813 * the matcher was created with the "*" matching string, this function
17814 * will always return %TRUE.
17816 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
17821 * g_file_attribute_matcher_matches_only:
17822 * @matcher: a #GFileAttributeMatcher.
17823 * @attribute: a file attribute key.
17825 * Checks if a attribute matcher only matches a given attribute. Always
17826 * returns %FALSE if "*" was used when creating the matcher.
17828 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
17833 * g_file_attribute_matcher_new:
17834 * @attributes: an attribute string to match.
17836 * Creates a new file attribute matcher, which matches attributes
17837 * against a given string. #GFileAttributeMatcher<!-- -->s are reference
17838 * counted structures, and are created with a reference count of 1. If
17839 * the number of references falls to 0, the #GFileAttributeMatcher is
17840 * automatically destroyed.
17842 * The @attribute string should be formatted with specific keys separated
17843 * from namespaces with a double colon. Several "namespace::key" strings may be
17844 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
17845 * The wildcard "*" may be used to match all keys and namespaces, or
17846 * "namespace::*" will match all keys in a given namespace.
17848 * Examples of strings to use:
17850 * <title>File Attribute Matcher strings and results</title>
17851 * <tgroup cols='2' align='left'><thead>
17852 * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead>
17854 * <row><entry>"*"</entry><entry>matches all attributes.</entry></row>
17855 * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row>
17856 * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and
17857 * all keys in the unix namespace.</entry></row>
17858 * </tbody></tgroup>
17861 * Returns: a #GFileAttributeMatcher.
17866 * g_file_attribute_matcher_ref:
17867 * @matcher: a #GFileAttributeMatcher.
17869 * References a file attribute matcher.
17871 * Returns: a #GFileAttributeMatcher.
17876 * g_file_attribute_matcher_subtract:
17877 * @matcher: Matcher to subtract from
17878 * @subtract: The matcher to subtract
17880 * Subtracts all attributes of @subtract from @matcher and returns
17881 * a matcher that supports those attributes.
17883 * Note that currently it is not possible to remove a single
17884 * attribute when the @matcher matches the whole namespace - or remove
17885 * a namespace or attribute when the matcher matches everything. This
17886 * is a limitation of the current implementation, but may be fixed
17889 * Returns: A file attribute matcher matching all attributes of @matcher that are not matched by @subtract
17894 * g_file_attribute_matcher_to_string:
17895 * @matcher: (allow-none): a #GFileAttributeMatcher.
17897 * Prints what the matcher is matching against. The format will be
17898 * equal to the format passed to g_file_attribute_matcher_new().
17899 * The output however, might not be identical, as the matcher may
17900 * decide to use a different order or omit needless parts.
17902 * Returns: a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL.
17908 * g_file_attribute_matcher_unref:
17909 * @matcher: a #GFileAttributeMatcher.
17911 * Unreferences @matcher. If the reference count falls below 1,
17912 * the @matcher is automatically freed.
17918 * @source: input #GFile
17919 * @destination: destination #GFile
17920 * @flags: set of #GFileCopyFlags
17921 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
17922 * @progress_callback: (allow-none) (scope call): function to callback with progress information, or %NULL if progress information is not needed
17923 * @progress_callback_data: (closure): user data to pass to @progress_callback
17924 * @error: #GError to set on error, or %NULL
17926 * Copies the file @source to the location specified by @destination.
17927 * Can not handle recursive copies of directories.
17929 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
17930 * existing @destination file is overwritten.
17932 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
17933 * will be copied as symlinks, otherwise the target of the
17934 * @source symlink will be copied.
17936 * If @cancellable is not %NULL, then the operation can be cancelled by
17937 * triggering the cancellable object from another thread. If the operation
17938 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
17940 * If @progress_callback is not %NULL, then the operation can be monitored
17941 * by setting this to a #GFileProgressCallback function.
17942 * @progress_callback_data will be passed to this function. It is guaranteed
17943 * that this callback will be called after all data has been transferred with
17944 * the total number of bytes copied during the operation.
17946 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
17947 * is returned, independent on the status of the @destination.
17949 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
17950 * the error %G_IO_ERROR_EXISTS is returned.
17952 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
17953 * error is returned. If trying to overwrite a directory with a directory the
17954 * %G_IO_ERROR_WOULD_MERGE error is returned.
17956 * If the source is a directory and the target does not exist, or
17957 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
17958 * %G_IO_ERROR_WOULD_RECURSE error is returned.
17960 * If you are interested in copying the #GFile object itself (not the on-disk
17961 * file), see g_file_dup().
17963 * Returns: %TRUE on success, %FALSE otherwise.
17968 * g_file_copy_async: (skip)
17969 * @source: input #GFile
17970 * @destination: destination #GFile
17971 * @flags: set of #GFileCopyFlags
17972 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
17973 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
17974 * @progress_callback: (allow-none): function to callback with progress information, or %NULL if progress information is not needed
17975 * @progress_callback_data: (closure): user data to pass to @progress_callback
17976 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
17977 * @user_data: the data to pass to callback function
17979 * Copies the file @source to the location specified by @destination
17980 * asynchronously. For details of the behaviour, see g_file_copy().
17982 * If @progress_callback is not %NULL, then that function that will be called
17983 * just like in g_file_copy(), however the callback will run in the main loop,
17984 * not in the thread that is doing the I/O operation.
17986 * When the operation is finished, @callback will be called. You can then call
17987 * g_file_copy_finish() to get the result of the operation.
17992 * g_file_copy_attributes:
17993 * @source: a #GFile with attributes
17994 * @destination: a #GFile to copy attributes to
17995 * @flags: a set of #GFileCopyFlags
17996 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
17997 * @error: a #GError, %NULL to ignore
17999 * Copies the file attributes from @source to @destination.
18001 * Normally only a subset of the file attributes are copied,
18002 * those that are copies in a normal file copy operation
18003 * (which for instance does not include e.g. owner). However
18004 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
18005 * all the metadata that is possible to copy is copied. This
18006 * is useful when implementing move by copy + delete source.
18008 * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise.
18013 * g_file_copy_finish:
18014 * @file: input #GFile
18015 * @res: a #GAsyncResult
18016 * @error: a #GError, or %NULL
18018 * Finishes copying the file started with g_file_copy_async().
18020 * Returns: a %TRUE on success, %FALSE on error.
18026 * @file: input #GFile
18027 * @flags: a set of #GFileCreateFlags
18028 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18029 * @error: a #GError, or %NULL
18031 * Creates a new file and returns an output stream for writing to it.
18032 * The file must not already exist.
18034 * By default files created are generally readable by everyone,
18035 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
18036 * will be made readable only to the current user, to the level
18037 * that is supported on the target filesystem.
18039 * If @cancellable is not %NULL, then the operation can be cancelled
18040 * by triggering the cancellable object from another thread. If the
18041 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
18044 * If a file or directory with this name already exists the
18045 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
18046 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
18047 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
18048 * be returned. Other errors are possible too, and depend on what kind
18049 * of filesystem the file is on.
18051 * Returns: (transfer full): a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref().
18056 * g_file_create_async:
18057 * @file: input #GFile
18058 * @flags: a set of #GFileCreateFlags
18059 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
18060 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18061 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
18062 * @user_data: (closure): the data to pass to callback function
18064 * Asynchronously creates a new file and returns an output stream
18065 * for writing to it. The file must not already exist.
18067 * For more details, see g_file_create() which is
18068 * the synchronous version of this call.
18070 * When the operation is finished, @callback will be called.
18071 * You can then call g_file_create_finish() to get the result
18072 * of the operation.
18077 * g_file_create_finish:
18078 * @file: input #GFile
18079 * @res: a #GAsyncResult
18080 * @error: a #GError, or %NULL
18082 * Finishes an asynchronous file create operation started with
18083 * g_file_create_async().
18085 * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref().
18090 * g_file_create_readwrite:
18092 * @flags: a set of #GFileCreateFlags
18093 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18094 * @error: return location for a #GError, or %NULL
18096 * Creates a new file and returns a stream for reading and
18097 * writing to it. The file must not already exist.
18099 * By default files created are generally readable by everyone,
18100 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
18101 * will be made readable only to the current user, to the level
18102 * that is supported on the target filesystem.
18104 * If @cancellable is not %NULL, then the operation can be cancelled
18105 * by triggering the cancellable object from another thread. If the
18106 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
18109 * If a file or directory with this name already exists, the
18110 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
18111 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
18112 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
18113 * will be returned. Other errors are possible too, and depend on what
18114 * kind of filesystem the file is on.
18116 * Note that in many non-local file cases read and write streams are
18117 * not supported, so make sure you really need to do read and write
18118 * streaming, rather than just opening for reading or writing.
18120 * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref().
18126 * g_file_create_readwrite_async:
18127 * @file: input #GFile
18128 * @flags: a set of #GFileCreateFlags
18129 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
18130 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18131 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
18132 * @user_data: (closure): the data to pass to callback function
18134 * Asynchronously creates a new file and returns a stream
18135 * for reading and writing to it. The file must not already exist.
18137 * For more details, see g_file_create_readwrite() which is
18138 * the synchronous version of this call.
18140 * When the operation is finished, @callback will be called.
18141 * You can then call g_file_create_readwrite_finish() to get
18142 * the result of the operation.
18149 * g_file_create_readwrite_finish:
18150 * @file: input #GFile
18151 * @res: a #GAsyncResult
18152 * @error: a #GError, or %NULL
18154 * Finishes an asynchronous file create operation started with
18155 * g_file_create_readwrite_async().
18157 * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
18164 * @file: input #GFile
18165 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18166 * @error: a #GError, or %NULL
18168 * Deletes a file. If the @file is a directory, it will only be
18169 * deleted if it is empty. This has the same semantics as g_unlink().
18171 * If @cancellable is not %NULL, then the operation can be cancelled by
18172 * triggering the cancellable object from another thread. If the operation
18173 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
18175 * Virtual: delete_file
18176 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
18181 * g_file_delete_async:
18182 * @file: input #GFile
18183 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
18184 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18185 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
18186 * @user_data: the data to pass to callback function
18188 * Asynchronously delete a file. If the @file is a directory, it will
18189 * only be deleted if it is empty. This has the same semantics as
18192 * Virtual: delete_file_async
18198 * g_file_delete_finish:
18199 * @file: input #GFile
18200 * @result: a #GAsyncResult
18201 * @error: a #GError, or %NULL
18203 * Finishes deleting a file started with g_file_delete_async().
18205 * Virtual: delete_file_finish
18211 * g_file_descriptor_based_get_fd:
18212 * @fd_based: a #GFileDescriptorBased.
18214 * Gets the underlying file descriptor.
18216 * Returns: The file descriptor
18223 * @file: input #GFile
18225 * Duplicates a #GFile handle. This operation does not duplicate
18226 * the actual file or directory represented by the #GFile; see
18227 * g_file_copy() if attempting to copy a file.
18229 * This call does no blocking I/O.
18231 * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile.
18236 * g_file_eject_mountable:
18237 * @file: input #GFile
18238 * @flags: flags affecting the operation
18239 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18240 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
18241 * @user_data: (closure): the data to pass to callback function
18243 * Starts an asynchronous eject on a mountable.
18244 * When this operation has completed, @callback will be called with
18245 * @user_user data, and the operation can be finalized with
18246 * g_file_eject_mountable_finish().
18248 * If @cancellable is not %NULL, then the operation can be cancelled by
18249 * triggering the cancellable object from another thread. If the operation
18250 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
18252 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
18257 * g_file_eject_mountable_finish:
18258 * @file: input #GFile
18259 * @result: a #GAsyncResult
18260 * @error: a #GError, or %NULL
18262 * Finishes an asynchronous eject operation started by
18263 * g_file_eject_mountable().
18265 * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise.
18266 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead.
18271 * g_file_eject_mountable_with_operation:
18272 * @file: input #GFile
18273 * @flags: flags affecting the operation
18274 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
18275 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18276 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
18277 * @user_data: (closure): the data to pass to callback function
18279 * Starts an asynchronous eject on a mountable.
18280 * When this operation has completed, @callback will be called with
18281 * @user_user data, and the operation can be finalized with
18282 * g_file_eject_mountable_with_operation_finish().
18284 * If @cancellable is not %NULL, then the operation can be cancelled by
18285 * triggering the cancellable object from another thread. If the operation
18286 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
18293 * g_file_eject_mountable_with_operation_finish:
18294 * @file: input #GFile
18295 * @result: a #GAsyncResult
18296 * @error: a #GError, or %NULL
18298 * Finishes an asynchronous eject operation started by
18299 * g_file_eject_mountable_with_operation().
18301 * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise.
18307 * g_file_enumerate_children:
18308 * @file: input #GFile
18309 * @attributes: an attribute query string
18310 * @flags: a set of #GFileQueryInfoFlags
18311 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18312 * @error: #GError for error reporting
18314 * Gets the requested information about the files in a directory.
18315 * The result is a #GFileEnumerator object that will give out
18316 * #GFileInfo objects for all the files in the directory.
18318 * The @attributes value is a string that specifies the file
18319 * attributes that should be gathered. It is not an error if
18320 * it's not possible to read a particular requested attribute
18321 * from a file - it just won't be set. @attributes should
18322 * be a comma-separated list of attributes or attribute wildcards.
18323 * The wildcard "*" means all attributes, and a wildcard like
18324 * "standard::*" means all attributes in the standard namespace.
18325 * An example attribute query be "standard::*,owner::user".
18326 * The standard attributes are available as defines, like
18327 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
18329 * If @cancellable is not %NULL, then the operation can be cancelled
18330 * by triggering the cancellable object from another thread. If the
18331 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
18334 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
18335 * be returned. If the file is not a directory, the %G_FILE_ERROR_NOTDIR
18336 * error will be returned. Other errors are possible too.
18338 * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref().
18343 * g_file_enumerate_children_async:
18344 * @file: input #GFile
18345 * @attributes: an attribute query string
18346 * @flags: a set of #GFileQueryInfoFlags
18347 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
18348 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18349 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
18350 * @user_data: (closure): the data to pass to callback function
18352 * Asynchronously gets the requested information about the files
18353 * in a directory. The result is a #GFileEnumerator object that will
18354 * give out #GFileInfo objects for all the files in the directory.
18356 * For more details, see g_file_enumerate_children() which is
18357 * the synchronous version of this call.
18359 * When the operation is finished, @callback will be called. You can
18360 * then call g_file_enumerate_children_finish() to get the result of
18366 * g_file_enumerate_children_finish:
18367 * @file: input #GFile
18368 * @res: a #GAsyncResult
18369 * @error: a #GError
18371 * Finishes an async enumerate children operation.
18372 * See g_file_enumerate_children_async().
18374 * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref().
18379 * g_file_enumerator_close:
18380 * @enumerator: a #GFileEnumerator.
18381 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18382 * @error: location to store the error occurring, or %NULL to ignore
18384 * Releases all resources used by this enumerator, making the
18385 * enumerator return %G_IO_ERROR_CLOSED on all calls.
18387 * This will be automatically called when the last reference
18388 * is dropped, but you might want to call this function to make
18389 * sure resources are released as early as possible.
18391 * Returns: #TRUE on success or #FALSE on error.
18396 * g_file_enumerator_close_async:
18397 * @enumerator: a #GFileEnumerator.
18398 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
18399 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18400 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
18401 * @user_data: (closure): the data to pass to callback function
18403 * Asynchronously closes the file enumerator.
18405 * If @cancellable is not %NULL, then the operation can be cancelled by
18406 * triggering the cancellable object from another thread. If the operation
18407 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
18408 * g_file_enumerator_close_finish().
18413 * g_file_enumerator_close_finish:
18414 * @enumerator: a #GFileEnumerator.
18415 * @result: a #GAsyncResult.
18416 * @error: a #GError location to store the error occurring, or %NULL to ignore.
18418 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
18420 * If the file enumerator was already closed when g_file_enumerator_close_async()
18421 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
18422 * return %FALSE. If the file enumerator had pending operation when the close
18423 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
18424 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
18425 * cancelled by triggering the cancellable object from another thread. If the operation
18426 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
18429 * Returns: %TRUE if the close operation has finished successfully.
18434 * g_file_enumerator_get_container:
18435 * @enumerator: a #GFileEnumerator
18437 * Get the #GFile container which is being enumerated.
18439 * Returns: (transfer none): the #GFile which is being enumerated.
18445 * g_file_enumerator_has_pending:
18446 * @enumerator: a #GFileEnumerator.
18448 * Checks if the file enumerator has pending operations.
18450 * Returns: %TRUE if the @enumerator has pending operations.
18455 * g_file_enumerator_is_closed:
18456 * @enumerator: a #GFileEnumerator.
18458 * Checks if the file enumerator has been closed.
18460 * Returns: %TRUE if the @enumerator is closed.
18465 * g_file_enumerator_next_file:
18466 * @enumerator: a #GFileEnumerator.
18467 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18468 * @error: location to store the error occurring, or %NULL to ignore
18470 * Returns information for the next file in the enumerated object.
18471 * Will block until the information is available. The #GFileInfo
18472 * returned from this function will contain attributes that match the
18473 * attribute string that was passed when the #GFileEnumerator was created.
18475 * On error, returns %NULL and sets @error to the error. If the
18476 * enumerator is at the end, %NULL will be returned and @error will
18479 * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed.
18484 * g_file_enumerator_next_files_async:
18485 * @enumerator: a #GFileEnumerator.
18486 * @num_files: the number of file info objects to request
18487 * @io_priority: the <link linkend="io-priority">io priority</link> of the request.
18488 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18489 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
18490 * @user_data: (closure): the data to pass to callback function
18492 * Request information for a number of files from the enumerator asynchronously.
18493 * When all i/o for the operation is finished the @callback will be called with
18494 * the requested information.
18496 * The callback can be called with less than @num_files files in case of error
18497 * or at the end of the enumerator. In case of a partial error the callback will
18498 * be called with any succeeding items and no error, and on the next request the
18499 * error will be reported. If a request is cancelled the callback will be called
18500 * with %G_IO_ERROR_CANCELLED.
18502 * During an async request no other sync and async calls are allowed, and will
18503 * result in %G_IO_ERROR_PENDING errors.
18505 * Any outstanding i/o request with higher priority (lower numerical value) will
18506 * be executed before an outstanding request with lower priority. Default
18507 * priority is %G_PRIORITY_DEFAULT.
18512 * g_file_enumerator_next_files_finish:
18513 * @enumerator: a #GFileEnumerator.
18514 * @result: a #GAsyncResult.
18515 * @error: a #GError location to store the error occurring, or %NULL to ignore.
18517 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
18519 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them.
18524 * g_file_enumerator_set_pending:
18525 * @enumerator: a #GFileEnumerator.
18526 * @pending: a boolean value.
18528 * Sets the file enumerator as having pending operations.
18534 * @file1: the first #GFile
18535 * @file2: the second #GFile
18537 * Checks equality of two given #GFiles.
18539 * Note that two #GFiles that differ can still refer to the same
18540 * file on the filesystem due to various forms of filename
18543 * This call does no blocking I/O.
18545 * Returns: %TRUE if @file1 and @file2 are equal. %FALSE if either is not a #GFile.
18550 * g_file_find_enclosing_mount:
18551 * @file: input #GFile
18552 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18553 * @error: a #GError
18555 * Gets a #GMount for the #GFile.
18557 * If the #GFileIface for @file does not have a mount (e.g.
18558 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
18559 * and %NULL will be returned.
18561 * If @cancellable is not %NULL, then the operation can be cancelled by
18562 * triggering the cancellable object from another thread. If the operation
18563 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
18565 * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref().
18570 * g_file_find_enclosing_mount_async:
18572 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
18573 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18574 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
18575 * @user_data: (closure): the data to pass to callback function
18577 * Asynchronously gets the mount for the file.
18579 * For more details, see g_file_find_enclosing_mount() which is
18580 * the synchronous version of this call.
18582 * When the operation is finished, @callback will be called.
18583 * You can then call g_file_find_enclosing_mount_finish() to
18584 * get the result of the operation.
18589 * g_file_find_enclosing_mount_finish:
18591 * @res: a #GAsyncResult
18592 * @error: a #GError
18594 * Finishes an asynchronous find mount request.
18595 * See g_file_find_enclosing_mount_async().
18597 * Returns: (transfer full): #GMount for given @file or %NULL on error. Free the returned object with g_object_unref().
18602 * g_file_get_basename:
18603 * @file: input #GFile
18605 * Gets the base name (the last component of the path) for a given #GFile.
18607 * If called for the top level of a system (such as the filesystem root
18608 * or a uri like sftp://host/) it will return a single directory separator
18609 * (and on Windows, possibly a drive letter).
18611 * The base name is a byte string (not UTF-8). It has no defined encoding
18612 * or rules other than it may not contain zero bytes. If you want to use
18613 * filenames in a user interface you should use the display name that you
18614 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
18615 * attribute with g_file_query_info().
18617 * This call does no blocking I/O.
18619 * Returns: string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed.
18624 * g_file_get_child:
18625 * @file: input #GFile
18626 * @name: string containing the child's basename
18628 * Gets a child of @file with basename equal to @name.
18630 * Note that the file with that specific name might not exist, but
18631 * you can still have a #GFile that points to it. You can use this
18632 * for instance to create that file.
18634 * This call does no blocking I/O.
18636 * Returns: (transfer full): a #GFile to a child specified by @name. Free the returned object with g_object_unref().
18641 * g_file_get_child_for_display_name:
18642 * @file: input #GFile
18643 * @display_name: string to a possible child
18644 * @error: return location for an error
18646 * Gets the child of @file for a given @display_name (i.e. a UTF-8
18647 * version of the name). If this function fails, it returns %NULL
18648 * and @error will be set. This is very useful when constructing a
18649 * #GFile for a new file and the user entered the filename in the
18650 * user interface, for instance when you select a directory and
18651 * type a filename in the file selector.
18653 * This call does no blocking I/O.
18655 * Returns: (transfer full): a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref().
18660 * g_file_get_parent:
18661 * @file: input #GFile
18663 * Gets the parent directory for the @file.
18664 * If the @file represents the root directory of the
18665 * file system, then %NULL will be returned.
18667 * This call does no blocking I/O.
18669 * Returns: (transfer full): a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref().
18674 * g_file_get_parse_name:
18675 * @file: input #GFile
18677 * Gets the parse name of the @file.
18678 * A parse name is a UTF-8 string that describes the
18679 * file such that one can get the #GFile back using
18680 * g_file_parse_name().
18682 * This is generally used to show the #GFile as a nice
18683 * full-pathname kind of string in a user interface,
18684 * like in a location entry.
18686 * For local files with names that can safely be converted
18687 * to UTF-8 the pathname is used, otherwise the IRI is used
18688 * (a form of URI that allows UTF-8 characters unescaped).
18690 * This call does no blocking I/O.
18692 * Returns: a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed.
18698 * @file: input #GFile
18700 * Gets the local pathname for #GFile, if one exists.
18702 * This call does no blocking I/O.
18704 * Returns: string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed.
18709 * g_file_get_relative_path:
18710 * @parent: input #GFile
18711 * @descendant: input #GFile
18713 * Gets the path for @descendant relative to @parent.
18715 * This call does no blocking I/O.
18717 * Returns: string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed.
18723 * @file: input #GFile
18725 * Gets the URI for the @file.
18727 * This call does no blocking I/O.
18729 * Returns: a string containing the #GFile's URI. The returned string should be freed with g_free() when no longer needed.
18734 * g_file_get_uri_scheme:
18735 * @file: input #GFile
18737 * Gets the URI scheme for a #GFile.
18738 * RFC 3986 decodes the scheme as:
18740 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
18741 * </programlisting>
18742 * Common schemes include "file", "http", "ftp", etc.
18744 * This call does no blocking I/O.
18746 * Returns: a string containing the URI scheme for the given #GFile. The returned string should be freed with g_free() when no longer needed.
18751 * g_file_has_parent:
18752 * @file: input #GFile
18753 * @parent: (allow-none): the parent to check for, or %NULL
18755 * Checks if @file has a parent, and optionally, if it is @parent.
18757 * If @parent is %NULL then this function returns %TRUE if @file has any
18758 * parent at all. If @parent is non-%NULL then %TRUE is only returned
18759 * if @file is a child of @parent.
18761 * Returns: %TRUE if @file is a child of @parent (or any parent in the case that @parent is %NULL).
18767 * g_file_has_prefix:
18768 * @file: input #GFile
18769 * @prefix: input #GFile
18771 * Checks whether @file has the prefix specified by @prefix.
18773 * In other words, if the names of initial elements of @file's
18774 * pathname match @prefix. Only full pathname elements are matched,
18775 * so a path like /foo is not considered a prefix of /foobar, only
18778 * This call does no I/O, as it works purely on names. As such it can
18779 * sometimes return %FALSE even if @file is inside a @prefix (from a
18780 * filesystem point of view), because the prefix of @file is an alias
18783 * Virtual: prefix_matches
18784 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, %FALSE otherwise.
18789 * g_file_has_uri_scheme:
18790 * @file: input #GFile
18791 * @uri_scheme: a string containing a URI scheme
18793 * Checks to see if a #GFile has a given URI scheme.
18795 * This call does no blocking I/O.
18797 * Returns: %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid.
18803 * @file: (type GFile): #gconstpointer to a #GFile
18805 * Creates a hash value for a #GFile.
18807 * This call does no blocking I/O.
18810 * Returns: 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure.
18815 * g_file_icon_get_file:
18818 * Gets the #GFile associated with the given @icon.
18820 * Returns: (transfer none): a #GFile, or %NULL.
18828 * Creates a new icon for a file.
18830 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given @file, or %NULL on error.
18835 * g_file_info_clear_status:
18836 * @info: a #GFileInfo.
18838 * Clears the status information from @info.
18843 * g_file_info_copy_into:
18844 * @src_info: source to copy attributes from.
18845 * @dest_info: destination to copy attributes to.
18847 * Copies all of the <link linkend="gio-GFileAttribute">GFileAttribute</link>s
18848 * from @src_info to @dest_info.
18854 * @other: a #GFileInfo.
18856 * Duplicates a file info structure.
18858 * Returns: (transfer full): a duplicate #GFileInfo of @other.
18863 * g_file_info_get_attribute_as_string:
18864 * @info: a #GFileInfo.
18865 * @attribute: a file attribute key.
18867 * Gets the value of a attribute, formated as a string.
18868 * This escapes things as needed to make the string valid
18871 * Returns: a UTF-8 string associated with the given @attribute. When you're done with the string it must be freed with g_free().
18876 * g_file_info_get_attribute_boolean:
18877 * @info: a #GFileInfo.
18878 * @attribute: a file attribute key.
18880 * Gets the value of a boolean attribute. If the attribute does not
18881 * contain a boolean value, %FALSE will be returned.
18883 * Returns: the boolean value contained within the attribute.
18888 * g_file_info_get_attribute_byte_string:
18889 * @info: a #GFileInfo.
18890 * @attribute: a file attribute key.
18892 * Gets the value of a byte string attribute. If the attribute does
18893 * not contain a byte string, %NULL will be returned.
18895 * Returns: the contents of the @attribute value as a byte string, or %NULL otherwise.
18900 * g_file_info_get_attribute_data:
18901 * @info: a #GFileInfo
18902 * @attribute: a file attribute key
18903 * @type: (out) (allow-none): return location for the attribute type, or %NULL
18904 * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
18905 * @status: (out) (allow-none): return location for the attribute status, or %NULL
18907 * Gets the attribute type, value and status for an attribute key.
18909 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, %FALSE otherwise.
18914 * g_file_info_get_attribute_int32:
18915 * @info: a #GFileInfo.
18916 * @attribute: a file attribute key.
18918 * Gets a signed 32-bit integer contained within the attribute. If the
18919 * attribute does not contain a signed 32-bit integer, or is invalid,
18920 * 0 will be returned.
18922 * Returns: a signed 32-bit integer from the attribute.
18927 * g_file_info_get_attribute_int64:
18928 * @info: a #GFileInfo.
18929 * @attribute: a file attribute key.
18931 * Gets a signed 64-bit integer contained within the attribute. If the
18932 * attribute does not contain an signed 64-bit integer, or is invalid,
18933 * 0 will be returned.
18935 * Returns: a signed 64-bit integer from the attribute.
18940 * g_file_info_get_attribute_object:
18941 * @info: a #GFileInfo.
18942 * @attribute: a file attribute key.
18944 * Gets the value of a #GObject attribute. If the attribute does
18945 * not contain a #GObject, %NULL will be returned.
18947 * Returns: (transfer none): a #GObject associated with the given @attribute, or %NULL otherwise.
18952 * g_file_info_get_attribute_status:
18953 * @info: a #GFileInfo
18954 * @attribute: a file attribute key
18956 * Gets the attribute status for an attribute key.
18958 * Returns: a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
18963 * g_file_info_get_attribute_string:
18964 * @info: a #GFileInfo.
18965 * @attribute: a file attribute key.
18967 * Gets the value of a string attribute. If the attribute does
18968 * not contain a string, %NULL will be returned.
18970 * Returns: the contents of the @attribute value as a UTF-8 string, or %NULL otherwise.
18975 * g_file_info_get_attribute_stringv:
18976 * @info: a #GFileInfo.
18977 * @attribute: a file attribute key.
18979 * Gets the value of a stringv attribute. If the attribute does
18980 * not contain a stringv, %NULL will be returned.
18982 * Returns: (transfer none): the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8.
18988 * g_file_info_get_attribute_type:
18989 * @info: a #GFileInfo.
18990 * @attribute: a file attribute key.
18992 * Gets the attribute type for an attribute key.
18994 * Returns: a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
18999 * g_file_info_get_attribute_uint32:
19000 * @info: a #GFileInfo.
19001 * @attribute: a file attribute key.
19003 * Gets an unsigned 32-bit integer contained within the attribute. If the
19004 * attribute does not contain an unsigned 32-bit integer, or is invalid,
19005 * 0 will be returned.
19007 * Returns: an unsigned 32-bit integer from the attribute.
19012 * g_file_info_get_attribute_uint64:
19013 * @info: a #GFileInfo.
19014 * @attribute: a file attribute key.
19016 * Gets a unsigned 64-bit integer contained within the attribute. If the
19017 * attribute does not contain an unsigned 64-bit integer, or is invalid,
19018 * 0 will be returned.
19020 * Returns: a unsigned 64-bit integer from the attribute.
19025 * g_file_info_get_content_type:
19026 * @info: a #GFileInfo.
19028 * Gets the file's content type.
19030 * Returns: a string containing the file's content type.
19035 * g_file_info_get_display_name:
19036 * @info: a #GFileInfo.
19038 * Gets a display name for a file.
19040 * Returns: a string containing the display name.
19045 * g_file_info_get_edit_name:
19046 * @info: a #GFileInfo.
19048 * Gets the edit name for a file.
19050 * Returns: a string containing the edit name.
19055 * g_file_info_get_etag:
19056 * @info: a #GFileInfo.
19058 * Gets the <link linkend="gfile-etag">entity tag</link> for a given
19059 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
19061 * Returns: a string containing the value of the "etag:value" attribute.
19066 * g_file_info_get_file_type:
19067 * @info: a #GFileInfo.
19069 * Gets a file's type (whether it is a regular file, symlink, etc).
19070 * This is different from the file's content type, see g_file_info_get_content_type().
19072 * Returns: a #GFileType for the given file.
19077 * g_file_info_get_icon:
19078 * @info: a #GFileInfo.
19080 * Gets the icon for a file.
19082 * Returns: (transfer none): #GIcon for the given @info.
19087 * g_file_info_get_is_backup:
19088 * @info: a #GFileInfo.
19090 * Checks if a file is a backup file.
19092 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
19097 * g_file_info_get_is_hidden:
19098 * @info: a #GFileInfo.
19100 * Checks if a file is hidden.
19102 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
19107 * g_file_info_get_is_symlink:
19108 * @info: a #GFileInfo.
19110 * Checks if a file is a symlink.
19112 * Returns: %TRUE if the given @info is a symlink.
19117 * g_file_info_get_modification_time:
19118 * @info: a #GFileInfo.
19119 * @result: (out caller-allocates): a #GTimeVal.
19121 * Gets the modification time of the current @info and sets it
19127 * g_file_info_get_name:
19128 * @info: a #GFileInfo.
19130 * Gets the name for a file.
19132 * Returns: a string containing the file name.
19137 * g_file_info_get_size:
19138 * @info: a #GFileInfo.
19140 * Gets the file's size.
19142 * Returns: a #goffset containing the file's size.
19147 * g_file_info_get_sort_order:
19148 * @info: a #GFileInfo.
19150 * Gets the value of the sort_order attribute from the #GFileInfo.
19151 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
19153 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
19158 * g_file_info_get_symbolic_icon:
19159 * @info: a #GFileInfo.
19161 * Gets the symbolic icon for a file.
19163 * Returns: (transfer none): #GIcon for the given @info.
19169 * g_file_info_get_symlink_target:
19170 * @info: a #GFileInfo.
19172 * Gets the symlink target for a given #GFileInfo.
19174 * Returns: a string containing the symlink target.
19179 * g_file_info_has_attribute:
19180 * @info: a #GFileInfo.
19181 * @attribute: a file attribute key.
19183 * Checks if a file info structure has an attribute named @attribute.
19185 * Returns: %TRUE if @Ginfo has an attribute named @attribute, %FALSE otherwise.
19190 * g_file_info_has_namespace:
19191 * @info: a #GFileInfo.
19192 * @name_space: a file attribute namespace.
19194 * Checks if a file info structure has an attribute in the
19195 * specified @name_space.
19197 * Returns: %TRUE if @Ginfo has an attribute in @name_space, %FALSE otherwise.
19203 * g_file_info_list_attributes:
19204 * @info: a #GFileInfo.
19205 * @name_space: a file attribute key's namespace.
19207 * Lists the file info structure's attributes.
19209 * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error.
19216 * Creates a new file info structure.
19218 * Returns: a #GFileInfo.
19223 * g_file_info_remove_attribute:
19224 * @info: a #GFileInfo.
19225 * @attribute: a file attribute key.
19227 * Removes all cases of @attribute from @info if it exists.
19232 * g_file_info_set_attribute:
19233 * @info: a #GFileInfo.
19234 * @attribute: a file attribute key.
19235 * @type: a #GFileAttributeType
19236 * @value_p: pointer to the value
19238 * Sets the @attribute to contain the given value, if possible. To unset the
19239 * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
19244 * g_file_info_set_attribute_boolean:
19245 * @info: a #GFileInfo.
19246 * @attribute: a file attribute key.
19247 * @attr_value: a boolean value.
19249 * Sets the @attribute to contain the given @attr_value,
19255 * g_file_info_set_attribute_byte_string:
19256 * @info: a #GFileInfo.
19257 * @attribute: a file attribute key.
19258 * @attr_value: a byte string.
19260 * Sets the @attribute to contain the given @attr_value,
19266 * g_file_info_set_attribute_int32:
19267 * @info: a #GFileInfo.
19268 * @attribute: a file attribute key.
19269 * @attr_value: a signed 32-bit integer
19271 * Sets the @attribute to contain the given @attr_value,
19277 * g_file_info_set_attribute_int64:
19278 * @info: a #GFileInfo.
19279 * @attribute: attribute name to set.
19280 * @attr_value: int64 value to set attribute to.
19282 * Sets the @attribute to contain the given @attr_value,
19288 * g_file_info_set_attribute_mask:
19289 * @info: a #GFileInfo.
19290 * @mask: a #GFileAttributeMatcher.
19292 * Sets @mask on @info to match specific attribute types.
19297 * g_file_info_set_attribute_object:
19298 * @info: a #GFileInfo.
19299 * @attribute: a file attribute key.
19300 * @attr_value: a #GObject.
19302 * Sets the @attribute to contain the given @attr_value,
19308 * g_file_info_set_attribute_status:
19309 * @info: a #GFileInfo
19310 * @attribute: a file attribute key
19311 * @status: a #GFileAttributeStatus
19313 * Sets the attribute status for an attribute key. This is only
19314 * needed by external code that implement g_file_set_attributes_from_info()
19315 * or similar functions.
19317 * The attribute must exist in @info for this to work. Otherwise %FALSE
19318 * is returned and @info is unchanged.
19320 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
19326 * g_file_info_set_attribute_string:
19327 * @info: a #GFileInfo.
19328 * @attribute: a file attribute key.
19329 * @attr_value: a UTF-8 string.
19331 * Sets the @attribute to contain the given @attr_value,
19337 * g_file_info_set_attribute_stringv:
19338 * @info: a #GFileInfo.
19339 * @attribute: a file attribute key
19340 * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
19342 * Sets the @attribute to contain the given @attr_value,
19350 * g_file_info_set_attribute_uint32:
19351 * @info: a #GFileInfo.
19352 * @attribute: a file attribute key.
19353 * @attr_value: an unsigned 32-bit integer.
19355 * Sets the @attribute to contain the given @attr_value,
19361 * g_file_info_set_attribute_uint64:
19362 * @info: a #GFileInfo.
19363 * @attribute: a file attribute key.
19364 * @attr_value: an unsigned 64-bit integer.
19366 * Sets the @attribute to contain the given @attr_value,
19372 * g_file_info_set_content_type:
19373 * @info: a #GFileInfo.
19374 * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>.
19376 * Sets the content type attribute for a given #GFileInfo.
19377 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
19382 * g_file_info_set_display_name:
19383 * @info: a #GFileInfo.
19384 * @display_name: a string containing a display name.
19386 * Sets the display name for the current #GFileInfo.
19387 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
19392 * g_file_info_set_edit_name:
19393 * @info: a #GFileInfo.
19394 * @edit_name: a string containing an edit name.
19396 * Sets the edit name for the current file.
19397 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
19402 * g_file_info_set_file_type:
19403 * @info: a #GFileInfo.
19404 * @type: a #GFileType.
19406 * Sets the file type in a #GFileInfo to @type.
19407 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
19412 * g_file_info_set_icon:
19413 * @info: a #GFileInfo.
19416 * Sets the icon for a given #GFileInfo.
19417 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
19422 * g_file_info_set_is_hidden:
19423 * @info: a #GFileInfo.
19424 * @is_hidden: a #gboolean.
19426 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink.
19427 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
19432 * g_file_info_set_is_symlink:
19433 * @info: a #GFileInfo.
19434 * @is_symlink: a #gboolean.
19436 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
19437 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
19442 * g_file_info_set_modification_time:
19443 * @info: a #GFileInfo.
19444 * @mtime: a #GTimeVal.
19446 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
19447 * info to the given time value.
19452 * g_file_info_set_name:
19453 * @info: a #GFileInfo.
19454 * @name: a string containing a name.
19456 * Sets the name attribute for the current #GFileInfo.
19457 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
19462 * g_file_info_set_size:
19463 * @info: a #GFileInfo.
19464 * @size: a #goffset containing the file's size.
19466 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
19467 * to the given size.
19472 * g_file_info_set_sort_order:
19473 * @info: a #GFileInfo.
19474 * @sort_order: a sort order integer.
19476 * Sets the sort order attribute in the file info structure. See
19477 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
19482 * g_file_info_set_symbolic_icon:
19483 * @info: a #GFileInfo.
19486 * Sets the symbolic icon for a given #GFileInfo.
19487 * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
19494 * g_file_info_set_symlink_target:
19495 * @info: a #GFileInfo.
19496 * @symlink_target: a static string containing a path to a symlink target.
19498 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
19499 * to the given symlink target.
19504 * g_file_info_unset_attribute_mask:
19505 * @info: #GFileInfo.
19507 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
19513 * g_file_input_stream_query_info:
19514 * @stream: a #GFileInputStream.
19515 * @attributes: a file attribute query string.
19516 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19517 * @error: a #GError location to store the error occurring, or %NULL to ignore.
19519 * Queries a file input stream the given @attributes. This function blocks
19520 * while querying the stream. For the asynchronous (non-blocking) version
19521 * of this function, see g_file_input_stream_query_info_async(). While the
19522 * stream is blocked, the stream will set the pending flag internally, and
19523 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
19525 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
19530 * g_file_input_stream_query_info_async:
19531 * @stream: a #GFileInputStream.
19532 * @attributes: a file attribute query string.
19533 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
19534 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19535 * @callback: (scope async): callback to call when the request is satisfied
19536 * @user_data: (closure): the data to pass to callback function
19538 * Queries the stream information asynchronously.
19539 * When the operation is finished @callback will be called.
19540 * You can then call g_file_input_stream_query_info_finish()
19541 * to get the result of the operation.
19543 * For the synchronous version of this function,
19544 * see g_file_input_stream_query_info().
19546 * If @cancellable is not %NULL, then the operation can be cancelled by
19547 * triggering the cancellable object from another thread. If the operation
19548 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
19553 * g_file_input_stream_query_info_finish:
19554 * @stream: a #GFileInputStream.
19555 * @result: a #GAsyncResult.
19556 * @error: a #GError location to store the error occurring, or %NULL to ignore.
19558 * Finishes an asynchronous info query operation.
19560 * Returns: (transfer full): #GFileInfo.
19565 * g_file_io_stream_get_etag:
19566 * @stream: a #GFileIOStream.
19568 * Gets the entity tag for the file when it has been written.
19569 * This must be called after the stream has been written
19570 * and closed, as the etag can change while writing.
19572 * Returns: the entity tag for the stream.
19578 * g_file_io_stream_query_info:
19579 * @stream: a #GFileIOStream.
19580 * @attributes: a file attribute query string.
19581 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19582 * @error: a #GError, %NULL to ignore.
19584 * Queries a file io stream for the given @attributes.
19585 * This function blocks while querying the stream. For the asynchronous
19586 * version of this function, see g_file_io_stream_query_info_async().
19587 * While the stream is blocked, the stream will set the pending flag
19588 * internally, and any other operations on the stream will fail with
19589 * %G_IO_ERROR_PENDING.
19591 * Can fail if the stream was already closed (with @error being set to
19592 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
19593 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
19594 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
19595 * all cases of failure, %NULL will be returned.
19597 * If @cancellable is not %NULL, then the operation can be cancelled by
19598 * triggering the cancellable object from another thread. If the operation
19599 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
19602 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
19608 * g_file_io_stream_query_info_async:
19609 * @stream: a #GFileIOStream.
19610 * @attributes: a file attribute query string.
19611 * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request.
19612 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19613 * @callback: (scope async): callback to call when the request is satisfied
19614 * @user_data: (closure): the data to pass to callback function
19616 * Asynchronously queries the @stream for a #GFileInfo. When completed,
19617 * @callback will be called with a #GAsyncResult which can be used to
19618 * finish the operation with g_file_io_stream_query_info_finish().
19620 * For the synchronous version of this function, see
19621 * g_file_io_stream_query_info().
19628 * g_file_io_stream_query_info_finish:
19629 * @stream: a #GFileIOStream.
19630 * @result: a #GAsyncResult.
19631 * @error: a #GError, %NULL to ignore.
19633 * Finalizes the asynchronous query started
19634 * by g_file_io_stream_query_info_async().
19636 * Returns: (transfer full): A #GFileInfo for the finished query.
19642 * g_file_is_native:
19643 * @file: input #GFile
19645 * Checks to see if a file is native to the platform.
19647 * A native file s one expressed in the platform-native filename format,
19648 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
19649 * as it might be on a locally mounted remote filesystem.
19651 * On some systems non-native files may be available using the native
19652 * filesystem via a userspace filesystem (FUSE), in these cases this call
19653 * will return %FALSE, but g_file_get_path() will still return a native path.
19655 * This call does no blocking I/O.
19657 * Returns: %TRUE if @file is native
19662 * g_file_load_contents:
19663 * @file: input #GFile
19664 * @cancellable: optional #GCancellable object, %NULL to ignore
19665 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
19666 * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
19667 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed
19668 * @error: a #GError, or %NULL
19670 * Loads the content of the file into memory. The data is always
19671 * zero-terminated, but this is not included in the resultant @length.
19672 * The returned @content should be freed with g_free() when no longer
19675 * If @cancellable is not %NULL, then the operation can be cancelled by
19676 * triggering the cancellable object from another thread. If the operation
19677 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19679 * Returns: %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors.
19684 * g_file_load_contents_async:
19685 * @file: input #GFile
19686 * @cancellable: optional #GCancellable object, %NULL to ignore
19687 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
19688 * @user_data: the data to pass to callback function
19690 * Starts an asynchronous load of the @file's contents.
19692 * For more details, see g_file_load_contents() which is
19693 * the synchronous version of this call.
19695 * When the load operation has completed, @callback will be called
19696 * with @user data. To finish the operation, call
19697 * g_file_load_contents_finish() with the #GAsyncResult returned by
19700 * If @cancellable is not %NULL, then the operation can be cancelled by
19701 * triggering the cancellable object from another thread. If the operation
19702 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19707 * g_file_load_contents_finish:
19708 * @file: input #GFile
19709 * @res: a #GAsyncResult
19710 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
19711 * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
19712 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed
19713 * @error: a #GError, or %NULL
19715 * Finishes an asynchronous load of the @file's contents.
19716 * The contents are placed in @contents, and @length is set to the
19717 * size of the @contents string. The @content should be freed with
19718 * g_free() when no longer needed. If @etag_out is present, it will be
19719 * set to the new entity tag for the @file.
19721 * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately.
19726 * g_file_load_partial_contents_async: (skip)
19727 * @file: input #GFile
19728 * @cancellable: optional #GCancellable object, %NULL to ignore
19729 * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read
19730 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
19731 * @user_data: the data to pass to the callback functions
19733 * Reads the partial contents of a file. A #GFileReadMoreCallback should
19734 * be used to stop reading from the file when appropriate, else this
19735 * function will behave exactly as g_file_load_contents_async(). This
19736 * operation can be finished by g_file_load_partial_contents_finish().
19738 * Users of this function should be aware that @user_data is passed to
19739 * both the @read_more_callback and the @callback.
19741 * If @cancellable is not %NULL, then the operation can be cancelled by
19742 * triggering the cancellable object from another thread. If the operation
19743 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19748 * g_file_load_partial_contents_finish:
19749 * @file: input #GFile
19750 * @res: a #GAsyncResult
19751 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
19752 * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
19753 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed
19754 * @error: a #GError, or %NULL
19756 * Finishes an asynchronous partial load operation that was started
19757 * with g_file_load_partial_contents_async(). The data is always
19758 * zero-terminated, but this is not included in the resultant @length.
19759 * The returned @content should be freed with g_free() when no longer
19762 * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately.
19767 * g_file_make_directory:
19768 * @file: input #GFile
19769 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19770 * @error: a #GError, or %NULL
19772 * Creates a directory. Note that this will only create a child directory
19773 * of the immediate parent directory of the path or URI given by the #GFile.
19774 * To recursively create directories, see g_file_make_directory_with_parents().
19775 * This function will fail if the parent directory does not exist, setting
19776 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
19777 * creating directories, this function will fail, setting @error to
19778 * %G_IO_ERROR_NOT_SUPPORTED.
19780 * For a local #GFile the newly created directory will have the default
19781 * (current) ownership and permissions of the current process.
19783 * If @cancellable is not %NULL, then the operation can be cancelled by
19784 * triggering the cancellable object from another thread. If the operation
19785 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19787 * Returns: %TRUE on successful creation, %FALSE otherwise.
19792 * g_file_make_directory_with_parents:
19793 * @file: input #GFile
19794 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19795 * @error: a #GError, or %NULL
19797 * Creates a directory and any parent directories that may not
19798 * exist similar to 'mkdir -p'. If the file system does not support
19799 * creating directories, this function will fail, setting @error to
19800 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
19801 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
19802 * the similar g_mkdir_with_parents().
19804 * For a local #GFile the newly created directories will have the default
19805 * (current) ownership and permissions of the current process.
19807 * If @cancellable is not %NULL, then the operation can be cancelled by
19808 * triggering the cancellable object from another thread. If the operation
19809 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19811 * Returns: %TRUE if all directories have been successfully created, %FALSE otherwise.
19817 * g_file_make_symbolic_link:
19818 * @file: a #GFile with the name of the symlink to create
19819 * @symlink_value: a string with the path for the target of the new symlink
19820 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19821 * @error: a #GError
19823 * Creates a symbolic link named @file which contains the string
19826 * If @cancellable is not %NULL, then the operation can be cancelled by
19827 * triggering the cancellable object from another thread. If the operation
19828 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19830 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
19836 * @file: input #GFile
19837 * @flags: a set of #GFileMonitorFlags
19838 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19839 * @error: a #GError, or %NULL
19841 * Obtains a file or directory monitor for the given file,
19842 * depending on the type of the file.
19844 * If @cancellable is not %NULL, then the operation can be cancelled by
19845 * triggering the cancellable object from another thread. If the operation
19846 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19848 * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref().
19854 * g_file_monitor_cancel:
19855 * @monitor: a #GFileMonitor.
19857 * Cancels a file monitor.
19859 * Returns: %TRUE if monitor was cancelled.
19864 * g_file_monitor_directory:
19865 * @file: input #GFile
19866 * @flags: a set of #GFileMonitorFlags
19867 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19868 * @error: a #GError, or %NULL
19870 * Obtains a directory monitor for the given file.
19871 * This may fail if directory monitoring is not supported.
19873 * If @cancellable is not %NULL, then the operation can be cancelled by
19874 * triggering the cancellable object from another thread. If the operation
19875 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19877 * Virtual: monitor_dir
19878 * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref().
19883 * g_file_monitor_emit_event:
19884 * @monitor: a #GFileMonitor.
19885 * @child: a #GFile.
19886 * @other_file: a #GFile.
19887 * @event_type: a set of #GFileMonitorEvent flags.
19889 * Emits the #GFileMonitor::changed signal if a change
19890 * has taken place. Should be called from file monitor
19891 * implementations only.
19893 * The signal will be emitted from an idle handler (in the <link
19894 * linkend="g-main-context-push-thread-default">thread-default main
19900 * g_file_monitor_file:
19901 * @file: input #GFile
19902 * @flags: a set of #GFileMonitorFlags
19903 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19904 * @error: a #GError, or %NULL
19906 * Obtains a file monitor for the given file. If no file notification
19907 * mechanism exists, then regular polling of the file is used.
19909 * If @cancellable is not %NULL, then the operation can be cancelled by
19910 * triggering the cancellable object from another thread. If the operation
19911 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19913 * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref().
19918 * g_file_monitor_is_cancelled:
19919 * @monitor: a #GFileMonitor
19921 * Returns whether the monitor is canceled.
19923 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
19928 * g_file_monitor_set_rate_limit:
19929 * @monitor: a #GFileMonitor.
19930 * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes
19932 * Sets the rate limit to which the @monitor will report
19933 * consecutive change events to the same file.
19938 * g_file_mount_enclosing_volume:
19939 * @location: input #GFile
19940 * @flags: flags affecting the operation
19941 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
19942 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19943 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
19944 * @user_data: the data to pass to callback function
19946 * Starts a @mount_operation, mounting the volume that contains
19947 * the file @location.
19949 * When this operation has completed, @callback will be called with
19950 * @user_user data, and the operation can be finalized with
19951 * g_file_mount_enclosing_volume_finish().
19953 * If @cancellable is not %NULL, then the operation can be cancelled by
19954 * triggering the cancellable object from another thread. If the operation
19955 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19960 * g_file_mount_enclosing_volume_finish:
19961 * @location: input #GFile
19962 * @result: a #GAsyncResult
19963 * @error: a #GError, or %NULL
19965 * Finishes a mount operation started by g_file_mount_enclosing_volume().
19967 * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
19972 * g_file_mount_mountable:
19973 * @file: input #GFile
19974 * @flags: flags affecting the operation
19975 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
19976 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19977 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
19978 * @user_data: (closure): the data to pass to callback function
19980 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
19981 * Using @mount_operation, you can request callbacks when, for instance,
19982 * passwords are needed during authentication.
19984 * If @cancellable is not %NULL, then the operation can be cancelled by
19985 * triggering the cancellable object from another thread. If the operation
19986 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19988 * When the operation is finished, @callback will be called.
19989 * You can then call g_file_mount_mountable_finish() to get
19990 * the result of the operation.
19995 * g_file_mount_mountable_finish:
19996 * @file: input #GFile
19997 * @result: a #GAsyncResult
19998 * @error: a #GError, or %NULL
20000 * Finishes a mount operation. See g_file_mount_mountable() for details.
20002 * Finish an asynchronous mount operation that was started
20003 * with g_file_mount_mountable().
20005 * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref().
20011 * @source: #GFile pointing to the source location
20012 * @destination: #GFile pointing to the destination location
20013 * @flags: set of #GFileCopyFlags
20014 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20015 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback function for updates
20016 * @progress_callback_data: (closure): gpointer to user data for the callback function
20017 * @error: #GError for returning error conditions, or %NULL
20019 * Tries to move the file or directory @source to the location specified
20020 * by @destination. If native move operations are supported then this is
20021 * used, otherwise a copy + delete fallback is used. The native
20022 * implementation may support moving directories (for instance on moves
20023 * inside the same filesystem), but the fallback code does not.
20025 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
20026 * existing @destination file is overwritten.
20028 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
20029 * will be copied as symlinks, otherwise the target of the
20030 * @source symlink will be copied.
20032 * If @cancellable is not %NULL, then the operation can be cancelled by
20033 * triggering the cancellable object from another thread. If the operation
20034 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20036 * If @progress_callback is not %NULL, then the operation can be monitored
20037 * by setting this to a #GFileProgressCallback function.
20038 * @progress_callback_data will be passed to this function. It is
20039 * guaranteed that this callback will be called after all data has been
20040 * transferred with the total number of bytes copied during the operation.
20042 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
20043 * error is returned, independent on the status of the @destination.
20045 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
20046 * then the error %G_IO_ERROR_EXISTS is returned.
20048 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
20049 * error is returned. If trying to overwrite a directory with a directory the
20050 * %G_IO_ERROR_WOULD_MERGE error is returned.
20052 * If the source is a directory and the target does not exist, or
20053 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
20054 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
20055 * move operation isn't available).
20057 * Returns: %TRUE on successful move, %FALSE otherwise.
20062 * g_file_new_for_commandline_arg:
20063 * @arg: a command line string
20065 * Creates a #GFile with the given argument from the command line.
20066 * The value of @arg can be either a URI, an absolute path or a
20067 * relative path resolved relative to the current working directory.
20068 * This operation never fails, but the returned object might not
20069 * support any I/O operation if @arg points to a malformed path.
20071 * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref().
20076 * g_file_new_for_path:
20077 * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding.
20079 * Constructs a #GFile for a given path. This operation never
20080 * fails, but the returned object might not support any I/O
20081 * operation if @path is malformed.
20083 * Returns: (transfer full): a new #GFile for the given @path. Free the returned object with g_object_unref().
20088 * g_file_new_for_uri:
20089 * @uri: a UTF-8 string containing a URI
20091 * Constructs a #GFile for a given URI. This operation never
20092 * fails, but the returned object might not support any I/O
20093 * operation if @uri is malformed or if the uri type is
20096 * Returns: (transfer full): a new #GFile for the given @uri. Free the returned object with g_object_unref().
20102 * @tmpl: (type filename) (allow-none): Template for the file name, as in g_file_open_tmp(), or %NULL for a default template
20103 * @iostream: (out): on return, a #GFileIOStream for the created file
20104 * @error: a #GError, or %NULL
20106 * Opens a file in the preferred directory for temporary files (as
20107 * returned by g_get_tmp_dir()) and returns a #GFile and
20108 * #GFileIOStream pointing to it.
20110 * @tmpl should be a string in the GLib file name encoding
20111 * containing a sequence of six 'X' characters, and containing no
20112 * directory components. If it is %NULL, a default template is used.
20114 * Unlike the other #GFile constructors, this will return %NULL if
20115 * a temporary file could not be created.
20117 * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref().
20123 * g_file_open_readwrite:
20124 * @file: #GFile to open
20125 * @cancellable: (allow-none): a #GCancellable
20126 * @error: a #GError, or %NULL
20128 * Opens an existing file for reading and writing. The result is
20129 * a #GFileIOStream that can be used to read and write the contents
20132 * If @cancellable is not %NULL, then the operation can be cancelled
20133 * by triggering the cancellable object from another thread. If the
20134 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
20137 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
20138 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
20139 * error will be returned. Other errors are possible too, and depend on
20140 * what kind of filesystem the file is on. Note that in many non-local
20141 * file cases read and write streams are not supported, so make sure you
20142 * really need to do read and write streaming, rather than just opening
20143 * for reading or writing.
20145 * Returns: (transfer full): #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
20151 * g_file_open_readwrite_async:
20152 * @file: input #GFile
20153 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
20154 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20155 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20156 * @user_data: (closure): the data to pass to callback function
20158 * Asynchronously opens @file for reading and writing.
20160 * For more details, see g_file_open_readwrite() which is
20161 * the synchronous version of this call.
20163 * When the operation is finished, @callback will be called.
20164 * You can then call g_file_open_readwrite_finish() to get
20165 * the result of the operation.
20172 * g_file_open_readwrite_finish:
20173 * @file: input #GFile
20174 * @res: a #GAsyncResult
20175 * @error: a #GError, or %NULL
20177 * Finishes an asynchronous file read operation started with
20178 * g_file_open_readwrite_async().
20180 * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
20186 * g_file_output_stream_get_etag:
20187 * @stream: a #GFileOutputStream.
20189 * Gets the entity tag for the file when it has been written.
20190 * This must be called after the stream has been written
20191 * and closed, as the etag can change while writing.
20193 * Returns: the entity tag for the stream.
20198 * g_file_output_stream_query_info:
20199 * @stream: a #GFileOutputStream.
20200 * @attributes: a file attribute query string.
20201 * @cancellable: optional #GCancellable object, %NULL to ignore.
20202 * @error: a #GError, %NULL to ignore.
20204 * Queries a file output stream for the given @attributes.
20205 * This function blocks while querying the stream. For the asynchronous
20206 * version of this function, see g_file_output_stream_query_info_async().
20207 * While the stream is blocked, the stream will set the pending flag
20208 * internally, and any other operations on the stream will fail with
20209 * %G_IO_ERROR_PENDING.
20211 * Can fail if the stream was already closed (with @error being set to
20212 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
20213 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
20214 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
20215 * all cases of failure, %NULL will be returned.
20217 * If @cancellable is not %NULL, then the operation can be cancelled by
20218 * triggering the cancellable object from another thread. If the operation
20219 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
20222 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
20227 * g_file_output_stream_query_info_async:
20228 * @stream: a #GFileOutputStream.
20229 * @attributes: a file attribute query string.
20230 * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request.
20231 * @cancellable: optional #GCancellable object, %NULL to ignore.
20232 * @callback: callback to call when the request is satisfied
20233 * @user_data: the data to pass to callback function
20235 * Asynchronously queries the @stream for a #GFileInfo. When completed,
20236 * @callback will be called with a #GAsyncResult which can be used to
20237 * finish the operation with g_file_output_stream_query_info_finish().
20239 * For the synchronous version of this function, see
20240 * g_file_output_stream_query_info().
20245 * g_file_output_stream_query_info_finish:
20246 * @stream: a #GFileOutputStream.
20247 * @result: a #GAsyncResult.
20248 * @error: a #GError, %NULL to ignore.
20250 * Finalizes the asynchronous query started
20251 * by g_file_output_stream_query_info_async().
20253 * Returns: (transfer full): A #GFileInfo for the finished query.
20258 * g_file_parse_name:
20259 * @parse_name: a file name or path to be parsed
20261 * Constructs a #GFile with the given @parse_name (i.e. something
20262 * given by g_file_get_parse_name()). This operation never fails,
20263 * but the returned object might not support any I/O operation if
20264 * the @parse_name cannot be parsed.
20266 * Returns: (transfer full): a new #GFile.
20271 * g_file_poll_mountable:
20272 * @file: input #GFile
20273 * @cancellable: optional #GCancellable object, %NULL to ignore
20274 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
20275 * @user_data: the data to pass to callback function
20277 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
20279 * If @cancellable is not %NULL, then the operation can be cancelled by
20280 * triggering the cancellable object from another thread. If the operation
20281 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20283 * When the operation is finished, @callback will be called.
20284 * You can then call g_file_mount_mountable_finish() to get
20285 * the result of the operation.
20292 * g_file_poll_mountable_finish:
20293 * @file: input #GFile
20294 * @result: a #GAsyncResult
20295 * @error: a #GError, or %NULL
20297 * Finishes a poll operation. See g_file_poll_mountable() for details.
20299 * Finish an asynchronous poll operation that was polled
20300 * with g_file_poll_mountable().
20302 * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
20308 * g_file_query_default_handler:
20309 * @file: a #GFile to open
20310 * @cancellable: optional #GCancellable object, %NULL to ignore
20311 * @error: a #GError, or %NULL
20313 * Returns the #GAppInfo that is registered as the default
20314 * application to handle the file specified by @file.
20316 * If @cancellable is not %NULL, then the operation can be cancelled by
20317 * triggering the cancellable object from another thread. If the operation
20318 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20320 * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref()
20325 * g_file_query_exists:
20326 * @file: input #GFile
20327 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20329 * Utility function to check if a particular file exists. This is
20330 * implemented using g_file_query_info() and as such does blocking I/O.
20332 * Note that in many cases it is racy to first check for file existence
20333 * and then execute something based on the outcome of that, because the
20334 * file might have been created or removed in between the operations. The
20335 * general approach to handling that is to not check, but just do the
20336 * operation and handle the errors as they come.
20338 * As an example of race-free checking, take the case of reading a file,
20339 * and if it doesn't exist, creating it. There are two racy versions: read
20340 * it, and on error create it; and: check if it exists, if not create it.
20341 * These can both result in two processes creating the file (with perhaps
20342 * a partially written file as the result). The correct approach is to
20343 * always try to create the file with g_file_create() which will either
20344 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
20346 * However, in many cases an existence check is useful in a user interface,
20347 * for instance to make a menu item sensitive/insensitive, so that you don't
20348 * have to fool users that something is possible and then just show an error
20349 * dialog. If you do this, you should make sure to also handle the errors
20350 * that can happen due to races when you execute the operation.
20352 * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled).
20357 * g_file_query_file_type:
20358 * @file: input #GFile
20359 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
20360 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20362 * Utility function to inspect the #GFileType of a file. This is
20363 * implemented using g_file_query_info() and as such does blocking I/O.
20365 * The primary use case of this method is to check if a file is
20366 * a regular file, directory, or symlink.
20368 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file does not exist
20374 * g_file_query_filesystem_info:
20375 * @file: input #GFile
20376 * @attributes: an attribute query string
20377 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20378 * @error: a #GError
20380 * Similar to g_file_query_info(), but obtains information
20381 * about the filesystem the @file is on, rather than the file itself.
20382 * For instance the amount of space available and the type of
20385 * The @attributes value is a string that specifies the attributes
20386 * that should be gathered. It is not an error if it's not possible
20387 * to read a particular requested attribute from a file - it just
20388 * won't be set. @attributes should be a comma-separated list of
20389 * attributes or attribute wildcards. The wildcard "*" means all
20390 * attributes, and a wildcard like "filesystem::*" means all attributes
20391 * in the filesystem namespace. The standard namespace for filesystem
20392 * attributes is "filesystem". Common attributes of interest are
20393 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
20394 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
20395 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
20397 * If @cancellable is not %NULL, then the operation can be cancelled
20398 * by triggering the cancellable object from another thread. If the
20399 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
20402 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
20403 * be returned. Other errors are possible too, and depend on what
20404 * kind of filesystem the file is on.
20406 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref().
20411 * g_file_query_filesystem_info_async:
20412 * @file: input #GFile
20413 * @attributes: an attribute query string
20414 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
20415 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20416 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20417 * @user_data: (closure): the data to pass to callback function
20419 * Asynchronously gets the requested information about the filesystem
20420 * that the specified @file is on. The result is a #GFileInfo object
20421 * that contains key-value attributes (such as type or size for the
20424 * For more details, see g_file_query_filesystem_info() which is the
20425 * synchronous version of this call.
20427 * When the operation is finished, @callback will be called. You can
20428 * then call g_file_query_info_finish() to get the result of the
20434 * g_file_query_filesystem_info_finish:
20435 * @file: input #GFile
20436 * @res: a #GAsyncResult
20437 * @error: a #GError
20439 * Finishes an asynchronous filesystem info query.
20440 * See g_file_query_filesystem_info_async().
20442 * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref().
20447 * g_file_query_info:
20448 * @file: input #GFile
20449 * @attributes: an attribute query string
20450 * @flags: a set of #GFileQueryInfoFlags
20451 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20452 * @error: a #GError
20454 * Gets the requested information about specified @file.
20455 * The result is a #GFileInfo object that contains key-value
20456 * attributes (such as the type or size of the file).
20458 * The @attributes value is a string that specifies the file
20459 * attributes that should be gathered. It is not an error if
20460 * it's not possible to read a particular requested attribute
20461 * from a file - it just won't be set. @attributes should be a
20462 * comma-separated list of attributes or attribute wildcards.
20463 * The wildcard "*" means all attributes, and a wildcard like
20464 * "standard::*" means all attributes in the standard namespace.
20465 * An example attribute query be "standard::*,owner::user".
20466 * The standard attributes are available as defines, like
20467 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
20469 * If @cancellable is not %NULL, then the operation can be cancelled
20470 * by triggering the cancellable object from another thread. If the
20471 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
20474 * For symlinks, normally the information about the target of the
20475 * symlink is returned, rather than information about the symlink
20476 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
20477 * in @flags the information about the symlink itself will be returned.
20478 * Also, for symlinks that point to non-existing files the information
20479 * about the symlink itself will be returned.
20481 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
20482 * returned. Other errors are possible too, and depend on what kind of
20483 * filesystem the file is on.
20485 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref().
20490 * g_file_query_info_async:
20491 * @file: input #GFile
20492 * @attributes: an attribute query string
20493 * @flags: a set of #GFileQueryInfoFlags
20494 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
20495 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20496 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20497 * @user_data: (closure): the data to pass to callback function
20499 * Asynchronously gets the requested information about specified @file.
20500 * The result is a #GFileInfo object that contains key-value attributes
20501 * (such as type or size for the file).
20503 * For more details, see g_file_query_info() which is the synchronous
20504 * version of this call.
20506 * When the operation is finished, @callback will be called. You can
20507 * then call g_file_query_info_finish() to get the result of the operation.
20512 * g_file_query_info_finish:
20513 * @file: input #GFile
20514 * @res: a #GAsyncResult
20515 * @error: a #GError
20517 * Finishes an asynchronous file info query.
20518 * See g_file_query_info_async().
20520 * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref().
20525 * g_file_query_settable_attributes:
20526 * @file: input #GFile
20527 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20528 * @error: a #GError, or %NULL
20530 * Obtain the list of settable attributes for the file.
20532 * Returns the type and full attribute name of all the attributes
20533 * that can be set on this file. This doesn't mean setting it will
20534 * always succeed though, you might get an access failure, or some
20535 * specific file may not support a specific attribute.
20537 * If @cancellable is not %NULL, then the operation can be cancelled by
20538 * triggering the cancellable object from another thread. If the operation
20539 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20541 * Returns: a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref()
20546 * g_file_query_writable_namespaces:
20547 * @file: input #GFile
20548 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20549 * @error: a #GError, or %NULL
20551 * Obtain the list of attribute namespaces where new attributes
20552 * can be created by a user. An example of this is extended
20553 * attributes (in the "xattr" namespace).
20555 * If @cancellable is not %NULL, then the operation can be cancelled by
20556 * triggering the cancellable object from another thread. If the operation
20557 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20559 * Returns: a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref()
20565 * @file: #GFile to read
20566 * @cancellable: (allow-none): a #GCancellable
20567 * @error: a #GError, or %NULL
20569 * Opens a file for reading. The result is a #GFileInputStream that
20570 * can be used to read the contents of the file.
20572 * If @cancellable is not %NULL, then the operation can be cancelled by
20573 * triggering the cancellable object from another thread. If the operation
20574 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20576 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
20577 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
20578 * error will be returned. Other errors are possible too, and depend
20579 * on what kind of filesystem the file is on.
20582 * Returns: (transfer full): #GFileInputStream or %NULL on error. Free the returned object with g_object_unref().
20587 * g_file_read_async:
20588 * @file: input #GFile
20589 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
20590 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20591 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20592 * @user_data: (closure): the data to pass to callback function
20594 * Asynchronously opens @file for reading.
20596 * For more details, see g_file_read() which is
20597 * the synchronous version of this call.
20599 * When the operation is finished, @callback will be called.
20600 * You can then call g_file_read_finish() to get the result
20601 * of the operation.
20606 * g_file_read_finish:
20607 * @file: input #GFile
20608 * @res: a #GAsyncResult
20609 * @error: a #GError, or %NULL
20611 * Finishes an asynchronous file read operation started with
20612 * g_file_read_async().
20614 * Returns: (transfer full): a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref().
20620 * @file: input #GFile
20621 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore
20622 * @make_backup: %TRUE if a backup should be created
20623 * @flags: a set of #GFileCreateFlags
20624 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20625 * @error: a #GError, or %NULL
20627 * Returns an output stream for overwriting the file, possibly
20628 * creating a backup copy of the file first. If the file doesn't exist,
20629 * it will be created.
20631 * This will try to replace the file in the safest way possible so
20632 * that any errors during the writing will not affect an already
20633 * existing copy of the file. For instance, for local files it
20634 * may write to a temporary file and then atomically rename over
20635 * the destination when the stream is closed.
20637 * By default files created are generally readable by everyone,
20638 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
20639 * will be made readable only to the current user, to the level that
20640 * is supported on the target filesystem.
20642 * If @cancellable is not %NULL, then the operation can be cancelled
20643 * by triggering the cancellable object from another thread. If the
20644 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
20647 * If you pass in a non-%NULL @etag value, then this value is
20648 * compared to the current entity tag of the file, and if they differ
20649 * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
20650 * that the file has been changed since you last read it. You can get
20651 * the new etag from g_file_output_stream_get_etag() after you've
20652 * finished writing and closed the #GFileOutputStream. When you load
20653 * a new file you can use g_file_input_stream_query_info() to get
20654 * the etag of the file.
20656 * If @make_backup is %TRUE, this function will attempt to make a
20657 * backup of the current file before overwriting it. If this fails
20658 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
20659 * want to replace anyway, try again with @make_backup set to %FALSE.
20661 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
20662 * be returned, and if the file is some other form of non-regular file
20663 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
20664 * file systems don't allow all file names, and may return an
20665 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
20666 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
20667 * possible too, and depend on what kind of filesystem the file is on.
20669 * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref().
20674 * g_file_replace_async:
20675 * @file: input #GFile
20676 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore
20677 * @make_backup: %TRUE if a backup should be created
20678 * @flags: a set of #GFileCreateFlags
20679 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
20680 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20681 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20682 * @user_data: (closure): the data to pass to callback function
20684 * Asynchronously overwrites the file, replacing the contents,
20685 * possibly creating a backup copy of the file first.
20687 * For more details, see g_file_replace() which is
20688 * the synchronous version of this call.
20690 * When the operation is finished, @callback will be called.
20691 * You can then call g_file_replace_finish() to get the result
20692 * of the operation.
20697 * g_file_replace_contents:
20698 * @file: input #GFile
20699 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
20700 * @length: the length of @contents in bytes
20701 * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL
20702 * @make_backup: %TRUE if a backup should be created
20703 * @flags: a set of #GFileCreateFlags
20704 * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when no longer needed, or %NULL
20705 * @cancellable: optional #GCancellable object, %NULL to ignore
20706 * @error: a #GError, or %NULL
20708 * Replaces the contents of @file with @contents of @length bytes.
20710 * If @etag is specified (not %NULL), any existing file must have that etag,
20711 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
20713 * If @make_backup is %TRUE, this function will attempt to make a backup
20716 * If @cancellable is not %NULL, then the operation can be cancelled by
20717 * triggering the cancellable object from another thread. If the operation
20718 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20720 * The returned @new_etag can be used to verify that the file hasn't
20721 * changed the next time it is saved over.
20723 * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
20728 * g_file_replace_contents_async:
20729 * @file: input #GFile
20730 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
20731 * @length: the length of @contents in bytes
20732 * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL
20733 * @make_backup: %TRUE if a backup should be created
20734 * @flags: a set of #GFileCreateFlags
20735 * @cancellable: optional #GCancellable object, %NULL to ignore
20736 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
20737 * @user_data: the data to pass to callback function
20739 * Starts an asynchronous replacement of @file with the given
20740 * @contents of @length bytes. @etag will replace the document's
20741 * current entity tag.
20743 * When this operation has completed, @callback will be called with
20744 * @user_user data, and the operation can be finalized with
20745 * g_file_replace_contents_finish().
20747 * If @cancellable is not %NULL, then the operation can be cancelled by
20748 * triggering the cancellable object from another thread. If the operation
20749 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20751 * If @make_backup is %TRUE, this function will attempt to
20752 * make a backup of @file.
20757 * g_file_replace_contents_finish:
20758 * @file: input #GFile
20759 * @res: a #GAsyncResult
20760 * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when it is no longer needed, or %NULL
20761 * @error: a #GError, or %NULL
20763 * Finishes an asynchronous replace of the given @file. See
20764 * g_file_replace_contents_async(). Sets @new_etag to the new entity
20765 * tag for the document, if present.
20767 * Returns: %TRUE on success, %FALSE on failure.
20772 * g_file_replace_finish:
20773 * @file: input #GFile
20774 * @res: a #GAsyncResult
20775 * @error: a #GError, or %NULL
20777 * Finishes an asynchronous file replace operation started with
20778 * g_file_replace_async().
20780 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref().
20785 * g_file_replace_readwrite:
20787 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore
20788 * @make_backup: %TRUE if a backup should be created
20789 * @flags: a set of #GFileCreateFlags
20790 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20791 * @error: return location for a #GError, or %NULL
20793 * Returns an output stream for overwriting the file in readwrite mode,
20794 * possibly creating a backup copy of the file first. If the file doesn't
20795 * exist, it will be created.
20797 * For details about the behaviour, see g_file_replace() which does the
20798 * same thing but returns an output stream only.
20800 * Note that in many non-local file cases read and write streams are not
20801 * supported, so make sure you really need to do read and write streaming,
20802 * rather than just opening for reading or writing.
20804 * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
20810 * g_file_replace_readwrite_async:
20811 * @file: input #GFile
20812 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore
20813 * @make_backup: %TRUE if a backup should be created
20814 * @flags: a set of #GFileCreateFlags
20815 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
20816 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20817 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
20818 * @user_data: (closure): the data to pass to callback function
20820 * Asynchronously overwrites the file in read-write mode,
20821 * replacing the contents, possibly creating a backup copy
20822 * of the file first.
20824 * For more details, see g_file_replace_readwrite() which is
20825 * the synchronous version of this call.
20827 * When the operation is finished, @callback will be called.
20828 * You can then call g_file_replace_readwrite_finish() to get
20829 * the result of the operation.
20836 * g_file_replace_readwrite_finish:
20837 * @file: input #GFile
20838 * @res: a #GAsyncResult
20839 * @error: a #GError, or %NULL
20841 * Finishes an asynchronous file replace operation started with
20842 * g_file_replace_readwrite_async().
20844 * Returns: (transfer full): a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref().
20850 * g_file_resolve_relative_path:
20851 * @file: input #GFile
20852 * @relative_path: a given relative path string
20854 * Resolves a relative path for @file to an absolute path.
20856 * This call does no blocking I/O.
20858 * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path is %NULL or if @file is invalid. Free the returned object with g_object_unref().
20863 * g_file_set_attribute:
20864 * @file: input #GFile
20865 * @attribute: a string containing the attribute's name
20866 * @type: The type of the attribute
20867 * @value_p: (allow-none): a pointer to the value (or the pointer itself if the type is a pointer type)
20868 * @flags: a set of #GFileQueryInfoFlags
20869 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20870 * @error: a #GError, or %NULL
20872 * Sets an attribute in the file with attribute name @attribute to @value.
20874 * Some attributes can be unset by setting @attribute to
20875 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
20877 * If @cancellable is not %NULL, then the operation can be cancelled by
20878 * triggering the cancellable object from another thread. If the operation
20879 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20881 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
20886 * g_file_set_attribute_byte_string:
20887 * @file: input #GFile
20888 * @attribute: a string containing the attribute's name
20889 * @value: a string containing the attribute's new value
20890 * @flags: a #GFileQueryInfoFlags
20891 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20892 * @error: a #GError, or %NULL
20894 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
20895 * If @attribute is of a different type, this operation will fail,
20896 * returning %FALSE.
20898 * If @cancellable is not %NULL, then the operation can be cancelled by
20899 * triggering the cancellable object from another thread. If the operation
20900 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20902 * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
20907 * g_file_set_attribute_int32:
20908 * @file: input #GFile
20909 * @attribute: a string containing the attribute's name
20910 * @value: a #gint32 containing the attribute's new value
20911 * @flags: a #GFileQueryInfoFlags
20912 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20913 * @error: a #GError, or %NULL
20915 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
20916 * If @attribute is of a different type, this operation will fail.
20918 * If @cancellable is not %NULL, then the operation can be cancelled by
20919 * triggering the cancellable object from another thread. If the operation
20920 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20922 * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
20927 * g_file_set_attribute_int64:
20928 * @file: input #GFile
20929 * @attribute: a string containing the attribute's name
20930 * @value: a #guint64 containing the attribute's new value
20931 * @flags: a #GFileQueryInfoFlags
20932 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20933 * @error: a #GError, or %NULL
20935 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
20936 * If @attribute is of a different type, this operation will fail.
20938 * If @cancellable is not %NULL, then the operation can be cancelled by
20939 * triggering the cancellable object from another thread. If the operation
20940 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20942 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
20947 * g_file_set_attribute_string:
20948 * @file: input #GFile
20949 * @attribute: a string containing the attribute's name
20950 * @value: a string containing the attribute's value
20951 * @flags: #GFileQueryInfoFlags
20952 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20953 * @error: a #GError, or %NULL
20955 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
20956 * If @attribute is of a different type, this operation will fail.
20958 * If @cancellable is not %NULL, then the operation can be cancelled by
20959 * triggering the cancellable object from another thread. If the operation
20960 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20962 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
20967 * g_file_set_attribute_uint32:
20968 * @file: input #GFile
20969 * @attribute: a string containing the attribute's name
20970 * @value: a #guint32 containing the attribute's new value
20971 * @flags: a #GFileQueryInfoFlags
20972 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20973 * @error: a #GError, or %NULL
20975 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
20976 * If @attribute is of a different type, this operation will fail.
20978 * If @cancellable is not %NULL, then the operation can be cancelled by
20979 * triggering the cancellable object from another thread. If the operation
20980 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20982 * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
20987 * g_file_set_attribute_uint64:
20988 * @file: input #GFile
20989 * @attribute: a string containing the attribute's name
20990 * @value: a #guint64 containing the attribute's new value
20991 * @flags: a #GFileQueryInfoFlags
20992 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
20993 * @error: a #GError, or %NULL
20995 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
20996 * If @attribute is of a different type, this operation will fail.
20998 * If @cancellable is not %NULL, then the operation can be cancelled by
20999 * triggering the cancellable object from another thread. If the operation
21000 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21002 * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
21007 * g_file_set_attributes_async:
21008 * @file: input #GFile
21009 * @info: a #GFileInfo
21010 * @flags: a #GFileQueryInfoFlags
21011 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
21012 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21013 * @callback: (scope async): a #GAsyncReadyCallback
21014 * @user_data: (closure): a #gpointer
21016 * Asynchronously sets the attributes of @file with @info.
21018 * For more details, see g_file_set_attributes_from_info(),
21019 * which is the synchronous version of this call.
21021 * When the operation is finished, @callback will be called.
21022 * You can then call g_file_set_attributes_finish() to get
21023 * the result of the operation.
21028 * g_file_set_attributes_finish:
21029 * @file: input #GFile
21030 * @result: a #GAsyncResult
21031 * @info: (out) (transfer full): a #GFileInfo
21032 * @error: a #GError, or %NULL
21034 * Finishes setting an attribute started in g_file_set_attributes_async().
21036 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
21041 * g_file_set_attributes_from_info:
21042 * @file: input #GFile
21043 * @info: a #GFileInfo
21044 * @flags: #GFileQueryInfoFlags
21045 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21046 * @error: a #GError, or %NULL
21048 * Tries to set all attributes in the #GFileInfo on the target
21049 * values, not stopping on the first error.
21051 * If there is any error during this operation then @error will
21052 * be set to the first error. Error on particular fields are flagged
21053 * by setting the "status" field in the attribute value to
21054 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
21055 * also detect further errors.
21057 * If @cancellable is not %NULL, then the operation can be cancelled by
21058 * triggering the cancellable object from another thread. If the operation
21059 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21061 * Returns: %TRUE if there was any error, %FALSE otherwise.
21066 * g_file_set_display_name:
21067 * @file: input #GFile
21068 * @display_name: a string
21069 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21070 * @error: a #GError, or %NULL
21072 * Renames @file to the specified display name.
21074 * The display name is converted from UTF-8 to the correct encoding
21075 * for the target filesystem if possible and the @file is renamed to this.
21077 * If you want to implement a rename operation in the user interface the
21078 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
21079 * initial value in the rename widget, and then the result after editing
21080 * should be passed to g_file_set_display_name().
21082 * On success the resulting converted filename is returned.
21084 * If @cancellable is not %NULL, then the operation can be cancelled by
21085 * triggering the cancellable object from another thread. If the operation
21086 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21088 * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref().
21093 * g_file_set_display_name_async:
21094 * @file: input #GFile
21095 * @display_name: a string
21096 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
21097 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21098 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
21099 * @user_data: (closure): the data to pass to callback function
21101 * Asynchronously sets the display name for a given #GFile.
21103 * For more details, see g_file_set_display_name() which is
21104 * the synchronous version of this call.
21106 * When the operation is finished, @callback will be called.
21107 * You can then call g_file_set_display_name_finish() to get
21108 * the result of the operation.
21113 * g_file_set_display_name_finish:
21114 * @file: input #GFile
21115 * @res: a #GAsyncResult
21116 * @error: a #GError, or %NULL
21118 * Finishes setting a display name started with
21119 * g_file_set_display_name_async().
21121 * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref().
21126 * g_file_start_mountable:
21127 * @file: input #GFile
21128 * @flags: flags affecting the operation
21129 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
21130 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21131 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
21132 * @user_data: the data to pass to callback function
21134 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
21135 * Using @start_operation, you can request callbacks when, for instance,
21136 * passwords are needed during authentication.
21138 * If @cancellable is not %NULL, then the operation can be cancelled by
21139 * triggering the cancellable object from another thread. If the operation
21140 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21142 * When the operation is finished, @callback will be called.
21143 * You can then call g_file_mount_mountable_finish() to get
21144 * the result of the operation.
21151 * g_file_start_mountable_finish:
21152 * @file: input #GFile
21153 * @result: a #GAsyncResult
21154 * @error: a #GError, or %NULL
21156 * Finishes a start operation. See g_file_start_mountable() for details.
21158 * Finish an asynchronous start operation that was started
21159 * with g_file_start_mountable().
21161 * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
21167 * g_file_stop_mountable:
21168 * @file: input #GFile
21169 * @flags: flags affecting the operation
21170 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
21171 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21172 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
21173 * @user_data: the data to pass to callback function
21175 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
21177 * If @cancellable is not %NULL, then the operation can be cancelled by
21178 * triggering the cancellable object from another thread. If the operation
21179 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21181 * When the operation is finished, @callback will be called.
21182 * You can then call g_file_stop_mountable_finish() to get
21183 * the result of the operation.
21190 * g_file_stop_mountable_finish:
21191 * @file: input #GFile
21192 * @result: a #GAsyncResult
21193 * @error: a #GError, or %NULL
21195 * Finishes an stop operation, see g_file_stop_mountable() for details.
21197 * Finish an asynchronous stop operation that was started
21198 * with g_file_stop_mountable().
21200 * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
21206 * g_file_supports_thread_contexts:
21209 * Checks if @file supports <link
21210 * linkend="g-main-context-push-thread-default-context">thread-default
21211 * contexts</link>. If this returns %FALSE, you cannot perform
21212 * asynchronous operations on @file in a thread that has a
21213 * thread-default context.
21215 * Returns: Whether or not @file supports thread-default contexts.
21222 * @file: #GFile to send to trash
21223 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21224 * @error: a #GError, or %NULL
21226 * Sends @file to the "Trashcan", if possible. This is similar to
21227 * deleting it, but the user can recover it before emptying the trashcan.
21228 * Not all file systems support trashing, so this call can return the
21229 * %G_IO_ERROR_NOT_SUPPORTED error.
21231 * If @cancellable is not %NULL, then the operation can be cancelled by
21232 * triggering the cancellable object from another thread. If the operation
21233 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21235 * Returns: %TRUE on successful trash, %FALSE otherwise.
21240 * g_file_unmount_mountable:
21241 * @file: input #GFile
21242 * @flags: flags affecting the operation
21243 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21244 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
21245 * @user_data: (closure): the data to pass to callback function
21247 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
21249 * If @cancellable is not %NULL, then the operation can be cancelled by
21250 * triggering the cancellable object from another thread. If the operation
21251 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21253 * When the operation is finished, @callback will be called.
21254 * You can then call g_file_unmount_mountable_finish() to get
21255 * the result of the operation.
21257 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
21262 * g_file_unmount_mountable_finish:
21263 * @file: input #GFile
21264 * @result: a #GAsyncResult
21265 * @error: a #GError, or %NULL
21267 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
21269 * Finish an asynchronous unmount operation that was started
21270 * with g_file_unmount_mountable().
21272 * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
21273 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead.
21278 * g_file_unmount_mountable_with_operation:
21279 * @file: input #GFile
21280 * @flags: flags affecting the operation
21281 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
21282 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
21283 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
21284 * @user_data: (closure): the data to pass to callback function
21286 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
21288 * If @cancellable is not %NULL, then the operation can be cancelled by
21289 * triggering the cancellable object from another thread. If the operation
21290 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21292 * When the operation is finished, @callback will be called.
21293 * You can then call g_file_unmount_mountable_finish() to get
21294 * the result of the operation.
21301 * g_file_unmount_mountable_with_operation_finish:
21302 * @file: input #GFile
21303 * @result: a #GAsyncResult
21304 * @error: a #GError, or %NULL
21306 * Finishes an unmount operation,
21307 * see g_file_unmount_mountable_with_operation() for details.
21309 * Finish an asynchronous unmount operation that was started
21310 * with g_file_unmount_mountable_with_operation().
21312 * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
21318 * g_filename_completer_get_completion_suffix:
21319 * @completer: the filename completer.
21320 * @initial_text: text to be completed.
21322 * Obtains a completion for @initial_text from @completer.
21324 * Returns: a completed string, or %NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished.
21329 * g_filename_completer_get_completions:
21330 * @completer: the filename completer.
21331 * @initial_text: text to be completed.
21333 * Gets an array of completion strings for a given initial text.
21335 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished.
21340 * g_filename_completer_new:
21342 * Creates a new filename completer.
21344 * Returns: a #GFilenameCompleter.
21349 * g_filename_completer_set_dirs_only:
21350 * @completer: the filename completer.
21351 * @dirs_only: a #gboolean.
21353 * If @dirs_only is %TRUE, @completer will only
21354 * complete directory names, and not file names.
21359 * g_filter_input_stream_get_base_stream:
21360 * @stream: a #GFilterInputStream.
21362 * Gets the base stream for the filter stream.
21364 * Returns: (transfer none): a #GInputStream.
21369 * g_filter_input_stream_get_close_base_stream:
21370 * @stream: a #GFilterInputStream.
21372 * Returns whether the base stream will be closed when @stream is
21375 * Returns: %TRUE if the base stream will be closed.
21380 * g_filter_input_stream_set_close_base_stream:
21381 * @stream: a #GFilterInputStream.
21382 * @close_base: %TRUE to close the base stream.
21384 * Sets whether the base stream will be closed when @stream is closed.
21389 * g_filter_output_stream_get_base_stream:
21390 * @stream: a #GFilterOutputStream.
21392 * Gets the base stream for the filter stream.
21394 * Returns: (transfer none): a #GOutputStream.
21399 * g_filter_output_stream_get_close_base_stream:
21400 * @stream: a #GFilterOutputStream.
21402 * Returns whether the base stream will be closed when @stream is
21405 * Returns: %TRUE if the base stream will be closed.
21410 * g_filter_output_stream_set_close_base_stream:
21411 * @stream: a #GFilterOutputStream.
21412 * @close_base: %TRUE to close the base stream.
21414 * Sets whether the base stream will be closed when @stream is closed.
21420 * @icon1: (allow-none): pointer to the first #GIcon.
21421 * @icon2: (allow-none): pointer to the second #GIcon.
21423 * Checks if two icons are equal.
21425 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
21431 * @icon: #gconstpointer to an icon object.
21433 * Gets a hash for an icon.
21436 * Returns: a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure.
21441 * g_icon_new_for_string:
21442 * @str: A string obtained via g_icon_to_string().
21443 * @error: Return location for error.
21445 * Generate a #GIcon instance from @str. This function can fail if
21446 * @str is not valid - see g_icon_to_string() for discussion.
21448 * If your application or library provides one or more #GIcon
21449 * implementations you need to ensure that each #GType is registered
21450 * with the type system prior to calling g_icon_new_for_string().
21452 * Returns: (transfer full): An object implementing the #GIcon interface or %NULL if @error is set.
21458 * g_icon_to_string:
21461 * Generates a textual representation of @icon that can be used for
21462 * serialization such as when passing @icon to a different process or
21463 * saving it to persistent storage. Use g_icon_new_for_string() to
21464 * get @icon back from the returned string.
21466 * The encoding of the returned string is proprietary to #GIcon except
21467 * in the following two cases
21471 * If @icon is a #GFileIcon, the returned string is a native path
21472 * (such as <literal>/path/to/my icon.png</literal>) without escaping
21473 * if the #GFile for @icon is a native file. If the file is not
21474 * native, the returned string is the result of g_file_get_uri()
21475 * (such as <literal>sftp://path/to/my%20icon.png</literal>).
21476 * </para></listitem>
21478 * If @icon is a #GThemedIcon with exactly one name, the encoding is
21479 * simply the name (such as <literal>network-server</literal>).
21480 * </para></listitem>
21483 * Virtual: to_tokens
21484 * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free.
21490 * g_inet_address_equal:
21491 * @address: A #GInetAddress.
21492 * @other_address: Another #GInetAddress.
21494 * Checks if two #GInetAddress instances are equal, e.g. the same address.
21496 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
21502 * g_inet_address_get_family:
21503 * @address: a #GInetAddress
21505 * Gets @address's family
21507 * Returns: @address's family
21513 * g_inet_address_get_is_any:
21514 * @address: a #GInetAddress
21516 * Tests whether @address is the "any" address for its family.
21518 * Returns: %TRUE if @address is the "any" address for its family.
21524 * g_inet_address_get_is_link_local:
21525 * @address: a #GInetAddress
21527 * Tests whether @address is a link-local address (that is, if it
21528 * identifies a host on a local network that is not connected to the
21531 * Returns: %TRUE if @address is a link-local address.
21537 * g_inet_address_get_is_loopback:
21538 * @address: a #GInetAddress
21540 * Tests whether @address is the loopback address for its family.
21542 * Returns: %TRUE if @address is the loopback address for its family.
21548 * g_inet_address_get_is_mc_global:
21549 * @address: a #GInetAddress
21551 * Tests whether @address is a global multicast address.
21553 * Returns: %TRUE if @address is a global multicast address.
21559 * g_inet_address_get_is_mc_link_local:
21560 * @address: a #GInetAddress
21562 * Tests whether @address is a link-local multicast address.
21564 * Returns: %TRUE if @address is a link-local multicast address.
21570 * g_inet_address_get_is_mc_node_local:
21571 * @address: a #GInetAddress
21573 * Tests whether @address is a node-local multicast address.
21575 * Returns: %TRUE if @address is a node-local multicast address.
21581 * g_inet_address_get_is_mc_org_local:
21582 * @address: a #GInetAddress
21584 * Tests whether @address is an organization-local multicast address.
21586 * Returns: %TRUE if @address is an organization-local multicast address.
21592 * g_inet_address_get_is_mc_site_local:
21593 * @address: a #GInetAddress
21595 * Tests whether @address is a site-local multicast address.
21597 * Returns: %TRUE if @address is a site-local multicast address.
21603 * g_inet_address_get_is_multicast:
21604 * @address: a #GInetAddress
21606 * Tests whether @address is a multicast address.
21608 * Returns: %TRUE if @address is a multicast address.
21614 * g_inet_address_get_is_site_local:
21615 * @address: a #GInetAddress
21617 * Tests whether @address is a site-local address such as 10.0.0.1
21618 * (that is, the address identifies a host on a local network that can
21619 * not be reached directly from the Internet, but which may have
21620 * outgoing Internet connectivity via a NAT or firewall).
21622 * Returns: %TRUE if @address is a site-local address.
21628 * g_inet_address_get_native_size:
21629 * @address: a #GInetAddress
21631 * Gets the size of the native raw binary address for @address. This
21632 * is the size of the data that you get from g_inet_address_to_bytes().
21634 * Returns: the number of bytes used for the native version of @address.
21640 * g_inet_address_mask_equal:
21641 * @mask: a #GInetAddressMask
21642 * @mask2: another #GInetAddressMask
21644 * Tests if @mask and @mask2 are the same mask.
21646 * Returns: whether @mask and @mask2 are the same mask
21652 * g_inet_address_mask_get_address:
21653 * @mask: a #GInetAddressMask
21655 * Gets @mask's base address
21657 * Returns: (transfer none): @mask's base address
21663 * g_inet_address_mask_get_family:
21664 * @mask: a #GInetAddressMask
21666 * Gets the #GSocketFamily of @mask's address
21668 * Returns: the #GSocketFamily of @mask's address
21674 * g_inet_address_mask_get_length:
21675 * @mask: a #GInetAddressMask
21677 * Gets @mask's length
21679 * Returns: @mask's length
21685 * g_inet_address_mask_matches:
21686 * @mask: a #GInetAddressMask
21687 * @address: a #GInetAddress
21689 * Tests if @address falls within the range described by @mask.
21691 * Returns: whether @address falls within the range described by @mask.
21697 * g_inet_address_mask_new:
21698 * @addr: a #GInetAddress
21699 * @length: number of bits of @addr to use
21700 * @error: return location for #GError, or %NULL
21702 * Creates a new #GInetAddressMask representing all addresses whose
21703 * first @length bits match @addr.
21705 * Returns: a new #GInetAddressMask, or %NULL on error
21711 * g_inet_address_mask_new_from_string:
21712 * @mask_string: an IP address or address/length string
21713 * @error: return location for #GError, or %NULL
21715 * Parses @mask_string as an IP address and (optional) length, and
21716 * creates a new #GInetAddressMask. The length, if present, is
21717 * delimited by a "/". If it is not present, then the length is
21718 * assumed to be the full length of the address.
21720 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL on error.
21726 * g_inet_address_mask_to_string:
21727 * @mask: a #GInetAddressMask
21729 * Converts @mask back to its corresponding string form.
21731 * Returns: a string corresponding to @mask.
21737 * g_inet_address_new_any:
21738 * @family: the address family
21740 * Creates a #GInetAddress for the "any" address (unassigned/"don't
21741 * care") for @family.
21743 * Returns: a new #GInetAddress corresponding to the "any" address for @family.
21749 * g_inet_address_new_from_bytes:
21750 * @bytes: (array) (element-type guint8): raw address data
21751 * @family: the address family of @bytes
21753 * Creates a new #GInetAddress from the given @family and @bytes.
21754 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
21755 * %G_SOCKET_FAMILY_IPV6.
21757 * Returns: a new #GInetAddress corresponding to @family and @bytes.
21763 * g_inet_address_new_from_string:
21764 * @string: a string representation of an IP address
21766 * Parses @string as an IP address and creates a new #GInetAddress.
21768 * Returns: a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed.
21774 * g_inet_address_new_loopback:
21775 * @family: the address family
21777 * Creates a #GInetAddress for the loopback address for @family.
21779 * Returns: a new #GInetAddress corresponding to the loopback address for @family.
21785 * g_inet_address_to_bytes: (skip)
21786 * @address: a #GInetAddress
21788 * Gets the raw binary address data from @address.
21790 * Returns: a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size().
21796 * g_inet_address_to_string:
21797 * @address: a #GInetAddress
21799 * Converts @address to string form.
21801 * Returns: a representation of @address as a string, which should be freed after use.
21807 * g_inet_socket_address_get_address:
21808 * @address: a #GInetSocketAddress
21810 * Gets @address's #GInetAddress.
21812 * Returns: (transfer none): the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored
21818 * g_inet_socket_address_get_flowinfo:
21819 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
21821 * Gets the <literal>sin6_flowinfo</literal> field from @address,
21822 * which must be an IPv6 address.
21824 * Returns: the flowinfo field
21830 * g_inet_socket_address_get_port:
21831 * @address: a #GInetSocketAddress
21833 * Gets @address's port.
21835 * Returns: the port for @address
21841 * g_inet_socket_address_get_scope_id:
21842 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
21844 * Gets the <literal>sin6_scope_id</literal> field from @address,
21845 * which must be an IPv6 address.
21847 * Returns: the scope id field
21853 * g_inet_socket_address_new:
21854 * @address: a #GInetAddress
21855 * @port: a port number
21857 * Creates a new #GInetSocketAddress for @address and @port.
21859 * Returns: a new #GInetSocketAddress
21866 * @initable: a #GInitable.
21867 * @cancellable: optional #GCancellable object, %NULL to ignore.
21868 * @error: a #GError location to store the error occurring, or %NULL to ignore.
21870 * Initializes the object implementing the interface.
21872 * The object must be initialized before any real use after initial
21873 * construction, either with this function or g_async_initable_init_async().
21875 * Implementations may also support cancellation. If @cancellable is not %NULL,
21876 * then initialization can be cancelled by triggering the cancellable object
21877 * from another thread. If the operation was cancelled, the error
21878 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
21879 * the object doesn't support cancellable initialization the error
21880 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
21882 * If the object is not initialized, or initialization returns with an
21883 * error, then all operations on the object except g_object_ref() and
21884 * g_object_unref() are considered to be invalid, and have undefined
21885 * behaviour. See the <xref linkend="ginitable"/> section introduction
21886 * for more details.
21888 * Implementations of this method must be idempotent, i.e. multiple calls
21889 * to this function with the same argument should return the same results.
21890 * Only the first call initializes the object, further calls return the result
21891 * of the first call. This is so that it's safe to implement the singleton
21892 * pattern in the GObject constructor function.
21894 * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
21901 * @object_type: a #GType supporting #GInitable.
21902 * @cancellable: optional #GCancellable object, %NULL to ignore.
21903 * @error: a #GError location to store the error occurring, or %NULL to ignore.
21904 * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties
21905 * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL.
21907 * Helper function for constructing #GInitable object. This is
21908 * similar to g_object_new() but also initializes the object
21909 * and returns %NULL, setting an error on failure.
21911 * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
21917 * g_initable_new_valist:
21918 * @object_type: a #GType supporting #GInitable.
21919 * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL.
21920 * @var_args: The var args list generated from @first_property_name.
21921 * @cancellable: optional #GCancellable object, %NULL to ignore.
21922 * @error: a #GError location to store the error occurring, or %NULL to ignore.
21924 * Helper function for constructing #GInitable object. This is
21925 * similar to g_object_new_valist() but also initializes the object
21926 * and returns %NULL, setting an error on failure.
21928 * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
21935 * @object_type: a #GType supporting #GInitable.
21936 * @n_parameters: the number of parameters in @parameters
21937 * @parameters: (array length=n_parameters): the parameters to use to construct the object
21938 * @cancellable: optional #GCancellable object, %NULL to ignore.
21939 * @error: a #GError location to store the error occurring, or %NULL to ignore.
21941 * Helper function for constructing #GInitable object. This is
21942 * similar to g_object_newv() but also initializes the object
21943 * and returns %NULL, setting an error on failure.
21945 * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
21951 * g_input_stream_clear_pending:
21952 * @stream: input stream
21954 * Clears the pending flag on @stream.
21959 * g_input_stream_close:
21960 * @stream: A #GInputStream.
21961 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21962 * @error: location to store the error occurring, or %NULL to ignore
21964 * Closes the stream, releasing resources related to it.
21966 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
21967 * Closing a stream multiple times will not return an error.
21969 * Streams will be automatically closed when the last reference
21970 * is dropped, but you might want to call this function to make sure
21971 * resources are released as early as possible.
21973 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
21974 * open after the stream is closed. See the documentation for the individual
21975 * stream for details.
21977 * On failure the first error that happened will be reported, but the close
21978 * operation will finish as much as possible. A stream that failed to
21979 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
21980 * is important to check and report the error to the user.
21982 * If @cancellable is not %NULL, then the operation can be cancelled by
21983 * triggering the cancellable object from another thread. If the operation
21984 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21985 * Cancelling a close will still leave the stream closed, but some streams
21986 * can use a faster close that doesn't block to e.g. check errors.
21988 * Returns: %TRUE on success, %FALSE on failure
21993 * g_input_stream_close_async:
21994 * @stream: A #GInputStream.
21995 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
21996 * @cancellable: (allow-none): optional cancellable object
21997 * @callback: (scope async): callback to call when the request is satisfied
21998 * @user_data: (closure): the data to pass to callback function
22000 * Requests an asynchronous closes of the stream, releasing resources related to it.
22001 * When the operation is finished @callback will be called.
22002 * You can then call g_input_stream_close_finish() to get the result of the
22005 * For behaviour details see g_input_stream_close().
22007 * The asyncronous methods have a default fallback that uses threads to implement
22008 * asynchronicity, so they are optional for inheriting classes. However, if you
22009 * override one you must override all.
22014 * g_input_stream_close_finish:
22015 * @stream: a #GInputStream.
22016 * @result: a #GAsyncResult.
22017 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22019 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
22021 * Returns: %TRUE if the stream was closed successfully.
22026 * g_input_stream_has_pending:
22027 * @stream: input stream.
22029 * Checks if an input stream has pending actions.
22031 * Returns: %TRUE if @stream has pending actions.
22036 * g_input_stream_is_closed:
22037 * @stream: input stream.
22039 * Checks if an input stream is closed.
22041 * Returns: %TRUE if the stream is closed.
22046 * g_input_stream_read:
22047 * @stream: a #GInputStream.
22048 * @buffer: a buffer to read data into (which should be at least count bytes long).
22049 * @count: the number of bytes that will be read from the stream
22050 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22051 * @error: location to store the error occurring, or %NULL to ignore
22053 * Tries to read @count bytes from the stream into the buffer starting at
22054 * @buffer. Will block during this read.
22056 * If count is zero returns zero and does nothing. A value of @count
22057 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
22059 * On success, the number of bytes read into the buffer is returned.
22060 * It is not an error if this is not the same as the requested size, as it
22061 * can happen e.g. near the end of a file. Zero is returned on end of file
22062 * (or if @count is zero), but never otherwise.
22064 * If @cancellable is not %NULL, then the operation can be cancelled by
22065 * triggering the cancellable object from another thread. If the operation
22066 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
22067 * operation was partially finished when the operation was cancelled the
22068 * partial result will be returned, without an error.
22070 * On error -1 is returned and @error is set accordingly.
22072 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
22077 * g_input_stream_read_all:
22078 * @stream: a #GInputStream.
22079 * @buffer: a buffer to read data into (which should be at least count bytes long).
22080 * @count: the number of bytes that will be read from the stream
22081 * @bytes_read: (out): location to store the number of bytes that was read from the stream
22082 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22083 * @error: location to store the error occurring, or %NULL to ignore
22085 * Tries to read @count bytes from the stream into the buffer starting at
22086 * @buffer. Will block during this read.
22088 * This function is similar to g_input_stream_read(), except it tries to
22089 * read as many bytes as requested, only stopping on an error or end of stream.
22091 * On a successful read of @count bytes, or if we reached the end of the
22092 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
22093 * read into @buffer.
22095 * If there is an error during the operation %FALSE is returned and @error
22096 * is set to indicate the error status, @bytes_read is updated to contain
22097 * the number of bytes read into @buffer before the error occurred.
22099 * Returns: %TRUE on success, %FALSE if there was an error
22104 * g_input_stream_read_async:
22105 * @stream: A #GInputStream.
22106 * @buffer: a buffer to read data into (which should be at least count bytes long).
22107 * @count: the number of bytes that will be read from the stream
22108 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
22109 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22110 * @callback: (scope async): callback to call when the request is satisfied
22111 * @user_data: (closure): the data to pass to callback function
22113 * Request an asynchronous read of @count bytes from the stream into the buffer
22114 * starting at @buffer. When the operation is finished @callback will be called.
22115 * You can then call g_input_stream_read_finish() to get the result of the
22118 * During an async request no other sync and async calls are allowed on @stream, and will
22119 * result in %G_IO_ERROR_PENDING errors.
22121 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
22123 * On success, the number of bytes read into the buffer will be passed to the
22124 * callback. It is not an error if this is not the same as the requested size, as it
22125 * can happen e.g. near the end of a file, but generally we try to read
22126 * as many bytes as requested. Zero is returned on end of file
22127 * (or if @count is zero), but never otherwise.
22129 * Any outstanding i/o request with higher priority (lower numerical value) will
22130 * be executed before an outstanding request with lower priority. Default
22131 * priority is %G_PRIORITY_DEFAULT.
22133 * The asyncronous methods have a default fallback that uses threads to implement
22134 * asynchronicity, so they are optional for inheriting classes. However, if you
22135 * override one you must override all.
22140 * g_input_stream_read_bytes:
22141 * @stream: a #GInputStream.
22142 * @count: maximum number of bytes that will be read from the stream. Common values include 4096 and 8192.
22143 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22144 * @error: location to store the error occurring, or %NULL to ignore
22146 * Like g_input_stream_read(), this tries to read @count bytes from
22147 * the stream in a blocking fashion. However, rather than reading into
22148 * a user-supplied buffer, this will create a new #GBytes containing
22149 * the data that was read. This may be easier to use from language
22152 * If count is zero, returns a zero-length #GBytes and does nothing. A
22153 * value of @count larger than %G_MAXSSIZE will cause a
22154 * %G_IO_ERROR_INVALID_ARGUMENT error.
22156 * On success, a new #GBytes is returned. It is not an error if the
22157 * size of this object is not the same as the requested size, as it
22158 * can happen e.g. near the end of a file. A zero-length #GBytes is
22159 * returned on end of file (or if @count is zero), but never
22162 * If @cancellable is not %NULL, then the operation can be cancelled by
22163 * triggering the cancellable object from another thread. If the operation
22164 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
22165 * operation was partially finished when the operation was cancelled the
22166 * partial result will be returned, without an error.
22168 * On error %NULL is returned and @error is set accordingly.
22170 * Returns: a new #GBytes, or %NULL on error
22175 * g_input_stream_read_bytes_async:
22176 * @stream: A #GInputStream.
22177 * @count: the number of bytes that will be read from the stream
22178 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
22179 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22180 * @callback: (scope async): callback to call when the request is satisfied
22181 * @user_data: (closure): the data to pass to callback function
22183 * Request an asynchronous read of @count bytes from the stream into a
22184 * new #GBytes. When the operation is finished @callback will be
22185 * called. You can then call g_input_stream_read_bytes_finish() to get the
22186 * result of the operation.
22188 * During an async request no other sync and async calls are allowed
22189 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
22191 * A value of @count larger than %G_MAXSSIZE will cause a
22192 * %G_IO_ERROR_INVALID_ARGUMENT error.
22194 * On success, the new #GBytes will be passed to the callback. It is
22195 * not an error if this is smaller than the requested size, as it can
22196 * happen e.g. near the end of a file, but generally we try to read as
22197 * many bytes as requested. Zero is returned on end of file (or if
22198 * @count is zero), but never otherwise.
22200 * Any outstanding I/O request with higher priority (lower numerical
22201 * value) will be executed before an outstanding request with lower
22202 * priority. Default priority is %G_PRIORITY_DEFAULT.
22207 * g_input_stream_read_bytes_finish:
22208 * @stream: a #GInputStream.
22209 * @result: a #GAsyncResult.
22210 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22212 * Finishes an asynchronous stream read-into-#GBytes operation.
22214 * Returns: the newly-allocated #GBytes, or %NULL on error
22219 * g_input_stream_read_finish:
22220 * @stream: a #GInputStream.
22221 * @result: a #GAsyncResult.
22222 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22224 * Finishes an asynchronous stream read operation.
22226 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
22231 * g_input_stream_set_pending:
22232 * @stream: input stream
22233 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22235 * Sets @stream to have actions pending. If the pending flag is
22236 * already set or @stream is closed, it will return %FALSE and set
22239 * Returns: %TRUE if pending was previously unset and is now set.
22244 * g_input_stream_skip:
22245 * @stream: a #GInputStream.
22246 * @count: the number of bytes that will be skipped from the stream
22247 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22248 * @error: location to store the error occurring, or %NULL to ignore
22250 * Tries to skip @count bytes from the stream. Will block during the operation.
22252 * This is identical to g_input_stream_read(), from a behaviour standpoint,
22253 * but the bytes that are skipped are not returned to the user. Some
22254 * streams have an implementation that is more efficient than reading the data.
22256 * This function is optional for inherited classes, as the default implementation
22257 * emulates it using read.
22259 * If @cancellable is not %NULL, then the operation can be cancelled by
22260 * triggering the cancellable object from another thread. If the operation
22261 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
22262 * operation was partially finished when the operation was cancelled the
22263 * partial result will be returned, without an error.
22265 * Returns: Number of bytes skipped, or -1 on error
22270 * g_input_stream_skip_async:
22271 * @stream: A #GInputStream.
22272 * @count: the number of bytes that will be skipped from the stream
22273 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
22274 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22275 * @callback: (scope async): callback to call when the request is satisfied
22276 * @user_data: (closure): the data to pass to callback function
22278 * Request an asynchronous skip of @count bytes from the stream.
22279 * When the operation is finished @callback will be called.
22280 * You can then call g_input_stream_skip_finish() to get the result
22281 * of the operation.
22283 * During an async request no other sync and async calls are allowed,
22284 * and will result in %G_IO_ERROR_PENDING errors.
22286 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
22288 * On success, the number of bytes skipped will be passed to the callback.
22289 * It is not an error if this is not the same as the requested size, as it
22290 * can happen e.g. near the end of a file, but generally we try to skip
22291 * as many bytes as requested. Zero is returned on end of file
22292 * (or if @count is zero), but never otherwise.
22294 * Any outstanding i/o request with higher priority (lower numerical value)
22295 * will be executed before an outstanding request with lower priority.
22296 * Default priority is %G_PRIORITY_DEFAULT.
22298 * The asynchronous methods have a default fallback that uses threads to
22299 * implement asynchronicity, so they are optional for inheriting classes.
22300 * However, if you override one, you must override all.
22305 * g_input_stream_skip_finish:
22306 * @stream: a #GInputStream.
22307 * @result: a #GAsyncResult.
22308 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22310 * Finishes a stream skip operation.
22312 * Returns: the size of the bytes skipped, or %-1 on error.
22317 * g_io_error_from_errno:
22318 * @err_no: Error number as defined in errno.h.
22320 * Converts errno.h error codes into GIO error codes.
22322 * Returns: #GIOErrorEnum value for the given errno.h error number.
22327 * g_io_error_from_win32_error:
22328 * @error_code: Windows error number.
22330 * Converts some common error codes into GIO error codes. The
22331 * fallback value G_IO_ERROR_FAILED is returned for error codes not
22334 * Returns: #GIOErrorEnum value for the given error number.
22340 * g_io_error_quark:
22342 * Gets the GIO Error Quark.
22344 * Returns: a #GQuark.
22349 * g_io_extension_get_name:
22350 * @extension: a #GIOExtension
22352 * Gets the name under which @extension was registered.
22354 * Note that the same type may be registered as extension
22355 * for multiple extension points, under different names.
22357 * Returns: the name of @extension.
22362 * g_io_extension_get_priority:
22363 * @extension: a #GIOExtension
22365 * Gets the priority with which @extension was registered.
22367 * Returns: the priority of @extension
22372 * g_io_extension_get_type:
22373 * @extension: a #GIOExtension
22375 * Gets the type associated with @extension.
22377 * Returns: the type of @extension
22382 * g_io_extension_point_get_extension_by_name:
22383 * @extension_point: a #GIOExtensionPoint
22384 * @name: the name of the extension to get
22386 * Finds a #GIOExtension for an extension point by name.
22388 * Returns: (transfer none): the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name
22393 * g_io_extension_point_get_extensions:
22394 * @extension_point: a #GIOExtensionPoint
22396 * Gets a list of all extensions that implement this extension point.
22397 * The list is sorted by priority, beginning with the highest priority.
22399 * Returns: (element-type GIOExtension) (transfer none): a #GList of #GIOExtension<!-- -->s. The list is owned by GIO and should not be modified.
22404 * g_io_extension_point_get_required_type:
22405 * @extension_point: a #GIOExtensionPoint
22407 * Gets the required type for @extension_point.
22409 * Returns: the #GType that all implementations must have, or #G_TYPE_INVALID if the extension point has no required type
22414 * g_io_extension_point_implement:
22415 * @extension_point_name: the name of the extension point
22416 * @type: the #GType to register as extension
22417 * @extension_name: the name for the extension
22418 * @priority: the priority for the extension
22420 * Registers @type as extension for the extension point with name
22421 * @extension_point_name.
22423 * If @type has already been registered as an extension for this
22424 * extension point, the existing #GIOExtension object is returned.
22426 * Returns: (transfer none): a #GIOExtension object for #GType
22431 * g_io_extension_point_lookup:
22432 * @name: the name of the extension point
22434 * Looks up an existing extension point.
22436 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name.
22441 * g_io_extension_point_register:
22442 * @name: The name of the extension point
22444 * Registers an extension point.
22446 * Returns: (transfer none): the new #GIOExtensionPoint. This object is owned by GIO and should not be freed.
22451 * g_io_extension_point_set_required_type:
22452 * @extension_point: a #GIOExtensionPoint
22453 * @type: the #GType to require
22455 * Sets the required type for @extension_point to @type.
22456 * All implementations must henceforth have this type.
22461 * g_io_extension_ref_class:
22462 * @extension: a #GIOExtension
22464 * Gets a reference to the class for the type that is
22465 * associated with @extension.
22467 * Returns: (transfer full): the #GTypeClass for the type of @extension
22473 * @filename: filename of the shared library module.
22475 * Creates a new GIOModule that will load the specific
22476 * shared library when in use.
22478 * Returns: a #GIOModule from given @filename, or %NULL on error.
22483 * g_io_module_scope_block:
22484 * @scope: a module loading scope
22485 * @basename: the basename to block
22487 * Block modules with the given @basename from being loaded when
22488 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
22489 * or g_io_modules_load_all_in_directory_with_scope().
22496 * g_io_module_scope_free:
22497 * @scope: a module loading scope
22499 * Free a module scope.
22506 * g_io_module_scope_new:
22507 * @flags: flags for the new scope
22509 * Create a new scope for loading of IO modules. A scope can be used for
22510 * blocking duplicate modules, or blocking a module you don't want to load.
22512 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
22513 * which have the same base name as a module that has already been seen
22516 * Returns: (transfer full): the new module scope
22522 * g_io_modules_load_all_in_directory:
22523 * @dirname: pathname for a directory containing modules to load.
22525 * Loads all the modules in the specified directory.
22527 * If don't require all modules to be initialized (and thus registering
22528 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
22529 * which allows delayed/lazy loading of modules.
22531 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free().
22536 * g_io_modules_load_all_in_directory_with_scope:
22537 * @dirname: pathname for a directory containing modules to load.
22538 * @scope: a scope to use when scanning the modules.
22540 * Loads all the modules in the specified directory.
22542 * If don't require all modules to be initialized (and thus registering
22543 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
22544 * which allows delayed/lazy loading of modules.
22546 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free().
22552 * g_io_modules_scan_all_in_directory:
22553 * @dirname: pathname for a directory containing modules to scan.
22555 * Scans all the modules in the specified directory, ensuring that
22556 * any extension point implemented by a module is registered.
22558 * This may not actually load and initialize all the types in each
22559 * module, some modules may be lazily loaded and initialized when
22560 * an extension point it implementes is used with e.g.
22561 * g_io_extension_point_get_extensions() or
22562 * g_io_extension_point_get_extension_by_name().
22564 * If you need to guarantee that all types are loaded in all the modules,
22565 * use g_io_modules_load_all_in_directory().
22572 * g_io_modules_scan_all_in_directory_with_scope:
22573 * @dirname: pathname for a directory containing modules to scan.
22574 * @scope: a scope to use when scanning the modules
22576 * Scans all the modules in the specified directory, ensuring that
22577 * any extension point implemented by a module is registered.
22579 * This may not actually load and initialize all the types in each
22580 * module, some modules may be lazily loaded and initialized when
22581 * an extension point it implementes is used with e.g.
22582 * g_io_extension_point_get_extensions() or
22583 * g_io_extension_point_get_extension_by_name().
22585 * If you need to guarantee that all types are loaded in all the modules,
22586 * use g_io_modules_load_all_in_directory().
22593 * g_io_scheduler_cancel_all_jobs:
22595 * Cancels all cancellable I/O jobs.
22597 * A job is cancellable if a #GCancellable was passed into
22598 * g_io_scheduler_push_job().
22600 * Deprecated: You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler.
22605 * g_io_scheduler_job_send_to_mainloop:
22606 * @job: a #GIOSchedulerJob
22607 * @func: a #GSourceFunc callback that will be called in the original thread
22608 * @user_data: data to pass to @func
22609 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
22611 * Used from an I/O job to send a callback to be run in the thread
22612 * that the job was started from, waiting for the result (and thus
22613 * blocking the I/O job).
22615 * Returns: The return value of @func
22616 * Deprecated: Use g_main_context_invoke().
22621 * g_io_scheduler_job_send_to_mainloop_async:
22622 * @job: a #GIOSchedulerJob
22623 * @func: a #GSourceFunc callback that will be called in the original thread
22624 * @user_data: data to pass to @func
22625 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
22627 * Used from an I/O job to send a callback to be run asynchronously in
22628 * the thread that the job was started from. The callback will be run
22629 * when the main loop is available, but at that time the I/O job might
22630 * have finished. The return value from the callback is ignored.
22632 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
22633 * on to this function you have to ensure that it is not freed before
22634 * @func is called, either by passing %NULL as @notify to
22635 * g_io_scheduler_push_job() or by using refcounting for @user_data.
22637 * Deprecated: Use g_main_context_invoke().
22642 * g_io_scheduler_push_job:
22643 * @job_func: a #GIOSchedulerJobFunc.
22644 * @user_data: data to pass to @job_func
22645 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
22646 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
22647 * @cancellable: optional #GCancellable object, %NULL to ignore.
22649 * Schedules the I/O job to run in another thread.
22651 * @notify will be called on @user_data after @job_func has returned,
22652 * regardless whether the job was cancelled or has run to completion.
22654 * If @cancellable is not %NULL, it can be used to cancel the I/O job
22655 * by calling g_cancellable_cancel() or by calling
22656 * g_io_scheduler_cancel_all_jobs().
22658 * Deprecated: use #GThreadPool or g_task_run_in_thread()
22663 * g_io_stream_clear_pending:
22664 * @stream: a #GIOStream
22666 * Clears the pending flag on @stream.
22673 * g_io_stream_close:
22674 * @stream: a #GIOStream
22675 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
22676 * @error: location to store the error occurring, or %NULL to ignore
22678 * Closes the stream, releasing resources related to it. This will also
22679 * closes the individual input and output streams, if they are not already
22682 * Once the stream is closed, all other operations will return
22683 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
22686 * Closing a stream will automatically flush any outstanding buffers
22689 * Streams will be automatically closed when the last reference
22690 * is dropped, but you might want to call this function to make sure
22691 * resources are released as early as possible.
22693 * Some streams might keep the backing store of the stream (e.g. a file
22694 * descriptor) open after the stream is closed. See the documentation for
22695 * the individual stream for details.
22697 * On failure the first error that happened will be reported, but the
22698 * close operation will finish as much as possible. A stream that failed
22699 * to close will still return %G_IO_ERROR_CLOSED for all operations.
22700 * Still, it is important to check and report the error to the user,
22701 * otherwise there might be a loss of data as all data might not be written.
22703 * If @cancellable is not NULL, then the operation can be cancelled by
22704 * triggering the cancellable object from another thread. If the operation
22705 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22706 * Cancelling a close will still leave the stream closed, but some streams
22707 * can use a faster close that doesn't block to e.g. check errors.
22709 * The default implementation of this method just calls close on the
22710 * individual input/output streams.
22712 * Returns: %TRUE on success, %FALSE on failure
22718 * g_io_stream_close_async:
22719 * @stream: a #GIOStream
22720 * @io_priority: the io priority of the request
22721 * @cancellable: (allow-none): optional cancellable object
22722 * @callback: (scope async): callback to call when the request is satisfied
22723 * @user_data: (closure): the data to pass to callback function
22725 * Requests an asynchronous close of the stream, releasing resources
22726 * related to it. When the operation is finished @callback will be
22727 * called. You can then call g_io_stream_close_finish() to get
22728 * the result of the operation.
22730 * For behaviour details see g_io_stream_close().
22732 * The asynchronous methods have a default fallback that uses threads
22733 * to implement asynchronicity, so they are optional for inheriting
22734 * classes. However, if you override one you must override all.
22741 * g_io_stream_close_finish:
22742 * @stream: a #GIOStream
22743 * @result: a #GAsyncResult
22744 * @error: a #GError location to store the error occurring, or %NULL to ignore
22748 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
22754 * g_io_stream_get_input_stream:
22755 * @stream: a #GIOStream
22757 * Gets the input stream for this object. This is used
22760 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. Do not free.
22766 * g_io_stream_get_output_stream:
22767 * @stream: a #GIOStream
22769 * Gets the output stream for this object. This is used for
22772 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. Do not free.
22778 * g_io_stream_has_pending:
22779 * @stream: a #GIOStream
22781 * Checks if a stream has pending actions.
22783 * Returns: %TRUE if @stream has pending actions.
22789 * g_io_stream_is_closed:
22790 * @stream: a #GIOStream
22792 * Checks if a stream is closed.
22794 * Returns: %TRUE if the stream is closed.
22800 * g_io_stream_set_pending:
22801 * @stream: a #GIOStream
22802 * @error: a #GError location to store the error occurring, or %NULL to ignore
22804 * Sets @stream to have actions pending. If the pending flag is
22805 * already set or @stream is closed, it will return %FALSE and set
22808 * Returns: %TRUE if pending was previously unset and is now set.
22814 * g_io_stream_splice_async:
22815 * @stream1: a #GIOStream.
22816 * @stream2: a #GIOStream.
22817 * @flags: a set of #GIOStreamSpliceFlags.
22818 * @io_priority: the io priority of the request.
22819 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22820 * @callback: (scope async): a #GAsyncReadyCallback.
22821 * @user_data: (closure): user data passed to @callback.
22823 * Asyncronously splice the output stream of @stream1 to the input stream of
22824 * @stream2, and splice the output stream of @stream2 to the input stream of
22827 * When the operation is finished @callback will be called.
22828 * You can then call g_io_stream_splice_finish() to get the
22829 * result of the operation.
22836 * g_io_stream_splice_finish:
22837 * @result: a #GAsyncResult.
22838 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22840 * Finishes an asynchronous io stream splice operation.
22842 * Returns: %TRUE on success, %FALSE otherwise.
22848 * g_keyfile_settings_backend_new:
22849 * @filename: the filename of the keyfile
22850 * @root_path: the path under which all settings keys appear
22851 * @root_group: (allow-none): the group name corresponding to @root_path, or %NULL
22853 * Creates a keyfile-backed #GSettingsBackend.
22855 * The filename of the keyfile to use is given by @filename.
22857 * All settings read to or written from the backend must fall under the
22858 * path given in @root_path (which must start and end with a slash and
22859 * not contain two consecutive slashes). @root_path may be "/".
22861 * If @root_group is non-%NULL then it specifies the name of the keyfile
22862 * group used for keys that are written directly below @root_path. For
22863 * example, if @root_path is "/apps/example/" and @root_group is
22864 * "toplevel", then settings the key "/apps/example/enabled" to a value
22865 * of %TRUE will cause the following to appear in the keyfile:
22872 * If @root_group is %NULL then it is not permitted to store keys
22873 * directly below the @root_path.
22875 * For keys not stored directly below @root_path (ie: in a sub-path),
22876 * the name of the subpath (with the final slash stripped) is used as
22877 * the name of the keyfile group. To continue the example, if
22878 * "/apps/example/profiles/default/font-size" were set to
22879 * 12 then the following would appear in the keyfile:
22882 * [profiles/default]
22886 * The backend will refuse writes (and return writability as being
22887 * %FALSE) for keys outside of @root_path and, in the event that
22888 * @root_group is %NULL, also for keys directly under @root_path.
22889 * Writes will also be refused if the backend detects that it has the
22890 * inability to rewrite the keyfile (ie: the containing directory is not
22893 * There is no checking done for your key namespace clashing with the
22894 * syntax of the key file format. For example, if you have '[' or ']'
22895 * characters in your path names or '=' in your key names you may be in
22898 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
22903 * g_loadable_icon_load:
22904 * @icon: a #GLoadableIcon.
22905 * @size: an integer.
22906 * @type: (out) (allow-none): a location to store the type of the loaded icon, %NULL to ignore.
22907 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22908 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22910 * Loads a loadable icon. For the asynchronous version of this function,
22911 * see g_loadable_icon_load_async().
22913 * Returns: (transfer full): a #GInputStream to read the icon from.
22918 * g_loadable_icon_load_async:
22919 * @icon: a #GLoadableIcon.
22920 * @size: an integer.
22921 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
22922 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
22923 * @user_data: (closure): the data to pass to callback function
22925 * Loads an icon asynchronously. To finish this function, see
22926 * g_loadable_icon_load_finish(). For the synchronous, blocking
22927 * version of this function, see g_loadable_icon_load().
22932 * g_loadable_icon_load_finish:
22933 * @icon: a #GLoadableIcon.
22934 * @res: a #GAsyncResult.
22935 * @type: a location to store the type of the loaded icon, %NULL to ignore.
22936 * @error: a #GError location to store the error occurring, or %NULL to ignore.
22938 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
22940 * Returns: (transfer full): a #GInputStream to read the icon from.
22947 * Returns a new #GVfs handle for a local vfs.
22949 * Returns: a new #GVfs handle.
22954 * g_memory_input_stream_add_bytes:
22955 * @stream: a #GMemoryInputStream
22956 * @bytes: input data
22958 * Appends @bytes to data that can be read from the input stream.
22965 * g_memory_input_stream_add_data:
22966 * @stream: a #GMemoryInputStream
22967 * @data: (array length=len) (element-type guint8) (transfer full): input data
22968 * @len: length of the data, may be -1 if @data is a nul-terminated string
22969 * @destroy: (allow-none): function that is called to free @data, or %NULL
22971 * Appends @data to data that can be read from the input stream
22976 * g_memory_input_stream_new:
22978 * Creates a new empty #GMemoryInputStream.
22980 * Returns: a new #GInputStream
22985 * g_memory_input_stream_new_from_bytes:
22986 * @bytes: a #GBytes
22988 * Creates a new #GMemoryInputStream with data from the given @bytes.
22990 * Returns: new #GInputStream read from @bytes
22996 * g_memory_input_stream_new_from_data:
22997 * @data: (array length=len) (element-type guint8) (transfer full): input data
22998 * @len: length of the data, may be -1 if @data is a nul-terminated string
22999 * @destroy: (allow-none): function that is called to free @data, or %NULL
23001 * Creates a new #GMemoryInputStream with data in memory of a given size.
23003 * Returns: new #GInputStream read from @data of @len bytes.
23008 * g_memory_output_stream_get_data:
23009 * @ostream: a #GMemoryOutputStream
23011 * Gets any loaded data from the @ostream.
23013 * Note that the returned pointer may become invalid on the next
23014 * write or truncate operation on the stream.
23016 * Returns: (transfer none): pointer to the stream's data
23021 * g_memory_output_stream_get_data_size:
23022 * @ostream: a #GMemoryOutputStream
23024 * Returns the number of bytes from the start up
23025 * to including the last byte written in the stream
23026 * that has not been truncated away.
23028 * Returns: the number of bytes written to the stream
23034 * g_memory_output_stream_get_size:
23035 * @ostream: a #GMemoryOutputStream
23037 * Gets the size of the currently allocated data area (available from
23038 * g_memory_output_stream_get_data()). If the stream isn't
23039 * growable (no realloc was passed to g_memory_output_stream_new()) then
23040 * this is the maximum size of the stream and further writes
23041 * will return %G_IO_ERROR_NO_SPACE.
23043 * Note that for growable streams the returned size may become invalid on
23044 * the next write or truncate operation on the stream.
23046 * If you want the number of bytes currently written to the stream, use
23047 * g_memory_output_stream_get_data_size().
23049 * Returns: the number of bytes allocated for the data buffer
23054 * g_memory_output_stream_new: (skip)
23055 * @data: (allow-none): pointer to a chunk of memory to use, or %NULL
23056 * @size: the size of @data
23057 * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL
23058 * @destroy_function: (allow-none): a function to be called on @data when the stream is finalized, or %NULL
23060 * Creates a new #GMemoryOutputStream.
23062 * If @data is non-%NULL, the stream will use that for its internal storage.
23063 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
23064 * storage when necessary. To construct a fixed-size output stream,
23065 * pass %NULL as @realloc_fn.
23068 * /* a stream that can grow */
23069 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
23071 * /* another stream that can grow */
23072 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
23074 * /* a fixed-size stream */
23075 * data = malloc (200);
23076 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
23079 * Returns: A newly created #GMemoryOutputStream object.
23084 * g_memory_output_stream_steal_as_bytes:
23085 * @ostream: a #GMemoryOutputStream
23087 * Returns data from the @ostream as a #GBytes. @ostream must be
23088 * closed before calling this function.
23090 * Returns: (transfer full): the stream's data
23096 * g_memory_output_stream_steal_data:
23097 * @ostream: a #GMemoryOutputStream
23099 * Gets any loaded data from the @ostream. Ownership of the data
23100 * is transferred to the caller; when no longer needed it must be
23101 * freed using the free function set in @ostream's
23102 * #GMemoryOutputStream:destroy-function property.
23104 * @ostream must be closed before calling this function.
23106 * Returns: (transfer full): the stream's data
23112 * g_memory_settings_backend_new:
23114 * Creates a memory-backed #GSettingsBackend.
23116 * This backend allows changes to settings, but does not write them
23117 * to any backing storage, so the next time you run your application,
23118 * the memory backend will start out with the default values again.
23120 * Returns: (transfer full): a newly created #GSettingsBackend
23128 * @label: (allow-none): the section label, or %NULL
23129 * @detailed_action: (allow-none): the detailed action string, or %NULL
23131 * Convenience function for appending a normal menu item to the end of
23132 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
23133 * flexible alternative.
23140 * g_menu_append_item:
23142 * @item: a #GMenuItem to append
23144 * Appends @item to the end of @menu.
23146 * See g_menu_insert_item() for more information.
23153 * g_menu_append_section:
23155 * @label: (allow-none): the section label, or %NULL
23156 * @section: a #GMenuModel with the items of the section
23158 * Convenience function for appending a section menu item to the end of
23159 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
23160 * more flexible alternative.
23167 * g_menu_append_submenu:
23169 * @label: (allow-none): the section label, or %NULL
23170 * @submenu: a #GMenuModel with the items of the submenu
23172 * Convenience function for appending a submenu menu item to the end of
23173 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
23174 * more flexible alternative.
23181 * g_menu_attribute_iter_get_name:
23182 * @iter: a #GMenuAttributeIter
23184 * Gets the name of the attribute at the current iterator position, as
23187 * The iterator is not advanced.
23189 * Returns: the name of the attribute
23195 * g_menu_attribute_iter_get_next:
23196 * @iter: a #GMenuAttributeIter
23197 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
23198 * @value: (out) (allow-none) (transfer full): the attribute value
23200 * This function combines g_menu_attribute_iter_next() with
23201 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
23203 * First the iterator is advanced to the next (possibly first) attribute.
23204 * If that fails, then %FALSE is returned and there are no other
23207 * If successful, @name and @value are set to the name and value of the
23208 * attribute that has just been advanced to. At this point,
23209 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
23210 * return the same values again.
23212 * The value returned in @name remains valid for as long as the iterator
23213 * remains at the current position. The value returned in @value must
23214 * be unreffed using g_variant_unref() when it is no longer in use.
23216 * Returns: %TRUE on success, or %FALSE if there is no additional attribute
23222 * g_menu_attribute_iter_get_value:
23223 * @iter: a #GMenuAttributeIter
23225 * Gets the value of the attribute at the current iterator position.
23227 * The iterator is not advanced.
23229 * Returns: (transfer full): the value of the current attribute
23235 * g_menu_attribute_iter_next:
23236 * @iter: a #GMenuAttributeIter
23238 * Attempts to advance the iterator to the next (possibly first)
23241 * %TRUE is returned on success, or %FALSE if there are no more
23244 * You must call this function when you first acquire the iterator
23245 * to advance it to the first attribute (and determine if the first
23246 * attribute exists at all).
23248 * Returns: %TRUE on success, or %FALSE when there are no more attributes
23257 * Marks @menu as frozen.
23259 * After the menu is frozen, it is an error to attempt to make any
23260 * changes to it. In effect this means that the #GMenu API must no
23263 * This function causes g_menu_model_is_mutable() to begin returning
23264 * %FALSE, which has some positive performance implications.
23273 * @position: the position at which to insert the item
23274 * @label: (allow-none): the section label, or %NULL
23275 * @detailed_action: (allow-none): the detailed action string, or %NULL
23277 * Convenience function for inserting a normal menu item into @menu.
23278 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
23286 * g_menu_insert_item:
23288 * @position: the position at which to insert the item
23289 * @item: the #GMenuItem to insert
23291 * Inserts @item into @menu.
23293 * The "insertion" is actually done by copying all of the attribute and
23294 * link values of @item and using them to form a new item within @menu.
23295 * As such, @item itself is not really inserted, but rather, a menu item
23296 * that is exactly the same as the one presently described by @item.
23298 * This means that @item is essentially useless after the insertion
23299 * occurs. Any changes you make to it are ignored unless it is inserted
23300 * again (at which point its updated values will be copied).
23302 * You should probably just free @item once you're done.
23304 * There are many convenience functions to take care of common cases.
23305 * See g_menu_insert(), g_menu_insert_section() and
23306 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
23307 * each of these functions.
23314 * g_menu_insert_section:
23316 * @position: the position at which to insert the item
23317 * @label: (allow-none): the section label, or %NULL
23318 * @section: a #GMenuModel with the items of the section
23320 * Convenience function for inserting a section menu item into @menu.
23321 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
23322 * flexible alternative.
23329 * g_menu_insert_submenu:
23331 * @position: the position at which to insert the item
23332 * @label: (allow-none): the section label, or %NULL
23333 * @submenu: a #GMenuModel with the items of the submenu
23335 * Convenience function for inserting a submenu menu item into @menu.
23336 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
23337 * flexible alternative.
23344 * g_menu_item_get_attribute:
23345 * @menu_item: a #GMenuItem
23346 * @attribute: the attribute name to query
23347 * @format_string: a #GVariant format string
23348 * @...: positional parameters, as per @format_string
23350 * Queries the named @attribute on @menu_item.
23352 * If the attribute exists and matches the #GVariantType corresponding
23353 * to @format_string then @format_string is used to deconstruct the
23354 * value into the positional parameters and %TRUE is returned.
23356 * If the attribute does not exist, or it does exist but has the wrong
23357 * type, then the positional parameters are ignored and %FALSE is
23360 * Returns: %TRUE if the named attribute was found with the expected type
23366 * g_menu_item_get_attribute_value:
23367 * @menu_item: a #GMenuItem
23368 * @attribute: the attribute name to query
23369 * @expected_type: (allow-none): the expected type of the attribute
23371 * Queries the named @attribute on @menu_item.
23373 * If @expected_type is specified and the attribute does not have this
23374 * type, %NULL is returned. %NULL is also returned if the attribute
23375 * simply does not exist.
23377 * Returns: (transfer full): the attribute value, or %NULL
23383 * g_menu_item_get_link:
23384 * @menu_item: a #GMenuItem
23385 * @link: the link name to query
23387 * Queries the named @link on @menu_item.
23389 * Returns: (transfer full): the link, or %NULL
23396 * @label: (allow-none): the section label, or %NULL
23397 * @detailed_action: (allow-none): the detailed action string, or %NULL
23399 * Creates a new #GMenuItem.
23401 * If @label is non-%NULL it is used to set the "label" attribute of the
23404 * If @detailed_action is non-%NULL it is used to set the "action" and
23405 * possibly the "target" attribute of the new item. See
23406 * g_menu_item_set_detailed_action() for more information.
23408 * Returns: a new #GMenuItem
23414 * g_menu_item_new_from_model:
23415 * @model: a #GMenuModel
23416 * @item_index: the index of an item in @model
23418 * Creates a #GMenuItem as an exact copy of an existing menu item in a
23421 * @item_index must be valid (ie: be sure to call
23422 * g_menu_model_get_n_items() first).
23424 * Returns: a new #GMenuItem.
23430 * g_menu_item_new_section:
23431 * @label: (allow-none): the section label, or %NULL
23432 * @section: a #GMenuModel with the items of the section
23434 * Creates a new #GMenuItem representing a section.
23436 * This is a convenience API around g_menu_item_new() and
23437 * g_menu_item_set_section().
23439 * The effect of having one menu appear as a section of another is
23440 * exactly as it sounds: the items from @section become a direct part of
23441 * the menu that @menu_item is added to.
23443 * Visual separation is typically displayed between two non-empty
23444 * sections. If @label is non-%NULL then it will be encorporated into
23445 * this visual indication. This allows for labeled subsections of a
23448 * As a simple example, consider a typical "Edit" menu from a simple
23449 * program. It probably contains an "Undo" and "Redo" item, followed by
23450 * a separator, followed by "Cut", "Copy" and "Paste".
23452 * This would be accomplished by creating three #GMenu instances. The
23453 * first would be populated with the "Undo" and "Redo" items, and the
23454 * second with the "Cut", "Copy" and "Paste" items. The first and
23455 * second menus would then be added as submenus of the third. In XML
23456 * format, this would look something like the following:
23458 * <informalexample><programlisting><![CDATA[
23459 * <menu id='edit-menu'>
23461 * <item label='Undo'/>
23462 * <item label='Redo'/>
23465 * <item label='Cut'/>
23466 * <item label='Copy'/>
23467 * <item label='Paste'/>
23470 * ]]></programlisting></informalexample>
23472 * The following example is exactly equivalent. It is more illustrative
23473 * of the exact relationship between the menus and items (keeping in
23474 * mind that the 'link' element defines a new menu that is linked to the
23475 * containing one). The style of the second example is more verbose and
23476 * difficult to read (and therefore not recommended except for the
23477 * purpose of understanding what is really going on).
23479 * <informalexample><programlisting><![CDATA[
23480 * <menu id='edit-menu'>
23482 * <link name='section'>
23483 * <item label='Undo'/>
23484 * <item label='Redo'/>
23488 * <link name='section'>
23489 * <item label='Cut'/>
23490 * <item label='Copy'/>
23491 * <item label='Paste'/>
23495 * ]]></programlisting></informalexample>
23497 * Returns: a new #GMenuItem
23503 * g_menu_item_new_submenu:
23504 * @label: (allow-none): the section label, or %NULL
23505 * @submenu: a #GMenuModel with the items of the submenu
23507 * Creates a new #GMenuItem representing a submenu.
23509 * This is a convenience API around g_menu_item_new() and
23510 * g_menu_item_set_submenu().
23512 * Returns: a new #GMenuItem
23518 * g_menu_item_set_action_and_target:
23519 * @menu_item: a #GMenuItem
23520 * @action: (allow-none): the name of the action for this item
23521 * @format_string: (allow-none): a GVariant format string
23522 * @...: positional parameters, as per @format_string
23524 * Sets or unsets the "action" and "target" attributes of @menu_item.
23526 * If @action is %NULL then both the "action" and "target" attributes
23527 * are unset (and @format_string is ignored along with the positional
23530 * If @action is non-%NULL then the "action" attribute is set.
23531 * @format_string is then inspected. If it is non-%NULL then the proper
23532 * position parameters are collected to create a #GVariant instance to
23533 * use as the target value. If it is %NULL then the positional
23534 * parameters are ignored and the "target" attribute is unset.
23536 * See also g_menu_item_set_action_and_target_value() for an equivalent
23537 * call that directly accepts a #GVariant. See
23538 * g_menu_item_set_detailed_action() for a more convenient version that
23539 * works with string-typed targets.
23541 * See also g_menu_item_set_action_and_target_value() for a
23542 * description of the semantics of the action and target attributes.
23549 * g_menu_item_set_action_and_target_value:
23550 * @menu_item: a #GMenuItem
23551 * @action: (allow-none): the name of the action for this item
23552 * @target_value: (allow-none): a #GVariant to use as the action target
23554 * Sets or unsets the "action" and "target" attributes of @menu_item.
23556 * If @action is %NULL then both the "action" and "target" attributes
23557 * are unset (and @target_value is ignored).
23559 * If @action is non-%NULL then the "action" attribute is set. The
23560 * "target" attribute is then set to the value of @target_value if it is
23561 * non-%NULL or unset otherwise.
23563 * Normal menu items (ie: not submenu, section or other custom item
23564 * types) are expected to have the "action" attribute set to identify
23565 * the action that they are associated with. The state type of the
23566 * action help to determine the disposition of the menu item. See
23567 * #GAction and #GActionGroup for an overview of actions.
23569 * In general, clicking on the menu item will result in activation of
23570 * the named action with the "target" attribute given as the parameter
23571 * to the action invocation. If the "target" attribute is not set then
23572 * the action is invoked with no parameter.
23574 * If the action has no state then the menu item is usually drawn as a
23575 * plain menu item (ie: with no additional decoration).
23577 * If the action has a boolean state then the menu item is usually drawn
23578 * as a toggle menu item (ie: with a checkmark or equivalent
23579 * indication). The item should be marked as 'toggled' or 'checked'
23580 * when the boolean state is %TRUE.
23582 * If the action has a string state then the menu item is usually drawn
23583 * as a radio menu item (ie: with a radio bullet or equivalent
23584 * indication). The item should be marked as 'selected' when the string
23585 * state is equal to the value of the @target property.
23587 * See g_menu_item_set_action_and_target() or
23588 * g_menu_item_set_detailed_action() for two equivalent calls that are
23589 * probably more convenient for most uses.
23596 * g_menu_item_set_attribute:
23597 * @menu_item: a #GMenuItem
23598 * @attribute: the attribute to set
23599 * @format_string: (allow-none): a #GVariant format string, or %NULL
23600 * @...: positional parameters, as per @format_string
23602 * Sets or unsets an attribute on @menu_item.
23604 * The attribute to set or unset is specified by @attribute. This
23605 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
23606 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
23608 * Attribute names are restricted to lowercase characters, numbers
23609 * and '-'. Furthermore, the names must begin with a lowercase character,
23610 * must not end with a '-', and must not contain consecutive dashes.
23612 * If @format_string is non-%NULL then the proper position parameters
23613 * are collected to create a #GVariant instance to use as the attribute
23614 * value. If it is %NULL then the positional parameterrs are ignored
23615 * and the named attribute is unset.
23617 * See also g_menu_item_set_attribute_value() for an equivalent call
23618 * that directly accepts a #GVariant.
23625 * g_menu_item_set_attribute_value:
23626 * @menu_item: a #GMenuItem
23627 * @attribute: the attribute to set
23628 * @value: (allow-none): a #GVariant to use as the value, or %NULL
23630 * Sets or unsets an attribute on @menu_item.
23632 * The attribute to set or unset is specified by @attribute. This
23633 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
23634 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
23636 * Attribute names are restricted to lowercase characters, numbers
23637 * and '-'. Furthermore, the names must begin with a lowercase character,
23638 * must not end with a '-', and must not contain consecutive dashes.
23640 * must consist only of lowercase
23641 * ASCII characters, digits and '-'.
23643 * If @value is non-%NULL then it is used as the new value for the
23644 * attribute. If @value is %NULL then the attribute is unset. If
23645 * the @value #GVariant is floating, it is consumed.
23647 * See also g_menu_item_set_attribute() for a more convenient way to do
23655 * g_menu_item_set_detailed_action:
23656 * @menu_item: a #GMenuItem
23657 * @detailed_action: the "detailed" action string
23659 * Sets the "action" and possibly the "target" attribute of @menu_item.
23661 * If @detailed_action contains a double colon ("::") then it is used as
23662 * a separator between an action name and a target string. In this
23663 * case, this call is equivalent to calling
23664 * g_menu_item_set_action_and_target() with the part before the "::" and
23665 * with a string-type #GVariant containing the part following the "::".
23667 * If @detailed_action doesn't contain "::" then the action is set to
23668 * the given string (verbatim) and the target value is unset.
23670 * See g_menu_item_set_action_and_target() or
23671 * g_menu_item_set_action_and_target_value() for more flexible (but
23672 * slightly less convenient) alternatives.
23674 * See also g_menu_item_set_action_and_target_value() for a description of
23675 * the semantics of the action and target attributes.
23682 * g_menu_item_set_label:
23683 * @menu_item: a #GMenuItem
23684 * @label: (allow-none): the label to set, or %NULL to unset
23686 * Sets or unsets the "label" attribute of @menu_item.
23688 * If @label is non-%NULL it is used as the label for the menu item. If
23689 * it is %NULL then the label attribute is unset.
23696 * g_menu_item_set_link:
23697 * @menu_item: a #GMenuItem
23698 * @link: type of link to establish or unset
23699 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
23701 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
23703 * Links are used to establish a relationship between a particular menu
23704 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
23705 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
23706 * is used to create a section. Other types of link can be used, but there
23707 * is no guarantee that clients will be able to make sense of them.
23708 * Link types are restricted to lowercase characters, numbers
23709 * and '-'. Furthermore, the names must begin with a lowercase character,
23710 * must not end with a '-', and must not contain consecutive dashes.
23717 * g_menu_item_set_section:
23718 * @menu_item: a #GMenuItem
23719 * @section: (allow-none): a #GMenuModel, or %NULL
23721 * Sets or unsets the "section" link of @menu_item to @section.
23723 * The effect of having one menu appear as a section of another is
23724 * exactly as it sounds: the items from @section become a direct part of
23725 * the menu that @menu_item is added to. See g_menu_item_new_section()
23726 * for more information about what it means for a menu item to be a
23734 * g_menu_item_set_submenu:
23735 * @menu_item: a #GMenuItem
23736 * @submenu: (allow-none): a #GMenuModel, or %NULL
23738 * Sets or unsets the "submenu" link of @menu_item to @submenu.
23740 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
23743 * The effect of having one menu appear as a submenu of another is
23744 * exactly as it sounds.
23751 * g_menu_link_iter_get_name:
23752 * @iter: a #GMenuLinkIter
23754 * Gets the name of the link at the current iterator position.
23756 * The iterator is not advanced.
23758 * Returns: the type of the link
23764 * g_menu_link_iter_get_next:
23765 * @iter: a #GMenuLinkIter
23766 * @out_link: (out) (allow-none) (transfer none): the name of the link
23767 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
23769 * This function combines g_menu_link_iter_next() with
23770 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
23772 * First the iterator is advanced to the next (possibly first) link.
23773 * If that fails, then %FALSE is returned and there are no other effects.
23775 * If successful, @out_link and @value are set to the name and #GMenuModel
23776 * of the link that has just been advanced to. At this point,
23777 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
23778 * same values again.
23780 * The value returned in @out_link remains valid for as long as the iterator
23781 * remains at the current position. The value returned in @value must
23782 * be unreffed using g_object_unref() when it is no longer in use.
23784 * Returns: %TRUE on success, or %FALSE if there is no additional link
23790 * g_menu_link_iter_get_value:
23791 * @iter: a #GMenuLinkIter
23793 * Gets the linked #GMenuModel at the current iterator position.
23795 * The iterator is not advanced.
23797 * Returns: (transfer full): the #GMenuModel that is linked to
23803 * g_menu_link_iter_next:
23804 * @iter: a #GMenuLinkIter
23806 * Attempts to advance the iterator to the next (possibly first)
23809 * %TRUE is returned on success, or %FALSE if there are no more links.
23811 * You must call this function when you first acquire the iterator to
23812 * advance it to the first link (and determine if the first link exists
23815 * Returns: %TRUE on success, or %FALSE when there are no more links
23821 * g_menu_model_get_item_attribute:
23822 * @model: a #GMenuModel
23823 * @item_index: the index of the item
23824 * @attribute: the attribute to query
23825 * @format_string: a #GVariant format string
23826 * @...: positional parameters, as per @format_string
23828 * Queries item at position @item_index in @model for the attribute
23829 * specified by @attribute.
23831 * If the attribute exists and matches the #GVariantType corresponding
23832 * to @format_string then @format_string is used to deconstruct the
23833 * value into the positional parameters and %TRUE is returned.
23835 * If the attribute does not exist, or it does exist but has the wrong
23836 * type, then the positional parameters are ignored and %FALSE is
23839 * This function is a mix of g_menu_model_get_item_attribute_value() and
23840 * g_variant_get(), followed by a g_variant_unref(). As such,
23841 * @format_string must make a complete copy of the data (since the
23842 * #GVariant may go away after the call to g_variant_unref()). In
23843 * particular, no '&' characters are allowed in @format_string.
23845 * Returns: %TRUE if the named attribute was found with the expected type
23851 * g_menu_model_get_item_attribute_value:
23852 * @model: a #GMenuModel
23853 * @item_index: the index of the item
23854 * @attribute: the attribute to query
23855 * @expected_type: (allow-none): the expected type of the attribute, or %NULL
23857 * Queries the item at position @item_index in @model for the attribute
23858 * specified by @attribute.
23860 * If @expected_type is non-%NULL then it specifies the expected type of
23861 * the attribute. If it is %NULL then any type will be accepted.
23863 * If the attribute exists and matches @expected_type (or if the
23864 * expected type is unspecified) then the value is returned.
23866 * If the attribute does not exist, or does not match the expected type
23867 * then %NULL is returned.
23869 * Returns: (transfer full): the value of the attribute
23875 * g_menu_model_get_item_link:
23876 * @model: a #GMenuModel
23877 * @item_index: the index of the item
23878 * @link: the link to query
23880 * Queries the item at position @item_index in @model for the link
23881 * specified by @link.
23883 * If the link exists, the linked #GMenuModel is returned. If the link
23884 * does not exist, %NULL is returned.
23886 * Returns: (transfer full): the linked #GMenuModel, or %NULL
23892 * g_menu_model_get_n_items:
23893 * @model: a #GMenuModel
23895 * Query the number of items in @model.
23897 * Returns: the number of items
23903 * g_menu_model_is_mutable:
23904 * @model: a #GMenuModel
23906 * Queries if @model is mutable.
23908 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
23909 * signal. Consumers of the model may make optimisations accordingly.
23911 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be emitted).
23917 * g_menu_model_items_changed:
23918 * @model: a #GMenuModel
23919 * @position: the position of the change
23920 * @removed: the number of items removed
23921 * @added: the number of items added
23923 * Requests emission of the #GMenuModel::items-changed signal on @model.
23925 * This function should never be called except by #GMenuModel
23926 * subclasses. Any other calls to this function will very likely lead
23927 * to a violation of the interface of the model.
23929 * The implementation should update its internal representation of the
23930 * menu before emitting the signal. The implementation should further
23931 * expect to receive queries about the new state of the menu (and
23932 * particularly added menu items) while signal handlers are running.
23934 * The implementation must dispatch this call directly from a mainloop
23935 * entry and not in response to calls -- particularly those from the
23936 * #GMenuModel API. Said another way: the menu must not change while
23937 * user code is running without returning to the mainloop.
23944 * g_menu_model_iterate_item_attributes:
23945 * @model: a #GMenuModel
23946 * @item_index: the index of the item
23948 * Creates a #GMenuAttributeIter to iterate over the attributes of
23949 * the item at position @item_index in @model.
23951 * You must free the iterator with g_object_unref() when you are done.
23953 * Returns: (transfer full): a new #GMenuAttributeIter
23959 * g_menu_model_iterate_item_links:
23960 * @model: a #GMenuModel
23961 * @item_index: the index of the item
23963 * Creates a #GMenuLinkIter to iterate over the links of the item at
23964 * position @item_index in @model.
23966 * You must free the iterator with g_object_unref() when you are done.
23968 * Returns: (transfer full): a new #GMenuLinkIter
23976 * Creates a new #GMenu.
23978 * The new menu has no items.
23980 * Returns: a new #GMenu
23988 * @label: (allow-none): the section label, or %NULL
23989 * @detailed_action: (allow-none): the detailed action string, or %NULL
23991 * Convenience function for prepending a normal menu item to the start
23992 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
23993 * flexible alternative.
24000 * g_menu_prepend_item:
24002 * @item: a #GMenuItem to prepend
24004 * Prepends @item to the start of @menu.
24006 * See g_menu_insert_item() for more information.
24013 * g_menu_prepend_section:
24015 * @label: (allow-none): the section label, or %NULL
24016 * @section: a #GMenuModel with the items of the section
24018 * Convenience function for prepending a section menu item to the start
24019 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
24020 * a more flexible alternative.
24027 * g_menu_prepend_submenu:
24029 * @label: (allow-none): the section label, or %NULL
24030 * @submenu: a #GMenuModel with the items of the submenu
24032 * Convenience function for prepending a submenu menu item to the start
24033 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
24034 * a more flexible alternative.
24043 * @position: the position of the item to remove
24045 * Removes an item from the menu.
24047 * @position gives the index of the item to remove.
24049 * It is an error if position is not in range the range from 0 to one
24050 * less than the number of items in the menu.
24052 * It is not possible to remove items by identity since items are added
24053 * to the menu simply by copying their links and attributes (ie:
24054 * identity of the item itself is not preserved).
24061 * g_mount_can_eject:
24062 * @mount: a #GMount.
24064 * Checks if @mount can be eject.
24066 * Returns: %TRUE if the @mount can be ejected.
24071 * g_mount_can_unmount:
24072 * @mount: a #GMount.
24074 * Checks if @mount can be mounted.
24076 * Returns: %TRUE if the @mount can be unmounted.
24082 * @mount: a #GMount.
24083 * @flags: flags affecting the unmount if required for eject
24084 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24085 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24086 * @user_data: user data passed to @callback.
24088 * Ejects a mount. This is an asynchronous operation, and is
24089 * finished by calling g_mount_eject_finish() with the @mount
24090 * and #GAsyncResult data returned in the @callback.
24092 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
24097 * g_mount_eject_finish:
24098 * @mount: a #GMount.
24099 * @result: a #GAsyncResult.
24100 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24102 * Finishes ejecting a mount. If any errors occurred during the operation,
24103 * @error will be set to contain the errors and %FALSE will be returned.
24105 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
24106 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
24111 * g_mount_eject_with_operation:
24112 * @mount: a #GMount.
24113 * @flags: flags affecting the unmount if required for eject
24114 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
24115 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24116 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24117 * @user_data: user data passed to @callback.
24119 * Ejects a mount. This is an asynchronous operation, and is
24120 * finished by calling g_mount_eject_with_operation_finish() with the @mount
24121 * and #GAsyncResult data returned in the @callback.
24128 * g_mount_eject_with_operation_finish:
24129 * @mount: a #GMount.
24130 * @result: a #GAsyncResult.
24131 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24133 * Finishes ejecting a mount. If any errors occurred during the operation,
24134 * @error will be set to contain the errors and %FALSE will be returned.
24136 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
24142 * g_mount_get_default_location:
24143 * @mount: a #GMount.
24145 * Gets the default location of @mount. The default location of the given
24146 * @mount is a path that reflects the main entry point for the user (e.g.
24147 * the home directory, or the root of the volume).
24149 * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed.
24154 * g_mount_get_drive:
24155 * @mount: a #GMount.
24157 * Gets the drive for the @mount.
24159 * This is a convenience method for getting the #GVolume and then
24160 * using that object to get the #GDrive.
24162 * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed.
24167 * g_mount_get_icon:
24168 * @mount: a #GMount.
24170 * Gets the icon for @mount.
24172 * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.
24177 * g_mount_get_name:
24178 * @mount: a #GMount.
24180 * Gets the name of @mount.
24182 * Returns: the name for the given @mount. The returned string should be freed with g_free() when no longer needed.
24187 * g_mount_get_root:
24188 * @mount: a #GMount.
24190 * Gets the root directory on @mount.
24192 * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed.
24197 * g_mount_get_sort_key:
24198 * @mount: A #GMount.
24200 * Gets the sort key for @mount, if any.
24202 * Returns: Sorting key for @mount or %NULL if no such key is available.
24208 * g_mount_get_symbolic_icon:
24209 * @mount: a #GMount.
24211 * Gets the symbolic icon for @mount.
24213 * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.
24219 * g_mount_get_uuid:
24220 * @mount: a #GMount.
24222 * Gets the UUID for the @mount. The reference is typically based on
24223 * the file system UUID for the mount in question and should be
24224 * considered an opaque string. Returns %NULL if there is no UUID
24227 * Returns: the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed.
24232 * g_mount_get_volume:
24233 * @mount: a #GMount.
24235 * Gets the volume for the @mount.
24237 * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed.
24242 * g_mount_guess_content_type:
24243 * @mount: a #GMount
24244 * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available
24245 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
24246 * @callback: a #GAsyncReadyCallback
24247 * @user_data: user data passed to @callback
24249 * Tries to guess the type of content stored on @mount. Returns one or
24250 * more textual identifiers of well-known content types (typically
24251 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
24252 * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
24253 * specification for more on x-content types.
24255 * This is an asynchronous operation (see
24256 * g_mount_guess_content_type_sync() for the synchronous version), and
24257 * is finished by calling g_mount_guess_content_type_finish() with the
24258 * @mount and #GAsyncResult data returned in the @callback.
24265 * g_mount_guess_content_type_finish:
24266 * @mount: a #GMount
24267 * @result: a #GAsyncResult
24268 * @error: a #GError location to store the error occurring, or %NULL to ignore
24270 * Finishes guessing content types of @mount. If any errors occurred
24271 * during the operation, @error will be set to contain the errors and
24272 * %FALSE will be returned. In particular, you may get an
24273 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
24276 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it.
24282 * g_mount_guess_content_type_sync:
24283 * @mount: a #GMount
24284 * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available
24285 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
24286 * @error: a #GError location to store the error occurring, or %NULL to ignore
24288 * Tries to guess the type of content stored on @mount. Returns one or
24289 * more textual identifiers of well-known content types (typically
24290 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
24291 * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
24292 * specification for more on x-content types.
24294 * This is an synchronous operation and as such may block doing IO;
24295 * see g_mount_guess_content_type() for the asynchronous version.
24297 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it.
24303 * g_mount_is_shadowed:
24304 * @mount: A #GMount.
24306 * Determines if @mount is shadowed. Applications or libraries should
24307 * avoid displaying @mount in the user interface if it is shadowed.
24309 * A mount is said to be shadowed if there exists one or more user
24310 * visible objects (currently #GMount objects) with a root that is
24311 * inside the root of @mount.
24313 * One application of shadow mounts is when exposing a single file
24314 * system that is used to address several logical volumes. In this
24315 * situation, a #GVolumeMonitor implementation would create two
24316 * #GVolume objects (for example, one for the camera functionality of
24317 * the device and one for a SD card reader on the device) with
24318 * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal>
24319 * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the
24320 * underlying mount (with root
24321 * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said
24322 * #GVolumeMonitor implementation would create two #GMount objects
24323 * (each with their root matching the corresponding volume activation
24324 * root) that would shadow the original mount.
24326 * The proxy monitor in GVfs 2.26 and later, automatically creates and
24327 * manage shadow mounts (and shadows the underlying mount) if the
24328 * activation root on a #GVolume is set.
24330 * Returns: %TRUE if @mount is shadowed.
24336 * g_mount_operation_get_anonymous:
24337 * @op: a #GMountOperation.
24339 * Check to see whether the mount operation is being used
24340 * for an anonymous user.
24342 * Returns: %TRUE if mount operation is anonymous.
24347 * g_mount_operation_get_choice:
24348 * @op: a #GMountOperation.
24350 * Gets a choice from the mount operation.
24352 * Returns: an integer containing an index of the user's choice from the choice's list, or %0.
24357 * g_mount_operation_get_domain:
24358 * @op: a #GMountOperation.
24360 * Gets the domain of the mount operation.
24362 * Returns: a string set to the domain.
24367 * g_mount_operation_get_password:
24368 * @op: a #GMountOperation.
24370 * Gets a password from the mount operation.
24372 * Returns: a string containing the password within @op.
24377 * g_mount_operation_get_password_save:
24378 * @op: a #GMountOperation.
24380 * Gets the state of saving passwords for the mount operation.
24382 * Returns: a #GPasswordSave flag.
24387 * g_mount_operation_get_username:
24388 * @op: a #GMountOperation.
24390 * Get the user name from the mount operation.
24392 * Returns: a string containing the user name.
24397 * g_mount_operation_new:
24399 * Creates a new mount operation.
24401 * Returns: a #GMountOperation.
24406 * g_mount_operation_reply:
24407 * @op: a #GMountOperation
24408 * @result: a #GMountOperationResult
24410 * Emits the #GMountOperation::reply signal.
24415 * g_mount_operation_set_anonymous:
24416 * @op: a #GMountOperation.
24417 * @anonymous: boolean value.
24419 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
24424 * g_mount_operation_set_choice:
24425 * @op: a #GMountOperation.
24426 * @choice: an integer.
24428 * Sets a default choice for the mount operation.
24433 * g_mount_operation_set_domain:
24434 * @op: a #GMountOperation.
24435 * @domain: the domain to set.
24437 * Sets the mount operation's domain.
24442 * g_mount_operation_set_password:
24443 * @op: a #GMountOperation.
24444 * @password: password to set.
24446 * Sets the mount operation's password to @password.
24451 * g_mount_operation_set_password_save:
24452 * @op: a #GMountOperation.
24453 * @save: a set of #GPasswordSave flags.
24455 * Sets the state of saving passwords for the mount operation.
24460 * g_mount_operation_set_username:
24461 * @op: a #GMountOperation.
24462 * @username: input username.
24464 * Sets the user name within @op to @username.
24470 * @mount: a #GMount.
24471 * @flags: flags affecting the operation
24472 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
24473 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24474 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24475 * @user_data: user data passed to @callback.
24477 * Remounts a mount. This is an asynchronous operation, and is
24478 * finished by calling g_mount_remount_finish() with the @mount
24479 * and #GAsyncResults data returned in the @callback.
24481 * Remounting is useful when some setting affecting the operation
24482 * of the volume has been changed, as these may need a remount to
24483 * take affect. While this is semantically equivalent with unmounting
24484 * and then remounting not all backends might need to actually be
24490 * g_mount_remount_finish:
24491 * @mount: a #GMount.
24492 * @result: a #GAsyncResult.
24493 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24495 * Finishes remounting a mount. If any errors occurred during the operation,
24496 * @error will be set to contain the errors and %FALSE will be returned.
24498 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
24504 * @mount: A #GMount.
24506 * Increments the shadow count on @mount. Usually used by
24507 * #GVolumeMonitor implementations when creating a shadow mount for
24508 * @mount, see g_mount_is_shadowed() for more information. The caller
24509 * will need to emit the #GMount::changed signal on @mount manually.
24517 * @mount: a #GMount.
24518 * @flags: flags affecting the operation
24519 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24520 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24521 * @user_data: user data passed to @callback.
24523 * Unmounts a mount. This is an asynchronous operation, and is
24524 * finished by calling g_mount_unmount_finish() with the @mount
24525 * and #GAsyncResult data returned in the @callback.
24527 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
24532 * g_mount_unmount_finish:
24533 * @mount: a #GMount.
24534 * @result: a #GAsyncResult.
24535 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24537 * Finishes unmounting a mount. If any errors occurred during the operation,
24538 * @error will be set to contain the errors and %FALSE will be returned.
24540 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
24541 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
24546 * g_mount_unmount_with_operation:
24547 * @mount: a #GMount.
24548 * @flags: flags affecting the operation
24549 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
24550 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24551 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24552 * @user_data: user data passed to @callback.
24554 * Unmounts a mount. This is an asynchronous operation, and is
24555 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
24556 * and #GAsyncResult data returned in the @callback.
24563 * g_mount_unmount_with_operation_finish:
24564 * @mount: a #GMount.
24565 * @result: a #GAsyncResult.
24566 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24568 * Finishes unmounting a mount. If any errors occurred during the operation,
24569 * @error will be set to contain the errors and %FALSE will be returned.
24571 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
24577 * g_mount_unshadow:
24578 * @mount: A #GMount.
24580 * Decrements the shadow count on @mount. Usually used by
24581 * #GVolumeMonitor implementations when destroying a shadow mount for
24582 * @mount, see g_mount_is_shadowed() for more information. The caller
24583 * will need to emit the #GMount::changed signal on @mount manually.
24590 * g_network_address_get_hostname:
24591 * @addr: a #GNetworkAddress
24593 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
24594 * depending on what @addr was created with.
24596 * Returns: @addr's hostname
24602 * g_network_address_get_port:
24603 * @addr: a #GNetworkAddress
24605 * Gets @addr's port number
24607 * Returns: @addr's port (which may be 0)
24613 * g_network_address_get_scheme:
24614 * @addr: a #GNetworkAddress
24616 * Gets @addr's scheme
24618 * Returns: @addr's scheme (%NULL if not built from URI)
24624 * g_network_address_new:
24625 * @hostname: the hostname
24628 * Creates a new #GSocketConnectable for connecting to the given
24629 * @hostname and @port.
24631 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
24637 * g_network_address_parse:
24638 * @host_and_port: the hostname and optionally a port
24639 * @default_port: the default port if not in @host_and_port
24640 * @error: a pointer to a #GError, or %NULL
24642 * Creates a new #GSocketConnectable for connecting to the given
24643 * @hostname and @port. May fail and return %NULL in case
24644 * parsing @host_and_port fails.
24646 * @host_and_port may be in any of a number of recognised formats; an IPv6
24647 * address, an IPv4 address, or a domain name (in which case a DNS
24648 * lookup is performed). Quoting with [] is supported for all address
24649 * types. A port override may be specified in the usual way with a
24652 * If no port is specified in @host_and_port then @default_port will be
24653 * used as the port number to connect to.
24655 * In general, @host_and_port is expected to be provided by the user
24656 * (allowing them to give the hostname, and a port overide if necessary)
24657 * and @default_port is expected to be provided by the application.
24659 * (The port component of @host_and_port can also be specified as a
24660 * service name rather than as a numeric port, but this functionality
24661 * is deprecated, because it depends on the contents of /etc/services,
24662 * which is generally quite sparse on platforms other than Linux.)
24664 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
24670 * g_network_address_parse_uri:
24671 * @uri: the hostname and optionally a port
24672 * @default_port: The default port if none is found in the URI
24673 * @error: a pointer to a #GError, or %NULL
24675 * Creates a new #GSocketConnectable for connecting to the given
24676 * @uri. May fail and return %NULL in case parsing @uri fails.
24678 * Using this rather than g_network_address_new() or
24679 * g_network_address_parse() allows #GSocketClient to determine
24680 * when to use application-specific proxy protocols.
24682 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
24688 * g_network_monitor_base_add_network:
24689 * @monitor: the #GNetworkMonitorBase
24690 * @network: a #GInetAddressMask
24692 * Adds @network to @monitor's list of available networks.
24699 * g_network_monitor_base_remove_network:
24700 * @monitor: the #GNetworkMonitorBase
24701 * @network: a #GInetAddressMask
24703 * Removes @network from @monitor's list of available networks.
24710 * g_network_monitor_base_set_networks:
24711 * @monitor: the #GNetworkMonitorBase
24712 * @networks: (array length=length): an array of #GInetAddressMask
24713 * @length: length of @networks
24715 * Drops @monitor's current list of available networks and replaces
24716 * it with @networks.
24721 * g_network_monitor_can_reach:
24722 * @monitor: a #GNetworkMonitor
24723 * @connectable: a #GSocketConnectable
24724 * @cancellable: (allow-none): a #GCancellable, or %NULL
24725 * @error: return location for a #GError, or %NULL
24727 * Attempts to determine whether or not the host pointed to by
24728 * @connectable can be reached, without actually trying to connect to
24731 * This may return %TRUE even when #GNetworkMonitor:network-available
24732 * is %FALSE, if, for example, @monitor can determine that
24733 * @connectable refers to a host on a local network.
24735 * If @monitor believes that an attempt to connect to @connectable
24736 * will succeed, it will return %TRUE. Otherwise, it will return
24737 * %FALSE and set @error to an appropriate error (such as
24738 * %G_IO_ERROR_HOST_UNREACHABLE).
24740 * Note that although this does not attempt to connect to
24741 * @connectable, it may still block for a brief period of time (eg,
24742 * trying to do multicast DNS on the local network), so if you do not
24743 * want to block, you should use g_network_monitor_can_reach_async().
24745 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
24751 * g_network_monitor_can_reach_async:
24752 * @monitor: a #GNetworkMonitor
24753 * @connectable: a #GSocketConnectable
24754 * @cancellable: (allow-none): a #GCancellable, or %NULL
24755 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
24756 * @user_data: (closure): the data to pass to callback function
24758 * Asynchronously attempts to determine whether or not the host
24759 * pointed to by @connectable can be reached, without actually
24760 * trying to connect to it.
24762 * For more details, see g_network_monitor_can_reach().
24764 * When the operation is finished, @callback will be called.
24765 * You can then call g_network_monitor_can_reach_finish()
24766 * to get the result of the operation.
24771 * g_network_monitor_can_reach_finish:
24772 * @monitor: a #GNetworkMonitor
24773 * @result: a #GAsyncResult
24774 * @error: return location for errors, or %NULL
24776 * Finishes an async network connectivity test.
24777 * See g_network_monitor_can_reach_async().
24779 * Returns: %TRUE if network is reachable, %FALSE if not.
24784 * g_network_monitor_get_default:
24786 * Gets the default #GNetworkMonitor for the system.
24788 * Returns: (transfer none): a #GNetworkMonitor
24794 * g_network_monitor_get_network_available:
24795 * @monitor: the #GNetworkMonitor
24797 * Checks if the network is available. "Available" here means that the
24798 * system has a default route available for at least one of IPv4 or
24799 * IPv6. It does not necessarily imply that the public Internet is
24800 * reachable. See #GNetworkMonitor:network-available for more details.
24802 * Returns: whether the network is available
24808 * g_network_service_get_domain:
24809 * @srv: a #GNetworkService
24811 * Gets the domain that @srv serves. This might be either UTF-8 or
24812 * ASCII-encoded, depending on what @srv was created with.
24814 * Returns: @srv's domain name
24820 * g_network_service_get_protocol:
24821 * @srv: a #GNetworkService
24823 * Gets @srv's protocol name (eg, "tcp").
24825 * Returns: @srv's protocol name
24831 * g_network_service_get_scheme:
24832 * @srv: a #GNetworkService
24834 * Get's the URI scheme used to resolve proxies. By default, the service name
24835 * is used as scheme.
24837 * Returns: @srv's scheme name
24843 * g_network_service_get_service:
24844 * @srv: a #GNetworkService
24846 * Gets @srv's service name (eg, "ldap").
24848 * Returns: @srv's service name
24854 * g_network_service_new:
24855 * @service: the service type to look up (eg, "ldap")
24856 * @protocol: the networking protocol to use for @service (eg, "tcp")
24857 * @domain: the DNS domain to look up the service in
24859 * Creates a new #GNetworkService representing the given @service,
24860 * @protocol, and @domain. This will initially be unresolved; use the
24861 * #GSocketConnectable interface to resolve it.
24863 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
24869 * g_network_service_set_scheme:
24870 * @srv: a #GNetworkService
24871 * @scheme: a URI scheme
24873 * Set's the URI scheme used to resolve proxies. By default, the service name
24874 * is used as scheme.
24881 * g_null_settings_backend_new:
24883 * Creates a readonly #GSettingsBackend.
24885 * This backend does not allow changes to settings, so all settings
24886 * will always have their default values.
24888 * Returns: (transfer full): a newly created #GSettingsBackend
24894 * g_output_stream_clear_pending:
24895 * @stream: output stream
24897 * Clears the pending flag on @stream.
24902 * g_output_stream_close:
24903 * @stream: A #GOutputStream.
24904 * @cancellable: (allow-none): optional cancellable object
24905 * @error: location to store the error occurring, or %NULL to ignore
24907 * Closes the stream, releasing resources related to it.
24909 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
24910 * Closing a stream multiple times will not return an error.
24912 * Closing a stream will automatically flush any outstanding buffers in the
24915 * Streams will be automatically closed when the last reference
24916 * is dropped, but you might want to call this function to make sure
24917 * resources are released as early as possible.
24919 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
24920 * open after the stream is closed. See the documentation for the individual
24921 * stream for details.
24923 * On failure the first error that happened will be reported, but the close
24924 * operation will finish as much as possible. A stream that failed to
24925 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
24926 * is important to check and report the error to the user, otherwise
24927 * there might be a loss of data as all data might not be written.
24929 * If @cancellable is not %NULL, then the operation can be cancelled by
24930 * triggering the cancellable object from another thread. If the operation
24931 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24932 * Cancelling a close will still leave the stream closed, but there some streams
24933 * can use a faster close that doesn't block to e.g. check errors. On
24934 * cancellation (as with any error) there is no guarantee that all written
24935 * data will reach the target.
24937 * Returns: %TRUE on success, %FALSE on failure
24942 * g_output_stream_close_async:
24943 * @stream: A #GOutputStream.
24944 * @io_priority: the io priority of the request.
24945 * @cancellable: (allow-none): optional cancellable object
24946 * @callback: (scope async): callback to call when the request is satisfied
24947 * @user_data: (closure): the data to pass to callback function
24949 * Requests an asynchronous close of the stream, releasing resources
24950 * related to it. When the operation is finished @callback will be
24951 * called. You can then call g_output_stream_close_finish() to get
24952 * the result of the operation.
24954 * For behaviour details see g_output_stream_close().
24956 * The asyncronous methods have a default fallback that uses threads
24957 * to implement asynchronicity, so they are optional for inheriting
24958 * classes. However, if you override one you must override all.
24963 * g_output_stream_close_finish:
24964 * @stream: a #GOutputStream.
24965 * @result: a #GAsyncResult.
24966 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24968 * Closes an output stream.
24970 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
24975 * g_output_stream_flush:
24976 * @stream: a #GOutputStream.
24977 * @cancellable: (allow-none): optional cancellable object
24978 * @error: location to store the error occurring, or %NULL to ignore
24980 * Forces a write of all user-space buffered data for the given
24981 * @stream. Will block during the operation. Closing the stream will
24982 * implicitly cause a flush.
24984 * This function is optional for inherited classes.
24986 * If @cancellable is not %NULL, then the operation can be cancelled by
24987 * triggering the cancellable object from another thread. If the operation
24988 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24990 * Returns: %TRUE on success, %FALSE on error
24995 * g_output_stream_flush_async:
24996 * @stream: a #GOutputStream.
24997 * @io_priority: the io priority of the request.
24998 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24999 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25000 * @user_data: (closure): the data to pass to callback function
25002 * Forces an asynchronous write of all user-space buffered data for
25003 * the given @stream.
25004 * For behaviour details see g_output_stream_flush().
25006 * When the operation is finished @callback will be
25007 * called. You can then call g_output_stream_flush_finish() to get the
25008 * result of the operation.
25013 * g_output_stream_flush_finish:
25014 * @stream: a #GOutputStream.
25015 * @result: a GAsyncResult.
25016 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25018 * Finishes flushing an output stream.
25020 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
25025 * g_output_stream_has_pending:
25026 * @stream: a #GOutputStream.
25028 * Checks if an ouput stream has pending actions.
25030 * Returns: %TRUE if @stream has pending actions.
25035 * g_output_stream_is_closed:
25036 * @stream: a #GOutputStream.
25038 * Checks if an output stream has already been closed.
25040 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
25045 * g_output_stream_is_closing:
25046 * @stream: a #GOutputStream.
25048 * Checks if an output stream is being closed. This can be
25049 * used inside e.g. a flush implementation to see if the
25050 * flush (or other i/o operation) is called from within
25051 * the closing operation.
25053 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
25059 * g_output_stream_set_pending:
25060 * @stream: a #GOutputStream.
25061 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25063 * Sets @stream to have actions pending. If the pending flag is
25064 * already set or @stream is closed, it will return %FALSE and set
25067 * Returns: %TRUE if pending was previously unset and is now set.
25072 * g_output_stream_splice:
25073 * @stream: a #GOutputStream.
25074 * @source: a #GInputStream.
25075 * @flags: a set of #GOutputStreamSpliceFlags.
25076 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25077 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25079 * Splices an input stream into an output stream.
25081 * Returns: a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced.
25086 * g_output_stream_splice_async:
25087 * @stream: a #GOutputStream.
25088 * @source: a #GInputStream.
25089 * @flags: a set of #GOutputStreamSpliceFlags.
25090 * @io_priority: the io priority of the request.
25091 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25092 * @callback: (scope async): a #GAsyncReadyCallback.
25093 * @user_data: (closure): user data passed to @callback.
25095 * Splices a stream asynchronously.
25096 * When the operation is finished @callback will be called.
25097 * You can then call g_output_stream_splice_finish() to get the
25098 * result of the operation.
25100 * For the synchronous, blocking version of this function, see
25101 * g_output_stream_splice().
25106 * g_output_stream_splice_finish:
25107 * @stream: a #GOutputStream.
25108 * @result: a #GAsyncResult.
25109 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25111 * Finishes an asynchronous stream splice operation.
25113 * Returns: a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced.
25118 * g_output_stream_write:
25119 * @stream: a #GOutputStream.
25120 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
25121 * @count: the number of bytes to write
25122 * @cancellable: (allow-none): optional cancellable object
25123 * @error: location to store the error occurring, or %NULL to ignore
25125 * Tries to write @count bytes from @buffer into the stream. Will block
25126 * during the operation.
25128 * If count is 0, returns 0 and does nothing. A value of @count
25129 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
25131 * On success, the number of bytes written to the stream is returned.
25132 * It is not an error if this is not the same as the requested size, as it
25133 * can happen e.g. on a partial I/O error, or if there is not enough
25134 * storage in the stream. All writes block until at least one byte
25135 * is written or an error occurs; 0 is never returned (unless
25138 * If @cancellable is not %NULL, then the operation can be cancelled by
25139 * triggering the cancellable object from another thread. If the operation
25140 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
25141 * operation was partially finished when the operation was cancelled the
25142 * partial result will be returned, without an error.
25144 * On error -1 is returned and @error is set accordingly.
25146 * Virtual: write_fn
25147 * Returns: Number of bytes written, or -1 on error
25152 * g_output_stream_write_all:
25153 * @stream: a #GOutputStream.
25154 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
25155 * @count: the number of bytes to write
25156 * @bytes_written: (out): location to store the number of bytes that was written to the stream
25157 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25158 * @error: location to store the error occurring, or %NULL to ignore
25160 * Tries to write @count bytes from @buffer into the stream. Will block
25161 * during the operation.
25163 * This function is similar to g_output_stream_write(), except it tries to
25164 * write as many bytes as requested, only stopping on an error.
25166 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
25167 * is set to @count.
25169 * If there is an error during the operation %FALSE is returned and @error
25170 * is set to indicate the error status, @bytes_written is updated to contain
25171 * the number of bytes written into the stream before the error occurred.
25173 * Returns: %TRUE on success, %FALSE if there was an error
25178 * g_output_stream_write_async:
25179 * @stream: A #GOutputStream.
25180 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
25181 * @count: the number of bytes to write
25182 * @io_priority: the io priority of the request.
25183 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25184 * @callback: (scope async): callback to call when the request is satisfied
25185 * @user_data: (closure): the data to pass to callback function
25187 * Request an asynchronous write of @count bytes from @buffer into
25188 * the stream. When the operation is finished @callback will be called.
25189 * You can then call g_output_stream_write_finish() to get the result of the
25192 * During an async request no other sync and async calls are allowed,
25193 * and will result in %G_IO_ERROR_PENDING errors.
25195 * A value of @count larger than %G_MAXSSIZE will cause a
25196 * %G_IO_ERROR_INVALID_ARGUMENT error.
25198 * On success, the number of bytes written will be passed to the
25199 * @callback. It is not an error if this is not the same as the
25200 * requested size, as it can happen e.g. on a partial I/O error,
25201 * but generally we try to write as many bytes as requested.
25203 * You are guaranteed that this method will never fail with
25204 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
25205 * method will just wait until this changes.
25207 * Any outstanding I/O request with higher priority (lower numerical
25208 * value) will be executed before an outstanding request with lower
25209 * priority. Default priority is %G_PRIORITY_DEFAULT.
25211 * The asyncronous methods have a default fallback that uses threads
25212 * to implement asynchronicity, so they are optional for inheriting
25213 * classes. However, if you override one you must override all.
25215 * For the synchronous, blocking version of this function, see
25216 * g_output_stream_write().
25221 * g_output_stream_write_bytes:
25222 * @stream: a #GOutputStream.
25223 * @bytes: the #GBytes to write
25224 * @cancellable: (allow-none): optional cancellable object
25225 * @error: location to store the error occurring, or %NULL to ignore
25227 * Tries to write the data from @bytes into the stream. Will block
25228 * during the operation.
25230 * If @bytes is 0-length, returns 0 and does nothing. A #GBytes larger
25231 * than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
25233 * On success, the number of bytes written to the stream is returned.
25234 * It is not an error if this is not the same as the requested size, as it
25235 * can happen e.g. on a partial I/O error, or if there is not enough
25236 * storage in the stream. All writes block until at least one byte
25237 * is written or an error occurs; 0 is never returned (unless
25238 * the size of @bytes is 0).
25240 * If @cancellable is not %NULL, then the operation can be cancelled by
25241 * triggering the cancellable object from another thread. If the operation
25242 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
25243 * operation was partially finished when the operation was cancelled the
25244 * partial result will be returned, without an error.
25246 * On error -1 is returned and @error is set accordingly.
25248 * Returns: Number of bytes written, or -1 on error
25253 * g_output_stream_write_bytes_async:
25254 * @stream: A #GOutputStream.
25255 * @bytes: The bytes to write
25256 * @io_priority: the io priority of the request.
25257 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25258 * @callback: (scope async): callback to call when the request is satisfied
25259 * @user_data: (closure): the data to pass to callback function
25261 * Request an asynchronous write of the data in @bytes to the stream.
25262 * When the operation is finished @callback will be called. You can
25263 * then call g_output_stream_write_bytes_finish() to get the result of
25266 * During an async request no other sync and async calls are allowed,
25267 * and will result in %G_IO_ERROR_PENDING errors.
25269 * A #GBytes larger than %G_MAXSSIZE will cause a
25270 * %G_IO_ERROR_INVALID_ARGUMENT error.
25272 * On success, the number of bytes written will be passed to the
25273 * @callback. It is not an error if this is not the same as the
25274 * requested size, as it can happen e.g. on a partial I/O error,
25275 * but generally we try to write as many bytes as requested.
25277 * You are guaranteed that this method will never fail with
25278 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
25279 * method will just wait until this changes.
25281 * Any outstanding I/O request with higher priority (lower numerical
25282 * value) will be executed before an outstanding request with lower
25283 * priority. Default priority is %G_PRIORITY_DEFAULT.
25285 * For the synchronous, blocking version of this function, see
25286 * g_output_stream_write_bytes().
25291 * g_output_stream_write_bytes_finish:
25292 * @stream: a #GOutputStream.
25293 * @result: a #GAsyncResult.
25294 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25296 * Finishes a stream write-from-#GBytes operation.
25298 * Returns: a #gssize containing the number of bytes written to the stream.
25303 * g_output_stream_write_finish:
25304 * @stream: a #GOutputStream.
25305 * @result: a #GAsyncResult.
25306 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25308 * Finishes a stream write operation.
25310 * Returns: a #gssize containing the number of bytes written to the stream.
25315 * g_permission_acquire:
25316 * @permission: a #GPermission instance
25317 * @cancellable: (allow-none): a #GCancellable, or %NULL
25318 * @error: a pointer to a %NULL #GError, or %NULL
25320 * Attempts to acquire the permission represented by @permission.
25322 * The precise method by which this happens depends on the permission
25323 * and the underlying authentication mechanism. A simple example is
25324 * that a dialog may appear asking the user to enter their password.
25326 * You should check with g_permission_get_can_acquire() before calling
25329 * If the permission is acquired then %TRUE is returned. Otherwise,
25330 * %FALSE is returned and @error is set appropriately.
25332 * This call is blocking, likely for a very long time (in the case that
25333 * user interaction is required). See g_permission_acquire_async() for
25334 * the non-blocking version.
25336 * Returns: %TRUE if the permission was successfully acquired
25342 * g_permission_acquire_async:
25343 * @permission: a #GPermission instance
25344 * @cancellable: (allow-none): a #GCancellable, or %NULL
25345 * @callback: the #GAsyncReadyCallback to call when done
25346 * @user_data: the user data to pass to @callback
25348 * Attempts to acquire the permission represented by @permission.
25350 * This is the first half of the asynchronous version of
25351 * g_permission_acquire().
25358 * g_permission_acquire_finish:
25359 * @permission: a #GPermission instance
25360 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
25361 * @error: a pointer to a %NULL #GError, or %NULL
25363 * Collects the result of attempting to acquire the permission
25364 * represented by @permission.
25366 * This is the second half of the asynchronous version of
25367 * g_permission_acquire().
25369 * Returns: %TRUE if the permission was successfully acquired
25375 * g_permission_get_allowed:
25376 * @permission: a #GPermission instance
25378 * Gets the value of the 'allowed' property. This property is %TRUE if
25379 * the caller currently has permission to perform the action that
25380 * @permission represents the permission to perform.
25382 * Returns: the value of the 'allowed' property
25388 * g_permission_get_can_acquire:
25389 * @permission: a #GPermission instance
25391 * Gets the value of the 'can-acquire' property. This property is %TRUE
25392 * if it is generally possible to acquire the permission by calling
25393 * g_permission_acquire().
25395 * Returns: the value of the 'can-acquire' property
25401 * g_permission_get_can_release:
25402 * @permission: a #GPermission instance
25404 * Gets the value of the 'can-release' property. This property is %TRUE
25405 * if it is generally possible to release the permission by calling
25406 * g_permission_release().
25408 * Returns: the value of the 'can-release' property
25414 * g_permission_impl_update:
25415 * @permission: a #GPermission instance
25416 * @allowed: the new value for the 'allowed' property
25417 * @can_acquire: the new value for the 'can-acquire' property
25418 * @can_release: the new value for the 'can-release' property
25420 * This function is called by the #GPermission implementation to update
25421 * the properties of the permission. You should never call this
25422 * function except from a #GPermission implementation.
25424 * GObject notify signals are generated, as appropriate.
25431 * g_permission_release:
25432 * @permission: a #GPermission instance
25433 * @cancellable: (allow-none): a #GCancellable, or %NULL
25434 * @error: a pointer to a %NULL #GError, or %NULL
25436 * Attempts to release the permission represented by @permission.
25438 * The precise method by which this happens depends on the permission
25439 * and the underlying authentication mechanism. In most cases the
25440 * permission will be dropped immediately without further action.
25442 * You should check with g_permission_get_can_release() before calling
25445 * If the permission is released then %TRUE is returned. Otherwise,
25446 * %FALSE is returned and @error is set appropriately.
25448 * This call is blocking, likely for a very long time (in the case that
25449 * user interaction is required). See g_permission_release_async() for
25450 * the non-blocking version.
25452 * Returns: %TRUE if the permission was successfully released
25458 * g_permission_release_async:
25459 * @permission: a #GPermission instance
25460 * @cancellable: (allow-none): a #GCancellable, or %NULL
25461 * @callback: the #GAsyncReadyCallback to call when done
25462 * @user_data: the user data to pass to @callback
25464 * Attempts to release the permission represented by @permission.
25466 * This is the first half of the asynchronous version of
25467 * g_permission_release().
25474 * g_permission_release_finish:
25475 * @permission: a #GPermission instance
25476 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
25477 * @error: a pointer to a %NULL #GError, or %NULL
25479 * Collects the result of attempting to release the permission
25480 * represented by @permission.
25482 * This is the second half of the asynchronous version of
25483 * g_permission_release().
25485 * Returns: %TRUE if the permission was successfully released
25491 * g_poll_file_monitor_new:
25494 * Polls @file for changes.
25496 * Returns: a new #GFileMonitor for the given #GFile.
25501 * g_pollable_input_stream_can_poll:
25502 * @stream: a #GPollableInputStream.
25504 * Checks if @stream is actually pollable. Some classes may implement
25505 * #GPollableInputStream but have only certain instances of that class
25506 * be pollable. If this method returns %FALSE, then the behavior of
25507 * other #GPollableInputStream methods is undefined.
25509 * For any given stream, the value returned by this method is constant;
25510 * a stream cannot switch from pollable to non-pollable or vice versa.
25512 * Returns: %TRUE if @stream is pollable, %FALSE if not.
25518 * g_pollable_input_stream_create_source:
25519 * @stream: a #GPollableInputStream.
25520 * @cancellable: (allow-none): a #GCancellable, or %NULL
25522 * Creates a #GSource that triggers when @stream can be read, or
25523 * @cancellable is triggered or an error occurs. The callback on the
25524 * source is of the #GPollableSourceFunc type.
25526 * As with g_pollable_input_stream_is_readable(), it is possible that
25527 * the stream may not actually be readable even after the source
25528 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
25529 * rather than g_input_stream_read() from the callback.
25531 * Returns: (transfer full): a new #GSource
25537 * g_pollable_input_stream_is_readable:
25538 * @stream: a #GPollableInputStream.
25540 * Checks if @stream can be read.
25542 * Note that some stream types may not be able to implement this 100%
25543 * reliably, and it is possible that a call to g_input_stream_read()
25544 * after this returns %TRUE would still block. To guarantee
25545 * non-blocking behavior, you should always use
25546 * g_pollable_input_stream_read_nonblocking(), which will return a
25547 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
25549 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error.
25555 * g_pollable_input_stream_read_nonblocking:
25556 * @stream: a #GPollableInputStream
25557 * @buffer: a buffer to read data into (which should be at least @count bytes long).
25558 * @count: the number of bytes you want to read
25559 * @cancellable: (allow-none): a #GCancellable, or %NULL
25560 * @error: #GError for error reporting, or %NULL to ignore.
25562 * Attempts to read up to @count bytes from @stream into @buffer, as
25563 * with g_input_stream_read(). If @stream is not currently readable,
25564 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
25565 * use g_pollable_input_stream_create_source() to create a #GSource
25566 * that will be triggered when @stream is readable.
25568 * Note that since this method never blocks, you cannot actually
25569 * use @cancellable to cancel it. However, it will return an error
25570 * if @cancellable has already been cancelled when you call, which
25571 * may happen if you call this method after a source triggers due
25572 * to having been cancelled.
25574 * Virtual: read_nonblocking
25575 * Returns: the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK).
25580 * g_pollable_output_stream_can_poll:
25581 * @stream: a #GPollableOutputStream.
25583 * Checks if @stream is actually pollable. Some classes may implement
25584 * #GPollableOutputStream but have only certain instances of that
25585 * class be pollable. If this method returns %FALSE, then the behavior
25586 * of other #GPollableOutputStream methods is undefined.
25588 * For any given stream, the value returned by this method is constant;
25589 * a stream cannot switch from pollable to non-pollable or vice versa.
25591 * Returns: %TRUE if @stream is pollable, %FALSE if not.
25597 * g_pollable_output_stream_create_source:
25598 * @stream: a #GPollableOutputStream.
25599 * @cancellable: (allow-none): a #GCancellable, or %NULL
25601 * Creates a #GSource that triggers when @stream can be written, or
25602 * @cancellable is triggered or an error occurs. The callback on the
25603 * source is of the #GPollableSourceFunc type.
25605 * As with g_pollable_output_stream_is_writable(), it is possible that
25606 * the stream may not actually be writable even after the source
25607 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
25608 * rather than g_output_stream_write() from the callback.
25610 * Returns: (transfer full): a new #GSource
25616 * g_pollable_output_stream_is_writable:
25617 * @stream: a #GPollableOutputStream.
25619 * Checks if @stream can be written.
25621 * Note that some stream types may not be able to implement this 100%
25622 * reliably, and it is possible that a call to g_output_stream_write()
25623 * after this returns %TRUE would still block. To guarantee
25624 * non-blocking behavior, you should always use
25625 * g_pollable_output_stream_write_nonblocking(), which will return a
25626 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
25628 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error.
25634 * g_pollable_output_stream_write_nonblocking:
25635 * @stream: a #GPollableOutputStream
25636 * @buffer: (array length=count) (element-type guint8): a buffer to write data from
25637 * @count: the number of bytes you want to write
25638 * @cancellable: (allow-none): a #GCancellable, or %NULL
25639 * @error: #GError for error reporting, or %NULL to ignore.
25641 * Attempts to write up to @count bytes from @buffer to @stream, as
25642 * with g_output_stream_write(). If @stream is not currently writable,
25643 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
25644 * use g_pollable_output_stream_create_source() to create a #GSource
25645 * that will be triggered when @stream is writable.
25647 * Note that since this method never blocks, you cannot actually
25648 * use @cancellable to cancel it. However, it will return an error
25649 * if @cancellable has already been cancelled when you call, which
25650 * may happen if you call this method after a source triggers due
25651 * to having been cancelled.
25653 * Virtual: write_nonblocking
25654 * Returns: the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK).
25659 * g_pollable_source_new:
25660 * @pollable_stream: the stream associated with the new source
25662 * Utility method for #GPollableInputStream and #GPollableOutputStream
25663 * implementations. Creates a new #GSource that expects a callback of
25664 * type #GPollableSourceFunc. The new source does not actually do
25665 * anything on its own; use g_source_add_child_source() to add other
25666 * sources to it to cause it to trigger.
25668 * Returns: (transfer full): the new #GSource.
25674 * g_pollable_source_new_full:
25675 * @pollable_stream: (type GObject): the stream associated with the new source
25676 * @child_source: (allow-none): optional child source to attach
25677 * @cancellable: (allow-none): optional #GCancellable to attach
25679 * Utility method for #GPollableInputStream and #GPollableOutputStream
25680 * implementations. Creates a new #GSource, as with
25681 * g_pollable_source_new(), but also attaching @child_source (with a
25682 * dummy callback), and @cancellable, if they are non-%NULL.
25684 * Returns: (transfer full): the new #GSource.
25690 * g_pollable_stream_read:
25691 * @stream: a #GInputStream
25692 * @buffer: a buffer to read data into
25693 * @count: the number of bytes to read
25694 * @blocking: whether to do blocking I/O
25695 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25696 * @error: location to store the error occurring, or %NULL to ignore
25698 * Tries to read from @stream, as with g_input_stream_read() (if
25699 * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
25700 * (if @blocking is %FALSE). This can be used to more easily share
25701 * code between blocking and non-blocking implementations of a method.
25703 * If @blocking is %FALSE, then @stream must be a
25704 * #GPollableInputStream for which g_pollable_input_stream_can_poll()
25705 * returns %TRUE, or else the behavior is undefined. If @blocking is
25706 * %TRUE, then @stream does not need to be a #GPollableInputStream.
25708 * Returns: the number of bytes read, or -1 on error.
25714 * g_pollable_stream_write:
25715 * @stream: a #GOutputStream.
25716 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
25717 * @count: the number of bytes to write
25718 * @blocking: whether to do blocking I/O
25719 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25720 * @error: location to store the error occurring, or %NULL to ignore
25722 * Tries to write to @stream, as with g_output_stream_write() (if
25723 * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
25724 * (if @blocking is %FALSE). This can be used to more easily share
25725 * code between blocking and non-blocking implementations of a method.
25727 * If @blocking is %FALSE, then @stream must be a
25728 * #GPollableOutputStream for which
25729 * g_pollable_output_stream_can_poll() returns %TRUE or else the
25730 * behavior is undefined. If @blocking is %TRUE, then @stream does not
25731 * need to be a #GPollableOutputStream.
25733 * Returns: the number of bytes written, or -1 on error.
25739 * g_pollable_stream_write_all:
25740 * @stream: a #GOutputStream.
25741 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
25742 * @count: the number of bytes to write
25743 * @blocking: whether to do blocking I/O
25744 * @bytes_written: (out): location to store the number of bytes that was written to the stream
25745 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25746 * @error: location to store the error occurring, or %NULL to ignore
25748 * Tries to write @count bytes to @stream, as with
25749 * g_output_stream_write_all(), but using g_pollable_stream_write()
25750 * rather than g_output_stream_write().
25752 * On a successful write of @count bytes, %TRUE is returned, and
25753 * @bytes_written is set to @count.
25755 * If there is an error during the operation (including
25756 * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
25757 * returned and @error is set to indicate the error status,
25758 * @bytes_written is updated to contain the number of bytes written
25759 * into the stream before the error occurred.
25761 * As with g_pollable_stream_write(), if @blocking is %FALSE, then
25762 * @stream must be a #GPollableOutputStream for which
25763 * g_pollable_output_stream_can_poll() returns %TRUE or else the
25764 * behavior is undefined. If @blocking is %TRUE, then @stream does not
25765 * need to be a #GPollableOutputStream.
25767 * Returns: %TRUE on success, %FALSE if there was an error
25773 * g_proxy_address_get_destination_hostname:
25774 * @proxy: a #GProxyAddress
25776 * Gets @proxy's destination hostname; that is, the name of the host
25777 * that will be connected to via the proxy, not the name of the proxy
25780 * Returns: the @proxy's destination hostname
25786 * g_proxy_address_get_destination_port:
25787 * @proxy: a #GProxyAddress
25789 * Gets @proxy's destination port; that is, the port on the
25790 * destination host that will be connected to via the proxy, not the
25791 * port number of the proxy itself.
25793 * Returns: the @proxy's destination port
25799 * g_proxy_address_get_destination_protocol:
25800 * @proxy: a #GProxyAddress
25802 * Gets the protocol that is being spoken to the destination
25803 * server; eg, "http" or "ftp".
25805 * Returns: the @proxy's destination protocol
25811 * g_proxy_address_get_password:
25812 * @proxy: a #GProxyAddress
25814 * Gets @proxy's password.
25816 * Returns: the @proxy's password
25822 * g_proxy_address_get_protocol:
25823 * @proxy: a #GProxyAddress
25825 * Gets @proxy's protocol. eg, "socks" or "http"
25827 * Returns: the @proxy's protocol
25833 * g_proxy_address_get_uri:
25834 * @proxy: a #GProxyAddress
25836 * Gets the proxy URI that @proxy was constructed from.
25838 * Returns: the @proxy's URI, or %NULL if unknown
25844 * g_proxy_address_get_username:
25845 * @proxy: a #GProxyAddress
25847 * Gets @proxy's username.
25849 * Returns: the @proxy's username
25855 * g_proxy_address_new:
25856 * @inetaddr: The proxy server #GInetAddress.
25857 * @port: The proxy server port.
25858 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
25859 * @dest_hostname: The destination hostname the proxy should tunnel to.
25860 * @dest_port: The destination port to tunnel to.
25861 * @username: (allow-none): The username to authenticate to the proxy server (or %NULL).
25862 * @password: (allow-none): The password to authenticate to the proxy server (or %NULL).
25864 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
25865 * tunnel through @dest_hostname and @dest_port.
25867 * (Note that this method doesn't set the #GProxyAddress:uri or
25868 * #GProxyAddress:destination-protocol fields; use g_object_new()
25869 * directly if you want to set those.)
25871 * Returns: a new #GProxyAddress
25878 * @proxy: a #GProxy
25879 * @connection: a #GIOStream
25880 * @proxy_address: a #GProxyAddress
25881 * @cancellable: (allow-none): a #GCancellable
25882 * @error: return #GError
25884 * Given @connection to communicate with a proxy (eg, a
25885 * #GSocketConnection that is connected to the proxy server), this
25886 * does the necessary handshake to connect to @proxy_address, and if
25887 * required, wraps the #GIOStream to handle proxy payload.
25889 * Returns: (transfer full): a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added.
25895 * g_proxy_connect_async:
25896 * @proxy: a #GProxy
25897 * @connection: a #GIOStream
25898 * @proxy_address: a #GProxyAddress
25899 * @cancellable: (allow-none): a #GCancellable
25900 * @callback: (scope async): a #GAsyncReadyCallback
25901 * @user_data: (closure): callback data
25903 * Asynchronous version of g_proxy_connect().
25910 * g_proxy_connect_finish:
25911 * @proxy: a #GProxy
25912 * @result: a #GAsyncResult
25913 * @error: return #GError
25915 * See g_proxy_connect().
25917 * Returns: (transfer full): a #GIOStream.
25923 * g_proxy_get_default_for_protocol:
25924 * @protocol: the proxy protocol name (e.g. http, socks, etc)
25926 * Lookup "gio-proxy" extension point for a proxy implementation that supports
25927 * specified protocol.
25929 * Returns: (transfer full): return a #GProxy or NULL if protocol is not supported.
25935 * g_proxy_resolver_get_default:
25937 * Gets the default #GProxyResolver for the system.
25939 * Returns: (transfer none): the default #GProxyResolver.
25945 * g_proxy_resolver_is_supported:
25946 * @resolver: a #GProxyResolver
25948 * Checks if @resolver can be used on this system. (This is used
25949 * internally; g_proxy_resolver_get_default() will only return a proxy
25950 * resolver that returns %TRUE for this method.)
25952 * Returns: %TRUE if @resolver is supported.
25958 * g_proxy_resolver_lookup:
25959 * @resolver: a #GProxyResolver
25960 * @uri: a URI representing the destination to connect to
25961 * @cancellable: (allow-none): a #GCancellable, or %NULL
25962 * @error: return location for a #GError, or %NULL
25964 * Looks into the system proxy configuration to determine what proxy,
25965 * if any, to use to connect to @uri. The returned proxy URIs are of the
25966 * form <literal><protocol>://[user[:password]@]host:port</literal>
25967 * or <literal>direct://</literal>, where <protocol> could be
25968 * http, rtsp, socks or other proxying protocol.
25970 * If you don't know what network protocol is being used on the
25971 * socket, you should use <literal>none</literal> as the URI protocol.
25972 * In this case, the resolver might still return a generic proxy type
25973 * (such as SOCKS), but would not return protocol-specific proxy types
25976 * <literal>direct://</literal> is used when no proxy is needed.
25977 * Direct connection should not be attempted unless it is part of the
25978 * returned array of proxies.
25980 * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev().
25986 * g_proxy_resolver_lookup_async:
25987 * @resolver: a #GProxyResolver
25988 * @uri: a URI representing the destination to connect to
25989 * @cancellable: (allow-none): a #GCancellable, or %NULL
25990 * @callback: (scope async): callback to call after resolution completes
25991 * @user_data: (closure): data for @callback
25993 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
26001 * g_proxy_resolver_lookup_finish:
26002 * @resolver: a #GProxyResolver
26003 * @result: the result passed to your #GAsyncReadyCallback
26004 * @error: return location for a #GError, or %NULL
26006 * Call this function to obtain the array of proxy URIs when
26007 * g_proxy_resolver_lookup_async() is complete. See
26008 * g_proxy_resolver_lookup() for more details.
26010 * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev().
26016 * g_proxy_supports_hostname:
26017 * @proxy: a #GProxy
26019 * Some proxy protocols expect to be passed a hostname, which they
26020 * will resolve to an IP address themselves. Others, like SOCKS4, do
26021 * not allow this. This function will return %FALSE if @proxy is
26022 * implementing such a protocol. When %FALSE is returned, the caller
26023 * should resolve the destination hostname first, and then pass a
26024 * #GProxyAddress containing the stringified IP address to
26025 * g_proxy_connect() or g_proxy_connect_async().
26027 * Returns: %TRUE if hostname resolution is supported.
26033 * g_remote_action_group_activate_action_full:
26034 * @remote: a #GDBusActionGroup
26035 * @action_name: the name of the action to activate
26036 * @parameter: (allow-none): the optional parameter to the activation
26037 * @platform_data: the platform data to send
26039 * Activates the remote action.
26041 * This is the same as g_action_group_activate_action() except that it
26042 * allows for provision of "platform data" to be sent along with the
26043 * activation request. This typically contains details such as the user
26044 * interaction timestamp or startup notification information.
26046 * @platform_data must be non-%NULL and must have the type
26047 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
26054 * g_remote_action_group_change_action_state_full:
26055 * @remote: a #GRemoteActionGroup
26056 * @action_name: the name of the action to change the state of
26057 * @value: the new requested value for the state
26058 * @platform_data: the platform data to send
26060 * Changes the state of a remote action.
26062 * This is the same as g_action_group_change_action_state() except that
26063 * it allows for provision of "platform data" to be sent along with the
26064 * state change request. This typically contains details such as the
26065 * user interaction timestamp or startup notification information.
26067 * @platform_data must be non-%NULL and must have the type
26068 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
26075 * g_resolver_error_quark:
26077 * Gets the #GResolver Error Quark.
26079 * Returns: a #GQuark.
26085 * g_resolver_free_addresses: (skip)
26086 * @addresses: a #GList of #GInetAddress
26088 * Frees @addresses (which should be the return value from
26089 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
26090 * (This is a convenience method; you can also simply free the results
26098 * g_resolver_free_targets: (skip)
26099 * @targets: a #GList of #GSrvTarget
26101 * Frees @targets (which should be the return value from
26102 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
26103 * (This is a convenience method; you can also simply free the
26104 * results by hand.)
26111 * g_resolver_get_default:
26113 * Gets the default #GResolver. You should unref it when you are done
26114 * with it. #GResolver may use its reference count as a hint about how
26115 * many threads it should allocate for concurrent DNS resolutions.
26117 * Returns: (transfer full): the default #GResolver.
26123 * g_resolver_lookup_by_address:
26124 * @resolver: a #GResolver
26125 * @address: the address to reverse-resolve
26126 * @cancellable: (allow-none): a #GCancellable, or %NULL
26127 * @error: return location for a #GError, or %NULL
26129 * Synchronously reverse-resolves @address to determine its
26130 * associated hostname.
26132 * If the DNS resolution fails, @error (if non-%NULL) will be set to
26133 * a value from #GResolverError.
26135 * If @cancellable is non-%NULL, it can be used to cancel the
26136 * operation, in which case @error (if non-%NULL) will be set to
26137 * %G_IO_ERROR_CANCELLED.
26139 * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error.
26145 * g_resolver_lookup_by_address_async:
26146 * @resolver: a #GResolver
26147 * @address: the address to reverse-resolve
26148 * @cancellable: (allow-none): a #GCancellable, or %NULL
26149 * @callback: (scope async): callback to call after resolution completes
26150 * @user_data: (closure): data for @callback
26152 * Begins asynchronously reverse-resolving @address to determine its
26153 * associated hostname, and eventually calls @callback, which must
26154 * call g_resolver_lookup_by_address_finish() to get the final result.
26161 * g_resolver_lookup_by_address_finish:
26162 * @resolver: a #GResolver
26163 * @result: the result passed to your #GAsyncReadyCallback
26164 * @error: return location for a #GError, or %NULL
26166 * Retrieves the result of a previous call to
26167 * g_resolver_lookup_by_address_async().
26169 * If the DNS resolution failed, @error (if non-%NULL) will be set to
26170 * a value from #GResolverError. If the operation was cancelled,
26171 * @error will be set to %G_IO_ERROR_CANCELLED.
26173 * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error.
26179 * g_resolver_lookup_by_name:
26180 * @resolver: a #GResolver
26181 * @hostname: the hostname to look up
26182 * @cancellable: (allow-none): a #GCancellable, or %NULL
26183 * @error: return location for a #GError, or %NULL
26185 * Synchronously resolves @hostname to determine its associated IP
26186 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
26187 * the textual form of an IP address (in which case this just becomes
26188 * a wrapper around g_inet_address_new_from_string()).
26190 * On success, g_resolver_lookup_by_name() will return a #GList of
26191 * #GInetAddress, sorted in order of preference and guaranteed to not
26192 * contain duplicates. That is, if using the result to connect to
26193 * @hostname, you should attempt to connect to the first address
26194 * first, then the second if the first fails, etc. If you are using
26195 * the result to listen on a socket, it is appropriate to add each
26196 * result using e.g. g_socket_listener_add_address().
26198 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
26199 * value from #GResolverError.
26201 * If @cancellable is non-%NULL, it can be used to cancel the
26202 * operation, in which case @error (if non-%NULL) will be set to
26203 * %G_IO_ERROR_CANCELLED.
26205 * If you are planning to connect to a socket on the resolved IP
26206 * address, it may be easier to create a #GNetworkAddress and use its
26207 * #GSocketConnectable interface.
26209 * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.)
26215 * g_resolver_lookup_by_name_async:
26216 * @resolver: a #GResolver
26217 * @hostname: the hostname to look up the address of
26218 * @cancellable: (allow-none): a #GCancellable, or %NULL
26219 * @callback: (scope async): callback to call after resolution completes
26220 * @user_data: (closure): data for @callback
26222 * Begins asynchronously resolving @hostname to determine its
26223 * associated IP address(es), and eventually calls @callback, which
26224 * must call g_resolver_lookup_by_name_finish() to get the result.
26225 * See g_resolver_lookup_by_name() for more details.
26232 * g_resolver_lookup_by_name_finish:
26233 * @resolver: a #GResolver
26234 * @result: the result passed to your #GAsyncReadyCallback
26235 * @error: return location for a #GError, or %NULL
26237 * Retrieves the result of a call to
26238 * g_resolver_lookup_by_name_async().
26240 * If the DNS resolution failed, @error (if non-%NULL) will be set to
26241 * a value from #GResolverError. If the operation was cancelled,
26242 * @error will be set to %G_IO_ERROR_CANCELLED.
26244 * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details.
26250 * g_resolver_lookup_records:
26251 * @resolver: a #GResolver
26252 * @rrname: the DNS name to lookup the record for
26253 * @record_type: the type of DNS record to lookup
26254 * @cancellable: (allow-none): a #GCancellable, or %NULL
26255 * @error: return location for a #GError, or %NULL
26257 * Synchronously performs a DNS record lookup for the given @rrname and returns
26258 * a list of records as #GVariant tuples. See #GResolverRecordType for
26259 * information on what the records contain for each @record_type.
26261 * If the DNS resolution fails, @error (if non-%NULL) will be set to
26262 * a value from #GResolverError.
26264 * If @cancellable is non-%NULL, it can be used to cancel the
26265 * operation, in which case @error (if non-%NULL) will be set to
26266 * %G_IO_ERROR_CANCELLED.
26268 * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
26274 * g_resolver_lookup_records_async:
26275 * @resolver: a #GResolver
26276 * @rrname: the DNS name to lookup the record for
26277 * @record_type: the type of DNS record to lookup
26278 * @cancellable: (allow-none): a #GCancellable, or %NULL
26279 * @callback: (scope async): callback to call after resolution completes
26280 * @user_data: (closure): data for @callback
26282 * Begins asynchronously performing a DNS lookup for the given
26283 * @rrname, and eventually calls @callback, which must call
26284 * g_resolver_lookup_records_finish() to get the final result. See
26285 * g_resolver_lookup_records() for more details.
26292 * g_resolver_lookup_records_finish:
26293 * @resolver: a #GResolver
26294 * @result: the result passed to your #GAsyncReadyCallback
26295 * @error: return location for a #GError, or %NULL
26297 * Retrieves the result of a previous call to
26298 * g_resolver_lookup_records_async(). Returns a list of records as #GVariant
26299 * tuples. See #GResolverRecordType for information on what the records contain.
26301 * If the DNS resolution failed, @error (if non-%NULL) will be set to
26302 * a value from #GResolverError. If the operation was cancelled,
26303 * @error will be set to %G_IO_ERROR_CANCELLED.
26305 * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
26311 * g_resolver_lookup_service:
26312 * @resolver: a #GResolver
26313 * @service: the service type to look up (eg, "ldap")
26314 * @protocol: the networking protocol to use for @service (eg, "tcp")
26315 * @domain: the DNS domain to look up the service in
26316 * @cancellable: (allow-none): a #GCancellable, or %NULL
26317 * @error: return location for a #GError, or %NULL
26319 * Synchronously performs a DNS SRV lookup for the given @service and
26320 * @protocol in the given @domain and returns an array of #GSrvTarget.
26321 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
26322 * @service and @protocol arguments <emphasis>do not</emphasis>
26323 * include the leading underscore that appears in the actual DNS
26326 * On success, g_resolver_lookup_service() will return a #GList of
26327 * #GSrvTarget, sorted in order of preference. (That is, you should
26328 * attempt to connect to the first target first, then the second if
26329 * the first fails, etc.)
26331 * If the DNS resolution fails, @error (if non-%NULL) will be set to
26332 * a value from #GResolverError.
26334 * If @cancellable is non-%NULL, it can be used to cancel the
26335 * operation, in which case @error (if non-%NULL) will be set to
26336 * %G_IO_ERROR_CANCELLED.
26338 * If you are planning to connect to the service, it is usually easier
26339 * to create a #GNetworkService and use its #GSocketConnectable
26342 * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.)
26348 * g_resolver_lookup_service_async:
26349 * @resolver: a #GResolver
26350 * @service: the service type to look up (eg, "ldap")
26351 * @protocol: the networking protocol to use for @service (eg, "tcp")
26352 * @domain: the DNS domain to look up the service in
26353 * @cancellable: (allow-none): a #GCancellable, or %NULL
26354 * @callback: (scope async): callback to call after resolution completes
26355 * @user_data: (closure): data for @callback
26357 * Begins asynchronously performing a DNS SRV lookup for the given
26358 * @service and @protocol in the given @domain, and eventually calls
26359 * @callback, which must call g_resolver_lookup_service_finish() to
26360 * get the final result. See g_resolver_lookup_service() for more
26368 * g_resolver_lookup_service_finish:
26369 * @resolver: a #GResolver
26370 * @result: the result passed to your #GAsyncReadyCallback
26371 * @error: return location for a #GError, or %NULL
26373 * Retrieves the result of a previous call to
26374 * g_resolver_lookup_service_async().
26376 * If the DNS resolution failed, @error (if non-%NULL) will be set to
26377 * a value from #GResolverError. If the operation was cancelled,
26378 * @error will be set to %G_IO_ERROR_CANCELLED.
26380 * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details.
26386 * g_resolver_set_default:
26387 * @resolver: the new default #GResolver
26389 * Sets @resolver to be the application's default resolver (reffing
26390 * @resolver, and unreffing the previous default resolver, if any).
26391 * Future calls to g_resolver_get_default() will return this resolver.
26393 * This can be used if an application wants to perform any sort of DNS
26394 * caching or "pinning"; it can implement its own #GResolver that
26395 * calls the original default resolver for DNS operations, and
26396 * implements its own cache policies on top of that, and then set
26397 * itself as the default resolver for all later code to use.
26404 * g_resource_enumerate_children:
26405 * @resource: A #GResource
26406 * @path: A pathname inside the resource
26407 * @lookup_flags: A #GResourceLookupFlags
26408 * @error: return location for a #GError, or %NULL
26410 * Returns all the names of children at the specified @path in the resource.
26411 * The return result is a %NULL terminated list of strings which should
26412 * be released with g_strfreev().
26414 * @lookup_flags controls the behaviour of the lookup.
26416 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
26422 * g_resource_error_quark:
26424 * Gets the #GResource Error Quark.
26426 * Returns: a #GQuark
26432 * g_resource_get_info:
26433 * @resource: A #GResource
26434 * @path: A pathname inside the resource
26435 * @lookup_flags: A #GResourceLookupFlags
26436 * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
26437 * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed
26438 * @error: return location for a #GError, or %NULL
26440 * Looks for a file at the specified @path in the resource and
26441 * if found returns information about it.
26443 * @lookup_flags controls the behaviour of the lookup.
26445 * Returns: %TRUE if the file was found. %FALSE if there were errors
26452 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
26453 * @error: return location for a #GError, or %NULL
26455 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
26456 * you to query it for data.
26458 * If you want to use this resource in the global resource namespace you need
26459 * to register it with g_resources_register().
26461 * Returns: (transfer full): a new #GResource, or %NULL on error
26467 * g_resource_lookup_data:
26468 * @resource: A #GResource
26469 * @path: A pathname inside the resource
26470 * @lookup_flags: A #GResourceLookupFlags
26471 * @error: return location for a #GError, or %NULL
26473 * Looks for a file at the specified @path in the resource and
26474 * returns a #GBytes that lets you directly access the data in
26477 * The data is always followed by a zero byte, so you
26478 * can safely use the data as a C string. However, that byte
26479 * is not included in the size of the GBytes.
26481 * For uncompressed resource files this is a pointer directly into
26482 * the resource bundle, which is typically in some readonly data section
26483 * in the program binary. For compressed files we allocate memory on
26484 * the heap and automatically uncompress the data.
26486 * @lookup_flags controls the behaviour of the lookup.
26488 * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref()
26494 * g_resource_new_from_data:
26496 * @error: return location for a #GError, or %NULL
26498 * Creates a GResource from a reference to the binary resource bundle.
26499 * This will keep a reference to @data while the resource lives, so
26500 * the data should not be modified or freed.
26502 * If you want to use this resource in the global resource namespace you need
26503 * to register it with g_resources_register().
26505 * Returns: (transfer full): a new #GResource, or %NULL on error
26511 * g_resource_open_stream:
26512 * @resource: A #GResource
26513 * @path: A pathname inside the resource
26514 * @lookup_flags: A #GResourceLookupFlags
26515 * @error: return location for a #GError, or %NULL
26517 * Looks for a file at the specified @path in the resource and
26518 * returns a #GInputStream that lets you read the data.
26520 * @lookup_flags controls the behaviour of the lookup.
26522 * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref()
26529 * @resource: A #GResource
26531 * Atomically increments the reference count of @array by one. This
26532 * function is MT-safe and may be called from any thread.
26534 * Returns: The passed in #GResource
26540 * g_resource_unref:
26541 * @resource: A #GResource
26543 * Atomically decrements the reference count of @resource by one. If the
26544 * reference count drops to 0, all memory allocated by the array is
26545 * released. This function is MT-safe and may be called from any
26553 * g_resources_enumerate_children:
26554 * @path: A pathname inside the resource
26555 * @lookup_flags: A #GResourceLookupFlags
26556 * @error: return location for a #GError, or %NULL
26558 * Returns all the names of children at the specified @path in the set of
26559 * globally registered resources.
26560 * The return result is a %NULL terminated list of strings which should
26561 * be released with g_strfreev().
26563 * @lookup_flags controls the behaviour of the lookup.
26565 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
26571 * g_resources_get_info:
26572 * @path: A pathname inside the resource
26573 * @lookup_flags: A #GResourceLookupFlags
26574 * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
26575 * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed
26576 * @error: return location for a #GError, or %NULL
26578 * Looks for a file at the specified @path in the set of
26579 * globally registered resources and if found returns information about it.
26581 * @lookup_flags controls the behaviour of the lookup.
26583 * Returns: %TRUE if the file was found. %FALSE if there were errors
26589 * g_resources_lookup_data:
26590 * @path: A pathname inside the resource
26591 * @lookup_flags: A #GResourceLookupFlags
26592 * @error: return location for a #GError, or %NULL
26594 * Looks for a file at the specified @path in the set of
26595 * globally registered resources and returns a #GBytes that
26596 * lets you directly access the data in memory.
26598 * The data is always followed by a zero byte, so you
26599 * can safely use the data as a C string. However, that byte
26600 * is not included in the size of the GBytes.
26602 * For uncompressed resource files this is a pointer directly into
26603 * the resource bundle, which is typically in some readonly data section
26604 * in the program binary. For compressed files we allocate memory on
26605 * the heap and automatically uncompress the data.
26607 * @lookup_flags controls the behaviour of the lookup.
26609 * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref()
26615 * g_resources_open_stream:
26616 * @path: A pathname inside the resource
26617 * @lookup_flags: A #GResourceLookupFlags
26618 * @error: return location for a #GError, or %NULL
26620 * Looks for a file at the specified @path in the set of
26621 * globally registered resources and returns a #GInputStream
26622 * that lets you read the data.
26624 * @lookup_flags controls the behaviour of the lookup.
26626 * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref()
26632 * g_resources_register:
26633 * @resource: A #GResource
26635 * Registers the resource with the process-global set of resources.
26636 * Once a resource is registered the files in it can be accessed
26637 * with the global resource lookup functions like g_resources_lookup_data().
26644 * g_resources_unregister:
26645 * @resource: A #GResource
26647 * Unregisters the resource from the process-global set of resources.
26654 * g_seekable_can_seek:
26655 * @seekable: a #GSeekable.
26657 * Tests if the stream supports the #GSeekableIface.
26659 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
26664 * g_seekable_can_truncate:
26665 * @seekable: a #GSeekable.
26667 * Tests if the stream can be truncated.
26669 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
26675 * @seekable: a #GSeekable.
26676 * @offset: a #goffset.
26677 * @type: a #GSeekType.
26678 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26679 * @error: a #GError location to store the error occurring, or %NULL to ignore.
26681 * Seeks in the stream by the given @offset, modified by @type.
26683 * If @cancellable is not %NULL, then the operation can be cancelled by
26684 * triggering the cancellable object from another thread. If the operation
26685 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
26687 * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
26693 * @seekable: a #GSeekable.
26695 * Tells the current position within the stream.
26697 * Returns: the offset from the beginning of the buffer.
26702 * g_seekable_truncate:
26703 * @seekable: a #GSeekable.
26704 * @offset: a #goffset.
26705 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26706 * @error: a #GError location to store the error occurring, or %NULL to ignore.
26708 * Truncates a stream with a given #offset.
26710 * If @cancellable is not %NULL, then the operation can be cancelled by
26711 * triggering the cancellable object from another thread. If the operation
26712 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
26713 * operation was partially finished when the operation was cancelled the
26714 * partial result will be returned, without an error.
26716 * Virtual: truncate_fn
26717 * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
26722 * g_settings_apply:
26723 * @settings: a #GSettings instance
26725 * Applies any changes that have been made to the settings. This
26726 * function does nothing unless @settings is in 'delay-apply' mode;
26727 * see g_settings_delay(). In the normal case settings are always
26728 * applied immediately.
26733 * g_settings_backend_changed:
26734 * @backend: a #GSettingsBackend implementation
26735 * @key: the name of the key
26736 * @origin_tag: the origin tag
26738 * Signals that a single key has possibly changed. Backend
26739 * implementations should call this if a key has possibly changed its
26742 * @key must be a valid key (ie starting with a slash, not containing
26743 * '//', and not ending with a slash).
26745 * The implementation must call this function during any call to
26746 * g_settings_backend_write(), before the call returns (except in the
26747 * case that no keys are actually changed and it cares to detect this
26748 * fact). It may not rely on the existence of a mainloop for
26749 * dispatching the signal later.
26751 * The implementation may call this function at any other time it likes
26752 * in response to other events (such as changes occurring outside of the
26753 * program). These calls may originate from a mainloop or may originate
26754 * in response to any other action (including from calls to
26755 * g_settings_backend_write()).
26757 * In the case that this call is in response to a call to
26758 * g_settings_backend_write() then @origin_tag must be set to the same
26759 * value that was passed to that call.
26766 * g_settings_backend_changed_tree:
26767 * @backend: a #GSettingsBackend implementation
26768 * @tree: a #GTree containing the changes
26769 * @origin_tag: the origin tag
26771 * This call is a convenience wrapper. It gets the list of changes from
26772 * @tree, computes the longest common prefix and calls
26773 * g_settings_backend_changed().
26780 * g_settings_backend_flatten_tree:
26781 * @tree: a #GTree containing the changes
26782 * @path: (out): the location to save the path
26783 * @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys
26784 * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL
26786 * Calculate the longest common prefix of all keys in a tree and write
26787 * out an array of the key names relative to that prefix and,
26788 * optionally, the value to store at each of those keys.
26790 * You must free the value returned in @path, @keys and @values using
26791 * g_free(). You should not attempt to free or unref the contents of
26792 * @keys or @values.
26799 * g_settings_backend_get_default:
26801 * Returns the default #GSettingsBackend. It is possible to override
26802 * the default by setting the <envar>GSETTINGS_BACKEND</envar>
26803 * environment variable to the name of a settings backend.
26805 * The user gets a reference to the backend.
26807 * Returns: (transfer full): the default #GSettingsBackend
26813 * g_settings_backend_keys_changed:
26814 * @backend: a #GSettingsBackend implementation
26815 * @path: the path containing the changes
26816 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
26817 * @origin_tag: the origin tag
26819 * Signals that a list of keys have possibly changed. Backend
26820 * implementations should call this if keys have possibly changed their
26823 * @path must be a valid path (ie starting and ending with a slash and
26824 * not containing '//'). Each string in @items must form a valid key
26825 * name when @path is prefixed to it (ie: each item must not start or
26826 * end with '/' and must not contain '//').
26828 * The meaning of this signal is that any of the key names resulting
26829 * from the contatenation of @path with each item in @items may have
26832 * The same rules for when notifications must occur apply as per
26833 * g_settings_backend_changed(). These two calls can be used
26834 * interchangeably if exactly one item has changed (although in that
26835 * case g_settings_backend_changed() is definitely preferred).
26837 * For efficiency reasons, the implementation should strive for @path to
26838 * be as long as possible (ie: the longest common prefix of all of the
26839 * keys that were changed) but this is not strictly required.
26846 * g_settings_backend_path_changed:
26847 * @backend: a #GSettingsBackend implementation
26848 * @path: the path containing the changes
26849 * @origin_tag: the origin tag
26851 * Signals that all keys below a given path may have possibly changed.
26852 * Backend implementations should call this if an entire path of keys
26853 * have possibly changed their values.
26855 * @path must be a valid path (ie starting and ending with a slash and
26856 * not containing '//').
26858 * The meaning of this signal is that any of the key which has a name
26859 * starting with @path may have changed.
26861 * The same rules for when notifications must occur apply as per
26862 * g_settings_backend_changed(). This call might be an appropriate
26863 * reasponse to a 'reset' call but implementations are also free to
26864 * explicitly list the keys that were affected by that call if they can
26867 * For efficiency reasons, the implementation should strive for @path to
26868 * be as long as possible (ie: the longest common prefix of all of the
26869 * keys that were changed) but this is not strictly required. As an
26870 * example, if this function is called with the path of "/" then every
26871 * single key in the application will be notified of a possible change.
26878 * g_settings_backend_path_writable_changed:
26879 * @backend: a #GSettingsBackend implementation
26880 * @path: the name of the path
26882 * Signals that the writability of all keys below a given path may have
26885 * Since GSettings performs no locking operations for itself, this call
26886 * will always be made in response to external events.
26893 * g_settings_backend_writable_changed:
26894 * @backend: a #GSettingsBackend implementation
26895 * @key: the name of the key
26897 * Signals that the writability of a single key has possibly changed.
26899 * Since GSettings performs no locking operations for itself, this call
26900 * will always be made in response to external events.
26908 * @settings: a #GSettings object
26909 * @key: the key to bind
26910 * @object: (type GObject.Object): a #GObject
26911 * @property: the name of the property to bind
26912 * @flags: flags for the binding
26914 * Create a binding between the @key in the @settings object
26915 * and the property @property of @object.
26917 * The binding uses the default GIO mapping functions to map
26918 * between the settings and property values. These functions
26919 * handle booleans, numeric types and string types in a
26920 * straightforward way. Use g_settings_bind_with_mapping() if
26921 * you need a custom mapping, or map between types that are not
26922 * supported by the default mapping functions.
26924 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
26925 * function also establishes a binding between the writability of
26926 * @key and the "sensitive" property of @object (if @object has
26927 * a boolean property by that name). See g_settings_bind_writable()
26928 * for more details about writable bindings.
26930 * Note that the lifecycle of the binding is tied to the object,
26931 * and that you can have only one binding per object property.
26932 * If you bind the same property twice on the same object, the second
26933 * binding overrides the first one.
26940 * g_settings_bind_with_mapping: (skip)
26941 * @settings: a #GSettings object
26942 * @key: the key to bind
26943 * @object: (type GObject.Object): a #GObject
26944 * @property: the name of the property to bind
26945 * @flags: flags for the binding
26946 * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping
26947 * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping
26948 * @user_data: data that gets passed to @get_mapping and @set_mapping
26949 * @destroy: #GDestroyNotify function for @user_data
26951 * Create a binding between the @key in the @settings object
26952 * and the property @property of @object.
26954 * The binding uses the provided mapping functions to map between
26955 * settings and property values.
26957 * Note that the lifecycle of the binding is tied to the object,
26958 * and that you can have only one binding per object property.
26959 * If you bind the same property twice on the same object, the second
26960 * binding overrides the first one.
26967 * g_settings_bind_writable:
26968 * @settings: a #GSettings object
26969 * @key: the key to bind
26970 * @object: (type GObject.Object): a #GObject
26971 * @property: the name of a boolean property to bind
26972 * @inverted: whether to 'invert' the value
26974 * Create a binding between the writability of @key in the
26975 * @settings object and the property @property of @object.
26976 * The property must be boolean; "sensitive" or "visible"
26977 * properties of widgets are the most likely candidates.
26979 * Writable bindings are always uni-directional; changes of the
26980 * writability of the setting will be propagated to the object
26981 * property, not the other way.
26983 * When the @inverted argument is %TRUE, the binding inverts the
26984 * value as it passes from the setting to the object, i.e. @property
26985 * will be set to %TRUE if the key is <emphasis>not</emphasis>
26988 * Note that the lifecycle of the binding is tied to the object,
26989 * and that you can have only one binding per object property.
26990 * If you bind the same property twice on the same object, the second
26991 * binding overrides the first one.
26998 * g_settings_create_action:
26999 * @settings: a #GSettings
27000 * @key: the name of a key in @settings
27002 * Creates a #GAction corresponding to a given #GSettings key.
27004 * The action has the same name as the key.
27006 * The value of the key becomes the state of the action and the action
27007 * is enabled when the key is writable. Changing the state of the
27008 * action results in the key being written to. Changes to the value or
27009 * writability of the key cause appropriate change notifications to be
27010 * emitted for the action.
27012 * For boolean-valued keys, action activations take no parameter and
27013 * result in the toggling of the value. For all other types,
27014 * activations take the new value for the key (which must have the
27017 * Returns: (transfer full): a new #GAction
27023 * g_settings_delay:
27024 * @settings: a #GSettings object
27026 * Changes the #GSettings object into 'delay-apply' mode. In this
27027 * mode, changes to @settings are not immediately propagated to the
27028 * backend, but kept locally until g_settings_apply() is called.
27036 * @settings: a #GSettings object
27037 * @key: the key to get the value for
27038 * @format: a #GVariant format string
27039 * @...: arguments as per @format
27041 * Gets the value that is stored at @key in @settings.
27043 * A convenience function that combines g_settings_get_value() with
27046 * It is a programmer error to give a @key that isn't contained in the
27047 * schema for @settings or for the #GVariantType of @format to mismatch
27048 * the type given in the schema.
27055 * g_settings_get_boolean:
27056 * @settings: a #GSettings object
27057 * @key: the key to get the value for
27059 * Gets the value that is stored at @key in @settings.
27061 * A convenience variant of g_settings_get() for booleans.
27063 * It is a programmer error to give a @key that isn't specified as
27064 * having a boolean type in the schema for @settings.
27066 * Returns: a boolean
27072 * g_settings_get_child:
27073 * @settings: a #GSettings object
27074 * @name: the name of the 'child' schema
27076 * Creates a 'child' settings object which has a base path of
27077 * <replaceable>base-path</replaceable>/@name, where
27078 * <replaceable>base-path</replaceable> is the base path of @settings.
27080 * The schema for the child settings object must have been declared
27081 * in the schema of @settings using a <tag class="starttag">child</tag> element.
27083 * Returns: (transfer full): a 'child' settings object
27089 * g_settings_get_double:
27090 * @settings: a #GSettings object
27091 * @key: the key to get the value for
27093 * Gets the value that is stored at @key in @settings.
27095 * A convenience variant of g_settings_get() for doubles.
27097 * It is a programmer error to give a @key that isn't specified as
27098 * having a 'double' type in the schema for @settings.
27100 * Returns: a double
27106 * g_settings_get_enum:
27107 * @settings: a #GSettings object
27108 * @key: the key to get the value for
27110 * Gets the value that is stored in @settings for @key and converts it
27111 * to the enum value that it represents.
27113 * In order to use this function the type of the value must be a string
27114 * and it must be marked in the schema file as an enumerated type.
27116 * It is a programmer error to give a @key that isn't contained in the
27117 * schema for @settings or is not marked as an enumerated type.
27119 * If the value stored in the configuration database is not a valid
27120 * value for the enumerated type then this function will return the
27123 * Returns: the enum value
27129 * g_settings_get_flags:
27130 * @settings: a #GSettings object
27131 * @key: the key to get the value for
27133 * Gets the value that is stored in @settings for @key and converts it
27134 * to the flags value that it represents.
27136 * In order to use this function the type of the value must be an array
27137 * of strings and it must be marked in the schema file as an flags type.
27139 * It is a programmer error to give a @key that isn't contained in the
27140 * schema for @settings or is not marked as a flags type.
27142 * If the value stored in the configuration database is not a valid
27143 * value for the flags type then this function will return the default
27146 * Returns: the flags value
27152 * g_settings_get_has_unapplied:
27153 * @settings: a #GSettings object
27155 * Returns whether the #GSettings object has any unapplied
27156 * changes. This can only be the case if it is in 'delayed-apply' mode.
27158 * Returns: %TRUE if @settings has unapplied changes
27164 * g_settings_get_int:
27165 * @settings: a #GSettings object
27166 * @key: the key to get the value for
27168 * Gets the value that is stored at @key in @settings.
27170 * A convenience variant of g_settings_get() for 32-bit integers.
27172 * It is a programmer error to give a @key that isn't specified as
27173 * having a int32 type in the schema for @settings.
27175 * Returns: an integer
27181 * g_settings_get_mapped:
27182 * @settings: a #GSettings object
27183 * @key: the key to get the value for
27184 * @mapping: (scope call): the function to map the value in the settings database to the value used by the application
27185 * @user_data: user data for @mapping
27187 * Gets the value that is stored at @key in @settings, subject to
27188 * application-level validation/mapping.
27190 * You should use this function when the application needs to perform
27191 * some processing on the value of the key (for example, parsing). The
27192 * @mapping function performs that processing. If the function
27193 * indicates that the processing was unsuccessful (due to a parse error,
27194 * for example) then the mapping is tried again with another value.
27196 * This allows a robust 'fall back to defaults' behaviour to be
27197 * implemented somewhat automatically.
27199 * The first value that is tried is the user's setting for the key. If
27200 * the mapping function fails to map this value, other values may be
27201 * tried in an unspecified order (system or site defaults, translated
27202 * schema default values, untranslated schema default values, etc).
27204 * If the mapping function fails for all possible values, one additional
27205 * attempt is made: the mapping function is called with a %NULL value.
27206 * If the mapping function still indicates failure at this point then
27207 * the application will be aborted.
27209 * The result parameter for the @mapping function is pointed to a
27210 * #gpointer which is initially set to %NULL. The same pointer is given
27211 * to each invocation of @mapping. The final value of that #gpointer is
27212 * what is returned by this function. %NULL is valid; it is returned
27213 * just as any other value would be.
27215 * Returns: (transfer full): the result, which may be %NULL
27220 * g_settings_get_range:
27221 * @settings: a #GSettings
27222 * @key: the key to query the range of
27224 * Queries the range of a key.
27226 * This function will return a #GVariant that fully describes the range
27227 * of values that are valid for @key.
27229 * The type of #GVariant returned is <literal>(sv)</literal>. The
27230 * string describes the type of range restriction in effect. The type
27231 * and meaning of the value contained in the variant depends on the
27234 * If the string is <literal>'type'</literal> then the variant contains
27235 * an empty array. The element type of that empty array is the expected
27236 * type of value and all values of that type are valid.
27238 * If the string is <literal>'enum'</literal> then the variant contains
27239 * an array enumerating the possible values. Each item in the array is
27240 * a possible valid value and no other values are valid.
27242 * If the string is <literal>'flags'</literal> then the variant contains
27243 * an array. Each item in the array is a value that may appear zero or
27244 * one times in an array to be used as the value for this key. For
27245 * example, if the variant contained the array <literal>['x',
27246 * 'y']</literal> then the valid values for the key would be
27247 * <literal>[]</literal>, <literal>['x']</literal>,
27248 * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
27249 * <literal>['y', 'x']</literal>.
27251 * Finally, if the string is <literal>'range'</literal> then the variant
27252 * contains a pair of like-typed values -- the minimum and maximum
27253 * permissible values for this key.
27255 * This information should not be used by normal programs. It is
27256 * considered to be a hint for introspection purposes. Normal programs
27257 * should already know what is permitted by their own schema. The
27258 * format may change in any way in the future -- but particularly, new
27259 * forms may be added to the possibilities described above.
27261 * It is a programmer error to give a @key that isn't contained in the
27262 * schema for @settings.
27264 * You should free the returned value with g_variant_unref() when it is
27265 * no longer needed.
27267 * Returns: a #GVariant describing the range
27273 * g_settings_get_string:
27274 * @settings: a #GSettings object
27275 * @key: the key to get the value for
27277 * Gets the value that is stored at @key in @settings.
27279 * A convenience variant of g_settings_get() for strings.
27281 * It is a programmer error to give a @key that isn't specified as
27282 * having a string type in the schema for @settings.
27284 * Returns: a newly-allocated string
27290 * g_settings_get_strv:
27291 * @settings: a #GSettings object
27292 * @key: the key to get the value for
27294 * A convenience variant of g_settings_get() for string arrays.
27296 * It is a programmer error to give a @key that isn't specified as
27297 * having an array of strings type in the schema for @settings.
27299 * Returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings.
27305 * g_settings_get_uint:
27306 * @settings: a #GSettings object
27307 * @key: the key to get the value for
27309 * Gets the value that is stored at @key in @settings.
27311 * A convenience variant of g_settings_get() for 32-bit unsigned
27314 * It is a programmer error to give a @key that isn't specified as
27315 * having a uint32 type in the schema for @settings.
27317 * Returns: an unsigned integer
27323 * g_settings_get_value:
27324 * @settings: a #GSettings object
27325 * @key: the key to get the value for
27327 * Gets the value that is stored in @settings for @key.
27329 * It is a programmer error to give a @key that isn't contained in the
27330 * schema for @settings.
27332 * Returns: a new #GVariant
27338 * g_settings_is_writable:
27339 * @settings: a #GSettings object
27340 * @name: the name of a key
27342 * Finds out if a key can be written or not
27344 * Returns: %TRUE if the key @name is writable
27350 * g_settings_list_children:
27351 * @settings: a #GSettings object
27353 * Gets the list of children on @settings.
27355 * The list is exactly the list of strings for which it is not an error
27356 * to call g_settings_get_child().
27358 * For GSettings objects that are lists, this value can change at any
27359 * time and you should connect to the "children-changed" signal to watch
27360 * for those changes. Note that there is a race condition here: you may
27361 * request a child after listing it only for it to have been destroyed
27362 * in the meantime. For this reason, g_settings_get_child() may return
27363 * %NULL even for a child that was listed by this function.
27365 * For GSettings objects that are not lists, you should probably not be
27366 * calling this function from "normal" code (since you should already
27367 * know what children are in your schema). This function may still be
27368 * useful there for introspection reasons, however.
27370 * You should free the return value with g_strfreev() when you are done
27373 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
27378 * g_settings_list_keys:
27379 * @settings: a #GSettings object
27381 * Introspects the list of keys on @settings.
27383 * You should probably not be calling this function from "normal" code
27384 * (since you should already know what keys are in your schema). This
27385 * function is intended for introspection reasons.
27387 * You should free the return value with g_strfreev() when you are done
27390 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
27395 * g_settings_list_relocatable_schemas:
27397 * Gets a list of the relocatable #GSettings schemas installed on the
27398 * system. These are schemas that do not provide their own path. It is
27399 * usual to instantiate these schemas directly, but if you want to you
27400 * can use g_settings_new_with_path() to specify the path.
27402 * The output of this function, taken together with the output of
27403 * g_settings_list_schemas() represents the complete list of all
27404 * installed schemas.
27406 * Returns: (element-type utf8) (transfer none): a list of relocatable #GSettings schemas that are available. The list must not be modified or freed.
27412 * g_settings_list_schemas:
27414 * Gets a list of the #GSettings schemas installed on the system. The
27415 * returned list is exactly the list of schemas for which you may call
27416 * g_settings_new() without adverse effects.
27418 * This function does not list the schemas that do not provide their own
27419 * paths (ie: schemas for which you must use
27420 * g_settings_new_with_path()). See
27421 * g_settings_list_relocatable_schemas() for that.
27423 * Returns: (element-type utf8) (transfer none): a list of #GSettings schemas that are available. The list must not be modified or freed.
27430 * @schema_id: the id of the schema
27432 * Creates a new #GSettings object with the schema specified by
27435 * Signals on the newly created #GSettings object will be dispatched
27436 * via the thread-default #GMainContext in effect at the time of the
27437 * call to g_settings_new(). The new #GSettings will hold a reference
27438 * on the context. See g_main_context_push_thread_default().
27440 * Returns: a new #GSettings object
27446 * g_settings_new_full:
27447 * @schema: a #GSettingsSchema
27448 * @backend: (allow-none): a #GSettingsBackend
27449 * @path: (allow-none): the path to use
27451 * Creates a new #GSettings object with a given schema, backend and
27454 * It should be extremely rare that you ever want to use this function.
27455 * It is made available for advanced use-cases (such as plugin systems
27456 * that want to provide access to schemas loaded from custom locations,
27459 * At the most basic level, a #GSettings object is a pure composition of
27460 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
27461 * backend, and a #GMainContext to which signals are dispatched.
27463 * This constructor therefore gives you full control over constructing
27464 * #GSettings instances. The first 4 parameters are given directly as
27465 * @schema, @backend and @path, and the main context is taken from the
27466 * thread-default (as per g_settings_new()).
27468 * If @backend is %NULL then the default backend is used.
27470 * If @path is %NULL then the path from the schema is used. It is an
27471 * error f @path is %NULL and the schema has no path of its own or if
27472 * @path is non-%NULL and not equal to the path that the schema does
27475 * Returns: a new #GSettings object
27481 * g_settings_new_with_backend:
27482 * @schema_id: the id of the schema
27483 * @backend: the #GSettingsBackend to use
27485 * Creates a new #GSettings object with the schema specified by
27486 * @schema_id and a given #GSettingsBackend.
27488 * Creating a #GSettings object with a different backend allows accessing
27489 * settings from a database other than the usual one. For example, it may make
27490 * sense to pass a backend corresponding to the "defaults" settings database on
27491 * the system to get a settings object that modifies the system default
27492 * settings instead of the settings for this user.
27494 * Returns: a new #GSettings object
27500 * g_settings_new_with_backend_and_path:
27501 * @schema_id: the id of the schema
27502 * @backend: the #GSettingsBackend to use
27503 * @path: the path to use
27505 * Creates a new #GSettings object with the schema specified by
27506 * @schema_id and a given #GSettingsBackend and path.
27508 * This is a mix of g_settings_new_with_backend() and
27509 * g_settings_new_with_path().
27511 * Returns: a new #GSettings object
27517 * g_settings_new_with_path:
27518 * @schema_id: the id of the schema
27519 * @path: the path to use
27521 * Creates a new #GSettings object with the relocatable schema specified
27522 * by @schema_id and a given path.
27524 * You only need to do this if you want to directly create a settings
27525 * object with a schema that doesn't have a specified path of its own.
27526 * That's quite rare.
27528 * It is a programmer error to call this function for a schema that
27529 * has an explicitly specified path.
27531 * Returns: a new #GSettings object
27537 * g_settings_range_check:
27538 * @settings: a #GSettings
27539 * @key: the key to check
27540 * @value: the value to check
27542 * Checks if the given @value is of the correct type and within the
27543 * permitted range for @key.
27545 * This API is not intended to be used by normal programs -- they should
27546 * already know what is permitted by their own schemas. This API is
27547 * meant to be used by programs such as editors or commandline tools.
27549 * It is a programmer error to give a @key that isn't contained in the
27550 * schema for @settings.
27552 * Returns: %TRUE if @value is valid for @key
27558 * g_settings_reset:
27559 * @settings: a #GSettings object
27560 * @key: the name of a key
27562 * Resets @key to its default value.
27564 * This call resets the key, as much as possible, to its default value.
27565 * That might the value specified in the schema or the one set by the
27571 * g_settings_revert:
27572 * @settings: a #GSettings instance
27574 * Reverts all non-applied changes to the settings. This function
27575 * does nothing unless @settings is in 'delay-apply' mode; see
27576 * g_settings_delay(). In the normal case settings are always applied
27579 * Change notifications will be emitted for affected keys.
27584 * g_settings_schema_get_id:
27585 * @schema: a #GSettingsSchema
27587 * Get the ID of @schema.
27589 * Returns: (transfer none): the ID
27594 * g_settings_schema_get_path:
27595 * @schema: a #GSettingsSchema
27597 * Gets the path associated with @schema, or %NULL.
27599 * Schemas may be single-instance or relocatable. Single-instance
27600 * schemas correspond to exactly one set of keys in the backend
27601 * database: those located at the path returned by this function.
27603 * Relocatable schemas can be referenced by other schemas and can
27604 * threfore describe multiple sets of keys at different locations. For
27605 * relocatable schemas, this function will return %NULL.
27607 * Returns: (transfer none): the path of the schema, or %NULL
27613 * g_settings_schema_ref:
27614 * @schema: a #GSettingsSchema
27616 * Increase the reference count of @schema, returning a new reference.
27618 * Returns: a new reference to @schema
27624 * g_settings_schema_source_get_default:
27626 * Gets the default system schema source.
27628 * This function is not required for normal uses of #GSettings but it
27629 * may be useful to authors of plugin management systems or to those who
27630 * want to introspect the content of schemas.
27632 * If no schemas are installed, %NULL will be returned.
27634 * The returned source may actually consist of multiple schema sources
27635 * from different directories, depending on which directories were given
27636 * in <envar>XDG_DATA_DIRS</envar> and
27637 * <envar>GSETTINGS_SCHEMA_DIR</envar>. For this reason, all lookups
27638 * performed against the default source should probably be done
27641 * Returns: (transfer none): the default schema source
27647 * g_settings_schema_source_lookup:
27648 * @source: a #GSettingsSchemaSource
27649 * @schema_id: a schema ID
27650 * @recursive: %TRUE if the lookup should be recursive
27652 * Looks up a schema with the identifier @schema_id in @source.
27654 * This function is not required for normal uses of #GSettings but it
27655 * may be useful to authors of plugin management systems or to those who
27656 * want to introspect the content of schemas.
27658 * If the schema isn't found directly in @source and @recursive is %TRUE
27659 * then the parent sources will also be checked.
27661 * If the schema isn't found, %NULL is returned.
27663 * Returns: (transfer full): a new #GSettingsSchema
27669 * g_settings_schema_source_new_from_directory:
27670 * @directory: the filename of a directory
27671 * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
27672 * @trusted: %TRUE, if the directory is trusted
27673 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
27675 * Attempts to create a new schema source corresponding to the contents
27676 * of the given directory.
27678 * This function is not required for normal uses of #GSettings but it
27679 * may be useful to authors of plugin management systems.
27681 * The directory should contain a file called
27682 * <filename>gschemas.compiled</filename> as produced by
27683 * <command>glib-compile-schemas</command>.
27685 * If @trusted is %TRUE then <filename>gschemas.compiled</filename> is
27686 * trusted not to be corrupted. This assumption has a performance
27687 * advantage, but can result in crashes or inconsistent behaviour in the
27688 * case of a corrupted file. Generally, you should set @trusted to
27689 * %TRUE for files installed by the system and to %FALSE for files in
27690 * the home directory.
27692 * If @parent is non-%NULL then there are two effects.
27694 * First, if g_settings_schema_source_lookup() is called with the
27695 * @recursive flag set to %TRUE and the schema can not be found in the
27696 * source, the lookup will recurse to the parent.
27698 * Second, any references to other schemas specified within this
27699 * source (ie: <literal>child</literal> or <literal>extends</literal>)
27700 * references may be resolved from the @parent.
27702 * For this second reason, except in very unusual situations, the
27703 * @parent should probably be given as the default schema source, as
27704 * returned by g_settings_schema_source_get_default().
27711 * g_settings_schema_source_ref:
27712 * @source: a #GSettingsSchemaSource
27714 * Increase the reference count of @source, returning a new reference.
27716 * Returns: a new reference to @source
27722 * g_settings_schema_source_unref:
27723 * @source: a #GSettingsSchemaSource
27725 * Decrease the reference count of @source, possibly freeing it.
27732 * g_settings_schema_unref:
27733 * @schema: a #GSettingsSchema
27735 * Decrease the reference count of @schema, possibly freeing it.
27743 * @settings: a #GSettings object
27744 * @key: the name of the key to set
27745 * @format: a #GVariant format string
27746 * @...: arguments as per @format
27748 * Sets @key in @settings to @value.
27750 * A convenience function that combines g_settings_set_value() with
27753 * It is a programmer error to give a @key that isn't contained in the
27754 * schema for @settings or for the #GVariantType of @format to mismatch
27755 * the type given in the schema.
27757 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27763 * g_settings_set_boolean:
27764 * @settings: a #GSettings object
27765 * @key: the name of the key to set
27766 * @value: the value to set it to
27768 * Sets @key in @settings to @value.
27770 * A convenience variant of g_settings_set() for booleans.
27772 * It is a programmer error to give a @key that isn't specified as
27773 * having a boolean type in the schema for @settings.
27775 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27781 * g_settings_set_double:
27782 * @settings: a #GSettings object
27783 * @key: the name of the key to set
27784 * @value: the value to set it to
27786 * Sets @key in @settings to @value.
27788 * A convenience variant of g_settings_set() for doubles.
27790 * It is a programmer error to give a @key that isn't specified as
27791 * having a 'double' type in the schema for @settings.
27793 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27799 * g_settings_set_enum:
27800 * @settings: a #GSettings object
27801 * @key: a key, within @settings
27802 * @value: an enumerated value
27804 * Looks up the enumerated type nick for @value and writes it to @key,
27805 * within @settings.
27807 * It is a programmer error to give a @key that isn't contained in the
27808 * schema for @settings or is not marked as an enumerated type, or for
27809 * @value not to be a valid value for the named type.
27811 * After performing the write, accessing @key directly with
27812 * g_settings_get_string() will return the 'nick' associated with
27815 * Returns: %TRUE, if the set succeeds
27820 * g_settings_set_flags:
27821 * @settings: a #GSettings object
27822 * @key: a key, within @settings
27823 * @value: a flags value
27825 * Looks up the flags type nicks for the bits specified by @value, puts
27826 * them in an array of strings and writes the array to @key, within
27829 * It is a programmer error to give a @key that isn't contained in the
27830 * schema for @settings or is not marked as a flags type, or for @value
27831 * to contain any bits that are not value for the named type.
27833 * After performing the write, accessing @key directly with
27834 * g_settings_get_strv() will return an array of 'nicks'; one for each
27837 * Returns: %TRUE, if the set succeeds
27842 * g_settings_set_int:
27843 * @settings: a #GSettings object
27844 * @key: the name of the key to set
27845 * @value: the value to set it to
27847 * Sets @key in @settings to @value.
27849 * A convenience variant of g_settings_set() for 32-bit integers.
27851 * It is a programmer error to give a @key that isn't specified as
27852 * having a int32 type in the schema for @settings.
27854 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27860 * g_settings_set_string:
27861 * @settings: a #GSettings object
27862 * @key: the name of the key to set
27863 * @value: the value to set it to
27865 * Sets @key in @settings to @value.
27867 * A convenience variant of g_settings_set() for strings.
27869 * It is a programmer error to give a @key that isn't specified as
27870 * having a string type in the schema for @settings.
27872 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27878 * g_settings_set_strv:
27879 * @settings: a #GSettings object
27880 * @key: the name of the key to set
27881 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
27883 * Sets @key in @settings to @value.
27885 * A convenience variant of g_settings_set() for string arrays. If
27886 * @value is %NULL, then @key is set to be the empty array.
27888 * It is a programmer error to give a @key that isn't specified as
27889 * having an array of strings type in the schema for @settings.
27891 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27897 * g_settings_set_uint:
27898 * @settings: a #GSettings object
27899 * @key: the name of the key to set
27900 * @value: the value to set it to
27902 * Sets @key in @settings to @value.
27904 * A convenience variant of g_settings_set() for 32-bit unsigned
27907 * It is a programmer error to give a @key that isn't specified as
27908 * having a uint32 type in the schema for @settings.
27910 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27916 * g_settings_set_value:
27917 * @settings: a #GSettings object
27918 * @key: the name of the key to set
27919 * @value: a #GVariant of the correct type
27921 * Sets @key in @settings to @value.
27923 * It is a programmer error to give a @key that isn't contained in the
27924 * schema for @settings or for @value to have the incorrect type, per
27927 * If @value is floating then this function consumes the reference.
27929 * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
27937 * Ensures that all pending operations for the given are complete for
27938 * the default backend.
27940 * Writes made to a #GSettings are handled asynchronously. For this
27941 * reason, it is very unlikely that the changes have it to disk by the
27942 * time g_settings_set() returns.
27944 * This call will block until all of the writes have made it to the
27945 * backend. Since the mainloop is not running, no change notifications
27946 * will be dispatched during this call (but some may be queued by the
27947 * time the call is done).
27952 * g_settings_unbind:
27953 * @object: the object
27954 * @property: the property whose binding is removed
27956 * Removes an existing binding for @property on @object.
27958 * Note that bindings are automatically removed when the
27959 * object is finalized, so it is rarely necessary to call this
27967 * g_simple_action_group_add_entries:
27968 * @simple: a #GSimpleActionGroup
27969 * @entries: (array length=n_entries): a pointer to the first item in an array of #GActionEntry structs
27970 * @n_entries: the length of @entries, or -1
27971 * @user_data: the user data for signal connections
27973 * A convenience function for creating multiple #GSimpleAction instances
27974 * and adding them to the action group.
27981 * g_simple_action_group_insert:
27982 * @simple: a #GSimpleActionGroup
27983 * @action: a #GAction
27985 * Adds an action to the action group.
27987 * If the action group already contains an action with the same name as
27988 * @action then the old action is dropped from the group.
27990 * The action group takes its own reference on @action.
27997 * g_simple_action_group_lookup:
27998 * @simple: a #GSimpleActionGroup
27999 * @action_name: the name of an action
28001 * Looks up the action with the name @action_name in the group.
28003 * If no such action exists, returns %NULL.
28005 * Returns: (transfer none): a #GAction, or %NULL
28011 * g_simple_action_group_new:
28013 * Creates a new, empty, #GSimpleActionGroup.
28015 * Returns: a new #GSimpleActionGroup
28021 * g_simple_action_group_remove:
28022 * @simple: a #GSimpleActionGroup
28023 * @action_name: the name of the action
28025 * Removes the named action from the action group.
28027 * If no action of this name is in the group then nothing happens.
28034 * g_simple_action_new:
28035 * @name: the name of the action
28036 * @parameter_type: (allow-none): the type of parameter to the activate function
28038 * Creates a new action.
28040 * The created action is stateless. See g_simple_action_new_stateful().
28042 * Returns: a new #GSimpleAction
28048 * g_simple_action_new_stateful:
28049 * @name: the name of the action
28050 * @parameter_type: (allow-none): the type of the parameter to the activate function
28051 * @state: the initial state of the action
28053 * Creates a new stateful action.
28055 * @state is the initial state of the action. All future state values
28056 * must have the same #GVariantType as the initial state.
28058 * If the @state GVariant is floating, it is consumed.
28060 * Returns: a new #GSimpleAction
28066 * g_simple_action_set_enabled:
28067 * @simple: a #GSimpleAction
28068 * @enabled: whether the action is enabled
28070 * Sets the action as enabled or not.
28072 * An action must be enabled in order to be activated or in order to
28073 * have its state changed from outside callers.
28075 * This should only be called by the implementor of the action. Users
28076 * of the action should not attempt to modify its enabled flag.
28083 * g_simple_action_set_state:
28084 * @simple: a #GSimpleAction
28085 * @value: the new #GVariant for the state
28087 * Sets the state of the action.
28089 * This directly updates the 'state' property to the given value.
28091 * This should only be called by the implementor of the action. Users
28092 * of the action should not attempt to directly modify the 'state'
28093 * property. Instead, they should call g_action_change_state() to
28094 * request the change.
28101 * g_simple_async_report_error_in_idle: (skip)
28102 * @object: (allow-none): a #GObject, or %NULL.
28103 * @callback: a #GAsyncReadyCallback.
28104 * @user_data: user data passed to @callback.
28105 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
28106 * @code: a specific error code.
28107 * @format: a formatted error reporting string.
28108 * @...: a list of variables to fill in @format.
28110 * Reports an error in an asynchronous function in an idle function by
28111 * directly setting the contents of the #GAsyncResult with the given error
28117 * g_simple_async_report_gerror_in_idle:
28118 * @object: (allow-none): a #GObject, or %NULL
28119 * @callback: (scope async): a #GAsyncReadyCallback.
28120 * @user_data: (closure): user data passed to @callback.
28121 * @error: the #GError to report
28123 * Reports an error in an idle function. Similar to
28124 * g_simple_async_report_error_in_idle(), but takes a #GError rather
28125 * than building a new one.
28130 * g_simple_async_report_take_gerror_in_idle: (skip)
28131 * @object: (allow-none): a #GObject, or %NULL
28132 * @callback: a #GAsyncReadyCallback.
28133 * @user_data: user data passed to @callback.
28134 * @error: the #GError to report
28136 * Reports an error in an idle function. Similar to
28137 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
28138 * ownership of @error, so the caller does not have to free it any more.
28145 * g_simple_async_result_complete:
28146 * @simple: a #GSimpleAsyncResult.
28148 * Completes an asynchronous I/O job immediately. Must be called in
28149 * the thread where the asynchronous result was to be delivered, as it
28150 * invokes the callback directly. If you are in a different thread use
28151 * g_simple_async_result_complete_in_idle().
28153 * Calling this function takes a reference to @simple for as long as
28154 * is needed to complete the call.
28159 * g_simple_async_result_complete_in_idle:
28160 * @simple: a #GSimpleAsyncResult.
28162 * Completes an asynchronous function in an idle handler in the <link
28163 * linkend="g-main-context-push-thread-default">thread-default main
28164 * loop</link> of the thread that @simple was initially created in
28165 * (and re-pushes that context around the invocation of the callback).
28167 * Calling this function takes a reference to @simple for as long as
28168 * is needed to complete the call.
28173 * g_simple_async_result_get_op_res_gboolean:
28174 * @simple: a #GSimpleAsyncResult.
28176 * Gets the operation result boolean from within the asynchronous result.
28178 * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE.
28183 * g_simple_async_result_get_op_res_gpointer: (skip)
28184 * @simple: a #GSimpleAsyncResult.
28186 * Gets a pointer result as returned by the asynchronous function.
28188 * Returns: a pointer from the result.
28193 * g_simple_async_result_get_op_res_gssize:
28194 * @simple: a #GSimpleAsyncResult.
28196 * Gets a gssize from the asynchronous result.
28198 * Returns: a gssize returned from the asynchronous function.
28203 * g_simple_async_result_get_source_tag: (skip)
28204 * @simple: a #GSimpleAsyncResult.
28206 * Gets the source tag for the #GSimpleAsyncResult.
28208 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
28213 * g_simple_async_result_is_valid:
28214 * @result: the #GAsyncResult passed to the _finish function.
28215 * @source: the #GObject passed to the _finish function.
28216 * @source_tag: the asynchronous function.
28218 * Ensures that the data passed to the _finish function of an async
28219 * operation is consistent. Three checks are performed.
28221 * First, @result is checked to ensure that it is really a
28222 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
28223 * matches the source object of @result. Third, @source_tag is
28224 * checked to ensure that it is either %NULL (as it is when the result was
28225 * created by g_simple_async_report_error_in_idle() or
28226 * g_simple_async_report_gerror_in_idle()) or equal to the
28227 * @source_tag argument given to g_simple_async_result_new() (which, by
28228 * convention, is a pointer to the _async function corresponding to the
28229 * _finish function from which this function is called).
28231 * Returns: #TRUE if all checks passed or #FALSE if any failed.
28237 * g_simple_async_result_new:
28238 * @source_object: (allow-none): a #GObject, or %NULL.
28239 * @callback: (scope async): a #GAsyncReadyCallback.
28240 * @user_data: (closure): user data passed to @callback.
28241 * @source_tag: the asynchronous function.
28243 * Creates a #GSimpleAsyncResult.
28245 * The common convention is to create the #GSimpleAsyncResult in the
28246 * function that starts the asynchronous operation and use that same
28247 * function as the @source_tag.
28249 * If your operation supports cancellation with #GCancellable (which it
28250 * probably should) then you should provide the user's cancellable to
28251 * g_simple_async_result_set_check_cancellable() immediately after
28252 * this function returns.
28254 * Returns: a #GSimpleAsyncResult.
28259 * g_simple_async_result_new_error:
28260 * @source_object: (allow-none): a #GObject, or %NULL.
28261 * @callback: (scope async): a #GAsyncReadyCallback.
28262 * @user_data: (closure): user data passed to @callback.
28263 * @domain: a #GQuark.
28264 * @code: an error code.
28265 * @format: a string with format characters.
28266 * @...: a list of values to insert into @format.
28268 * Creates a new #GSimpleAsyncResult with a set error.
28270 * Returns: a #GSimpleAsyncResult.
28275 * g_simple_async_result_new_from_error:
28276 * @source_object: (allow-none): a #GObject, or %NULL.
28277 * @callback: (scope async): a #GAsyncReadyCallback.
28278 * @user_data: (closure): user data passed to @callback.
28279 * @error: a #GError
28281 * Creates a #GSimpleAsyncResult from an error condition.
28283 * Returns: a #GSimpleAsyncResult.
28288 * g_simple_async_result_new_take_error: (skip)
28289 * @source_object: (allow-none): a #GObject, or %NULL
28290 * @callback: (scope async): a #GAsyncReadyCallback
28291 * @user_data: (closure): user data passed to @callback
28292 * @error: a #GError
28294 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
28295 * caller's ownership of @error, so the caller does not need to free it anymore.
28297 * Returns: a #GSimpleAsyncResult
28303 * g_simple_async_result_propagate_error:
28304 * @simple: a #GSimpleAsyncResult.
28305 * @dest: (out): a location to propagate the error to.
28307 * Propagates an error from within the simple asynchronous result to
28308 * a given destination.
28310 * If the #GCancellable given to a prior call to
28311 * g_simple_async_result_set_check_cancellable() is cancelled then this
28312 * function will return %TRUE with @dest set appropriately.
28314 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
28319 * g_simple_async_result_run_in_thread: (skip)
28320 * @simple: a #GSimpleAsyncResult.
28321 * @func: a #GSimpleAsyncThreadFunc.
28322 * @io_priority: the io priority of the request.
28323 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28325 * Runs the asynchronous job in a separate thread and then calls
28326 * g_simple_async_result_complete_in_idle() on @simple to return
28327 * the result to the appropriate main loop.
28329 * Calling this function takes a reference to @simple for as long as
28330 * is needed to run the job and report its completion.
28335 * g_simple_async_result_set_check_cancellable:
28336 * @simple: a #GSimpleAsyncResult
28337 * @check_cancellable: (allow-none): a #GCancellable to check, or %NULL to unset
28339 * Sets a #GCancellable to check before dispatching results.
28341 * This function has one very specific purpose: the provided cancellable
28342 * is checked at the time of g_simple_async_result_propagate_error() If
28343 * it is cancelled, these functions will return an "Operation was
28344 * cancelled" error (%G_IO_ERROR_CANCELLED).
28346 * Implementors of cancellable asynchronous functions should use this in
28347 * order to provide a guarantee to their callers that cancelling an
28348 * async operation will reliably result in an error being returned for
28349 * that operation (even if a positive result for the operation has
28350 * already been sent as an idle to the main context to be dispatched).
28352 * The checking described above is done regardless of any call to the
28353 * unrelated g_simple_async_result_set_handle_cancellation() function.
28360 * g_simple_async_result_set_error: (skip)
28361 * @simple: a #GSimpleAsyncResult.
28362 * @domain: a #GQuark (usually #G_IO_ERROR).
28363 * @code: an error code.
28364 * @format: a formatted error reporting string.
28365 * @...: a list of variables to fill in @format.
28367 * Sets an error within the asynchronous result without a #GError.
28372 * g_simple_async_result_set_error_va: (skip)
28373 * @simple: a #GSimpleAsyncResult.
28374 * @domain: a #GQuark (usually #G_IO_ERROR).
28375 * @code: an error code.
28376 * @format: a formatted error reporting string.
28377 * @args: va_list of arguments.
28379 * Sets an error within the asynchronous result without a #GError.
28380 * Unless writing a binding, see g_simple_async_result_set_error().
28385 * g_simple_async_result_set_from_error:
28386 * @simple: a #GSimpleAsyncResult.
28389 * Sets the result from a #GError.
28394 * g_simple_async_result_set_handle_cancellation:
28395 * @simple: a #GSimpleAsyncResult.
28396 * @handle_cancellation: a #gboolean.
28398 * Sets whether to handle cancellation within the asynchronous operation.
28400 * This function has nothing to do with
28401 * g_simple_async_result_set_check_cancellable(). It only refers to the
28402 * #GCancellable passed to g_simple_async_result_run_in_thread().
28407 * g_simple_async_result_set_op_res_gboolean:
28408 * @simple: a #GSimpleAsyncResult.
28409 * @op_res: a #gboolean.
28411 * Sets the operation result to a boolean within the asynchronous result.
28416 * g_simple_async_result_set_op_res_gpointer: (skip)
28417 * @simple: a #GSimpleAsyncResult.
28418 * @op_res: a pointer result from an asynchronous function.
28419 * @destroy_op_res: a #GDestroyNotify function.
28421 * Sets the operation result within the asynchronous result to a pointer.
28426 * g_simple_async_result_set_op_res_gssize:
28427 * @simple: a #GSimpleAsyncResult.
28428 * @op_res: a #gssize.
28430 * Sets the operation result within the asynchronous result to
28431 * the given @op_res.
28436 * g_simple_async_result_take_error: (skip)
28437 * @simple: a #GSimpleAsyncResult
28438 * @error: a #GError
28440 * Sets the result from @error, and takes over the caller's ownership
28441 * of @error, so the caller does not need to free it any more.
28448 * g_simple_permission_new:
28449 * @allowed: %TRUE if the action is allowed
28451 * Creates a new #GPermission instance that represents an action that is
28452 * either always or never allowed.
28454 * Returns: the #GSimplePermission, as a #GPermission
28461 * @socket: a #GSocket.
28462 * @cancellable: (allow-none): a %GCancellable or %NULL
28463 * @error: #GError for error reporting, or %NULL to ignore.
28465 * Accept incoming connections on a connection-based socket. This removes
28466 * the first outstanding connection request from the listening socket and
28467 * creates a #GSocket object for it.
28469 * The @socket must be bound to a local address with g_socket_bind() and
28470 * must be listening for incoming connections (g_socket_listen()).
28472 * If there are no outstanding connections then the operation will block
28473 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
28474 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
28476 * Returns: (transfer full): a new #GSocket, or %NULL on error. Free the returned object with g_object_unref().
28482 * g_socket_address_enumerator_next:
28483 * @enumerator: a #GSocketAddressEnumerator
28484 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28485 * @error: a #GError.
28487 * Retrieves the next #GSocketAddress from @enumerator. Note that this
28488 * may block for some amount of time. (Eg, a #GNetworkAddress may need
28489 * to do a DNS lookup before it can return an address.) Use
28490 * g_socket_address_enumerator_next_async() if you need to avoid
28493 * If @enumerator is expected to yield addresses, but for some reason
28494 * is unable to (eg, because of a DNS error), then the first call to
28495 * g_socket_address_enumerator_next() will return an appropriate error
28496 * in *@error. However, if the first call to
28497 * g_socket_address_enumerator_next() succeeds, then any further
28498 * internal errors (other than @cancellable being triggered) will be
28501 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses.
28506 * g_socket_address_enumerator_next_async:
28507 * @enumerator: a #GSocketAddressEnumerator
28508 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28509 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
28510 * @user_data: (closure): the data to pass to callback function
28512 * Asynchronously retrieves the next #GSocketAddress from @enumerator
28513 * and then calls @callback, which must call
28514 * g_socket_address_enumerator_next_finish() to get the result.
28519 * g_socket_address_enumerator_next_finish:
28520 * @enumerator: a #GSocketAddressEnumerator
28521 * @result: a #GAsyncResult
28522 * @error: a #GError
28524 * Retrieves the result of a completed call to
28525 * g_socket_address_enumerator_next_async(). See
28526 * g_socket_address_enumerator_next() for more information about
28529 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses.
28534 * g_socket_address_get_family:
28535 * @address: a #GSocketAddress
28537 * Gets the socket family type of @address.
28539 * Returns: the socket family type of @address.
28545 * g_socket_address_get_native_size:
28546 * @address: a #GSocketAddress
28548 * Gets the size of @address's native <type>struct sockaddr</type>.
28549 * You can use this to allocate memory to pass to
28550 * g_socket_address_to_native().
28552 * Returns: the size of the native <type>struct sockaddr</type> that @address represents
28558 * g_socket_address_new_from_native:
28559 * @native: a pointer to a <type>struct sockaddr</type>
28560 * @len: the size of the memory location pointed to by @native
28562 * Creates a #GSocketAddress subclass corresponding to the native
28563 * <type>struct sockaddr</type> @native.
28565 * Returns: a new #GSocketAddress if @native could successfully be converted, otherwise %NULL.
28571 * g_socket_address_to_native:
28572 * @address: a #GSocketAddress
28573 * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>.
28574 * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size().
28575 * @error: #GError for error reporting, or %NULL to ignore.
28577 * Converts a #GSocketAddress to a native <type>struct
28578 * sockaddr</type>, which can be passed to low-level functions like
28579 * connect() or bind().
28581 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
28582 * returned. If the address type is not known on the system
28583 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
28585 * Returns: %TRUE if @dest was filled in, %FALSE on error
28592 * @socket: a #GSocket.
28593 * @address: a #GSocketAddress specifying the local address.
28594 * @allow_reuse: whether to allow reusing this address
28595 * @error: #GError for error reporting, or %NULL to ignore.
28597 * When a socket is created it is attached to an address family, but it
28598 * doesn't have an address in this family. g_socket_bind() assigns the
28599 * address (sometimes called name) of the socket.
28601 * It is generally required to bind to a local address before you can
28602 * receive connections. (See g_socket_listen() and g_socket_accept() ).
28603 * In certain situations, you may also want to bind a socket that will be
28604 * used to initiate connections, though this is not normally required.
28606 * @allow_reuse should be %TRUE for server sockets (sockets that you will
28607 * eventually call g_socket_accept() on), and %FALSE for client sockets.
28608 * (Specifically, if it is %TRUE, then g_socket_bind() will set the
28609 * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if
28610 * that address was previously used by another socket that has not yet been
28611 * fully cleaned-up by the kernel. Failing to set this flag on a server
28612 * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if
28613 * the server program is stopped and then immediately restarted.)
28615 * Returns: %TRUE on success, %FALSE on error.
28621 * g_socket_check_connect_result:
28622 * @socket: a #GSocket
28623 * @error: #GError for error reporting, or %NULL to ignore.
28625 * Checks and resets the pending connect error for the socket.
28626 * This is used to check for errors when g_socket_connect() is
28627 * used in non-blocking mode.
28629 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
28635 * g_socket_client_add_application_proxy:
28636 * @client: a #GSocketClient
28637 * @protocol: The proxy protocol
28639 * Enable proxy protocols to be handled by the application. When the
28640 * indicated proxy protocol is returned by the #GProxyResolver,
28641 * #GSocketClient will consider this protocol as supported but will
28642 * not try to find a #GProxy instance to handle handshaking. The
28643 * application must check for this case by calling
28644 * g_socket_connection_get_remote_address() on the returned
28645 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
28646 * appropriate type, to determine whether or not it needs to handle
28647 * the proxy handshaking itself.
28649 * This should be used for proxy protocols that are dialects of
28650 * another protocol such as HTTP proxy. It also allows cohabitation of
28651 * proxy protocols that are reused between protocols. A good example
28652 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
28653 * be use as generic socket proxy through the HTTP CONNECT method.
28655 * When the proxy is detected as being an application proxy, TLS handshake
28656 * will be skipped. This is required to let the application do the proxy
28657 * specific handshake.
28662 * g_socket_client_connect:
28663 * @client: a #GSocketClient.
28664 * @connectable: a #GSocketConnectable specifying the remote address.
28665 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28666 * @error: #GError for error reporting, or %NULL to ignore.
28668 * Tries to resolve the @connectable and make a network connection to it.
28670 * Upon a successful connection, a new #GSocketConnection is constructed
28671 * and returned. The caller owns this new object and must drop their
28672 * reference to it when finished with it.
28674 * The type of the #GSocketConnection object returned depends on the type of
28675 * the underlying socket that is used. For instance, for a TCP/IP connection
28676 * it will be a #GTcpConnection.
28678 * The socket created will be the same family as the address that the
28679 * @connectable resolves to, unless family is set with g_socket_client_set_family()
28680 * or indirectly via g_socket_client_set_local_address(). The socket type
28681 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
28682 * g_socket_client_set_socket_type().
28684 * If a local address is specified with g_socket_client_set_local_address() the
28685 * socket will be bound to this address before connecting.
28687 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28693 * g_socket_client_connect_async:
28694 * @client: a #GSocketClient
28695 * @connectable: a #GSocketConnectable specifying the remote address.
28696 * @cancellable: (allow-none): a #GCancellable, or %NULL
28697 * @callback: (scope async): a #GAsyncReadyCallback
28698 * @user_data: (closure): user data for the callback
28700 * This is the asynchronous version of g_socket_client_connect().
28702 * When the operation is finished @callback will be
28703 * called. You can then call g_socket_client_connect_finish() to get
28704 * the result of the operation.
28711 * g_socket_client_connect_finish:
28712 * @client: a #GSocketClient.
28713 * @result: a #GAsyncResult.
28714 * @error: a #GError location to store the error occurring, or %NULL to ignore.
28716 * Finishes an async connect operation. See g_socket_client_connect_async()
28718 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28724 * g_socket_client_connect_to_host:
28725 * @client: a #GSocketClient
28726 * @host_and_port: the name and optionally port of the host to connect to
28727 * @default_port: the default port to connect to
28728 * @cancellable: (allow-none): a #GCancellable, or %NULL
28729 * @error: a pointer to a #GError, or %NULL
28731 * This is a helper function for g_socket_client_connect().
28733 * Attempts to create a TCP connection to the named host.
28735 * @host_and_port may be in any of a number of recognized formats; an IPv6
28736 * address, an IPv4 address, or a domain name (in which case a DNS
28737 * lookup is performed). Quoting with [] is supported for all address
28738 * types. A port override may be specified in the usual way with a
28739 * colon. Ports may be given as decimal numbers or symbolic names (in
28740 * which case an /etc/services lookup is performed).
28742 * If no port override is given in @host_and_port then @default_port will be
28743 * used as the port number to connect to.
28745 * In general, @host_and_port is expected to be provided by the user (allowing
28746 * them to give the hostname, and a port override if necessary) and
28747 * @default_port is expected to be provided by the application.
28749 * In the case that an IP address is given, a single connection
28750 * attempt is made. In the case that a name is given, multiple
28751 * connection attempts may be made, in turn and according to the
28752 * number of address records in DNS, until a connection succeeds.
28754 * Upon a successful connection, a new #GSocketConnection is constructed
28755 * and returned. The caller owns this new object and must drop their
28756 * reference to it when finished with it.
28758 * In the event of any failure (DNS error, service not found, no hosts
28759 * connectable) %NULL is returned and @error (if non-%NULL) is set
28762 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28768 * g_socket_client_connect_to_host_async:
28769 * @client: a #GSocketClient
28770 * @host_and_port: the name and optionally the port of the host to connect to
28771 * @default_port: the default port to connect to
28772 * @cancellable: (allow-none): a #GCancellable, or %NULL
28773 * @callback: (scope async): a #GAsyncReadyCallback
28774 * @user_data: (closure): user data for the callback
28776 * This is the asynchronous version of g_socket_client_connect_to_host().
28778 * When the operation is finished @callback will be
28779 * called. You can then call g_socket_client_connect_to_host_finish() to get
28780 * the result of the operation.
28787 * g_socket_client_connect_to_host_finish:
28788 * @client: a #GSocketClient.
28789 * @result: a #GAsyncResult.
28790 * @error: a #GError location to store the error occurring, or %NULL to ignore.
28792 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
28794 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28800 * g_socket_client_connect_to_service:
28801 * @client: a #GSocketConnection
28802 * @domain: a domain name
28803 * @service: the name of the service to connect to
28804 * @cancellable: (allow-none): a #GCancellable, or %NULL
28805 * @error: a pointer to a #GError, or %NULL
28807 * Attempts to create a TCP connection to a service.
28809 * This call looks up the SRV record for @service at @domain for the
28810 * "tcp" protocol. It then attempts to connect, in turn, to each of
28811 * the hosts providing the service until either a connection succeeds
28812 * or there are no hosts remaining.
28814 * Upon a successful connection, a new #GSocketConnection is constructed
28815 * and returned. The caller owns this new object and must drop their
28816 * reference to it when finished with it.
28818 * In the event of any failure (DNS error, service not found, no hosts
28819 * connectable) %NULL is returned and @error (if non-%NULL) is set
28822 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
28827 * g_socket_client_connect_to_service_async:
28828 * @client: a #GSocketClient
28829 * @domain: a domain name
28830 * @service: the name of the service to connect to
28831 * @cancellable: (allow-none): a #GCancellable, or %NULL
28832 * @callback: (scope async): a #GAsyncReadyCallback
28833 * @user_data: (closure): user data for the callback
28835 * This is the asynchronous version of
28836 * g_socket_client_connect_to_service().
28843 * g_socket_client_connect_to_service_finish:
28844 * @client: a #GSocketClient.
28845 * @result: a #GAsyncResult.
28846 * @error: a #GError location to store the error occurring, or %NULL to ignore.
28848 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
28850 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28856 * g_socket_client_connect_to_uri:
28857 * @client: a #GSocketClient
28858 * @uri: A network URI
28859 * @default_port: the default port to connect to
28860 * @cancellable: (allow-none): a #GCancellable, or %NULL
28861 * @error: a pointer to a #GError, or %NULL
28863 * This is a helper function for g_socket_client_connect().
28865 * Attempts to create a TCP connection with a network URI.
28867 * @uri may be any valid URI containing an "authority" (hostname/port)
28868 * component. If a port is not specified in the URI, @default_port
28869 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
28870 * (#GSocketClient does not know to automatically assume TLS for
28871 * certain URI schemes.)
28873 * Using this rather than g_socket_client_connect() or
28874 * g_socket_client_connect_to_host() allows #GSocketClient to
28875 * determine when to use application-specific proxy protocols.
28877 * Upon a successful connection, a new #GSocketConnection is constructed
28878 * and returned. The caller owns this new object and must drop their
28879 * reference to it when finished with it.
28881 * In the event of any failure (DNS error, service not found, no hosts
28882 * connectable) %NULL is returned and @error (if non-%NULL) is set
28885 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28891 * g_socket_client_connect_to_uri_async:
28892 * @client: a #GSocketClient
28893 * @uri: a network uri
28894 * @default_port: the default port to connect to
28895 * @cancellable: (allow-none): a #GCancellable, or %NULL
28896 * @callback: (scope async): a #GAsyncReadyCallback
28897 * @user_data: (closure): user data for the callback
28899 * This is the asynchronous version of g_socket_client_connect_to_uri().
28901 * When the operation is finished @callback will be
28902 * called. You can then call g_socket_client_connect_to_uri_finish() to get
28903 * the result of the operation.
28910 * g_socket_client_connect_to_uri_finish:
28911 * @client: a #GSocketClient.
28912 * @result: a #GAsyncResult.
28913 * @error: a #GError location to store the error occurring, or %NULL to ignore.
28915 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
28917 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
28923 * g_socket_client_get_enable_proxy:
28924 * @client: a #GSocketClient.
28926 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
28928 * Returns: whether proxying is enabled
28934 * g_socket_client_get_family:
28935 * @client: a #GSocketClient.
28937 * Gets the socket family of the socket client.
28939 * See g_socket_client_set_family() for details.
28941 * Returns: a #GSocketFamily
28947 * g_socket_client_get_local_address:
28948 * @client: a #GSocketClient.
28950 * Gets the local address of the socket client.
28952 * See g_socket_client_set_local_address() for details.
28954 * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
28960 * g_socket_client_get_protocol:
28961 * @client: a #GSocketClient
28963 * Gets the protocol name type of the socket client.
28965 * See g_socket_client_set_protocol() for details.
28967 * Returns: a #GSocketProtocol
28973 * g_socket_client_get_socket_type:
28974 * @client: a #GSocketClient.
28976 * Gets the socket type of the socket client.
28978 * See g_socket_client_set_socket_type() for details.
28980 * Returns: a #GSocketFamily
28986 * g_socket_client_get_timeout:
28987 * @client: a #GSocketClient
28989 * Gets the I/O timeout time for sockets created by @client.
28991 * See g_socket_client_set_timeout() for details.
28993 * Returns: the timeout in seconds
28999 * g_socket_client_get_tls:
29000 * @client: a #GSocketClient.
29002 * Gets whether @client creates TLS connections. See
29003 * g_socket_client_set_tls() for details.
29005 * Returns: whether @client uses TLS
29011 * g_socket_client_get_tls_validation_flags:
29012 * @client: a #GSocketClient.
29014 * Gets the TLS validation flags used creating TLS connections via
29017 * Returns: the TLS validation flags
29023 * g_socket_client_new:
29025 * Creates a new #GSocketClient with the default options.
29027 * Returns: a #GSocketClient. Free the returned object with g_object_unref().
29033 * g_socket_client_set_enable_proxy:
29034 * @client: a #GSocketClient.
29035 * @enable: whether to enable proxies
29037 * Sets whether or not @client attempts to make connections via a
29038 * proxy server. When enabled (the default), #GSocketClient will use a
29039 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
29040 * needed, and automatically do the necessary proxy negotiation.
29047 * g_socket_client_set_family:
29048 * @client: a #GSocketClient.
29049 * @family: a #GSocketFamily
29051 * Sets the socket family of the socket client.
29052 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
29053 * then the sockets created by this object will be of the specified
29056 * This might be useful for instance if you want to force the local
29057 * connection to be an ipv4 socket, even though the address might
29058 * be an ipv6 mapped to ipv4 address.
29065 * g_socket_client_set_local_address:
29066 * @client: a #GSocketClient.
29067 * @address: (allow-none): a #GSocketAddress, or %NULL
29069 * Sets the local address of the socket client.
29070 * The sockets created by this object will bound to the
29071 * specified address (if not %NULL) before connecting.
29073 * This is useful if you want to ensure that the local
29074 * side of the connection is on a specific port, or on
29075 * a specific interface.
29082 * g_socket_client_set_protocol:
29083 * @client: a #GSocketClient.
29084 * @protocol: a #GSocketProtocol
29086 * Sets the protocol of the socket client.
29087 * The sockets created by this object will use of the specified
29090 * If @protocol is %0 that means to use the default
29091 * protocol for the socket family and type.
29098 * g_socket_client_set_socket_type:
29099 * @client: a #GSocketClient.
29100 * @type: a #GSocketType
29102 * Sets the socket type of the socket client.
29103 * The sockets created by this object will be of the specified
29106 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
29107 * as GSocketClient is used for connection oriented services.
29114 * g_socket_client_set_timeout:
29115 * @client: a #GSocketClient.
29116 * @timeout: the timeout
29118 * Sets the I/O timeout for sockets created by @client. @timeout is a
29119 * time in seconds, or 0 for no timeout (the default).
29121 * The timeout value affects the initial connection attempt as well,
29122 * so setting this may cause calls to g_socket_client_connect(), etc,
29123 * to fail with %G_IO_ERROR_TIMED_OUT.
29130 * g_socket_client_set_tls:
29131 * @client: a #GSocketClient.
29132 * @tls: whether to use TLS
29134 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
29135 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
29136 * and perform a TLS handshake when connecting.
29138 * Note that since #GSocketClient must return a #GSocketConnection,
29139 * but #GTlsClientConnection is not a #GSocketConnection, this
29140 * actually wraps the resulting #GTlsClientConnection in a
29141 * #GTcpWrapperConnection when returning it. You can use
29142 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
29143 * to extract the #GTlsClientConnection.
29145 * If you need to modify the behavior of the TLS handshake (eg, by
29146 * setting a client-side certificate to use, or connecting to the
29147 * #GTlsConnection::accept-certificate signal), you can connect to
29148 * @client's #GSocketClient::event signal and wait for it to be
29149 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
29150 * a chance to see the #GTlsClientConnection before the handshake
29158 * g_socket_client_set_tls_validation_flags:
29159 * @client: a #GSocketClient.
29160 * @flags: the validation flags
29162 * Sets the TLS validation flags used when creating TLS connections
29163 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
29171 * @socket: a #GSocket
29172 * @error: #GError for error reporting, or %NULL to ignore.
29174 * Closes the socket, shutting down any active connection.
29176 * Closing a socket does not wait for all outstanding I/O operations
29177 * to finish, so the caller should not rely on them to be guaranteed
29178 * to complete even if the close returns with no error.
29180 * Once the socket is closed, all other operations will return
29181 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
29184 * Sockets will be automatically closed when the last reference
29185 * is dropped, but you might want to call this function to make sure
29186 * resources are released as early as possible.
29188 * Beware that due to the way that TCP works, it is possible for
29189 * recently-sent data to be lost if either you close a socket while the
29190 * %G_IO_IN condition is set, or else if the remote connection tries to
29191 * send something to you after you close the socket but before it has
29192 * finished reading all of the data you sent. There is no easy generic
29193 * way to avoid this problem; the easiest fix is to design the network
29194 * protocol such that the client will never send data "out of turn".
29195 * Another solution is for the server to half-close the connection by
29196 * calling g_socket_shutdown() with only the @shutdown_write flag set,
29197 * and then wait for the client to notice this and close its side of the
29198 * connection, after which the server can safely call g_socket_close().
29199 * (This is what #GTcpConnection does if you call
29200 * g_tcp_connection_set_graceful_disconnect(). But of course, this
29201 * only works if the client will close its connection after the server
29204 * Returns: %TRUE on success, %FALSE on error
29210 * g_socket_condition_check:
29211 * @socket: a #GSocket
29212 * @condition: a #GIOCondition mask to check
29214 * Checks on the readiness of @socket to perform operations.
29215 * The operations specified in @condition are checked for and masked
29216 * against the currently-satisfied conditions on @socket. The result
29219 * Note that on Windows, it is possible for an operation to return
29220 * %G_IO_ERROR_WOULD_BLOCK even immediately after
29221 * g_socket_condition_check() has claimed that the socket is ready for
29222 * writing. Rather than calling g_socket_condition_check() and then
29223 * writing to the socket if it succeeds, it is generally better to
29224 * simply try writing to the socket right away, and try again later if
29225 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
29227 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
29228 * these conditions will always be set in the output if they are true.
29230 * This call never blocks.
29232 * Returns: the @GIOCondition mask of the current state
29238 * g_socket_condition_timed_wait:
29239 * @socket: a #GSocket
29240 * @condition: a #GIOCondition mask to wait for
29241 * @timeout: the maximum time (in microseconds) to wait, or -1
29242 * @cancellable: (allow-none): a #GCancellable, or %NULL
29243 * @error: a #GError pointer, or %NULL
29245 * Waits for up to @timeout microseconds for @condition to become true
29246 * on @socket. If the condition is met, %TRUE is returned.
29248 * If @cancellable is cancelled before the condition is met, or if
29249 * @timeout (or the socket's #GSocket:timeout) is reached before the
29250 * condition is met, then %FALSE is returned and @error, if non-%NULL,
29251 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
29252 * %G_IO_ERROR_TIMED_OUT).
29254 * If you don't want a timeout, use g_socket_condition_wait().
29255 * (Alternatively, you can pass -1 for @timeout.)
29257 * Note that although @timeout is in microseconds for consistency with
29258 * other GLib APIs, this function actually only has millisecond
29259 * resolution, and the behavior is undefined if @timeout is not an
29260 * exact number of milliseconds.
29262 * Returns: %TRUE if the condition was met, %FALSE otherwise
29268 * g_socket_condition_wait:
29269 * @socket: a #GSocket
29270 * @condition: a #GIOCondition mask to wait for
29271 * @cancellable: (allow-none): a #GCancellable, or %NULL
29272 * @error: a #GError pointer, or %NULL
29274 * Waits for @condition to become true on @socket. When the condition
29275 * is met, %TRUE is returned.
29277 * If @cancellable is cancelled before the condition is met, or if the
29278 * socket has a timeout set and it is reached before the condition is
29279 * met, then %FALSE is returned and @error, if non-%NULL, is set to
29280 * the appropriate value (%G_IO_ERROR_CANCELLED or
29281 * %G_IO_ERROR_TIMED_OUT).
29283 * See also g_socket_condition_timed_wait().
29285 * Returns: %TRUE if the condition was met, %FALSE otherwise
29291 * g_socket_connect:
29292 * @socket: a #GSocket.
29293 * @address: a #GSocketAddress specifying the remote address.
29294 * @cancellable: (allow-none): a %GCancellable or %NULL
29295 * @error: #GError for error reporting, or %NULL to ignore.
29297 * Connect the socket to the specified remote address.
29299 * For connection oriented socket this generally means we attempt to make
29300 * a connection to the @address. For a connection-less socket it sets
29301 * the default address for g_socket_send() and discards all incoming datagrams
29302 * from other sources.
29304 * Generally connection oriented sockets can only connect once, but
29305 * connection-less sockets can connect multiple times to change the
29308 * If the connect call needs to do network I/O it will block, unless
29309 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
29310 * and the user can be notified of the connection finishing by waiting
29311 * for the G_IO_OUT condition. The result of the connection must then be
29312 * checked with g_socket_check_connect_result().
29314 * Returns: %TRUE if connected, %FALSE on error.
29320 * g_socket_connectable_enumerate:
29321 * @connectable: a #GSocketConnectable
29323 * Creates a #GSocketAddressEnumerator for @connectable.
29325 * Returns: (transfer full): a new #GSocketAddressEnumerator.
29331 * g_socket_connectable_proxy_enumerate:
29332 * @connectable: a #GSocketConnectable
29334 * Creates a #GSocketAddressEnumerator for @connectable that will
29335 * return #GProxyAddress<!-- -->es for addresses that you must connect
29338 * If @connectable does not implement
29339 * g_socket_connectable_proxy_enumerate(), this will fall back to
29340 * calling g_socket_connectable_enumerate().
29342 * Returns: (transfer full): a new #GSocketAddressEnumerator.
29348 * g_socket_connection_connect:
29349 * @connection: a #GSocketConnection
29350 * @address: a #GSocketAddress specifying the remote address.
29351 * @cancellable: (allow-none): a %GCancellable or %NULL
29352 * @error: #GError for error reporting, or %NULL to ignore.
29354 * Connect @connection to the specified remote address.
29356 * Returns: %TRUE if the connection succeeded, %FALSE on error
29362 * g_socket_connection_connect_async:
29363 * @connection: a #GSocketConnection
29364 * @address: a #GSocketAddress specifying the remote address.
29365 * @cancellable: (allow-none): a %GCancellable or %NULL
29366 * @callback: (scope async): a #GAsyncReadyCallback
29367 * @user_data: (closure): user data for the callback
29369 * Asynchronously connect @connection to the specified remote address.
29371 * This clears the #GSocket:blocking flag on @connection's underlying
29372 * socket if it is currently set.
29374 * Use g_socket_connection_connect_finish() to retrieve the result.
29381 * g_socket_connection_connect_finish:
29382 * @connection: a #GSocketConnection
29383 * @result: the #GAsyncResult
29384 * @error: #GError for error reporting, or %NULL to ignore.
29386 * Gets the result of a g_socket_connection_connect_async() call.
29388 * Returns: %TRUE if the connection succeeded, %FALSE on error
29394 * g_socket_connection_factory_create_connection:
29395 * @socket: a #GSocket
29397 * Creates a #GSocketConnection subclass of the right type for
29400 * Returns: (transfer full): a #GSocketConnection
29406 * g_socket_connection_factory_lookup_type:
29407 * @family: a #GSocketFamily
29408 * @type: a #GSocketType
29409 * @protocol_id: a protocol id
29411 * Looks up the #GType to be used when creating socket connections on
29412 * sockets with the specified @family, @type and @protocol_id.
29414 * If no type is registered, the #GSocketConnection base type is returned.
29416 * Returns: a #GType
29422 * g_socket_connection_factory_register_type:
29423 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
29424 * @family: a #GSocketFamily
29425 * @type: a #GSocketType
29426 * @protocol: a protocol id
29428 * Looks up the #GType to be used when creating socket connections on
29429 * sockets with the specified @family, @type and @protocol.
29431 * If no type is registered, the #GSocketConnection base type is returned.
29438 * g_socket_connection_get_local_address:
29439 * @connection: a #GSocketConnection
29440 * @error: #GError for error reporting, or %NULL to ignore.
29442 * Try to get the local address of a socket connection.
29444 * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
29450 * g_socket_connection_get_remote_address:
29451 * @connection: a #GSocketConnection
29452 * @error: #GError for error reporting, or %NULL to ignore.
29454 * Try to get the remote address of a socket connection.
29456 * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
29462 * g_socket_connection_get_socket:
29463 * @connection: a #GSocketConnection
29465 * Gets the underlying #GSocket object of the connection.
29466 * This can be useful if you want to do something unusual on it
29467 * not supported by the #GSocketConnection APIs.
29469 * Returns: (transfer none): a #GSocketAddress or %NULL on error.
29475 * g_socket_connection_is_connected:
29476 * @connection: a #GSocketConnection
29478 * Checks if @connection is connected. This is equivalent to calling
29479 * g_socket_is_connected() on @connection's underlying #GSocket.
29481 * Returns: whether @connection is connected
29487 * g_socket_control_message_deserialize:
29488 * @level: a socket level
29489 * @type: a socket control message type for the given @level
29490 * @size: the size of the data in bytes
29491 * @data: (array length=size) (element-type guint8): pointer to the message data
29493 * Tries to deserialize a socket control message of a given
29494 * @level and @type. This will ask all known (to GType) subclasses
29495 * of #GSocketControlMessage if they can understand this kind
29496 * of message and if so deserialize it into a #GSocketControlMessage.
29498 * If there is no implementation for this kind of control message, %NULL
29499 * will be returned.
29501 * Returns: (transfer full): the deserialized message or %NULL
29507 * g_socket_control_message_get_level:
29508 * @message: a #GSocketControlMessage
29510 * Returns the "level" (i.e. the originating protocol) of the control message.
29511 * This is often SOL_SOCKET.
29513 * Returns: an integer describing the level
29519 * g_socket_control_message_get_msg_type:
29520 * @message: a #GSocketControlMessage
29522 * Returns the protocol specific type of the control message.
29523 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
29525 * Returns: an integer describing the type of control message
29531 * g_socket_control_message_get_size:
29532 * @message: a #GSocketControlMessage
29534 * Returns the space required for the control message, not including
29535 * headers or alignment.
29537 * Returns: The number of bytes required.
29543 * g_socket_control_message_serialize:
29544 * @message: a #GSocketControlMessage
29545 * @data: A buffer to write data to
29547 * Converts the data in the message to bytes placed in the
29550 * @data is guaranteed to have enough space to fit the size
29551 * returned by g_socket_control_message_get_size() on this
29559 * g_socket_create_source: (skip)
29560 * @socket: a #GSocket
29561 * @condition: a #GIOCondition mask to monitor
29562 * @cancellable: (allow-none): a %GCancellable or %NULL
29564 * Creates a %GSource that can be attached to a %GMainContext to monitor
29565 * for the availibility of the specified @condition on the socket.
29567 * The callback on the source is of the #GSocketSourceFunc type.
29569 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
29570 * these conditions will always be reported output if they are true.
29572 * @cancellable if not %NULL can be used to cancel the source, which will
29573 * cause the source to trigger, reporting the current condition (which
29574 * is likely 0 unless cancellation happened at the same time as a
29575 * condition change). You can check for this in the callback using
29576 * g_cancellable_is_cancelled().
29578 * If @socket has a timeout set, and it is reached before @condition
29579 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
29580 * %G_IO_OUT depending on @condition. However, @socket will have been
29581 * marked as having had a timeout, and so the next #GSocket I/O method
29582 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
29584 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
29590 * g_socket_get_available_bytes:
29591 * @socket: a #GSocket
29593 * Get the amount of data pending in the OS input buffer.
29595 * Returns: the number of bytes that can be read from the socket without blocking or -1 on error.
29601 * g_socket_get_blocking:
29602 * @socket: a #GSocket.
29604 * Gets the blocking mode of the socket. For details on blocking I/O,
29605 * see g_socket_set_blocking().
29607 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
29613 * g_socket_get_broadcast:
29614 * @socket: a #GSocket.
29616 * Gets the broadcast setting on @socket; if %TRUE,
29617 * it is possible to send packets to broadcast
29618 * addresses or receive from broadcast addresses.
29620 * Returns: the broadcast setting on @socket
29626 * g_socket_get_credentials:
29627 * @socket: a #GSocket.
29628 * @error: #GError for error reporting, or %NULL to ignore.
29630 * Returns the credentials of the foreign process connected to this
29631 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
29634 * If this operation isn't supported on the OS, the method fails with
29635 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
29636 * by reading the %SO_PEERCRED option on the underlying socket.
29638 * Other ways to obtain credentials from a foreign peer includes the
29639 * #GUnixCredentialsMessage type and
29640 * g_unix_connection_send_credentials() /
29641 * g_unix_connection_receive_credentials() functions.
29643 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref().
29649 * g_socket_get_family:
29650 * @socket: a #GSocket.
29652 * Gets the socket family of the socket.
29654 * Returns: a #GSocketFamily
29661 * @socket: a #GSocket.
29663 * Returns the underlying OS socket object. On unix this
29664 * is a socket file descriptor, and on Windows this is
29665 * a Winsock2 SOCKET handle. This may be useful for
29666 * doing platform specific or otherwise unusual operations
29669 * Returns: the file descriptor of the socket.
29675 * g_socket_get_keepalive:
29676 * @socket: a #GSocket.
29678 * Gets the keepalive mode of the socket. For details on this,
29679 * see g_socket_set_keepalive().
29681 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
29687 * g_socket_get_listen_backlog:
29688 * @socket: a #GSocket.
29690 * Gets the listen backlog setting of the socket. For details on this,
29691 * see g_socket_set_listen_backlog().
29693 * Returns: the maximum number of pending connections.
29699 * g_socket_get_local_address:
29700 * @socket: a #GSocket.
29701 * @error: #GError for error reporting, or %NULL to ignore.
29703 * Try to get the local address of a bound socket. This is only
29704 * useful if the socket has been bound to a local address,
29705 * either explicitly or implicitly when connecting.
29707 * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
29713 * g_socket_get_multicast_loopback:
29714 * @socket: a #GSocket.
29716 * Gets the multicast loopback setting on @socket; if %TRUE (the
29717 * default), outgoing multicast packets will be looped back to
29718 * multicast listeners on the same host.
29720 * Returns: the multicast loopback setting on @socket
29726 * g_socket_get_multicast_ttl:
29727 * @socket: a #GSocket.
29729 * Gets the multicast time-to-live setting on @socket; see
29730 * g_socket_set_multicast_ttl() for more details.
29732 * Returns: the multicast time-to-live setting on @socket
29738 * g_socket_get_protocol:
29739 * @socket: a #GSocket.
29741 * Gets the socket protocol id the socket was created with.
29742 * In case the protocol is unknown, -1 is returned.
29744 * Returns: a protocol id, or -1 if unknown
29750 * g_socket_get_remote_address:
29751 * @socket: a #GSocket.
29752 * @error: #GError for error reporting, or %NULL to ignore.
29754 * Try to get the remove address of a connected socket. This is only
29755 * useful for connection oriented sockets that have been connected.
29757 * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
29763 * g_socket_get_socket_type:
29764 * @socket: a #GSocket.
29766 * Gets the socket type of the socket.
29768 * Returns: a #GSocketType
29774 * g_socket_get_timeout:
29775 * @socket: a #GSocket.
29777 * Gets the timeout setting of the socket. For details on this, see
29778 * g_socket_set_timeout().
29780 * Returns: the timeout in seconds
29786 * g_socket_get_ttl:
29787 * @socket: a #GSocket.
29789 * Gets the unicast time-to-live setting on @socket; see
29790 * g_socket_set_ttl() for more details.
29792 * Returns: the time-to-live setting on @socket
29798 * g_socket_is_closed:
29799 * @socket: a #GSocket
29801 * Checks whether a socket is closed.
29803 * Returns: %TRUE if socket is closed, %FALSE otherwise
29809 * g_socket_is_connected:
29810 * @socket: a #GSocket.
29812 * Check whether the socket is connected. This is only useful for
29813 * connection-oriented sockets.
29815 * Returns: %TRUE if socket is connected, %FALSE otherwise.
29821 * g_socket_join_multicast_group:
29822 * @socket: a #GSocket.
29823 * @group: a #GInetAddress specifying the group address to join.
29824 * @iface: (allow-none): Name of the interface to use, or %NULL
29825 * @source_specific: %TRUE if source-specific multicast should be used
29826 * @error: #GError for error reporting, or %NULL to ignore.
29828 * Registers @socket to receive multicast messages sent to @group.
29829 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
29830 * been bound to an appropriate interface and port with
29833 * If @iface is %NULL, the system will automatically pick an interface
29834 * to bind to based on @group.
29836 * If @source_specific is %TRUE, source-specific multicast as defined
29837 * in RFC 4604 is used. Note that on older platforms this may fail
29838 * with a %G_IO_ERROR_NOT_SUPPORTED error.
29840 * Returns: %TRUE on success, %FALSE on error.
29846 * g_socket_leave_multicast_group:
29847 * @socket: a #GSocket.
29848 * @group: a #GInetAddress specifying the group address to leave.
29849 * @iface: (allow-none): Interface used
29850 * @source_specific: %TRUE if source-specific multicast was used
29851 * @error: #GError for error reporting, or %NULL to ignore.
29853 * Removes @socket from the multicast group defined by @group, @iface,
29854 * and @source_specific (which must all have the same values they had
29855 * when you joined the group).
29857 * @socket remains bound to its address and port, and can still receive
29858 * unicast messages after calling this.
29860 * Returns: %TRUE on success, %FALSE on error.
29867 * @socket: a #GSocket.
29868 * @error: #GError for error reporting, or %NULL to ignore.
29870 * Marks the socket as a server socket, i.e. a socket that is used
29871 * to accept incoming requests using g_socket_accept().
29873 * Before calling this the socket must be bound to a local address using
29876 * To set the maximum amount of outstanding clients, use
29877 * g_socket_set_listen_backlog().
29879 * Returns: %TRUE on success, %FALSE on error.
29885 * g_socket_listener_accept:
29886 * @listener: a #GSocketListener
29887 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
29888 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29889 * @error: #GError for error reporting, or %NULL to ignore.
29891 * Blocks waiting for a client to connect to any of the sockets added
29892 * to the listener. Returns a #GSocketConnection for the socket that was
29895 * If @source_object is not %NULL it will be filled out with the source
29896 * object specified when the corresponding socket or address was added
29899 * If @cancellable is not %NULL, then the operation can be cancelled by
29900 * triggering the cancellable object from another thread. If the operation
29901 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
29903 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
29909 * g_socket_listener_accept_async:
29910 * @listener: a #GSocketListener
29911 * @cancellable: (allow-none): a #GCancellable, or %NULL
29912 * @callback: (scope async): a #GAsyncReadyCallback
29913 * @user_data: (closure): user data for the callback
29915 * This is the asynchronous version of g_socket_listener_accept().
29917 * When the operation is finished @callback will be
29918 * called. You can then call g_socket_listener_accept_socket()
29919 * to get the result of the operation.
29926 * g_socket_listener_accept_finish:
29927 * @listener: a #GSocketListener
29928 * @result: a #GAsyncResult.
29929 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
29930 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29932 * Finishes an async accept operation. See g_socket_listener_accept_async()
29934 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
29940 * g_socket_listener_accept_socket:
29941 * @listener: a #GSocketListener
29942 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
29943 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29944 * @error: #GError for error reporting, or %NULL to ignore.
29946 * Blocks waiting for a client to connect to any of the sockets added
29947 * to the listener. Returns the #GSocket that was accepted.
29949 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
29950 * which is often the case, then you should use g_socket_listener_accept()
29953 * If @source_object is not %NULL it will be filled out with the source
29954 * object specified when the corresponding socket or address was added
29957 * If @cancellable is not %NULL, then the operation can be cancelled by
29958 * triggering the cancellable object from another thread. If the operation
29959 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
29961 * Returns: (transfer full): a #GSocket on success, %NULL on error.
29967 * g_socket_listener_accept_socket_async:
29968 * @listener: a #GSocketListener
29969 * @cancellable: (allow-none): a #GCancellable, or %NULL
29970 * @callback: (scope async): a #GAsyncReadyCallback
29971 * @user_data: (closure): user data for the callback
29973 * This is the asynchronous version of g_socket_listener_accept_socket().
29975 * When the operation is finished @callback will be
29976 * called. You can then call g_socket_listener_accept_socket_finish()
29977 * to get the result of the operation.
29984 * g_socket_listener_accept_socket_finish:
29985 * @listener: a #GSocketListener
29986 * @result: a #GAsyncResult.
29987 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
29988 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29990 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
29992 * Returns: (transfer full): a #GSocket on success, %NULL on error.
29998 * g_socket_listener_add_address:
29999 * @listener: a #GSocketListener
30000 * @address: a #GSocketAddress
30001 * @type: a #GSocketType
30002 * @protocol: a #GSocketProtocol
30003 * @source_object: (allow-none): Optional #GObject identifying this source
30004 * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
30005 * @error: #GError for error reporting, or %NULL to ignore.
30007 * Creates a socket of type @type and protocol @protocol, binds
30008 * it to @address and adds it to the set of sockets we're accepting
30011 * Note that adding an IPv6 address, depending on the platform,
30012 * may or may not result in a listener that also accepts IPv4
30013 * connections. For more deterministic behavior, see
30014 * g_socket_listener_add_inet_port().
30016 * @source_object will be passed out in the various calls
30017 * to accept to identify this particular source, which is
30018 * useful if you're listening on multiple addresses and do
30019 * different things depending on what address is connected to.
30021 * If successful and @effective_address is non-%NULL then it will
30022 * be set to the address that the binding actually occurred at. This
30023 * is helpful for determining the port number that was used for when
30024 * requesting a binding to port 0 (ie: "any port"). This address, if
30025 * requested, belongs to the caller and must be freed.
30027 * Returns: %TRUE on success, %FALSE on error.
30033 * g_socket_listener_add_any_inet_port:
30034 * @listener: a #GSocketListener
30035 * @source_object: (allow-none): Optional #GObject identifying this source
30036 * @error: a #GError location to store the error occurring, or %NULL to ignore.
30038 * Listens for TCP connections on any available port number for both
30039 * IPv6 and IPv4 (if each is available).
30041 * This is useful if you need to have a socket for incoming connections
30042 * but don't care about the specific port number.
30044 * @source_object will be passed out in the various calls
30045 * to accept to identify this particular source, which is
30046 * useful if you're listening on multiple addresses and do
30047 * different things depending on what address is connected to.
30049 * Returns: the port number, or 0 in case of failure.
30055 * g_socket_listener_add_inet_port:
30056 * @listener: a #GSocketListener
30057 * @port: an IP port number (non-zero)
30058 * @source_object: (allow-none): Optional #GObject identifying this source
30059 * @error: #GError for error reporting, or %NULL to ignore.
30061 * Helper function for g_socket_listener_add_address() that
30062 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
30063 * supported) on the specified port on all interfaces.
30065 * @source_object will be passed out in the various calls
30066 * to accept to identify this particular source, which is
30067 * useful if you're listening on multiple addresses and do
30068 * different things depending on what address is connected to.
30070 * Returns: %TRUE on success, %FALSE on error.
30076 * g_socket_listener_add_socket:
30077 * @listener: a #GSocketListener
30078 * @socket: a listening #GSocket
30079 * @source_object: (allow-none): Optional #GObject identifying this source
30080 * @error: #GError for error reporting, or %NULL to ignore.
30082 * Adds @socket to the set of sockets that we try to accept
30083 * new clients from. The socket must be bound to a local
30084 * address and listened to.
30086 * @source_object will be passed out in the various calls
30087 * to accept to identify this particular source, which is
30088 * useful if you're listening on multiple addresses and do
30089 * different things depending on what address is connected to.
30091 * Returns: %TRUE on success, %FALSE on error.
30097 * g_socket_listener_close:
30098 * @listener: a #GSocketListener
30100 * Closes all the sockets in the listener.
30107 * g_socket_listener_new:
30109 * Creates a new #GSocketListener with no sockets to listen for.
30110 * New listeners can be added with e.g. g_socket_listener_add_address()
30111 * or g_socket_listener_add_inet_port().
30113 * Returns: a new #GSocketListener.
30119 * g_socket_listener_set_backlog:
30120 * @listener: a #GSocketListener
30121 * @listen_backlog: an integer
30123 * Sets the listen backlog on the sockets in the listener.
30125 * See g_socket_set_listen_backlog() for details
30133 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
30134 * @type: the socket type to use.
30135 * @protocol: the id of the protocol to use, or 0 for default.
30136 * @error: #GError for error reporting, or %NULL to ignore.
30138 * Creates a new #GSocket with the defined family, type and protocol.
30139 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
30140 * for the family and type is used.
30142 * The @protocol is a family and type specific int that specifies what
30143 * kind of protocol to use. #GSocketProtocol lists several common ones.
30144 * Many families only support one protocol, and use 0 for this, others
30145 * support several and using 0 means to use the default protocol for
30146 * the family and type.
30148 * The protocol id is passed directly to the operating
30149 * system, so you can use protocols not listed in #GSocketProtocol if you
30150 * know the protocol number used for it.
30152 * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref().
30158 * g_socket_new_from_fd:
30159 * @fd: a native socket file descriptor.
30160 * @error: #GError for error reporting, or %NULL to ignore.
30162 * Creates a new #GSocket from a native file descriptor
30163 * or winsock SOCKET handle.
30165 * This reads all the settings from the file descriptor so that
30166 * all properties should work. Note that the file descriptor
30167 * will be set to non-blocking mode, independent on the blocking
30168 * mode of the #GSocket.
30170 * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref().
30176 * g_socket_receive:
30177 * @socket: a #GSocket
30178 * @buffer: a buffer to read data into (which should be at least @size bytes long).
30179 * @size: the number of bytes you want to read from the socket
30180 * @cancellable: (allow-none): a %GCancellable or %NULL
30181 * @error: #GError for error reporting, or %NULL to ignore.
30183 * Receive data (up to @size bytes) from a socket. This is mainly used by
30184 * connection-oriented sockets; it is identical to g_socket_receive_from()
30185 * with @address set to %NULL.
30187 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
30188 * g_socket_receive() will always read either 0 or 1 complete messages from
30189 * the socket. If the received message is too large to fit in @buffer, then
30190 * the data beyond @size bytes will be discarded, without any explicit
30191 * indication that this has occurred.
30193 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
30194 * number of bytes, up to @size. If more than @size bytes have been
30195 * received, the additional data will be returned in future calls to
30196 * g_socket_receive().
30198 * If the socket is in blocking mode the call will block until there
30199 * is some data to receive, the connection is closed, or there is an
30200 * error. If there is no data available and the socket is in
30201 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
30202 * returned. To be notified when data is available, wait for the
30203 * %G_IO_IN condition.
30205 * On error -1 is returned and @error is set accordingly.
30207 * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
30213 * g_socket_receive_from:
30214 * @socket: a #GSocket
30215 * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL
30216 * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long).
30217 * @size: the number of bytes you want to read from the socket
30218 * @cancellable: (allow-none): a %GCancellable or %NULL
30219 * @error: #GError for error reporting, or %NULL to ignore.
30221 * Receive data (up to @size bytes) from a socket.
30223 * If @address is non-%NULL then @address will be set equal to the
30224 * source address of the received packet.
30225 * @address is owned by the caller.
30227 * See g_socket_receive() for additional information.
30229 * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
30235 * g_socket_receive_message:
30236 * @socket: a #GSocket
30237 * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL
30238 * @vectors: (array length=num_vectors): an array of #GInputVector structs
30239 * @num_vectors: the number of elements in @vectors, or -1
30240 * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL
30241 * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL
30242 * @flags: a pointer to an int containing #GSocketMsgFlags flags
30243 * @cancellable: (allow-none): a %GCancellable or %NULL
30244 * @error: a #GError pointer, or %NULL
30246 * Receive data from a socket. This is the most complicated and
30247 * fully-featured version of this call. For easier use, see
30248 * g_socket_receive() and g_socket_receive_from().
30250 * If @address is non-%NULL then @address will be set equal to the
30251 * source address of the received packet.
30252 * @address is owned by the caller.
30254 * @vector must point to an array of #GInputVector structs and
30255 * @num_vectors must be the length of this array. These structs
30256 * describe the buffers that received data will be scattered into.
30257 * If @num_vectors is -1, then @vectors is assumed to be terminated
30258 * by a #GInputVector with a %NULL buffer pointer.
30260 * As a special case, if @num_vectors is 0 (in which case, @vectors
30261 * may of course be %NULL), then a single byte is received and
30262 * discarded. This is to facilitate the common practice of sending a
30263 * single '\0' byte for the purposes of transferring ancillary data.
30265 * @messages, if non-%NULL, will be set to point to a newly-allocated
30266 * array of #GSocketControlMessage instances or %NULL if no such
30267 * messages was received. These correspond to the control messages
30268 * received from the kernel, one #GSocketControlMessage per message
30269 * from the kernel. This array is %NULL-terminated and must be freed
30270 * by the caller using g_free() after calling g_object_unref() on each
30271 * element. If @messages is %NULL, any control messages received will
30274 * @num_messages, if non-%NULL, will be set to the number of control
30275 * messages received.
30277 * If both @messages and @num_messages are non-%NULL, then
30278 * @num_messages gives the number of #GSocketControlMessage instances
30279 * in @messages (ie: not including the %NULL terminator).
30281 * @flags is an in/out parameter. The commonly available arguments
30282 * for this are available in the #GSocketMsgFlags enum, but the
30283 * values there are the same as the system values, and the flags
30284 * are passed in as-is, so you can pass in system-specific flags too
30285 * (and g_socket_receive_message() may pass system-specific flags out).
30287 * As with g_socket_receive(), data may be discarded if @socket is
30288 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
30289 * provide enough buffer space to read a complete message. You can pass
30290 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
30291 * removing it from the receive queue, but there is no portable way to find
30292 * out the length of the message other than by reading it into a
30293 * sufficiently-large buffer.
30295 * If the socket is in blocking mode the call will block until there
30296 * is some data to receive, the connection is closed, or there is an
30297 * error. If there is no data available and the socket is in
30298 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
30299 * returned. To be notified when data is available, wait for the
30300 * %G_IO_IN condition.
30302 * On error -1 is returned and @error is set accordingly.
30304 * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
30310 * g_socket_receive_with_blocking:
30311 * @socket: a #GSocket
30312 * @buffer: a buffer to read data into (which should be at least @size bytes long).
30313 * @size: the number of bytes you want to read from the socket
30314 * @blocking: whether to do blocking or non-blocking I/O
30315 * @cancellable: (allow-none): a %GCancellable or %NULL
30316 * @error: #GError for error reporting, or %NULL to ignore.
30318 * This behaves exactly the same as g_socket_receive(), except that
30319 * the choice of blocking or non-blocking behavior is determined by
30320 * the @blocking argument rather than by @socket's properties.
30322 * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
30329 * @socket: a #GSocket
30330 * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send.
30331 * @size: the number of bytes to send
30332 * @cancellable: (allow-none): a %GCancellable or %NULL
30333 * @error: #GError for error reporting, or %NULL to ignore.
30335 * Tries to send @size bytes from @buffer on the socket. This is
30336 * mainly used by connection-oriented sockets; it is identical to
30337 * g_socket_send_to() with @address set to %NULL.
30339 * If the socket is in blocking mode the call will block until there is
30340 * space for the data in the socket queue. If there is no space available
30341 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
30342 * will be returned. To be notified when space is available, wait for the
30343 * %G_IO_OUT condition. Note though that you may still receive
30344 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
30345 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
30346 * very common due to the way the underlying APIs work.)
30348 * On error -1 is returned and @error is set accordingly.
30350 * Returns: Number of bytes written (which may be less than @size), or -1 on error
30356 * g_socket_send_message:
30357 * @socket: a #GSocket
30358 * @address: (allow-none): a #GSocketAddress, or %NULL
30359 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
30360 * @num_vectors: the number of elements in @vectors, or -1
30361 * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL.
30362 * @num_messages: number of elements in @messages, or -1.
30363 * @flags: an int containing #GSocketMsgFlags flags
30364 * @cancellable: (allow-none): a %GCancellable or %NULL
30365 * @error: #GError for error reporting, or %NULL to ignore.
30367 * Send data to @address on @socket. This is the most complicated and
30368 * fully-featured version of this call. For easier use, see
30369 * g_socket_send() and g_socket_send_to().
30371 * If @address is %NULL then the message is sent to the default receiver
30372 * (set by g_socket_connect()).
30374 * @vectors must point to an array of #GOutputVector structs and
30375 * @num_vectors must be the length of this array. (If @num_vectors is -1,
30376 * then @vectors is assumed to be terminated by a #GOutputVector with a
30377 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
30378 * that the sent data will be gathered from. Using multiple
30379 * #GOutputVector<!-- -->s is more memory-efficient than manually copying
30380 * data from multiple sources into a single buffer, and more
30381 * network-efficient than making multiple calls to g_socket_send().
30383 * @messages, if non-%NULL, is taken to point to an array of @num_messages
30384 * #GSocketControlMessage instances. These correspond to the control
30385 * messages to be sent on the socket.
30386 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
30389 * @flags modify how the message is sent. The commonly available arguments
30390 * for this are available in the #GSocketMsgFlags enum, but the
30391 * values there are the same as the system values, and the flags
30392 * are passed in as-is, so you can pass in system-specific flags too.
30394 * If the socket is in blocking mode the call will block until there is
30395 * space for the data in the socket queue. If there is no space available
30396 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
30397 * will be returned. To be notified when space is available, wait for the
30398 * %G_IO_OUT condition. Note though that you may still receive
30399 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
30400 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
30401 * very common due to the way the underlying APIs work.)
30403 * On error -1 is returned and @error is set accordingly.
30405 * Returns: Number of bytes written (which may be less than @size), or -1 on error
30411 * g_socket_send_to:
30412 * @socket: a #GSocket
30413 * @address: (allow-none): a #GSocketAddress, or %NULL
30414 * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send.
30415 * @size: the number of bytes to send
30416 * @cancellable: (allow-none): a %GCancellable or %NULL
30417 * @error: #GError for error reporting, or %NULL to ignore.
30419 * Tries to send @size bytes from @buffer to @address. If @address is
30420 * %NULL then the message is sent to the default receiver (set by
30421 * g_socket_connect()).
30423 * See g_socket_send() for additional information.
30425 * Returns: Number of bytes written (which may be less than @size), or -1 on error
30431 * g_socket_send_with_blocking:
30432 * @socket: a #GSocket
30433 * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send.
30434 * @size: the number of bytes to send
30435 * @blocking: whether to do blocking or non-blocking I/O
30436 * @cancellable: (allow-none): a %GCancellable or %NULL
30437 * @error: #GError for error reporting, or %NULL to ignore.
30439 * This behaves exactly the same as g_socket_send(), except that
30440 * the choice of blocking or non-blocking behavior is determined by
30441 * the @blocking argument rather than by @socket's properties.
30443 * Returns: Number of bytes written (which may be less than @size), or -1 on error
30449 * g_socket_service_is_active:
30450 * @service: a #GSocketService
30452 * Check whether the service is active or not. An active
30453 * service will accept new clients that connect, while
30454 * a non-active service will let connecting clients queue
30455 * up until the service is started.
30457 * Returns: %TRUE if the service is active, %FALSE otherwise
30463 * g_socket_service_new:
30465 * Creates a new #GSocketService with no sockets to listen for.
30466 * New listeners can be added with e.g. g_socket_listener_add_address()
30467 * or g_socket_listener_add_inet_port().
30469 * Returns: a new #GSocketService.
30475 * g_socket_service_start:
30476 * @service: a #GSocketService
30478 * Starts the service, i.e. start accepting connections
30479 * from the added sockets when the mainloop runs.
30481 * This call is thread-safe, so it may be called from a thread
30482 * handling an incoming client request.
30489 * g_socket_service_stop:
30490 * @service: a #GSocketService
30492 * Stops the service, i.e. stops accepting connections
30493 * from the added sockets when the mainloop runs.
30495 * This call is thread-safe, so it may be called from a thread
30496 * handling an incoming client request.
30503 * g_socket_set_blocking:
30504 * @socket: a #GSocket.
30505 * @blocking: Whether to use blocking I/O or not.
30507 * Sets the blocking mode of the socket. In blocking mode
30508 * all operations block until they succeed or there is an error. In
30509 * non-blocking mode all functions return results immediately or
30510 * with a %G_IO_ERROR_WOULD_BLOCK error.
30512 * All sockets are created in blocking mode. However, note that the
30513 * platform level socket is always non-blocking, and blocking mode
30514 * is a GSocket level feature.
30521 * g_socket_set_broadcast:
30522 * @socket: a #GSocket.
30523 * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses
30525 * Sets whether @socket should allow sending to and receiving from
30526 * broadcast addresses. This is %FALSE by default.
30533 * g_socket_set_keepalive:
30534 * @socket: a #GSocket.
30535 * @keepalive: Value for the keepalive flag
30537 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
30538 * this flag is set on a socket, the system will attempt to verify that the
30539 * remote socket endpoint is still present if a sufficiently long period of
30540 * time passes with no data being exchanged. If the system is unable to
30541 * verify the presence of the remote endpoint, it will automatically close
30544 * This option is only functional on certain kinds of sockets. (Notably,
30545 * %G_SOCKET_PROTOCOL_TCP sockets.)
30547 * The exact time between pings is system- and protocol-dependent, but will
30548 * normally be at least two hours. Most commonly, you would set this flag
30549 * on a server socket if you want to allow clients to remain idle for long
30550 * periods of time, but also want to ensure that connections are eventually
30551 * garbage-collected if clients crash or become unreachable.
30558 * g_socket_set_listen_backlog:
30559 * @socket: a #GSocket.
30560 * @backlog: the maximum number of pending connections.
30562 * Sets the maximum number of outstanding connections allowed
30563 * when listening on this socket. If more clients than this are
30564 * connecting to the socket and the application is not handling them
30565 * on time then the new connections will be refused.
30567 * Note that this must be called before g_socket_listen() and has no
30568 * effect if called after that.
30575 * g_socket_set_multicast_loopback:
30576 * @socket: a #GSocket.
30577 * @loopback: whether @socket should receive messages sent to its multicast groups from the local host
30579 * Sets whether outgoing multicast packets will be received by sockets
30580 * listening on that multicast address on the same host. This is %TRUE
30588 * g_socket_set_multicast_ttl:
30589 * @socket: a #GSocket.
30590 * @ttl: the time-to-live value for all multicast datagrams on @socket
30592 * Sets the time-to-live for outgoing multicast datagrams on @socket.
30593 * By default, this is 1, meaning that multicast packets will not leave
30594 * the local network.
30601 * g_socket_set_timeout:
30602 * @socket: a #GSocket.
30603 * @timeout: the timeout for @socket, in seconds, or 0 for none
30605 * Sets the time in seconds after which I/O operations on @socket will
30606 * time out if they have not yet completed.
30608 * On a blocking socket, this means that any blocking #GSocket
30609 * operation will time out after @timeout seconds of inactivity,
30610 * returning %G_IO_ERROR_TIMED_OUT.
30612 * On a non-blocking socket, calls to g_socket_condition_wait() will
30613 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
30614 * created with g_socket_create_source() will trigger after
30615 * @timeout seconds of inactivity, with the requested condition
30616 * set, at which point calling g_socket_receive(), g_socket_send(),
30617 * g_socket_check_connect_result(), etc, will fail with
30618 * %G_IO_ERROR_TIMED_OUT.
30620 * If @timeout is 0 (the default), operations will never time out
30623 * Note that if an I/O operation is interrupted by a signal, this may
30624 * cause the timeout to be reset.
30631 * g_socket_set_ttl:
30632 * @socket: a #GSocket.
30633 * @ttl: the time-to-live value for all unicast packets on @socket
30635 * Sets the time-to-live for outgoing unicast packets on @socket.
30636 * By default the platform-specific default value is used.
30643 * g_socket_shutdown:
30644 * @socket: a #GSocket
30645 * @shutdown_read: whether to shut down the read side
30646 * @shutdown_write: whether to shut down the write side
30647 * @error: #GError for error reporting, or %NULL to ignore.
30649 * Shut down part of a full-duplex connection.
30651 * If @shutdown_read is %TRUE then the receiving side of the connection
30652 * is shut down, and further reading is disallowed.
30654 * If @shutdown_write is %TRUE then the sending side of the connection
30655 * is shut down, and further writing is disallowed.
30657 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
30659 * One example where this is used is graceful disconnect for TCP connections
30660 * where you close the sending side, then wait for the other side to close
30661 * the connection, thus ensuring that the other side saw all sent data.
30663 * Returns: %TRUE on success, %FALSE on error
30669 * g_socket_speaks_ipv4:
30670 * @socket: a #GSocket
30672 * Checks if a socket is capable of speaking IPv4.
30674 * IPv4 sockets are capable of speaking IPv4. On some operating systems
30675 * and under some combinations of circumstances IPv6 sockets are also
30676 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
30679 * No other types of sockets are currently considered as being capable
30680 * of speaking IPv4.
30682 * Returns: %TRUE if this socket can be used with IPv4.
30688 * g_srv_target_copy:
30689 * @target: a #GSrvTarget
30693 * Returns: a copy of @target
30699 * g_srv_target_free:
30700 * @target: a #GSrvTarget
30709 * g_srv_target_get_hostname:
30710 * @target: a #GSrvTarget
30712 * Gets @target's hostname (in ASCII form; if you are going to present
30713 * this to the user, you should use g_hostname_is_ascii_encoded() to
30714 * check if it contains encoded Unicode segments, and use
30715 * g_hostname_to_unicode() to convert it if it does.)
30717 * Returns: @target's hostname
30723 * g_srv_target_get_port:
30724 * @target: a #GSrvTarget
30726 * Gets @target's port
30728 * Returns: @target's port
30734 * g_srv_target_get_priority:
30735 * @target: a #GSrvTarget
30737 * Gets @target's priority. You should not need to look at this;
30738 * #GResolver already sorts the targets according to the algorithm in
30741 * Returns: @target's priority
30747 * g_srv_target_get_weight:
30748 * @target: a #GSrvTarget
30750 * Gets @target's weight. You should not need to look at this;
30751 * #GResolver already sorts the targets according to the algorithm in
30754 * Returns: @target's weight
30760 * g_srv_target_list_sort: (skip)
30761 * @targets: a #GList of #GSrvTarget
30763 * Sorts @targets in place according to the algorithm in RFC 2782.
30765 * Returns: (transfer full): the head of the sorted list.
30771 * g_srv_target_new:
30772 * @hostname: the host that the service is running on
30773 * @port: the port that the service is running on
30774 * @priority: the target's priority
30775 * @weight: the target's weight
30777 * Creates a new #GSrvTarget with the given parameters.
30779 * You should not need to use this; normally #GSrvTarget<!-- -->s are
30780 * created by #GResolver.
30782 * Returns: a new #GSrvTarget.
30788 * g_static_resource_fini:
30789 * @static_resource: pointer to a static #GStaticResource
30791 * Finalized a GResource initialized by g_static_resource_init().
30793 * This is normally used by code generated by
30794 * <link linkend="glib-compile-resources">glib-compile-resources</link>
30795 * and is not typically used by other code.
30802 * g_static_resource_get_resource:
30803 * @static_resource: pointer to a static #GStaticResource
30805 * Gets the GResource that was registered by a call to g_static_resource_init().
30807 * This is normally used by code generated by
30808 * <link linkend="glib-compile-resources">glib-compile-resources</link>
30809 * and is not typically used by other code.
30811 * Returns: (transfer none): a #GResource
30817 * g_static_resource_init:
30818 * @static_resource: pointer to a static #GStaticResource
30820 * Initializes a GResource from static data using a
30823 * This is normally used by code generated by
30824 * <link linkend="glib-compile-resources">glib-compile-resources</link>
30825 * and is not typically used by other code.
30832 * g_task_attach_source:
30834 * @source: the source to attach
30835 * @callback: the callback to invoke when @source triggers
30837 * A utility function for dealing with async operations where you need
30838 * to wait for a #GSource to trigger. Attaches @source to @task's
30839 * #GMainContext with @task's <link
30840 * linkend="io-priority">priority</link>, and sets @source's callback
30841 * to @callback, with @task as the callback's
30842 * <literal>user_data</literal>.
30844 * This takes a reference on @task until @source is destroyed.
30851 * g_task_get_cancellable:
30854 * Gets @task's #GCancellable
30856 * Returns: (transfer none): @task's #GCancellable
30862 * g_task_get_check_cancellable:
30863 * @task: the #GTask
30865 * Gets @task's check-cancellable flag. See
30866 * g_task_set_check_cancellable() for more details.
30873 * g_task_get_context:
30876 * Gets the #GMainContext that @task will return its result in (that
30877 * is, the context that was the <link
30878 * linkend="g-main-context-push-thread-default">thread-default main
30879 * context</link> at the point when @task was created).
30881 * This will always return a non-%NULL value, even if the task's
30882 * context is the default #GMainContext.
30884 * Returns: (transfer none): @task's #GMainContext
30890 * g_task_get_priority:
30893 * Gets @task's priority
30895 * Returns: @task's priority
30901 * g_task_get_return_on_cancel:
30902 * @task: the #GTask
30904 * Gets @task's return-on-cancel flag. See
30905 * g_task_set_return_on_cancel() for more details.
30912 * g_task_get_source_object:
30915 * Gets the source object from @task. Like
30916 * g_async_result_get_source_object(), but does not ref the object.
30918 * Returns: (transfer none): @task's source object, or %NULL
30924 * g_task_get_source_tag:
30927 * Gets @task's source tag. See g_task_set_source_tag().
30929 * Returns: (transfer none): @task's source tag
30935 * g_task_get_task_data:
30938 * Gets @task's <literal>task_data</literal>.
30940 * Returns: (transfer none): @task's <literal>task_data</literal>.
30946 * g_task_had_error:
30949 * Tests if @task resulted in an error.
30951 * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
30958 * @result: (type Gio.AsyncResult): A #GAsyncResult
30959 * @source_object: (allow-none): the source object expected to be associated with the task
30961 * Checks that @result is a #GTask, and that @source_object is its
30962 * source object (or that @source_object is %NULL and @result has no
30963 * source object). This can be used in g_return_if_fail() checks.
30965 * Returns: %TRUE if @result and @source_object are valid, %FALSE if not
30972 * @source_object: (allow-none): the #GObject that owns this task, or %NULL.
30973 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30974 * @callback: (scope async): a #GAsyncReadyCallback.
30975 * @callback_data: (closure): user data passed to @callback.
30977 * Creates a #GTask acting on @source_object, which will eventually be
30978 * used to invoke @callback in the current <link
30979 * linkend="g-main-context-push-thread-default">thread-default main
30982 * Call this in the "start" method of your asynchronous method, and
30983 * pass the #GTask around throughout the asynchronous operation. You
30984 * can use g_task_set_task_data() to attach task-specific data to the
30985 * object, which you can retrieve later via g_task_get_task_data().
30987 * By default, if @cancellable is cancelled, then the return value of
30988 * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
30989 * already completed before the cancellation. This allows for
30990 * simplified handling in cases where cancellation may imply that
30991 * other objects that the task depends on have been destroyed. If you
30992 * do not want this behavior, you can use
30993 * g_task_set_check_cancellable() to change it.
30995 * Returns: a #GTask.
31001 * g_task_propagate_boolean:
31003 * @error: return location for a #GError
31005 * Gets the result of @task as a #gboolean.
31007 * If the task resulted in an error, or was cancelled, then this will
31008 * instead return %FALSE and set @error.
31010 * Since this method transfers ownership of the return value (or
31011 * error) to the caller, you may only call it once.
31013 * Returns: the task result, or %FALSE on error
31019 * g_task_propagate_int:
31021 * @error: return location for a #GError
31023 * Gets the result of @task as an integer (#gssize).
31025 * If the task resulted in an error, or was cancelled, then this will
31026 * instead return -1 and set @error.
31028 * Since this method transfers ownership of the return value (or
31029 * error) to the caller, you may only call it once.
31031 * Returns: the task result, or -1 on error
31037 * g_task_propagate_pointer:
31039 * @error: return location for a #GError
31041 * Gets the result of @task as a pointer, and transfers ownership
31042 * of that value to the caller.
31044 * If the task resulted in an error, or was cancelled, then this will
31045 * instead return %NULL and set @error.
31047 * Since this method transfers ownership of the return value (or
31048 * error) to the caller, you may only call it once.
31050 * Returns: (transfer full): the task result, or %NULL on error
31056 * g_task_report_error:
31057 * @source_object: (allow-none): the #GObject that owns this task, or %NULL.
31058 * @callback: (scope async): a #GAsyncReadyCallback.
31059 * @callback_data: (closure): user data passed to @callback.
31060 * @source_tag: an opaque pointer indicating the source of this task
31061 * @error: (transfer full): error to report
31063 * Creates a #GTask and then immediately calls g_task_return_error()
31064 * on it. Use this in the wrapper function of an asynchronous method
31065 * when you want to avoid even calling the virtual method. You can
31066 * then use g_async_result_is_tagged() in the finish method wrapper to
31067 * check if the result there is tagged as having been created by the
31068 * wrapper method, and deal with it appropriately if so.
31070 * See also g_task_report_new_error().
31077 * g_task_report_new_error:
31078 * @source_object: (allow-none): the #GObject that owns this task, or %NULL.
31079 * @callback: (scope async): a #GAsyncReadyCallback.
31080 * @callback_data: (closure): user data passed to @callback.
31081 * @source_tag: an opaque pointer indicating the source of this task
31082 * @domain: a #GQuark.
31083 * @code: an error code.
31084 * @format: a string with format characters.
31085 * @...: a list of values to insert into @format.
31087 * Creates a #GTask and then immediately calls
31088 * g_task_return_new_error() on it. Use this in the wrapper function
31089 * of an asynchronous method when you want to avoid even calling the
31090 * virtual method. You can then use g_async_result_is_tagged() in the
31091 * finish method wrapper to check if the result there is tagged as
31092 * having been created by the wrapper method, and deal with it
31093 * appropriately if so.
31095 * See also g_task_report_error().
31102 * g_task_return_boolean:
31104 * @result: the #gboolean result of a task function.
31106 * Sets @task's result to @result and completes the task (see
31107 * g_task_return_pointer() for more discussion of exactly what this
31115 * g_task_return_error:
31117 * @error: (transfer full): the #GError result of a task function.
31119 * Sets @task's result to @error (which @task assumes ownership of)
31120 * and completes the task (see g_task_return_pointer() for more
31121 * discussion of exactly what this means).
31123 * Note that since the task takes ownership of @error, and since the
31124 * task may be completed before returning from g_task_return_error(),
31125 * you cannot assume that @error is still valid after calling this.
31126 * Call g_error_copy() on the error if you need to keep a local copy
31129 * See also g_task_return_new_error().
31136 * g_task_return_error_if_cancelled:
31139 * Checks if @task's #GCancellable has been cancelled, and if so, sets
31140 * @task's error accordingly and completes the task (see
31141 * g_task_return_pointer() for more discussion of exactly what this
31144 * Returns: %TRUE if @task has been cancelled, %FALSE if not
31150 * g_task_return_int:
31152 * @result: the integer (#gssize) result of a task function.
31154 * Sets @task's result to @result and completes the task (see
31155 * g_task_return_pointer() for more discussion of exactly what this
31163 * g_task_return_new_error:
31165 * @domain: a #GQuark.
31166 * @code: an error code.
31167 * @format: a string with format characters.
31168 * @...: a list of values to insert into @format.
31170 * Sets @task's result to a new #GError created from @domain, @code,
31171 * @format, and the remaining arguments, and completes the task (see
31172 * g_task_return_pointer() for more discussion of exactly what this
31175 * See also g_task_return_error().
31182 * g_task_return_pointer:
31184 * @result: (allow-none) (transfer full): the pointer result of a task function
31185 * @result_destroy: (allow-none): a #GDestroyNotify function.
31187 * Sets @task's result to @result and completes the task. If @result
31188 * is not %NULL, then @result_destroy will be used to free @result if
31189 * the caller does not take ownership of it with
31190 * g_task_propagate_pointer().
31192 * "Completes the task" means that for an ordinary asynchronous task
31193 * it will either invoke the task's callback, or else queue that
31194 * callback to be invoked in the proper #GMainContext, or in the next
31195 * iteration of the current #GMainContext. For a task run via
31196 * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
31197 * method will save @result to be returned to the caller later, but
31198 * the task will not actually be completed until the #GTaskThreadFunc
31201 * Note that since the task may be completed before returning from
31202 * g_task_return_pointer(), you cannot assume that @result is still
31203 * valid after calling this, unless you are still holding another
31211 * g_task_run_in_thread:
31213 * @task_func: a #GTaskThreadFunc
31215 * Runs @task_func in another thread. When @task_func returns, @task's
31216 * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
31218 * This takes a ref on @task until the task completes.
31220 * See #GTaskThreadFunc for more details about how @task_func is handled.
31227 * g_task_run_in_thread_sync:
31229 * @task_func: a #GTaskThreadFunc
31231 * Runs @task_func in another thread, and waits for it to return or be
31232 * cancelled. You can use g_task_propagate_pointer(), etc, afterward
31233 * to get the result of @task_func.
31235 * See #GTaskThreadFunc for more details about how @task_func is handled.
31237 * Normally this is used with tasks created with a %NULL
31238 * <literal>callback</literal>, but note that even if the task does
31239 * have a callback, it will not be invoked when @task_func returns.
31246 * g_task_set_check_cancellable:
31247 * @task: the #GTask
31248 * @check_cancellable: whether #GTask will check the state of its #GCancellable for you.
31250 * Sets or clears @task's check-cancellable flag. If this is %TRUE
31251 * (the default), then g_task_propagate_pointer(), etc, and
31252 * g_task_had_error() will check the task's #GCancellable first, and
31253 * if it has been cancelled, then they will consider the task to have
31254 * returned an "Operation was cancelled" error
31255 * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
31256 * value the task may have had.
31258 * If @check_cancellable is %FALSE, then the #GTask will not check the
31259 * cancellable itself, and it is up to @task's owner to do this (eg,
31260 * via g_task_return_error_if_cancelled()).
31262 * If you are using g_task_set_return_on_cancel() as well, then
31263 * you must leave check-cancellable set %TRUE.
31270 * g_task_set_priority:
31271 * @task: the #GTask
31272 * @priority: the <link linkend="io-priority">priority</link> of the request.
31274 * Sets @task's priority. If you do not call this, it will default to
31275 * %G_PRIORITY_DEFAULT.
31277 * This will affect the priority of #GSources created with
31278 * g_task_attach_source() and the scheduling of tasks run in threads,
31279 * and can also be explicitly retrieved later via
31280 * g_task_get_priority().
31287 * g_task_set_return_on_cancel:
31288 * @task: the #GTask
31289 * @return_on_cancel: whether the task returns automatically when it is cancelled.
31291 * Sets or clears @task's return-on-cancel flag. This is only
31292 * meaningful for tasks run via g_task_run_in_thread() or
31293 * g_task_run_in_thread_sync().
31295 * If @return_on_cancel is %TRUE, then cancelling @task's
31296 * #GCancellable will immediately cause it to return, as though the
31297 * task's #GTaskThreadFunc had called
31298 * g_task_return_error_if_cancelled() and then returned.
31300 * This allows you to create a cancellable wrapper around an
31301 * uninterruptable function. The #GTaskThreadFunc just needs to be
31302 * careful that it does not modify any externally-visible state after
31303 * it has been cancelled. To do that, the thread should call
31304 * g_task_set_return_on_cancel() again to (atomically) set
31305 * return-on-cancel %FALSE before making externally-visible changes;
31306 * if the task gets cancelled before the return-on-cancel flag could
31307 * be changed, g_task_set_return_on_cancel() will indicate this by
31308 * returning %FALSE.
31310 * You can disable and re-enable this flag multiple times if you wish.
31311 * If the task's #GCancellable is cancelled while return-on-cancel is
31312 * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
31313 * again will cause the task to be cancelled at that point.
31315 * If the task's #GCancellable is already cancelled before you call
31316 * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
31317 * #GTaskThreadFunc will still be run (for consistency), but the task
31318 * will also be completed right away.
31320 * Returns: %TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled.
31326 * g_task_set_source_tag:
31327 * @task: the #GTask
31328 * @source_tag: an opaque pointer indicating the source of this task
31330 * Sets @task's source tag. You can use this to tag a task return
31331 * value with a particular pointer (usually a pointer to the function
31332 * doing the tagging) and then later check it using
31333 * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
31334 * task's "finish" function, to figure out if the response came from a
31335 * particular place.
31342 * g_task_set_task_data:
31343 * @task: the #GTask
31344 * @task_data: (allow-none): task-specific data
31345 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
31347 * Sets @task's task data (freeing the existing task data, if any).
31354 * g_tcp_connection_get_graceful_disconnect:
31355 * @connection: a #GTcpConnection
31357 * Checks if graceful disconnects are used. See
31358 * g_tcp_connection_set_graceful_disconnect().
31360 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
31366 * g_tcp_connection_set_graceful_disconnect:
31367 * @connection: a #GTcpConnection
31368 * @graceful_disconnect: Whether to do graceful disconnects or not
31370 * This enabled graceful disconnects on close. A graceful disconnect
31371 * means that we signal the receiving end that the connection is terminated
31372 * and wait for it to close the connection before closing the connection.
31374 * A graceful disconnect means that we can be sure that we successfully sent
31375 * all the outstanding data to the other end, or get an error reported.
31376 * However, it also means we have to wait for all the data to reach the
31377 * other side and for it to acknowledge this by closing the socket, which may
31378 * take a while. For this reason it is disabled by default.
31385 * g_tcp_wrapper_connection_get_base_io_stream:
31386 * @conn: a #GTcpWrapperConnection
31388 * Get's @conn's base #GIOStream
31390 * Returns: (transfer none): @conn's base #GIOStream
31395 * g_tcp_wrapper_connection_new:
31396 * @base_io_stream: the #GIOStream to wrap
31397 * @socket: the #GSocket associated with @base_io_stream
31399 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
31401 * Returns: the new #GSocketConnection.
31407 * g_test_dbus_add_service_dir:
31408 * @self: a #GTestDBus
31409 * @path: path to a directory containing .service files
31411 * Add a path where dbus-daemon will lookup for .services files. This can't be
31412 * called after g_test_dbus_up().
31417 * g_test_dbus_down:
31418 * @self: a #GTestDBus
31420 * Stop the session bus started by g_test_dbus_up().
31422 * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
31423 * is destroyed. This is done to ensure that the next unit test won't get a
31424 * leaked singleton from this test.
31429 * g_test_dbus_get_bus_address:
31430 * @self: a #GTestDBus
31432 * Get the address on which dbus-daemon is running. if g_test_dbus_up() has not
31433 * been called yet, %NULL is returned. This can be used with
31434 * g_dbus_connection_new_for_address()
31436 * Returns: the address of the bus, or %NULL.
31441 * g_test_dbus_get_flags:
31442 * @self: a #GTestDBus
31444 * Gets the flags of the #GTestDBus object.
31446 * Returns: the value of #GTestDBus:flags property
31452 * @flags: a #GTestDBusFlags
31454 * Create a new #GTestDBus object.
31456 * Returns: (transfer full): a new #GTestDBus.
31461 * g_test_dbus_stop:
31462 * @self: a #GTestDBus
31464 * Stop the session bus started by g_test_dbus_up().
31466 * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
31467 * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
31468 * tests wanting to verify behaviour after the session bus has been stopped
31469 * can use this function but should still call g_test_dbus_down() when done.
31474 * g_test_dbus_unset:
31476 * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
31477 * won't use user's session bus.
31479 * This is useful for unit tests that want to verify behaviour when no session
31480 * bus is running. It is not necessary to call this if unit test already calls
31481 * g_test_dbus_up() before acquiring the session bus.
31487 * @self: a #GTestDBus
31489 * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
31490 * call, it is safe for unit tests to start sending messages on the session bus.
31492 * If this function is called from setup callback of g_test_add(),
31493 * g_test_dbus_down() must be called in its teardown callback.
31495 * If this function is called from unit test's main(), then g_test_dbus_down()
31496 * must be called after g_test_run().
31501 * g_themed_icon_append_name:
31502 * @icon: a #GThemedIcon
31503 * @iconname: name of icon to append to list of icons from within @icon.
31505 * Append a name to the list of icons from within @icon.
31508 * Note that doing so invalidates the hash computed by prior calls
31509 * to g_icon_hash().
31515 * g_themed_icon_get_names:
31516 * @icon: a #GThemedIcon.
31518 * Gets the names of icons from within @icon.
31520 * Returns: (transfer none): a list of icon names.
31525 * g_themed_icon_new:
31526 * @iconname: a string containing an icon name.
31528 * Creates a new themed icon for @iconname.
31530 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
31535 * g_themed_icon_new_from_names:
31536 * @iconnames: (array length=len): an array of strings containing icon names.
31537 * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated
31539 * Creates a new themed icon for @iconnames.
31541 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
31546 * g_themed_icon_new_with_default_fallbacks:
31547 * @iconname: a string containing an icon name
31549 * Creates a new themed icon for @iconname, and all the names
31550 * that can be created by shortening @iconname at '-' characters.
31552 * In the following example, @icon1 and @icon2 are equivalent:
31554 * const char *names[] = {
31555 * "gnome-dev-cdrom-audio",
31556 * "gnome-dev-cdrom",
31561 * icon1 = g_themed_icon_new_from_names (names, 4);
31562 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
31565 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
31570 * g_themed_icon_prepend_name:
31571 * @icon: a #GThemedIcon
31572 * @iconname: name of icon to prepend to list of icons from within @icon.
31574 * Prepend a name to the list of icons from within @icon.
31577 * Note that doing so invalidates the hash computed by prior calls
31578 * to g_icon_hash().
31586 * g_threaded_socket_service_new:
31587 * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit
31589 * Creates a new #GThreadedSocketService with no listeners. Listeners
31590 * must be added with one of the #GSocketListener "add" methods.
31592 * Returns: a new #GSocketService.
31598 * g_tls_backend_get_certificate_type:
31599 * @backend: the #GTlsBackend
31601 * Gets the #GType of @backend's #GTlsCertificate implementation.
31603 * Returns: the #GType of @backend's #GTlsCertificate implementation.
31609 * g_tls_backend_get_client_connection_type:
31610 * @backend: the #GTlsBackend
31612 * Gets the #GType of @backend's #GTlsClientConnection implementation.
31614 * Returns: the #GType of @backend's #GTlsClientConnection implementation.
31620 * g_tls_backend_get_default:
31622 * Gets the default #GTlsBackend for the system.
31624 * Returns: (transfer none): a #GTlsBackend
31630 * g_tls_backend_get_default_database:
31631 * @backend: the #GTlsBackend
31633 * Gets the default #GTlsDatabase used to verify TLS connections.
31635 * Returns: (transfer full): the default database, which should be unreffed when done.
31641 * g_tls_backend_get_file_database_type:
31642 * @backend: the #GTlsBackend
31644 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
31646 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
31652 * g_tls_backend_get_server_connection_type:
31653 * @backend: the #GTlsBackend
31655 * Gets the #GType of @backend's #GTlsServerConnection implementation.
31657 * Returns: the #GType of @backend's #GTlsServerConnection implementation.
31663 * g_tls_backend_supports_tls:
31664 * @backend: the #GTlsBackend
31666 * Checks if TLS is supported; if this returns %FALSE for the default
31667 * #GTlsBackend, it means no "real" TLS backend is available.
31669 * Returns: whether or not TLS is supported
31675 * g_tls_certificate_get_issuer:
31676 * @cert: a #GTlsCertificate
31678 * Gets the #GTlsCertificate representing @cert's issuer, if known
31680 * Returns: (transfer none): The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate.
31686 * g_tls_certificate_is_same:
31687 * @cert_one: first certificate to compare
31688 * @cert_two: second certificate to compare
31690 * Check if two #GTlsCertificate objects represent the same certificate.
31691 * The raw DER byte data of the two certificates are checked for equality.
31692 * This has the effect that two certificates may compare equal even if
31693 * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
31694 * #GTlsCertificate:private-key-pem properties differ.
31696 * Returns: whether the same or not
31702 * g_tls_certificate_list_new_from_file:
31703 * @file: file containing PEM-encoded certificates to import
31704 * @error: #GError for error reporting, or %NULL to ignore.
31706 * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
31707 * data in @file. If @file cannot be read or parsed, the function will
31708 * return %NULL and set @error. If @file does not contain any
31709 * PEM-encoded certificates, this will return an empty list and not
31712 * Returns: (element-type Gio.TlsCertificate) (transfer full): a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it.
31718 * g_tls_certificate_new_from_file:
31719 * @file: file containing a PEM-encoded certificate to import
31720 * @error: #GError for error reporting, or %NULL to ignore.
31722 * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
31723 * @file cannot be read or parsed, the function will return %NULL and
31724 * set @error. Otherwise, this behaves like
31725 * g_tls_certificate_new_from_pem().
31727 * Returns: the new certificate, or %NULL on error
31733 * g_tls_certificate_new_from_files:
31734 * @cert_file: file containing a PEM-encoded certificate to import
31735 * @key_file: file containing a PEM-encoded private key to import
31736 * @error: #GError for error reporting, or %NULL to ignore.
31738 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
31739 * and @key_file. If either file cannot be read or parsed, the
31740 * function will return %NULL and set @error. Otherwise, this behaves
31741 * like g_tls_certificate_new_from_pem().
31743 * Returns: the new certificate, or %NULL on error
31749 * g_tls_certificate_new_from_pem:
31750 * @data: PEM-encoded certificate data
31751 * @length: the length of @data, or -1 if it's 0-terminated.
31752 * @error: #GError for error reporting, or %NULL to ignore.
31754 * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
31755 * If @data includes both a certificate and a private key, then the
31756 * returned certificate will include the private key data as well. (See
31757 * the #GTlsCertificate:private-key-pem property for information about
31758 * supported formats.)
31760 * If @data includes multiple certificates, only the first one will be
31763 * Returns: the new certificate, or %NULL if @data is invalid
31769 * g_tls_certificate_verify:
31770 * @cert: a #GTlsCertificate
31771 * @identity: (allow-none): the expected peer identity
31772 * @trusted_ca: (allow-none): the certificate of a trusted authority
31774 * This verifies @cert and returns a set of #GTlsCertificateFlags
31775 * indicating any problems found with it. This can be used to verify a
31776 * certificate outside the context of making a connection, or to
31777 * check a certificate against a CA that is not part of the system
31780 * If @identity is not %NULL, @cert's name(s) will be compared against
31781 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
31782 * value if it does not match. If @identity is %NULL, that bit will
31783 * never be set in the return value.
31785 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
31786 * in its chain) must be signed by it, or else
31787 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
31788 * @trusted_ca is %NULL, that bit will never be set in the return
31791 * (All other #GTlsCertificateFlags values will always be set or unset
31794 * Returns: the appropriate #GTlsCertificateFlags
31800 * g_tls_client_connection_get_accepted_cas:
31801 * @conn: the #GTlsClientConnection
31803 * Gets the list of distinguished names of the Certificate Authorities
31804 * that the server will accept certificates from. This will be set
31805 * during the TLS handshake if the server requests a certificate.
31806 * Otherwise, it will be %NULL.
31808 * Each item in the list is a #GByteArray which contains the complete
31809 * subject DN of the certificate authority.
31811 * Returns: (element-type GByteArray) (transfer full): the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free().
31817 * g_tls_client_connection_get_server_identity:
31818 * @conn: the #GTlsClientConnection
31820 * Gets @conn's expected server identity
31822 * Returns: (transfer none): a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known.
31828 * g_tls_client_connection_get_use_ssl3:
31829 * @conn: the #GTlsClientConnection
31831 * Gets whether @conn will use SSL 3.0 rather than the
31832 * highest-supported version of TLS; see
31833 * g_tls_client_connection_set_use_ssl3().
31835 * Returns: whether @conn will use SSL 3.0
31841 * g_tls_client_connection_get_validation_flags:
31842 * @conn: the #GTlsClientConnection
31844 * Gets @conn's validation flags
31846 * Returns: the validation flags
31852 * g_tls_client_connection_new:
31853 * @base_io_stream: the #GIOStream to wrap
31854 * @server_identity: (allow-none): the expected identity of the server
31855 * @error: #GError for error reporting, or %NULL to ignore.
31857 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
31858 * must have pollable input and output streams) which is assumed to
31859 * communicate with the server identified by @server_identity.
31861 * Returns: (transfer full) (type GTlsClientConnection): the new #GTlsClientConnection, or %NULL on error
31867 * g_tls_client_connection_set_server_identity:
31868 * @conn: the #GTlsClientConnection
31869 * @identity: a #GSocketConnectable describing the expected server identity
31871 * Sets @conn's expected server identity, which is used both to tell
31872 * servers on virtual hosts which certificate to present, and also
31873 * to let @conn know what name to look for in the certificate when
31874 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
31881 * g_tls_client_connection_set_use_ssl3:
31882 * @conn: the #GTlsClientConnection
31883 * @use_ssl3: whether to use SSL 3.0
31885 * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
31886 * trying to properly negotiate the right version of TLS or SSL to use.
31887 * This can be used when talking to servers that do not implement the
31888 * fallbacks correctly and which will therefore fail to handshake with
31889 * a "modern" TLS handshake attempt.
31896 * g_tls_client_connection_set_validation_flags:
31897 * @conn: the #GTlsClientConnection
31898 * @flags: the #GTlsCertificateFlags to use
31900 * Sets @conn's validation flags, to override the default set of
31901 * checks performed when validating a server certificate. By default,
31902 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
31909 * g_tls_connection_emit_accept_certificate:
31910 * @conn: a #GTlsConnection
31911 * @peer_cert: the peer's #GTlsCertificate
31912 * @errors: the problems with @peer_cert
31914 * Used by #GTlsConnection implementations to emit the
31915 * #GTlsConnection::accept-certificate signal.
31917 * Returns: %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert
31923 * g_tls_connection_get_certificate:
31924 * @conn: a #GTlsConnection
31926 * Gets @conn's certificate, as set by
31927 * g_tls_connection_set_certificate().
31929 * Returns: (transfer none): @conn's certificate, or %NULL
31935 * g_tls_connection_get_database:
31936 * @conn: a #GTlsConnection
31938 * Gets the certificate database that @conn uses to verify
31939 * peer certificates. See g_tls_connection_set_database().
31941 * Returns: (transfer none): the certificate database that @conn uses or %NULL
31947 * g_tls_connection_get_interaction:
31948 * @conn: a connection
31950 * Get the object that will be used to interact with the user. It will be used
31951 * for things like prompting the user for passwords. If %NULL is returned, then
31952 * no user interaction will occur for this connection.
31954 * Returns: (transfer none): The interaction object.
31960 * g_tls_connection_get_peer_certificate:
31961 * @conn: a #GTlsConnection
31963 * Gets @conn's peer's certificate after the handshake has completed.
31964 * (It is not set during the emission of
31965 * #GTlsConnection::accept-certificate.)
31967 * Returns: (transfer none): @conn's peer's certificate, or %NULL
31973 * g_tls_connection_get_peer_certificate_errors:
31974 * @conn: a #GTlsConnection
31976 * Gets the errors associated with validating @conn's peer's
31977 * certificate, after the handshake has completed. (It is not set
31978 * during the emission of #GTlsConnection::accept-certificate.)
31980 * Returns: @conn's peer's certificate errors
31986 * g_tls_connection_get_rehandshake_mode:
31987 * @conn: a #GTlsConnection
31989 * Gets @conn rehandshaking mode. See
31990 * g_tls_connection_set_rehandshake_mode() for details.
31992 * Returns: @conn's rehandshaking mode
31998 * g_tls_connection_get_require_close_notify:
31999 * @conn: a #GTlsConnection
32001 * Tests whether or not @conn expects a proper TLS close notification
32002 * when the connection is closed. See
32003 * g_tls_connection_set_require_close_notify() for details.
32005 * Returns: %TRUE if @conn requires a proper TLS close notification.
32011 * g_tls_connection_get_use_system_certdb:
32012 * @conn: a #GTlsConnection
32014 * Gets whether @conn uses the system certificate database to verify
32015 * peer certificates. See g_tls_connection_set_use_system_certdb().
32017 * Returns: whether @conn uses the system certificate database
32018 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
32023 * g_tls_connection_handshake:
32024 * @conn: a #GTlsConnection
32025 * @cancellable: (allow-none): a #GCancellable, or %NULL
32026 * @error: a #GError, or %NULL
32028 * Attempts a TLS handshake on @conn.
32030 * On the client side, it is never necessary to call this method;
32031 * although the connection needs to perform a handshake after
32032 * connecting (or after sending a "STARTTLS"-type command) and may
32033 * need to rehandshake later if the server requests it,
32034 * #GTlsConnection will handle this for you automatically when you try
32035 * to send or receive data on the connection. However, you can call
32036 * g_tls_connection_handshake() manually if you want to know for sure
32037 * whether the initial handshake succeeded or failed (as opposed to
32038 * just immediately trying to write to @conn's output stream, in which
32039 * case if it fails, it may not be possible to tell if it failed
32040 * before or after completing the handshake).
32042 * Likewise, on the server side, although a handshake is necessary at
32043 * the beginning of the communication, you do not need to call this
32044 * function explicitly unless you want clearer error reporting.
32045 * However, you may call g_tls_connection_handshake() later on to
32046 * renegotiate parameters (encryption methods, etc) with the client.
32048 * #GTlsConnection::accept_certificate may be emitted during the
32051 * Returns: success or failure
32057 * g_tls_connection_handshake_async:
32058 * @conn: a #GTlsConnection
32059 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
32060 * @cancellable: (allow-none): a #GCancellable, or %NULL
32061 * @callback: callback to call when the handshake is complete
32062 * @user_data: the data to pass to the callback function
32064 * Asynchronously performs a TLS handshake on @conn. See
32065 * g_tls_connection_handshake() for more information.
32072 * g_tls_connection_handshake_finish:
32073 * @conn: a #GTlsConnection
32074 * @result: a #GAsyncResult.
32075 * @error: a #GError pointer, or %NULL
32077 * Finish an asynchronous TLS handshake operation. See
32078 * g_tls_connection_handshake() for more information.
32080 * Returns: %TRUE on success, %FALSE on failure, in which case @error will be set.
32086 * g_tls_connection_set_certificate:
32087 * @conn: a #GTlsConnection
32088 * @certificate: the certificate to use for @conn
32090 * This sets the certificate that @conn will present to its peer
32091 * during the TLS handshake. For a #GTlsServerConnection, it is
32092 * mandatory to set this, and that will normally be done at construct
32095 * For a #GTlsClientConnection, this is optional. If a handshake fails
32096 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
32097 * requires a certificate, and if you try connecting again, you should
32098 * call this method first. You can call
32099 * g_tls_client_connection_get_accepted_cas() on the failed connection
32100 * to get a list of Certificate Authorities that the server will
32101 * accept certificates from.
32103 * (It is also possible that a server will allow the connection with
32104 * or without a certificate; in that case, if you don't provide a
32105 * certificate, you can tell that the server requested one by the fact
32106 * that g_tls_client_connection_get_accepted_cas() will return
32114 * g_tls_connection_set_database:
32115 * @conn: a #GTlsConnection
32116 * @database: a #GTlsDatabase
32118 * Sets the certificate database that is used to verify peer certificates.
32119 * This is set to the default database by default. See
32120 * g_tls_backend_get_default_database(). If set to %NULL, then
32121 * peer certificate validation will always set the
32122 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
32123 * #GTlsConnection::accept-certificate will always be emitted on
32124 * client-side connections, unless that bit is not set in
32125 * #GTlsClientConnection:validation-flags).
32132 * g_tls_connection_set_interaction:
32133 * @conn: a connection
32134 * @interaction: (allow-none): an interaction object, or %NULL
32136 * Set the object that will be used to interact with the user. It will be used
32137 * for things like prompting the user for passwords.
32139 * The @interaction argument will normally be a derived subclass of
32140 * #GTlsInteraction. %NULL can also be provided if no user interaction
32141 * should occur for this connection.
32148 * g_tls_connection_set_rehandshake_mode:
32149 * @conn: a #GTlsConnection
32150 * @mode: the rehandshaking mode
32152 * Sets how @conn behaves with respect to rehandshaking requests.
32154 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
32155 * rehandshake after the initial handshake is complete. (For a client,
32156 * this means it will refuse rehandshake requests from the server, and
32157 * for a server, this means it will close the connection with an error
32158 * if the client attempts to rehandshake.)
32160 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
32161 * rehandshake only if the other end of the connection supports the
32162 * TLS <literal>renegotiation_info</literal> extension. This is the
32163 * default behavior, but means that rehandshaking will not work
32164 * against older implementations that do not support that extension.
32166 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
32167 * rehandshaking even without the
32168 * <literal>renegotiation_info</literal> extension. On the server side
32169 * in particular, this is not recommended, since it leaves the server
32170 * open to certain attacks. However, this mode is necessary if you
32171 * need to allow renegotiation with older client software.
32178 * g_tls_connection_set_require_close_notify:
32179 * @conn: a #GTlsConnection
32180 * @require_close_notify: whether or not to require close notification
32182 * Sets whether or not @conn expects a proper TLS close notification
32183 * before the connection is closed. If this is %TRUE (the default),
32184 * then @conn will expect to receive a TLS close notification from its
32185 * peer before the connection is closed, and will return a
32186 * %G_TLS_ERROR_EOF error if the connection is closed without proper
32187 * notification (since this may indicate a network error, or
32188 * man-in-the-middle attack).
32190 * In some protocols, the application will know whether or not the
32191 * connection was closed cleanly based on application-level data
32192 * (because the application-level data includes a length field, or is
32193 * somehow self-delimiting); in this case, the close notify is
32194 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
32195 * in TLS 1.0 it is technically an error, but often done anyway.) You
32196 * can use g_tls_connection_set_require_close_notify() to tell @conn
32197 * to allow an "unannounced" connection close, in which case the close
32198 * will show up as a 0-length read, as in a non-TLS
32199 * #GSocketConnection, and it is up to the application to check that
32200 * the data has been fully received.
32202 * Note that this only affects the behavior when the peer closes the
32203 * connection; when the application calls g_io_stream_close() itself
32204 * on @conn, this will send a close notification regardless of the
32205 * setting of this property. If you explicitly want to do an unclean
32206 * close, you can close @conn's #GTlsConnection:base-io-stream rather
32207 * than closing @conn itself.
32214 * g_tls_connection_set_use_system_certdb:
32215 * @conn: a #GTlsConnection
32216 * @use_system_certdb: whether to use the system certificate database
32218 * Sets whether @conn uses the system certificate database to verify
32219 * peer certificates. This is %TRUE by default. If set to %FALSE, then
32220 * peer certificate validation will always set the
32221 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
32222 * #GTlsConnection::accept-certificate will always be emitted on
32223 * client-side connections, unless that bit is not set in
32224 * #GTlsClientConnection:validation-flags).
32226 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
32231 * g_tls_database_create_certificate_handle:
32232 * @self: a #GTlsDatabase
32233 * @certificate: certificate for which to create a handle.
32235 * Create a handle string for the certificate. The database will only be able
32236 * to create a handle for certificates that originate from the database. In
32237 * cases where the database cannot create a handle for a certificate, %NULL
32238 * will be returned.
32240 * This handle should be stable across various instances of the application,
32241 * and between applications. If a certificate is modified in the database,
32242 * then it is not guaranteed that this handle will continue to point to it.
32244 * Returns: (allow-none): a newly allocated string containing the handle.
32250 * g_tls_database_lookup_certificate_for_handle:
32251 * @self: a #GTlsDatabase
32252 * @handle: a certificate handle
32253 * @interaction: (allow-none): used to interact with the user if necessary
32254 * @flags: Flags which affect the lookup.
32255 * @cancellable: (allow-none): a #GCancellable, or %NULL
32256 * @error: (allow-none): a #GError, or %NULL
32258 * Lookup a certificate by its handle.
32260 * The handle should have been created by calling
32261 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
32262 * the same TLS backend. The handle is designed to remain valid across
32263 * instantiations of the database.
32265 * If the handle is no longer valid, or does not point to a certificate in
32266 * this database, then %NULL will be returned.
32268 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
32269 * the lookup operation asynchronously.
32271 * Returns: (transfer full) (allow-none): a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
32277 * g_tls_database_lookup_certificate_for_handle_async:
32278 * @self: a #GTlsDatabase
32279 * @handle: a certificate handle
32280 * @interaction: (allow-none): used to interact with the user if necessary
32281 * @flags: Flags which affect the lookup.
32282 * @cancellable: (allow-none): a #GCancellable, or %NULL
32283 * @callback: callback to call when the operation completes
32284 * @user_data: the data to pass to the callback function
32286 * Asynchronously lookup a certificate by its handle in the database. See
32287 * g_tls_database_lookup_certificate_for_handle() for more information.
32294 * g_tls_database_lookup_certificate_for_handle_finish:
32295 * @self: a #GTlsDatabase
32296 * @result: a #GAsyncResult.
32297 * @error: a #GError pointer, or %NULL
32299 * Finish an asynchronous lookup of a certificate by its handle. See
32300 * g_tls_database_lookup_certificate_handle() for more information.
32302 * If the handle is no longer valid, or does not point to a certificate in
32303 * this database, then %NULL will be returned.
32305 * Returns: (transfer full): a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate.
32311 * g_tls_database_lookup_certificate_issuer:
32312 * @self: a #GTlsDatabase
32313 * @certificate: a #GTlsCertificate
32314 * @interaction: (allow-none): used to interact with the user if necessary
32315 * @flags: flags which affect the lookup operation
32316 * @cancellable: (allow-none): a #GCancellable, or %NULL
32317 * @error: (allow-none): a #GError, or %NULL
32319 * Lookup the issuer of @certificate in the database.
32321 * The %issuer property
32322 * of @certificate is not modified, and the two certificates are not hooked
32325 * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
32326 * the lookup operation asynchronously.
32328 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
32334 * g_tls_database_lookup_certificate_issuer_async:
32335 * @self: a #GTlsDatabase
32336 * @certificate: a #GTlsCertificate
32337 * @interaction: (allow-none): used to interact with the user if necessary
32338 * @flags: flags which affect the lookup operation
32339 * @cancellable: (allow-none): a #GCancellable, or %NULL
32340 * @callback: callback to call when the operation completes
32341 * @user_data: the data to pass to the callback function
32343 * Asynchronously lookup the issuer of @certificate in the database. See
32344 * g_tls_database_lookup_certificate_issuer() for more information.
32351 * g_tls_database_lookup_certificate_issuer_finish:
32352 * @self: a #GTlsDatabase
32353 * @result: a #GAsyncResult.
32354 * @error: a #GError pointer, or %NULL
32356 * Finish an asynchronous lookup issuer operation. See
32357 * g_tls_database_lookup_certificate_issuer() for more information.
32359 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
32365 * g_tls_database_lookup_certificates_issued_by:
32366 * @self: a #GTlsDatabase
32367 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
32368 * @interaction: (allow-none): used to interact with the user if necessary
32369 * @flags: Flags which affect the lookup operation.
32370 * @cancellable: (allow-none): a #GCancellable, or %NULL
32371 * @error: (allow-none): a #GError, or %NULL
32373 * Lookup certificates issued by this issuer in the database.
32375 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
32376 * the lookup operation asynchronously.
32378 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
32384 * g_tls_database_lookup_certificates_issued_by_async:
32385 * @self: a #GTlsDatabase
32386 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
32387 * @interaction: (allow-none): used to interact with the user if necessary
32388 * @flags: Flags which affect the lookup operation.
32389 * @cancellable: (allow-none): a #GCancellable, or %NULL
32390 * @callback: callback to call when the operation completes
32391 * @user_data: the data to pass to the callback function
32393 * Asynchronously lookup certificates issued by this issuer in the database. See
32394 * g_tls_database_lookup_certificates_issued_by() for more information.
32396 * The database may choose to hold a reference to the issuer byte array for the duration
32397 * of of this asynchronous operation. The byte array should not be modified during
32405 * g_tls_database_lookup_certificates_issued_by_finish:
32406 * @self: a #GTlsDatabase
32407 * @result: a #GAsyncResult.
32408 * @error: a #GError pointer, or %NULL
32410 * Finish an asynchronous lookup of certificates. See
32411 * g_tls_database_lookup_certificates_issued_by() for more information.
32413 * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
32419 * g_tls_database_verify_chain:
32420 * @self: a #GTlsDatabase
32421 * @chain: a #GTlsCertificate chain
32422 * @purpose: the purpose that this certificate chain will be used for.
32423 * @identity: (allow-none): the expected peer identity
32424 * @interaction: (allow-none): used to interact with the user if necessary
32425 * @flags: additional verify flags
32426 * @cancellable: (allow-none): a #GCancellable, or %NULL
32427 * @error: (allow-none): a #GError, or %NULL
32429 * Verify's a certificate chain after looking up and adding any missing
32430 * certificates to the chain.
32432 * @chain is a chain of #GTlsCertificate objects each pointing to the next
32433 * certificate in the chain by its %issuer property. The chain may initially
32434 * consist of one or more certificates. After the verification process is
32435 * complete, @chain may be modified by adding missing certificates, or removing
32436 * extra certificates. If a certificate anchor was found, then it is added to
32439 * @purpose describes the purpose (or usage) for which the certificate
32440 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
32441 * which means that the certificate is being used to authenticate a server
32442 * (and we are acting as the client).
32444 * The @identity is used to check for pinned certificates (trust exceptions)
32445 * in the database. These will override the normal verification process on a
32446 * host by host basis.
32448 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
32451 * This function can block, use g_tls_database_verify_chain_async() to perform
32452 * the verification operation asynchronously.
32454 * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification.
32460 * g_tls_database_verify_chain_async:
32461 * @self: a #GTlsDatabase
32462 * @chain: a #GTlsCertificate chain
32463 * @purpose: the purpose that this certificate chain will be used for.
32464 * @identity: (allow-none): the expected peer identity
32465 * @interaction: (allow-none): used to interact with the user if necessary
32466 * @flags: additional verify flags
32467 * @cancellable: (allow-none): a #GCancellable, or %NULL
32468 * @callback: callback to call when the operation completes
32469 * @user_data: the data to pass to the callback function
32471 * Asynchronously verify's a certificate chain after looking up and adding
32472 * any missing certificates to the chain. See g_tls_database_verify_chain()
32473 * for more information.
32480 * g_tls_database_verify_chain_finish:
32481 * @self: a #GTlsDatabase
32482 * @result: a #GAsyncResult.
32483 * @error: a #GError pointer, or %NULL
32485 * Finish an asynchronous verify chain operation. See
32486 * g_tls_database_verify_chain() for more information. *
32488 * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification.
32494 * g_tls_error_quark:
32496 * Gets the TLS error quark.
32498 * Returns: a #GQuark.
32504 * g_tls_file_database_new:
32505 * @anchors: filename of anchor certificate authorities.
32506 * @error: #GError for error reporting, or %NULL to ignore.
32508 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
32509 * in @anchors to verify certificate chains.
32511 * The certificates in @anchors must be PEM encoded.
32513 * Returns: (transfer full) (type GTlsFileDatabase): the new #GTlsFileDatabase, or %NULL on error
32519 * g_tls_interaction_ask_password:
32520 * @interaction: a #GTlsInteraction object
32521 * @password: a #GTlsPassword object
32522 * @cancellable: an optional #GCancellable cancellation object
32523 * @error: an optional location to place an error on failure
32525 * Run synchronous interaction to ask the user for a password. In general,
32526 * g_tls_interaction_invoke_ask_password() should be used instead of this
32529 * Derived subclasses usually implement a password prompt, although they may
32530 * also choose to provide a password from elsewhere. The @password value will
32531 * be filled in and then @callback will be called. Alternatively the user may
32532 * abort this password request, which will usually abort the TLS connection.
32534 * If the interaction is cancelled by the cancellation object, or by the
32535 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
32536 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
32537 * not support immediate cancellation.
32539 * Returns: The status of the ask password interaction.
32545 * g_tls_interaction_ask_password_async:
32546 * @interaction: a #GTlsInteraction object
32547 * @password: a #GTlsPassword object
32548 * @cancellable: an optional #GCancellable cancellation object
32549 * @callback: (allow-none): will be called when the interaction completes
32550 * @user_data: (allow-none): data to pass to the @callback
32552 * Run asynchronous interaction to ask the user for a password. In general,
32553 * g_tls_interaction_invoke_ask_password() should be used instead of this
32556 * Derived subclasses usually implement a password prompt, although they may
32557 * also choose to provide a password from elsewhere. The @password value will
32558 * be filled in and then @callback will be called. Alternatively the user may
32559 * abort this password request, which will usually abort the TLS connection.
32561 * If the interaction is cancelled by the cancellation object, or by the
32562 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
32563 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
32564 * not support immediate cancellation.
32566 * Certain implementations may not support immediate cancellation.
32573 * g_tls_interaction_ask_password_finish:
32574 * @interaction: a #GTlsInteraction object
32575 * @result: the result passed to the callback
32576 * @error: an optional location to place an error on failure
32578 * Complete an ask password user interaction request. This should be once
32579 * the g_tls_interaction_ask_password_async() completion callback is called.
32581 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
32582 * to g_tls_interaction_ask_password() will have its password filled in.
32584 * If the interaction is cancelled by the cancellation object, or by the
32585 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
32586 * contains a %G_IO_ERROR_CANCELLED error code.
32588 * Returns: The status of the ask password interaction.
32594 * g_tls_interaction_invoke_ask_password:
32595 * @interaction: a #GTlsInteraction object
32596 * @password: a #GTlsPassword object
32597 * @cancellable: an optional #GCancellable cancellation object
32598 * @error: an optional location to place an error on failure
32600 * Invoke the interaction to ask the user for a password. It invokes this
32601 * interaction in the main loop, specifically the #GMainContext returned by
32602 * g_main_context_get_thread_default() when the interaction is created. This
32603 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
32606 * Derived subclasses usually implement a password prompt, although they may
32607 * also choose to provide a password from elsewhere. The @password value will
32608 * be filled in and then @callback will be called. Alternatively the user may
32609 * abort this password request, which will usually abort the TLS connection.
32611 * The implementation can either be a synchronous (eg: modal dialog) or an
32612 * asynchronous one (eg: modeless dialog). This function will take care of
32613 * calling which ever one correctly.
32615 * If the interaction is cancelled by the cancellation object, or by the
32616 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
32617 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
32618 * not support immediate cancellation.
32620 * Returns: The status of the ask password interaction.
32626 * g_tls_password_get_description:
32627 * @password: a #GTlsPassword object
32629 * Get a description string about what the password will be used for.
32631 * Returns: The description of the password.
32637 * g_tls_password_get_flags:
32638 * @password: a #GTlsPassword object
32640 * Get flags about the password.
32642 * Returns: The flags about the password.
32648 * g_tls_password_get_value:
32649 * @password: a #GTlsPassword object
32650 * @length: (allow-none): location to place the length of the password.
32652 * Get the password value. If @length is not %NULL then it will be
32653 * filled in with the length of the password value. (Note that the
32654 * password value is not nul-terminated, so you can only pass %NULL
32655 * for @length in contexts where you know the password will have a
32656 * certain fixed length.)
32658 * Returns: The password value (owned by the password object).
32664 * g_tls_password_get_warning:
32665 * @password: a #GTlsPassword object
32667 * Get a user readable translated warning. Usually this warning is a
32668 * representation of the password flags returned from
32669 * g_tls_password_get_flags().
32671 * Returns: The warning.
32677 * g_tls_password_new:
32678 * @flags: the password flags
32679 * @description: description of what the password is for
32681 * Create a new #GTlsPassword object.
32683 * Returns: (transfer full): The newly allocated password object
32688 * g_tls_password_set_description:
32689 * @password: a #GTlsPassword object
32690 * @description: The description of the password
32692 * Set a description string about what the password will be used for.
32699 * g_tls_password_set_flags:
32700 * @password: a #GTlsPassword object
32701 * @flags: The flags about the password
32703 * Set flags about the password.
32710 * g_tls_password_set_value:
32711 * @password: a #GTlsPassword object
32712 * @value: the new password value
32713 * @length: the length of the password, or -1
32715 * Set the value for this password. The @value will be copied by the password
32718 * Specify the @length, for a non-nul-terminated password. Pass -1 as
32719 * @length if using a nul-terminated password, and @length will be
32720 * calculated automatically. (Note that the terminating nul is not
32721 * considered part of the password in this case.)
32728 * g_tls_password_set_value_full:
32729 * @password: a #GTlsPassword object
32730 * @value: the value for the password
32731 * @length: the length of the password, or -1
32732 * @destroy: (allow-none): a function to use to free the password.
32734 * Provide the value for this password.
32736 * The @value will be owned by the password object, and later freed using
32737 * the @destroy function callback.
32739 * Specify the @length, for a non-nul-terminated password. Pass -1 as
32740 * @length if using a nul-terminated password, and @length will be
32741 * calculated automatically. (Note that the terminating nul is not
32742 * considered part of the password in this case.)
32744 * Virtual: set_value
32750 * g_tls_password_set_warning:
32751 * @password: a #GTlsPassword object
32752 * @warning: The user readable warning
32754 * Set a user readable translated warning. Usually this warning is a
32755 * representation of the password flags returned from
32756 * g_tls_password_get_flags().
32763 * g_tls_server_connection_new:
32764 * @base_io_stream: the #GIOStream to wrap
32765 * @certificate: (allow-none): the default server certificate, or %NULL
32766 * @error: #GError for error reporting, or %NULL to ignore.
32768 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
32769 * must have pollable input and output streams).
32771 * Returns: (transfer full) (type GTlsServerConnection): the new #GTlsServerConnection, or %NULL on error
32777 * g_unix_connection_receive_credentials:
32778 * @connection: A #GUnixConnection.
32779 * @cancellable: (allow-none): A #GCancellable or %NULL.
32780 * @error: Return location for error or %NULL.
32782 * Receives credentials from the sending end of the connection. The
32783 * sending end has to call g_unix_connection_send_credentials() (or
32784 * similar) for this to work.
32786 * As well as reading the credentials this also reads (and discards) a
32787 * single byte from the stream, as this is required for credentials
32788 * passing to work on some implementations.
32790 * Other ways to exchange credentials with a foreign peer includes the
32791 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
32793 * Returns: (transfer full): Received credentials on success (free with g_object_unref()), %NULL if @error is set.
32799 * g_unix_connection_receive_credentials_async:
32800 * @connection: A #GUnixConnection.
32801 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32802 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
32803 * @user_data: (closure): the data to pass to callback function
32805 * Asynchronously receive credentials.
32807 * For more details, see g_unix_connection_receive_credentials() which is
32808 * the synchronous version of this call.
32810 * When the operation is finished, @callback will be called. You can then call
32811 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
32818 * g_unix_connection_receive_credentials_finish:
32819 * @connection: A #GUnixConnection.
32820 * @result: a #GAsyncResult.
32821 * @error: a #GError, or %NULL
32823 * Finishes an asynchronous receive credentials operation started with
32824 * g_unix_connection_receive_credentials_async().
32826 * Returns: (transfer full): a #GCredentials, or %NULL on error. Free the returned object with g_object_unref().
32832 * g_unix_connection_receive_fd:
32833 * @connection: a #GUnixConnection
32834 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
32835 * @error: (allow-none): #GError for error reporting, or %NULL to ignore
32837 * Receives a file descriptor from the sending end of the connection.
32838 * The sending end has to call g_unix_connection_send_fd() for this
32841 * As well as reading the fd this also reads a single byte from the
32842 * stream, as this is required for fd passing to work on some
32845 * Returns: a file descriptor on success, -1 on error.
32851 * g_unix_connection_send_credentials:
32852 * @connection: A #GUnixConnection.
32853 * @cancellable: (allow-none): A #GCancellable or %NULL.
32854 * @error: Return location for error or %NULL.
32856 * Passes the credentials of the current user the receiving side
32857 * of the connection. The receiving end has to call
32858 * g_unix_connection_receive_credentials() (or similar) to accept the
32861 * As well as sending the credentials this also writes a single NUL
32862 * byte to the stream, as this is required for credentials passing to
32863 * work on some implementations.
32865 * Other ways to exchange credentials with a foreign peer includes the
32866 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
32868 * Returns: %TRUE on success, %FALSE if @error is set.
32874 * g_unix_connection_send_credentials_async:
32875 * @connection: A #GUnixConnection.
32876 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32877 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
32878 * @user_data: (closure): the data to pass to callback function
32880 * Asynchronously send credentials.
32882 * For more details, see g_unix_connection_send_credentials() which is
32883 * the synchronous version of this call.
32885 * When the operation is finished, @callback will be called. You can then call
32886 * g_unix_connection_send_credentials_finish() to get the result of the operation.
32893 * g_unix_connection_send_credentials_finish:
32894 * @connection: A #GUnixConnection.
32895 * @result: a #GAsyncResult.
32896 * @error: a #GError, or %NULL
32898 * Finishes an asynchronous send credentials operation started with
32899 * g_unix_connection_send_credentials_async().
32901 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
32907 * g_unix_connection_send_fd:
32908 * @connection: a #GUnixConnection
32909 * @fd: a file descriptor
32910 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32911 * @error: (allow-none): #GError for error reporting, or %NULL to ignore.
32913 * Passes a file descriptor to the receiving side of the
32914 * connection. The receiving end has to call g_unix_connection_receive_fd()
32915 * to accept the file descriptor.
32917 * As well as sending the fd this also writes a single byte to the
32918 * stream, as this is required for fd passing to work on some
32921 * Returns: a %TRUE on success, %NULL on error.
32927 * g_unix_credentials_message_get_credentials:
32928 * @message: A #GUnixCredentialsMessage.
32930 * Gets the credentials stored in @message.
32932 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
32938 * g_unix_credentials_message_is_supported:
32940 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
32942 * Returns: %TRUE if supported, %FALSE otherwise
32948 * g_unix_credentials_message_new:
32950 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
32952 * Returns: a new #GUnixCredentialsMessage
32958 * g_unix_credentials_message_new_with_credentials:
32959 * @credentials: A #GCredentials object.
32961 * Creates a new #GUnixCredentialsMessage holding @credentials.
32963 * Returns: a new #GUnixCredentialsMessage
32969 * g_unix_fd_list_append:
32970 * @list: a #GUnixFDList
32971 * @fd: a valid open file descriptor
32972 * @error: a #GError pointer
32974 * Adds a file descriptor to @list.
32976 * The file descriptor is duplicated using dup(). You keep your copy
32977 * of the descriptor and the copy contained in @list will be closed
32978 * when @list is finalized.
32980 * A possible cause of failure is exceeding the per-process or
32981 * system-wide file descriptor limit.
32983 * The index of the file descriptor in the list is returned. If you use
32984 * this index with g_unix_fd_list_get() then you will receive back a
32985 * duplicated copy of the same file descriptor.
32987 * Returns: the index of the appended fd in case of success, else -1 (and @error is set)
32993 * g_unix_fd_list_get:
32994 * @list: a #GUnixFDList
32995 * @index_: the index into the list
32996 * @error: a #GError pointer
32998 * Gets a file descriptor out of @list.
33000 * @index_ specifies the index of the file descriptor to get. It is a
33001 * programmer error for @index_ to be out of range; see
33002 * g_unix_fd_list_get_length().
33004 * The file descriptor is duplicated using dup() and set as
33005 * close-on-exec before being returned. You must call close() on it
33006 * when you are done.
33008 * A possible cause of failure is exceeding the per-process or
33009 * system-wide file descriptor limit.
33011 * Returns: the file descriptor, or -1 in case of error
33017 * g_unix_fd_list_get_length:
33018 * @list: a #GUnixFDList
33020 * Gets the length of @list (ie: the number of file descriptors
33021 * contained within).
33023 * Returns: the length of @list
33029 * g_unix_fd_list_new:
33031 * Creates a new #GUnixFDList containing no file descriptors.
33033 * Returns: a new #GUnixFDList
33039 * g_unix_fd_list_new_from_array:
33040 * @fds: (array length=n_fds): the initial list of file descriptors
33041 * @n_fds: the length of #fds, or -1
33043 * Creates a new #GUnixFDList containing the file descriptors given in
33044 * @fds. The file descriptors become the property of the new list and
33045 * may no longer be used by the caller. The array itself is owned by
33048 * Each file descriptor in the array should be set to close-on-exec.
33050 * If @n_fds is -1 then @fds must be terminated with -1.
33052 * Returns: a new #GUnixFDList
33058 * g_unix_fd_list_peek_fds:
33059 * @list: a #GUnixFDList
33060 * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL
33062 * Returns the array of file descriptors that is contained in this
33065 * After this call, the descriptors remain the property of @list. The
33066 * caller must not close them and must not free the array. The array is
33067 * valid only until @list is changed in any way.
33069 * If @length is non-%NULL then it is set to the number of file
33070 * descriptors in the returned array. The returned array is also
33071 * terminated with -1.
33073 * This function never returns %NULL. In case there are no file
33074 * descriptors contained in @list, an empty array is returned.
33076 * Returns: (array length=length) (transfer none): an array of file descriptors
33082 * g_unix_fd_list_steal_fds:
33083 * @list: a #GUnixFDList
33084 * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL
33086 * Returns the array of file descriptors that is contained in this
33089 * After this call, the descriptors are no longer contained in
33090 * @list. Further calls will return an empty list (unless more
33091 * descriptors have been added).
33093 * The return result of this function must be freed with g_free().
33094 * The caller is also responsible for closing all of the file
33095 * descriptors. The file descriptors in the array are set to
33098 * If @length is non-%NULL then it is set to the number of file
33099 * descriptors in the returned array. The returned array is also
33100 * terminated with -1.
33102 * This function never returns %NULL. In case there are no file
33103 * descriptors contained in @list, an empty array is returned.
33105 * Returns: (array length=length) (transfer full): an array of file descriptors
33111 * g_unix_fd_message_append_fd:
33112 * @message: a #GUnixFDMessage
33113 * @fd: a valid open file descriptor
33114 * @error: a #GError pointer
33116 * Adds a file descriptor to @message.
33118 * The file descriptor is duplicated using dup(). You keep your copy
33119 * of the descriptor and the copy contained in @message will be closed
33120 * when @message is finalized.
33122 * A possible cause of failure is exceeding the per-process or
33123 * system-wide file descriptor limit.
33125 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
33131 * g_unix_fd_message_get_fd_list:
33132 * @message: a #GUnixFDMessage
33134 * Gets the #GUnixFDList contained in @message. This function does not
33135 * return a reference to the caller, but the returned list is valid for
33136 * the lifetime of @message.
33138 * Returns: (transfer none): the #GUnixFDList from @message
33144 * g_unix_fd_message_new:
33146 * Creates a new #GUnixFDMessage containing an empty file descriptor
33149 * Returns: a new #GUnixFDMessage
33155 * g_unix_fd_message_new_with_fd_list:
33156 * @fd_list: a #GUnixFDList
33158 * Creates a new #GUnixFDMessage containing @list.
33160 * Returns: a new #GUnixFDMessage
33166 * g_unix_fd_message_steal_fds:
33167 * @message: a #GUnixFDMessage
33168 * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL
33170 * Returns the array of file descriptors that is contained in this
33173 * After this call, the descriptors are no longer contained in
33174 * @message. Further calls will return an empty list (unless more
33175 * descriptors have been added).
33177 * The return result of this function must be freed with g_free().
33178 * The caller is also responsible for closing all of the file
33181 * If @length is non-%NULL then it is set to the number of file
33182 * descriptors in the returned array. The returned array is also
33183 * terminated with -1.
33185 * This function never returns %NULL. In case there are no file
33186 * descriptors contained in @message, an empty array is returned.
33188 * Returns: (array length=length) (transfer full): an array of file descriptors
33194 * g_unix_input_stream_get_close_fd:
33195 * @stream: a #GUnixInputStream
33197 * Returns whether the file descriptor of @stream will be
33198 * closed when the stream is closed.
33200 * Returns: %TRUE if the file descriptor is closed when done
33206 * g_unix_input_stream_get_fd:
33207 * @stream: a #GUnixInputStream
33209 * Return the UNIX file descriptor that the stream reads from.
33211 * Returns: The file descriptor of @stream
33217 * g_unix_input_stream_new:
33218 * @fd: a UNIX file descriptor
33219 * @close_fd: %TRUE to close the file descriptor when done
33221 * Creates a new #GUnixInputStream for the given @fd.
33223 * If @close_fd is %TRUE, the file descriptor will be closed
33224 * when the stream is closed.
33226 * Returns: a new #GUnixInputStream
33231 * g_unix_input_stream_set_close_fd:
33232 * @stream: a #GUnixInputStream
33233 * @close_fd: %TRUE to close the file descriptor when done
33235 * Sets whether the file descriptor of @stream shall be closed
33236 * when the stream is closed.
33243 * g_unix_is_mount_path_system_internal:
33244 * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename>
33246 * Determines if @mount_path is considered an implementation of the
33247 * OS. This is primarily used for hiding mountable and mounted volumes
33248 * that only are used in the OS and has little to no relevance to the
33251 * Returns: %TRUE if @mount_path is considered an implementation detail of the OS.
33256 * g_unix_mount_at: (skip)
33257 * @mount_path: path for a possible unix mount.
33258 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
33260 * Gets a #GUnixMountEntry for a given mount path. If @time_read
33261 * is set, it will be filled with a unix timestamp for checking
33262 * if the mounts have changed since with g_unix_mounts_changed_since().
33264 * Returns: (transfer full): a #GUnixMountEntry.
33269 * g_unix_mount_compare:
33270 * @mount1: first #GUnixMountEntry to compare.
33271 * @mount2: second #GUnixMountEntry to compare.
33273 * Compares two unix mounts.
33275 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively.
33280 * g_unix_mount_free:
33281 * @mount_entry: a #GUnixMountEntry.
33283 * Frees a unix mount.
33288 * g_unix_mount_get_device_path:
33289 * @mount_entry: a #GUnixMount.
33291 * Gets the device path for a unix mount.
33293 * Returns: a string containing the device path.
33298 * g_unix_mount_get_fs_type:
33299 * @mount_entry: a #GUnixMount.
33301 * Gets the filesystem type for the unix mount.
33303 * Returns: a string containing the file system type.
33308 * g_unix_mount_get_mount_path:
33309 * @mount_entry: input #GUnixMountEntry to get the mount path for.
33311 * Gets the mount path for a unix mount.
33313 * Returns: the mount path for @mount_entry.
33318 * g_unix_mount_guess_can_eject:
33319 * @mount_entry: a #GUnixMountEntry
33321 * Guesses whether a Unix mount can be ejected.
33323 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
33328 * g_unix_mount_guess_icon:
33329 * @mount_entry: a #GUnixMountEntry
33331 * Guesses the icon of a Unix mount.
33333 * Returns: (transfer full): a #GIcon
33338 * g_unix_mount_guess_name:
33339 * @mount_entry: a #GUnixMountEntry
33341 * Guesses the name of a Unix mount.
33342 * The result is a translated string.
33344 * Returns: A newly allocated string that must be freed with g_free()
33349 * g_unix_mount_guess_should_display:
33350 * @mount_entry: a #GUnixMountEntry
33352 * Guesses whether a Unix mount should be displayed in the UI.
33354 * Returns: %TRUE if @mount_entry is deemed to be displayable.
33359 * g_unix_mount_guess_symbolic_icon:
33360 * @mount_entry: a #GUnixMountEntry
33362 * Guesses the symbolic icon of a Unix mount.
33364 * Returns: (transfer full): a #GIcon
33370 * g_unix_mount_is_readonly:
33371 * @mount_entry: a #GUnixMount.
33373 * Checks if a unix mount is mounted read only.
33375 * Returns: %TRUE if @mount_entry is read only.
33380 * g_unix_mount_is_system_internal:
33381 * @mount_entry: a #GUnixMount.
33383 * Checks if a unix mount is a system path.
33385 * Returns: %TRUE if the unix mount is for a system path.
33390 * g_unix_mount_monitor_new:
33392 * Gets a new #GUnixMountMonitor. The default rate limit for which the
33393 * monitor will report consecutive changes for the mount and mount
33394 * point entry files is the default for a #GFileMonitor. Use
33395 * g_unix_mount_monitor_set_rate_limit() to change this.
33397 * Returns: a #GUnixMountMonitor.
33402 * g_unix_mount_monitor_set_rate_limit:
33403 * @mount_monitor: a #GUnixMountMonitor
33404 * @limit_msec: a integer with the limit in milliseconds to poll for changes.
33406 * Sets the rate limit to which the @mount_monitor will report
33407 * consecutive change events to the mount and mount point entry files.
33414 * g_unix_mount_point_compare:
33415 * @mount1: a #GUnixMount.
33416 * @mount2: a #GUnixMount.
33418 * Compares two unix mount points.
33420 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively.
33425 * g_unix_mount_point_free:
33426 * @mount_point: unix mount point to free.
33428 * Frees a unix mount point.
33433 * g_unix_mount_point_get_device_path:
33434 * @mount_point: a #GUnixMountPoint.
33436 * Gets the device path for a unix mount point.
33438 * Returns: a string containing the device path.
33443 * g_unix_mount_point_get_fs_type:
33444 * @mount_point: a #GUnixMountPoint.
33446 * Gets the file system type for the mount point.
33448 * Returns: a string containing the file system type.
33453 * g_unix_mount_point_get_mount_path:
33454 * @mount_point: a #GUnixMountPoint.
33456 * Gets the mount path for a unix mount point.
33458 * Returns: a string containing the mount path.
33463 * g_unix_mount_point_get_options:
33464 * @mount_point: a #GUnixMountPoint.
33466 * Gets the options for the mount point.
33468 * Returns: a string containing the options.
33474 * g_unix_mount_point_guess_can_eject:
33475 * @mount_point: a #GUnixMountPoint
33477 * Guesses whether a Unix mount point can be ejected.
33479 * Returns: %TRUE if @mount_point is deemed to be ejectable.
33484 * g_unix_mount_point_guess_icon:
33485 * @mount_point: a #GUnixMountPoint
33487 * Guesses the icon of a Unix mount point.
33489 * Returns: (transfer full): a #GIcon
33494 * g_unix_mount_point_guess_name:
33495 * @mount_point: a #GUnixMountPoint
33497 * Guesses the name of a Unix mount point.
33498 * The result is a translated string.
33500 * Returns: A newly allocated string that must be freed with g_free()
33505 * g_unix_mount_point_guess_symbolic_icon:
33506 * @mount_point: a #GUnixMountPoint
33508 * Guesses the symbolic icon of a Unix mount point.
33510 * Returns: (transfer full): a #GIcon
33516 * g_unix_mount_point_is_loopback:
33517 * @mount_point: a #GUnixMountPoint.
33519 * Checks if a unix mount point is a loopback device.
33521 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
33526 * g_unix_mount_point_is_readonly:
33527 * @mount_point: a #GUnixMountPoint.
33529 * Checks if a unix mount point is read only.
33531 * Returns: %TRUE if a mount point is read only.
33536 * g_unix_mount_point_is_user_mountable:
33537 * @mount_point: a #GUnixMountPoint.
33539 * Checks if a unix mount point is mountable by the user.
33541 * Returns: %TRUE if the mount point is user mountable.
33546 * g_unix_mount_points_changed_since:
33547 * @time: guint64 to contain a timestamp.
33549 * Checks if the unix mount points have changed since a given unix time.
33551 * Returns: %TRUE if the mount points have changed since @time.
33556 * g_unix_mount_points_get: (skip)
33557 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
33559 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
33560 * If @time_read is set, it will be filled with the mount timestamp,
33561 * allowing for checking if the mounts have changed with
33562 * g_unix_mount_points_changed_since().
33564 * Returns: (element-type GUnixMountPoint) (transfer full): a #GList of the UNIX mountpoints.
33569 * g_unix_mounts_changed_since:
33570 * @time: guint64 to contain a timestamp.
33572 * Checks if the unix mounts have changed since a given unix time.
33574 * Returns: %TRUE if the mounts have changed since @time.
33579 * g_unix_mounts_get: (skip)
33580 * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
33582 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
33583 * If @time_read is set, it will be filled with the mount
33584 * timestamp, allowing for checking if the mounts have changed
33585 * with g_unix_mounts_changed_since().
33587 * Returns: (element-type GUnixMountEntry) (transfer full): a #GList of the UNIX mounts.
33592 * g_unix_output_stream_get_close_fd:
33593 * @stream: a #GUnixOutputStream
33595 * Returns whether the file descriptor of @stream will be
33596 * closed when the stream is closed.
33598 * Returns: %TRUE if the file descriptor is closed when done
33604 * g_unix_output_stream_get_fd:
33605 * @stream: a #GUnixOutputStream
33607 * Return the UNIX file descriptor that the stream writes to.
33609 * Returns: The file descriptor of @stream
33615 * g_unix_output_stream_new:
33616 * @fd: a UNIX file descriptor
33617 * @close_fd: %TRUE to close the file descriptor when done
33619 * Creates a new #GUnixOutputStream for the given @fd.
33621 * If @close_fd, is %TRUE, the file descriptor will be closed when
33622 * the output stream is destroyed.
33624 * Returns: a new #GOutputStream
33629 * g_unix_output_stream_set_close_fd:
33630 * @stream: a #GUnixOutputStream
33631 * @close_fd: %TRUE to close the file descriptor when done
33633 * Sets whether the file descriptor of @stream shall be closed
33634 * when the stream is closed.
33641 * g_unix_socket_address_abstract_names_supported:
33643 * Checks if abstract UNIX domain socket names are supported.
33645 * Returns: %TRUE if supported, %FALSE otherwise
33651 * g_unix_socket_address_get_address_type:
33652 * @address: a #GInetSocketAddress
33654 * Gets @address's type.
33656 * Returns: a #GUnixSocketAddressType
33662 * g_unix_socket_address_get_is_abstract:
33663 * @address: a #GInetSocketAddress
33665 * Tests if @address is abstract.
33667 * Returns: %TRUE if the address is abstract, %FALSE otherwise
33669 * Deprecated: Use g_unix_socket_address_get_address_type()
33674 * g_unix_socket_address_get_path:
33675 * @address: a #GInetSocketAddress
33677 * Gets @address's path, or for abstract sockets the "name".
33679 * Guaranteed to be zero-terminated, but an abstract socket
33680 * may contain embedded zeros, and thus you should use
33681 * g_unix_socket_address_get_path_len() to get the true length
33684 * Returns: the path for @address
33690 * g_unix_socket_address_get_path_len:
33691 * @address: a #GInetSocketAddress
33693 * Gets the length of @address's path.
33695 * For details, see g_unix_socket_address_get_path().
33697 * Returns: the length of the path
33703 * g_unix_socket_address_new:
33704 * @path: the socket path
33706 * Creates a new #GUnixSocketAddress for @path.
33708 * To create abstract socket addresses, on systems that support that,
33709 * use g_unix_socket_address_new_abstract().
33711 * Returns: a new #GUnixSocketAddress
33717 * g_unix_socket_address_new_abstract:
33718 * @path: (array length=path_len) (element-type gchar): the abstract name
33719 * @path_len: the length of @path, or -1
33721 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
33722 * #GUnixSocketAddress for @path.
33724 * Returns: a new #GUnixSocketAddress
33725 * Deprecated: Use g_unix_socket_address_new_with_type().
33730 * g_unix_socket_address_new_with_type:
33731 * @path: (array length=path_len) (element-type gchar): the name
33732 * @path_len: the length of @path, or -1
33733 * @type: a #GUnixSocketAddressType
33735 * Creates a new #GUnixSocketAddress of type @type with name @path.
33737 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
33738 * calling g_unix_socket_address_new().
33740 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
33741 * bytes of @path will be copied to the socket's path, and only those
33742 * bytes will be considered part of the name. (If @path_len is -1,
33743 * then @path is assumed to be NUL-terminated.) For example, if @path
33744 * was "test", then calling g_socket_address_get_native_size() on the
33745 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
33746 * abstract-socket indicator byte, and 4 bytes for the name "test").
33748 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
33749 * @path_len bytes of @path will be copied to the socket's path, the
33750 * rest of the path will be padded with 0 bytes, and the entire
33751 * zero-padded buffer will be considered the name. (As above, if
33752 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
33753 * this case, g_socket_address_get_native_size() will always return
33754 * the full size of a <literal>struct sockaddr_un</literal>, although
33755 * g_unix_socket_address_get_path_len() will still return just the
33758 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
33759 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
33760 * when connecting to a server created by another process, you must
33761 * use the appropriate type corresponding to how that process created
33762 * its listening socket.
33764 * Returns: a new #GUnixSocketAddress
33770 * g_vfs_get_default:
33772 * Gets the default #GVfs for the system.
33774 * Returns: (transfer none): a #GVfs.
33779 * g_vfs_get_file_for_path:
33781 * @path: a string containing a VFS path.
33783 * Gets a #GFile for @path.
33785 * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref().
33790 * g_vfs_get_file_for_uri:
33792 * @uri: a string containing a URI
33794 * Gets a #GFile for @uri.
33796 * This operation never fails, but the returned object
33797 * might not support any I/O operation if the URI
33798 * is malformed or if the URI scheme is not supported.
33800 * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref().
33807 * Gets the local #GVfs for the system.
33809 * Returns: (transfer none): a #GVfs.
33814 * g_vfs_get_supported_uri_schemes:
33817 * Gets a list of URI schemes supported by @vfs.
33819 * Returns: (transfer none): a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified.
33827 * Checks if the VFS is active.
33829 * Returns: %TRUE if construction of the @vfs was successful and it is now active.
33834 * g_vfs_parse_name:
33836 * @parse_name: a string to be parsed by the VFS module.
33838 * This operation never fails, but the returned object might
33839 * not support any I/O operations if the @parse_name cannot
33840 * be parsed by the #GVfs module.
33842 * Returns: (transfer full): a #GFile for the given @parse_name. Free the returned object with g_object_unref().
33847 * g_volume_can_eject:
33848 * @volume: a #GVolume.
33850 * Checks if a volume can be ejected.
33852 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
33857 * g_volume_can_mount:
33858 * @volume: a #GVolume.
33860 * Checks if a volume can be mounted.
33862 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
33868 * @volume: a #GVolume.
33869 * @flags: flags affecting the unmount if required for eject
33870 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
33871 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
33872 * @user_data: user data that gets passed to @callback
33874 * Ejects a volume. This is an asynchronous operation, and is
33875 * finished by calling g_volume_eject_finish() with the @volume
33876 * and #GAsyncResult returned in the @callback.
33878 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
33883 * g_volume_eject_finish:
33884 * @volume: pointer to a #GVolume.
33885 * @result: a #GAsyncResult.
33886 * @error: a #GError location to store an error, or %NULL to ignore
33888 * Finishes ejecting a volume. If any errors occurred during the operation,
33889 * @error will be set to contain the errors and %FALSE will be returned.
33891 * Returns: %TRUE, %FALSE if operation failed.
33892 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
33897 * g_volume_eject_with_operation:
33898 * @volume: a #GVolume.
33899 * @flags: flags affecting the unmount if required for eject
33900 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
33901 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
33902 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
33903 * @user_data: user data passed to @callback.
33905 * Ejects a volume. This is an asynchronous operation, and is
33906 * finished by calling g_volume_eject_with_operation_finish() with the @volume
33907 * and #GAsyncResult data returned in the @callback.
33914 * g_volume_eject_with_operation_finish:
33915 * @volume: a #GVolume.
33916 * @result: a #GAsyncResult.
33917 * @error: a #GError location to store the error occurring, or %NULL to ignore.
33919 * Finishes ejecting a volume. If any errors occurred during the operation,
33920 * @error will be set to contain the errors and %FALSE will be returned.
33922 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise.
33928 * g_volume_enumerate_identifiers:
33929 * @volume: a #GVolume
33931 * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
33932 * that @volume has. Use g_volume_get_identifier() to obtain
33933 * the identifiers themselves.
33935 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.
33940 * g_volume_get_activation_root:
33941 * @volume: a #GVolume
33943 * Gets the activation root for a #GVolume if it is known ahead of
33944 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
33945 * is mounted, then the result of g_mount_get_root() on the
33946 * #GMount object obtained from g_volume_get_mount() will always
33947 * either be equal or a prefix of what this function returns. In
33948 * other words, in code
33952 * GFile *mount_root
33953 * GFile *volume_activation_root;
33955 * mount = g_volume_get_mount (volume); /* mounted, so never NULL */
33956 * mount_root = g_mount_get_root (mount);
33957 * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
33958 * </programlisting>
33960 * then the expression
33963 * (g_file_has_prefix (volume_activation_root, mount_root) ||
33964 * g_file_equal (volume_activation_root, mount_root))
33965 * </programlisting>
33967 * will always be %TRUE.
33969 * Activation roots are typically used in #GVolumeMonitor
33970 * implementations to find the underlying mount to shadow, see
33971 * g_mount_is_shadowed() for more details.
33973 * Returns: (transfer full): the activation root of @volume or %NULL. Use g_object_unref() to free.
33979 * g_volume_get_drive:
33980 * @volume: a #GVolume.
33982 * Gets the drive for the @volume.
33984 * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed.
33989 * g_volume_get_icon:
33990 * @volume: a #GVolume.
33992 * Gets the icon for @volume.
33994 * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.
33999 * g_volume_get_identifier:
34000 * @volume: a #GVolume
34001 * @kind: the kind of identifier to return
34003 * Gets the identifier of the given kind for @volume.
34004 * See the <link linkend="volume-identifier">introduction</link>
34005 * for more information about volume identifiers.
34007 * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GVolume doesn't have this kind of identifier
34012 * g_volume_get_mount:
34013 * @volume: a #GVolume.
34015 * Gets the mount for the @volume.
34017 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed.
34022 * g_volume_get_name:
34023 * @volume: a #GVolume.
34025 * Gets the name of @volume.
34027 * Returns: the name for the given @volume. The returned string should be freed with g_free() when no longer needed.
34032 * g_volume_get_sort_key:
34033 * @volume: A #GVolume.
34035 * Gets the sort key for @volume, if any.
34037 * Returns: Sorting key for @volume or %NULL if no such key is available.
34043 * g_volume_get_symbolic_icon:
34044 * @volume: a #GVolume.
34046 * Gets the symbolic icon for @volume.
34048 * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.
34054 * g_volume_get_uuid:
34055 * @volume: a #GVolume.
34057 * Gets the UUID for the @volume. The reference is typically based on
34058 * the file system UUID for the volume in question and should be
34059 * considered an opaque string. Returns %NULL if there is no UUID
34062 * Returns: the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed.
34067 * g_volume_monitor_adopt_orphan_mount:
34068 * @mount: a #GMount object to find a parent for
34070 * This function should be called by any #GVolumeMonitor
34071 * implementation when a new #GMount object is created that is not
34072 * associated with a #GVolume object. It must be called just before
34073 * emitting the @mount_added signal.
34075 * If the return value is not %NULL, the caller must associate the
34076 * returned #GVolume object with the #GMount. This involves returning
34077 * it in its g_mount_get_volume() implementation. The caller must
34078 * also listen for the "removed" signal on the returned object
34079 * and give up its reference when handling that signal
34081 * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
34082 * the implementor must take a reference to @mount and return it in
34083 * its g_volume_get_mount() implemented. Also, the implementor must
34084 * listen for the "unmounted" signal on @mount and give up its
34085 * reference upon handling that signal.
34087 * There are two main use cases for this function.
34089 * One is when implementing a user space file system driver that reads
34090 * blocks of a block device that is already represented by the native
34091 * volume monitor (for example a CD Audio file system driver). Such
34092 * a driver will generate its own #GMount object that needs to be
34093 * associated with the #GVolume object that represents the volume.
34095 * The other is for implementing a #GVolumeMonitor whose sole purpose
34096 * is to return #GVolume objects representing entries in the users
34097 * "favorite servers" list or similar.
34099 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount.
34100 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions.
34105 * g_volume_monitor_get:
34107 * Gets the volume monitor used by gio.
34109 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it.
34114 * g_volume_monitor_get_connected_drives:
34115 * @volume_monitor: a #GVolumeMonitor.
34117 * Gets a list of drives connected to the system.
34119 * The returned list should be freed with g_list_free(), after
34120 * its elements have been unreffed with g_object_unref().
34122 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
34127 * g_volume_monitor_get_mount_for_uuid:
34128 * @volume_monitor: a #GVolumeMonitor.
34129 * @uuid: the UUID to look for
34131 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
34133 * Returns: (transfer full): a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref().
34138 * g_volume_monitor_get_mounts:
34139 * @volume_monitor: a #GVolumeMonitor.
34141 * Gets a list of the mounts on the system.
34143 * The returned list should be freed with g_list_free(), after
34144 * its elements have been unreffed with g_object_unref().
34146 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
34151 * g_volume_monitor_get_volume_for_uuid:
34152 * @volume_monitor: a #GVolumeMonitor.
34153 * @uuid: the UUID to look for
34155 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
34157 * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref().
34162 * g_volume_monitor_get_volumes:
34163 * @volume_monitor: a #GVolumeMonitor.
34165 * Gets a list of the volumes on the system.
34167 * The returned list should be freed with g_list_free(), after
34168 * its elements have been unreffed with g_object_unref().
34170 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
34176 * @volume: a #GVolume.
34177 * @flags: flags affecting the operation
34178 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
34179 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34180 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
34181 * @user_data: user data that gets passed to @callback
34183 * Mounts a volume. This is an asynchronous operation, and is
34184 * finished by calling g_volume_mount_finish() with the @volume
34185 * and #GAsyncResult returned in the @callback.
34187 * Virtual: mount_fn
34192 * g_volume_mount_finish:
34193 * @volume: a #GVolume
34194 * @result: a #GAsyncResult
34195 * @error: a #GError location to store an error, or %NULL to ignore
34197 * Finishes mounting a volume. If any errors occurred during the operation,
34198 * @error will be set to contain the errors and %FALSE will be returned.
34200 * If the mount operation succeeded, g_volume_get_mount() on @volume
34201 * is guaranteed to return the mount right after calling this
34202 * function; there's no need to listen for the 'mount-added' signal on
34205 * Returns: %TRUE, %FALSE if operation failed.
34210 * g_volume_should_automount:
34211 * @volume: a #GVolume
34213 * Returns whether the volume should be automatically mounted.
34215 * Returns: %TRUE if the volume should be automatically mounted.
34220 * g_win32_input_stream_get_close_handle:
34221 * @stream: a #GWin32InputStream
34223 * Returns whether the handle of @stream will be
34224 * closed when the stream is closed.
34226 * Returns: %TRUE if the handle is closed when done
34232 * g_win32_input_stream_get_handle:
34233 * @stream: a #GWin32InputStream
34235 * Return the Windows file handle that the stream reads from.
34237 * Returns: The file handle of @stream
34243 * g_win32_input_stream_new:
34244 * @handle: a Win32 file handle
34245 * @close_handle: %TRUE to close the handle when done
34247 * Creates a new #GWin32InputStream for the given @handle.
34249 * If @close_handle is %TRUE, the handle will be closed
34250 * when the stream is closed.
34252 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
34253 * as used in the Windows C libraries.
34255 * Returns: a new #GWin32InputStream
34260 * g_win32_input_stream_set_close_handle:
34261 * @stream: a #GWin32InputStream
34262 * @close_handle: %TRUE to close the handle when done
34264 * Sets whether the handle of @stream shall be closed
34265 * when the stream is closed.
34272 * g_win32_output_stream_get_close_handle:
34273 * @stream: a #GWin32OutputStream
34275 * Returns whether the handle of @stream will be closed when the
34276 * stream is closed.
34278 * Returns: %TRUE if the handle is closed when done
34284 * g_win32_output_stream_get_handle:
34285 * @stream: a #GWin32OutputStream
34287 * Return the Windows handle that the stream writes to.
34289 * Returns: The handle descriptor of @stream
34295 * g_win32_output_stream_new:
34296 * @handle: a Win32 file handle
34297 * @close_handle: %TRUE to close the handle when done
34299 * Creates a new #GWin32OutputStream for the given @handle.
34301 * If @close_handle, is %TRUE, the handle will be closed when the
34302 * output stream is destroyed.
34304 * Returns: a new #GOutputStream
34310 * g_win32_output_stream_set_close_handle:
34311 * @stream: a #GWin32OutputStream
34312 * @close_handle: %TRUE to close the handle when done
34314 * Sets whether the handle of @stream shall be closed when the stream
34322 * g_zlib_compressor_get_file_info:
34323 * @compressor: a #GZlibCompressor
34325 * Returns the #GZlibCompressor:file-info property.
34327 * Returns: (transfer none): a #GFileInfo, or %NULL
34333 * g_zlib_compressor_new:
34334 * @format: The format to use for the compressed data
34335 * @level: compression level (0-9), -1 for default
34337 * Creates a new #GZlibCompressor.
34339 * Returns: a new #GZlibCompressor
34345 * g_zlib_compressor_set_file_info:
34346 * @compressor: a #GZlibCompressor
34347 * @file_info: (allow-none): a #GFileInfo
34349 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
34350 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
34351 * it will be used to set the file name and modification time in
34352 * the GZIP header of the compressed data.
34354 * Note: it is an error to call this function while a compression is in
34355 * progress; it may only be called immediately after creation of @compressor,
34356 * or after resetting it with g_converter_reset().
34363 * g_zlib_decompressor_get_file_info:
34364 * @decompressor: a #GZlibDecompressor
34366 * Retrieves the #GFileInfo constructed from the GZIP header data
34367 * of compressed data processed by @compressor, or %NULL if @decompressor's
34368 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
34369 * or the header data was not fully processed yet, or it not present in the
34370 * data stream at all.
34372 * Returns: (transfer none): a #GFileInfo, or %NULL
34378 * g_zlib_decompressor_new:
34379 * @format: The format to use for the compressed data
34381 * Creates a new #GZlibDecompressor.
34383 * Returns: a new #GZlibDecompressor
34389 * get_all_desktop_entries_for_mime_type:
34390 * @mime_type: a mime type.
34391 * @except: NULL or a strv list
34393 * Returns all the desktop ids for @mime_type. The desktop files
34394 * are listed in an order so that default applications are listed before
34395 * non-default ones, and handlers for inherited mimetypes are listed
34396 * after the base ones.
34398 * Optionally doesn't list the desktop ids given in the @except
34400 * Returns: a #GList containing the desktop ids which claim to handle @mime_type.
34405 * mime_info_cache_reload:
34406 * @dir: directory path which needs reloading.
34408 * Reload the mime information for the @dir.
34413 /************************************************************/
34414 /* THIS FILE IS GENERATED DO NOT EDIT */
34415 /************************************************************/