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
61 * @parameter_type: the type of the parameter that must be passed to the
62 * activate function for this action, given as a single
63 * GVariant type string (or %NULL for no parameter)
64 * @state: the initial state for this action, given in GVariant text
65 * format. The state is parsed with no extra type information,
66 * so type tags must be added to the string if they are
68 * @change_state: the callback to connect to the "change-state" signal
71 * This struct defines a single action. It is for use with
72 * g_action_map_add_action_entries().
74 * The order of the items in the structure are intended to reflect
75 * frequency of use. It is permissible to use an incomplete initialiser
76 * in order to leave some of the later values as %NULL. All values
77 * after @name are optional. Additional optional fields may be added in
80 * See g_action_map_add_action_entries() for an example.
85 * GActionGroup::action-added:
86 * @action_group: the #GActionGroup that changed
87 * @action_name: the name of the action in @action_group
89 * Signals that a new action was just added to the group.
90 * This signal is emitted after the action has been added
98 * GActionGroup::action-enabled-changed:
99 * @action_group: the #GActionGroup that changed
100 * @action_name: the name of the action in @action_group
101 * @enabled: whether the action is enabled or not
103 * Signals that the enabled status of the named action has changed.
110 * GActionGroup::action-removed:
111 * @action_group: the #GActionGroup that changed
112 * @action_name: the name of the action in @action_group
114 * Signals that an action is just about to be removed from the group.
115 * This signal is emitted before the action is removed, so the action
116 * is still visible and can be queried from the signal handler.
123 * GActionGroup::action-state-changed:
124 * @action_group: the #GActionGroup that changed
125 * @action_name: the name of the action in @action_group
126 * @value: the new value of the state
128 * Signals that the state of the named action has changed.
135 * GActionGroupInterface:
136 * @has_action: the virtual function pointer for g_action_group_has_action()
137 * @list_actions: the virtual function pointer for g_action_group_list_actions()
138 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
139 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
140 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
141 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
142 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
143 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
144 * @query_action: the virtual function pointer for g_action_group_query_action()
145 * @activate_action: the virtual function pointer for g_action_group_activate_action()
146 * @action_added: the class closure for the #GActionGroup::action-added signal
147 * @action_removed: the class closure for the #GActionGroup::action-removed signal
148 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
149 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
151 * The virtual function table for #GActionGroup.
159 * @get_name: the virtual function pointer for g_action_get_name()
160 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
161 * @get_state_type: the virtual function pointer for g_action_get_state_type()
162 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
163 * @get_enabled: the virtual function pointer for g_action_get_enabled()
164 * @get_state: the virtual function pointer for g_action_get_state()
165 * @change_state: the virtual function pointer for g_action_change_state()
166 * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an
167 * 'activate' signal but that implementations of it may have one.
169 * The virtual function table for #GAction.
176 * GActionMapInterface:
177 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
178 * @add_action: the virtual function pointer for g_action_map_add_action()
179 * @remove_action: the virtual function pointer for g_action_map_remove_action()
181 * The virtual function table for #GActionMap.
190 * The only thing you can do with this is to get it via
191 * g_app_info_monitor_get() and connect to the "changed" signal.
198 * GApplication::activate:
199 * @application: the application
201 * The ::activate signal is emitted on the primary instance when an
202 * activation occurs. See g_application_activate().
207 * GApplication::command-line:
208 * @application: the application
209 * @command_line: a #GApplicationCommandLine representing the
212 * The ::command-line signal is emitted on the primary instance when
213 * a commandline is not handled locally. See g_application_run() and
214 * the #GApplicationCommandLine documentation for more information.
216 * Returns: An integer that is set as the exit status for the calling
217 * process. See g_application_command_line_set_exit_status().
222 * GApplication::open:
223 * @application: the application
224 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
225 * @n_files: the length of @files
226 * @hint: a hint provided by the calling instance
228 * The ::open signal is emitted on the primary instance when there are
229 * files to open. See g_application_open() for more information.
234 * GApplication::shutdown:
235 * @application: the application
237 * The ::shutdown signal is emitted only on the registered primary instance
238 * immediately after the main loop terminates.
243 * GApplication::startup:
244 * @application: the application
246 * The ::startup signal is emitted on the primary instance immediately
247 * after registration. See g_application_register().
253 * @startup: invoked on the primary instance immediately after registration
254 * @shutdown: invoked only on the registered primary instance immediately
255 * after the main loop terminates
256 * @activate: invoked on the primary instance when an activation occurs
257 * @open: invoked on the primary instance when there are files to open
258 * @command_line: invoked on the primary instance when a command-line is
259 * not handled locally
260 * @local_command_line: invoked (locally) when the process has been invoked
261 * via commandline execution (as opposed to, say, D-Bus activation - which
262 * is not currently supported by GApplication). The virtual function has
263 * the chance to inspect (and possibly replace) the list of command line
264 * arguments. See g_application_run() for more information.
265 * @before_emit: invoked on the primary instance before 'activate', 'open',
266 * 'command-line' or any action invocation, gets the 'platform data' from
267 * the calling instance
268 * @after_emit: invoked on the primary instance after 'activate', 'open',
269 * 'command-line' or any action invocation, gets the 'platform data' from
270 * the calling instance
271 * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
272 * the primary instance when activating, opening or invoking actions
273 * @quit_mainloop: Used to be invoked on the primary instance when the use
274 * count of the application drops to zero (and after any inactivity
275 * timeout, if requested). Not used anymore since 2.32
276 * @run_mainloop: Used to be invoked on the primary instance from
277 * g_application_run() if the use-count is non-zero. Since 2.32,
278 * GApplication is iterating the main context directly and is not
279 * using @run_mainloop anymore
280 * @dbus_register: invoked locally during registration, if the application is
281 * using its D-Bus backend. You can use this to export extra objects on the
282 * bus, that need to exist before the application tries to own the bus name.
283 * The function is passed the #GDBusConnection to to session bus, and the
284 * object path that #GApplication will use to export is D-Bus API.
285 * If this function returns %TRUE, registration will proceed; otherwise
286 * registration will abort. Since: 2.34
287 * @dbus_unregister: invoked locally during unregistration, if the application
288 * is using its D-Bus backend. Use this to undo anything done by the
289 * @dbus_register vfunc. Since: 2.34
291 * Virtual function table for #GApplication.
298 * GApplicationCommandLineClass:
300 * The <structname>GApplicationCommandLineClass</structname> structure
301 * contains private data only
310 * The bytes containing the icon.
315 * GCancellable::cancelled:
316 * @cancellable: a #GCancellable.
318 * Emitted when the operation has been cancelled.
320 * Can be used by implementations of cancellable operations. If the
321 * operation is cancelled from another thread, the signal will be
322 * emitted in the thread that cancelled the operation, not the
323 * thread that is running the operation.
325 * Note that disconnecting from this signal (or any signal) in a
326 * multi-threaded program is prone to race conditions. For instance
327 * it is possible that a signal handler may be invoked even
328 * <emphasis>after</emphasis> a call to
329 * g_signal_handler_disconnect() for that handler has already
332 * There is also a problem when cancellation happen
333 * right before connecting to the signal. If this happens the
334 * signal will unexpectedly not be emitted, and checking before
335 * connecting to the signal leaves a race condition where this is
338 * In order to make it safe and easy to connect handlers there
339 * are two helper functions: g_cancellable_connect() and
340 * g_cancellable_disconnect() which protect against problems
343 * An example of how to us this:
345 * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
346 * if (g_cancellable_set_error_if_cancelled (cancellable))
349 * /<!-- -->* Set up all the data needed to be able to
350 * * handle cancellation of the operation *<!-- -->/
351 * my_data = my_data_new (...);
355 * id = g_cancellable_connect (cancellable,
356 * G_CALLBACK (cancelled_handler)
359 * /<!-- -->* cancellable operation here... *<!-- -->/
361 * g_cancellable_disconnect (cancellable, id);
363 * /<!-- -->* cancelled_handler is never called after this, it
364 * * is now safe to free the data *<!-- -->/
365 * my_data_free (my_data);
368 * Note that the cancelled signal is emitted in the thread that
369 * the user cancelled from, which may be the main thread. So, the
370 * cancellable signal should not do something that can block.
377 * Conversions between character sets.
384 * The #GCredentials structure contains only private data and
385 * should only be accessed using the provided API.
394 * Class structure for #GCredentials.
401 * GDBusAuthMechanism:credentials:
403 * If authenticating as a server, this property contains the
404 * received credentials, if any.
406 * If authenticating as a client, the property contains the
407 * credentials that were sent, if any.
414 * The #GDBusAuthObserver structure contains only private data and
415 * should only be accessed using the provided API.
422 * GDBusAuthObserver::allow-mechanism:
423 * @observer: The #GDBusAuthObserver emitting the signal.
424 * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
426 * Emitted to check if @mechanism is allowed to be used.
428 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
434 * GDBusAuthObserver::authorize-authenticated-peer:
435 * @observer: The #GDBusAuthObserver emitting the signal.
436 * @stream: A #GIOStream for the #GDBusConnection.
437 * @credentials: (allow-none): Credentials received from the peer or %NULL.
439 * Emitted to check if a peer that is successfully authenticated
442 * Returns: %TRUE if the peer is authorized, %FALSE if not.
448 * GDBusAuthObserverClass:
449 * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
451 * Class structure for #GDBusAuthObserverClass.
460 * The #GDBusConnection structure contains only private data and
461 * should only be accessed using the provided API.
468 * GDBusConnection::closed:
469 * @connection: The #GDBusConnection emitting the signal.
470 * @remote_peer_vanished: %TRUE if @connection is closed because the
471 * remote peer closed its end of the connection.
472 * @error: (allow-none): A #GError with more details about the event or %NULL.
474 * Emitted when the connection is closed.
476 * The cause of this event can be
479 * If g_dbus_connection_close() is called. In this case
480 * @remote_peer_vanished is set to %FALSE and @error is %NULL.
483 * If the remote peer closes the connection. In this case
484 * @remote_peer_vanished is set to %TRUE and @error is set.
487 * If the remote peer sends invalid or malformed data. In this
488 * case @remote_peer_vanished is set to %FALSE and @error
493 * Upon receiving this signal, you should give up your reference to
494 * @connection. You are guaranteed that this signal is emitted only
502 * GDBusConnection:address:
504 * A D-Bus address specifying potential endpoints that can be used
505 * when establishing the connection.
512 * GDBusConnection:authentication-observer:
514 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
521 * GDBusConnection:capabilities:
523 * Flags from the #GDBusCapabilityFlags enumeration
524 * representing connection features negotiated with the other peer.
531 * GDBusConnection:closed:
533 * A boolean specifying whether the connection has been closed.
540 * GDBusConnection:exit-on-close:
542 * A boolean specifying whether the process will be terminated (by
543 * calling <literal>raise(SIGTERM)</literal>) if the connection
544 * is closed by the remote peer.
546 * Note that #GDBusConnection objects returned by g_bus_get_finish() and
547 * g_bus_get_sync() will (usually) have this property set to %TRUE.
554 * GDBusConnection:flags:
556 * Flags from the #GDBusConnectionFlags enumeration.
563 * GDBusConnection:guid:
565 * The GUID of the peer performing the role of server when
568 * If you are constructing a #GDBusConnection and pass
569 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
570 * #GDBusConnection:flags property then you MUST also set this
571 * property to a valid guid.
573 * If you are constructing a #GDBusConnection and pass
574 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
575 * #GDBusConnection:flags property you will be able to read the GUID
576 * of the other peer here after the connection has been successfully
584 * GDBusConnection:locked:
586 * A boolean specifying whether the message is locked.
593 * GDBusConnection:stream:
595 * The underlying #GIOStream used for I/O.
597 * If this is passed on construction and is a #GSocketConnection,
598 * then the corresponding #GSocket will be put into non-blocking mode.
600 * While the #GDBusConnection is active, it will interact with this
601 * stream from a worker thread, so it is not safe to interact with
602 * the stream directly.
609 * GDBusConnection:unique-name:
611 * The unique name as assigned by the message bus or %NULL if the
612 * connection is not open or not a message bus connection.
619 * GDBusConnectionClass:
620 * @closed: Signal class handler for the #GDBusConnection::closed signal.
622 * Class structure for #GDBusConnection.
629 * GDBusInterfaceSkeleton::g-authorize-method:
630 * @interface: The #GDBusInterfaceSkeleton emitting the signal.
631 * @invocation: A #GDBusMethodInvocation.
633 * Emitted when a method is invoked by a remote caller and used to
634 * determine if the method call is authorized.
636 * Note that this signal is emitted in a thread dedicated to
637 * handling the method call so handlers are allowed to perform
638 * blocking IO. This means that it is appropriate to call
640 * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</ulink>
642 * 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.
644 * If %FALSE is returned then no further handlers are run and the
645 * signal handler must take a reference to @invocation and finish
646 * handling the call (e.g. return an error via
647 * g_dbus_method_invocation_return_error()).
649 * Otherwise, if %TRUE is returned, signal emission continues. If no
650 * handlers return %FALSE, then the method is dispatched. If
651 * @interface has an enclosing #GDBusObjectSkeleton, then the
652 * #GDBusObjectSkeleton::authorize-method signal handlers run before
653 * the handlers for this signal.
655 * The default class handler just returns %TRUE.
657 * Please note that the common case is optimized: if no signals
658 * handlers are connected and the default class handler isn't
659 * overridden (for both @interface and the enclosing
660 * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
662 * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
663 * flags set, no dedicated thread is ever used and the call will be
664 * handled in the same thread as the object that @interface belongs
665 * to was exported in.
667 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
673 * GDBusInterfaceSkeleton:g-flags:
675 * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
684 * The #GDBusMessage structure contains only private data and should
685 * only be accessed using the provided API.
694 * Class structure for #GDBusMessage.
701 * GDBusMethodInvocation:
703 * The #GDBusMethodInvocation structure contains only private data and
704 * should only be accessed using the provided API.
711 * GDBusMethodInvocationClass:
713 * Class structure for #GDBusMethodInvocation.
720 * GDBusObject::interface-added:
721 * @object: The #GDBusObject emitting the signal.
722 * @interface: The #GDBusInterface that was added.
724 * Emitted when @interface is added to @object.
731 * GDBusObject::interface-removed:
732 * @object: The #GDBusObject emitting the signal.
733 * @interface: The #GDBusInterface that was removed.
735 * Emitted when @interface is removed from @object.
742 * GDBusObjectManager::interface-added:
743 * @manager: The #GDBusObjectManager emitting the signal.
744 * @object: The #GDBusObject on which an interface was added.
745 * @interface: The #GDBusInterface that was added.
747 * Emitted when @interface is added to @object.
749 * This signal exists purely as a convenience to avoid having to
750 * connect signals to all objects managed by @manager.
757 * GDBusObjectManager::interface-removed:
758 * @manager: The #GDBusObjectManager emitting the signal.
759 * @object: The #GDBusObject on which an interface was removed.
760 * @interface: The #GDBusInterface that was removed.
762 * Emitted when @interface has been removed from @object.
764 * This signal exists purely as a convenience to avoid having to
765 * connect signals to all objects managed by @manager.
772 * GDBusObjectManager::object-added:
773 * @manager: The #GDBusObjectManager emitting the signal.
774 * @object: The #GDBusObject that was added.
776 * Emitted when @object is added to @manager.
783 * GDBusObjectManager::object-removed:
784 * @manager: The #GDBusObjectManager emitting the signal.
785 * @object: The #GDBusObject that was removed.
787 * Emitted when @object is removed from @manager.
794 * GDBusObjectManagerClient::interface-proxy-properties-changed:
795 * @manager: The #GDBusObjectManagerClient emitting the signal.
796 * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
797 * @interface_proxy: The #GDBusProxy that has properties that are changing.
798 * @changed_properties: A #GVariant containing the properties that changed.
799 * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
801 * Emitted when one or more D-Bus properties on proxy changes. The
802 * local cache has already been updated when this signal fires. Note
803 * that both @changed_properties and @invalidated_properties are
804 * guaranteed to never be %NULL (either may be empty though).
806 * This signal exists purely as a convenience to avoid having to
807 * connect signals to all interface proxies managed by @manager.
809 * This signal is emitted in the
810 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
811 * that @manager was constructed in.
818 * GDBusObjectManagerClient::interface-proxy-signal:
819 * @manager: The #GDBusObjectManagerClient emitting the signal.
820 * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
821 * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
822 * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
823 * @signal_name: The signal name.
824 * @parameters: A #GVariant tuple with parameters for the signal.
826 * Emitted when a D-Bus signal is received on @interface_proxy.
828 * This signal exists purely as a convenience to avoid having to
829 * connect signals to all interface proxies managed by @manager.
831 * This signal is emitted in the
832 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
833 * that @manager was constructed in.
840 * GDBusObjectManagerClient:bus-type:
842 * If this property is not %G_BUS_TYPE_NONE, then
843 * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
844 * #GDBusConnection obtained by calling g_bus_get() with the value
852 * GDBusObjectManagerClient:connection:
854 * The #GDBusConnection to use.
861 * GDBusObjectManagerClient:flags:
863 * Flags from the #GDBusObjectManagerClientFlags enumeration.
870 * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
872 * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
879 * GDBusObjectManagerClient:get-proxy-type-func:
881 * The #GDBusProxyTypeFunc to use when determining what #GType to
882 * use for interface proxies or %NULL.
889 * GDBusObjectManagerClient:get-proxy-type-user-data:
891 * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
898 * GDBusObjectManagerClient:name:
900 * The well-known name or unique name that the manager is for.
907 * GDBusObjectManagerClient:name-owner:
909 * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
910 * no-one is currently owning the name. Connect to the
911 * #GObject::notify signal to track changes to this property.
918 * GDBusObjectManagerClient:object-path:
920 * The object path the manager is for.
927 * GDBusObjectManagerServer:connection:
929 * The #GDBusConnection to export objects on.
936 * GDBusObjectManagerServer:object-path:
938 * The object path to register the manager object at.
945 * GDBusObjectProxy:g-connection:
947 * The connection of the proxy.
954 * GDBusObjectProxy:g-object-path:
956 * The object path of the proxy.
963 * GDBusObjectSkeleton::authorize-method:
964 * @object: The #GDBusObjectSkeleton emitting the signal.
965 * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
966 * @invocation: A #GDBusMethodInvocation.
968 * Emitted when a method is invoked by a remote caller and used to
969 * determine if the method call is authorized.
971 * This signal is like #GDBusInterfaceSkeleton<!-- -->'s
972 * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
973 * for the enclosing object.
975 * The default class handler just returns %TRUE.
977 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
983 * GDBusObjectSkeleton:g-object-path:
985 * The object path where the object is exported.
992 * GDBusProxy::g-properties-changed:
993 * @proxy: The #GDBusProxy emitting the signal.
994 * @changed_properties: A #GVariant containing the properties that changed
995 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
997 * Emitted when one or more D-Bus properties on @proxy changes. The
998 * local cache has already been updated when this signal fires. Note
999 * that both @changed_properties and @invalidated_properties are
1000 * guaranteed to never be %NULL (either may be empty though).
1002 * If the proxy has the flag
1003 * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
1004 * @invalidated_properties will always be empty.
1006 * This signal corresponds to the
1007 * <literal>PropertiesChanged</literal> D-Bus signal on the
1008 * <literal>org.freedesktop.DBus.Properties</literal> interface.
1015 * GDBusProxy::g-signal:
1016 * @proxy: The #GDBusProxy emitting the signal.
1017 * @sender_name: (allow-none): The sender of the signal or %NULL if the connection is not a bus connection.
1018 * @signal_name: The name of the signal.
1019 * @parameters: A #GVariant tuple with parameters for the signal.
1021 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
1028 * GDBusProxy:g-bus-type:
1030 * If this property is not %G_BUS_TYPE_NONE, then
1031 * #GDBusProxy:g-connection must be %NULL and will be set to the
1032 * #GDBusConnection obtained by calling g_bus_get() with the value
1040 * GDBusProxy:g-connection:
1042 * The #GDBusConnection the proxy is for.
1049 * GDBusProxy:g-default-timeout:
1051 * The timeout to use if -1 (specifying default timeout) is passed
1052 * as @timeout_msec in the g_dbus_proxy_call() and
1053 * g_dbus_proxy_call_sync() functions.
1055 * This allows applications to set a proxy-wide timeout for all
1056 * remote method invocations on the proxy. If this property is -1,
1057 * the default timeout (typically 25 seconds) is used. If set to
1058 * %G_MAXINT, then no timeout is used.
1065 * GDBusProxy:g-flags:
1067 * Flags from the #GDBusProxyFlags enumeration.
1074 * GDBusProxy:g-interface-info:
1076 * Ensure that interactions with this proxy conform to the given
1077 * interface. This is mainly to ensure that malformed data received
1078 * from the other peer is ignored. The given #GDBusInterfaceInfo is
1079 * said to be the <emphasis>expected interface</emphasis>.
1081 * The checks performed are:
1084 * When completing a method call, if the type signature of
1085 * the reply message isn't what's expected, the reply is
1086 * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
1087 * </para></listitem>
1089 * Received signals that have a type signature mismatch are dropped and
1090 * a warning is logged via g_warning().
1091 * </para></listitem>
1093 * Properties received via the initial <literal>GetAll()</literal> call
1094 * or via the <literal>::PropertiesChanged</literal> signal (on the
1095 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface) or
1096 * set using g_dbus_proxy_set_cached_property() with a type signature
1097 * mismatch are ignored and a warning is logged via g_warning().
1098 * </para></listitem>
1100 * Note that these checks are never done on methods, signals and
1101 * properties that are not referenced in the given
1102 * #GDBusInterfaceInfo, since extending a D-Bus interface on the
1103 * service-side is not considered an ABI break.
1110 * GDBusProxy:g-interface-name:
1112 * The D-Bus interface name the proxy is for.
1119 * GDBusProxy:g-name:
1121 * The well-known or unique name that the proxy is for.
1128 * GDBusProxy:g-name-owner:
1130 * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
1131 * currently owns that name. You may connect to #GObject::notify signal to
1132 * track changes to this property.
1139 * GDBusProxy:g-object-path:
1141 * The object path the proxy is for.
1150 * The #GDBusServer structure contains only private data and
1151 * should only be accessed using the provided API.
1158 * GDBusServer::new-connection:
1159 * @server: The #GDBusServer emitting the signal.
1160 * @connection: A #GDBusConnection for the new connection.
1162 * Emitted when a new authenticated connection has been made. Use
1163 * g_dbus_connection_get_peer_credentials() to figure out what
1164 * identity (if any), was authenticated.
1166 * If you want to accept the connection, take a reference to the
1167 * @connection object and return %TRUE. When you are done with the
1168 * connection call g_dbus_connection_close() and give up your
1169 * reference. Note that the other peer may disconnect at any time -
1170 * a typical thing to do when accepting a connection is to listen to
1171 * the #GDBusConnection::closed signal.
1173 * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
1174 * then the signal is emitted in a new thread dedicated to the
1175 * connection. Otherwise the signal is emitted in the <link
1176 * linkend="g-main-context-push-thread-default">thread-default main
1177 * loop</link> of the thread that @server was constructed in.
1179 * You are guaranteed that signal handlers for this signal runs
1180 * before incoming messages on @connection are processed. This means
1181 * that it's suitable to call g_dbus_connection_register_object() or
1182 * similar from the signal handler.
1184 * Returns: %TRUE to claim @connection, %FALSE to let other handlers
1191 * GDBusServer:active:
1193 * Whether the server is currently active.
1200 * GDBusServer:address:
1202 * The D-Bus address to listen on.
1209 * GDBusServer:authentication-observer:
1211 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
1218 * GDBusServer:client-address:
1220 * The D-Bus address that clients can use.
1227 * GDBusServer:flags:
1229 * Flags from the #GDBusServerFlags enumeration.
1238 * The guid of the server.
1246 * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
1248 * Class structure for #GDBusServer.
1255 * GDataOutputStream:byte-order:
1257 * Determines the byte ordering that is used when writing
1258 * multi-byte entities (such as integers) to the stream.
1263 * GDataStream:byte-order:
1265 * The ::byte-order property determines the byte ordering that
1266 * is used when reading multi-byte entities (such as integers)
1272 * GDataStream:newline-type:
1274 * The :newline-type property determines what is considered
1275 * as a line ending when reading complete lines from the stream.
1282 * Information about an installed application from a desktop file.
1287 * GDesktopAppInfo:filename:
1289 * The origin filename of this #GDesktopAppInfo
1295 * @drive: a #GDrive.
1297 * Emitted when the drive's state has changed.
1302 * GDrive::disconnected:
1303 * @drive: a #GDrive.
1305 * This signal is emitted when the #GDrive have been
1306 * disconnected. If the recipient is holding references to the
1307 * object they should release them so the object can be
1313 * GDrive::eject-button:
1314 * @drive: a #GDrive.
1316 * Emitted when the physical eject button (if any) of a drive has
1322 * GDrive::stop-button:
1323 * @drive: a #GDrive.
1325 * Emitted when the physical stop button (if any) of a drive has
1335 * The file containing the icon.
1340 * GFileMonitor::changed:
1341 * @monitor: a #GFileMonitor.
1343 * @other_file: (allow-none): a #GFile or #NULL.
1344 * @event_type: a #GFileMonitorEvent.
1346 * Emitted when @file has been changed.
1348 * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
1349 * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
1350 * old path, and @other_file will be set to a #GFile containing the new path.
1352 * In all the other cases, @other_file will be set to #NULL.
1357 * GFilenameCompleter::got-completion-data:
1359 * Emitted when the file name completion information comes available.
1366 * Represents a scope for loading IO modules. A scope can be used for blocking
1367 * duplicate modules, or blocking a module you don't want to load.
1369 * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
1370 * or g_io_modules_scan_all_in_directory_with_scope().
1379 * An IPv4 or IPv6 internet address.
1384 * GInetAddress:is-any:
1386 * Whether this is the "any" address for its family.
1387 * See g_inet_address_get_is_any().
1394 * GInetAddress:is-link-local:
1396 * Whether this is a link-local address.
1397 * See g_inet_address_get_is_link_local().
1404 * GInetAddress:is-loopback:
1406 * Whether this is the loopback address for its family.
1407 * See g_inet_address_get_is_loopback().
1414 * GInetAddress:is-mc-global:
1416 * Whether this is a global multicast address.
1417 * See g_inet_address_get_is_mc_global().
1424 * GInetAddress:is-mc-link-local:
1426 * Whether this is a link-local multicast address.
1427 * See g_inet_address_get_is_mc_link_local().
1434 * GInetAddress:is-mc-node-local:
1436 * Whether this is a node-local multicast address.
1437 * See g_inet_address_get_is_mc_node_local().
1444 * GInetAddress:is-mc-org-local:
1446 * Whether this is an organization-local multicast address.
1447 * See g_inet_address_get_is_mc_org_local().
1454 * GInetAddress:is-mc-site-local:
1456 * Whether this is a site-local multicast address.
1457 * See g_inet_address_get_is_mc_site_local().
1464 * GInetAddress:is-multicast:
1466 * Whether this is a multicast address.
1467 * See g_inet_address_get_is_multicast().
1474 * GInetAddress:is-site-local:
1476 * Whether this is a site-local address.
1477 * See g_inet_address_get_is_loopback().
1486 * A combination of an IPv4 or IPv6 base address and a length,
1487 * representing a range of IP addresses.
1494 * GInetSocketAddress:
1496 * An IPv4 or IPv6 socket address, corresponding to a <type>struct
1497 * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
1502 * GInetSocketAddress:flowinfo:
1504 * The <literal>sin6_flowinfo</literal> field, for IPv6 addresses.
1511 * GInetSocketAddress:scope_id:
1513 * The <literal>sin6_scope_id</literal> field, for IPv6 addresses.
1520 * GMemoryOutputStream:data:
1522 * Pointer to buffer where data will be written.
1529 * GMemoryOutputStream:data-size:
1531 * Size of data written to the buffer.
1538 * GMemoryOutputStream:destroy-function: (skip)
1540 * Function called with the buffer as argument when the stream is destroyed.
1547 * GMemoryOutputStream:realloc-function: (skip)
1549 * Function with realloc semantics called to enlarge the buffer.
1556 * GMemoryOutputStream:size:
1558 * Current size of the data buffer.
1567 * #GMenu is an opaque structure type. You must access it using the
1575 * GMenuAttributeIter:
1577 * #GMenuAttributeIter is an opaque structure type. You must access it
1578 * using the functions below.
1587 * #GMenuItem is an opaque structure type. You must access it using the
1597 * #GMenuLinkIter is an opaque structure type. You must access it using
1598 * the functions below.
1607 * #GMenuModel is an opaque structure type. You must access it using the
1615 * GMenuModel::items-changed:
1616 * @model: the #GMenuModel that is changing
1617 * @position: the position of the change
1618 * @removed: the number of items removed
1619 * @added: the number of items added
1621 * Emitted when a change has occured to the menu.
1623 * The only changes that can occur to a menu is that items are removed
1624 * or added. Items may not change (except by being removed and added
1625 * back in the same location). This signal is capable of describing
1626 * both of those changes (at the same time).
1628 * The signal means that starting at the index @position, @removed
1629 * items were removed and @added items were added in their place. If
1630 * @removed is zero then only items were added. If @added is zero
1631 * then only items were removed.
1633 * As an example, if the menu contains items a, b, c, d (in that
1634 * order) and the signal (2, 1, 3) occurs then the new composition of
1635 * the menu will be a, b, _, _, _, d (with each _ representing some
1638 * Signal handlers may query the model (particularly the added items)
1639 * and expect to see the results of the modification that is being
1640 * reported. The signal is emitted after the modification.
1646 * @mount: the object on which the signal is emitted
1648 * Emitted when the mount has been changed.
1653 * GMount::pre-unmount:
1654 * @mount: the object on which the signal is emitted
1656 * This signal is emitted when the #GMount is about to be
1664 * GMount::unmounted:
1665 * @mount: the object on which the signal is emitted
1667 * This signal is emitted when the #GMount have been
1668 * unmounted. If the recipient is holding references to the
1669 * object they should release them so the object can be
1675 * GMountOperation::aborted:
1677 * Emitted by the backend when e.g. a device becomes unavailable
1678 * while a mount operation is in progress.
1680 * Implementations of GMountOperation should handle this signal
1681 * by dismissing open password dialogs.
1688 * GMountOperation::ask-password:
1689 * @op: a #GMountOperation requesting a password.
1690 * @message: string containing a message to display to the user.
1691 * @default_user: string containing the default user name.
1692 * @default_domain: string containing the default domain.
1693 * @flags: a set of #GAskPasswordFlags.
1695 * Emitted when a mount operation asks the user for a password.
1697 * If the message contains a line break, the first line should be
1698 * presented as a heading. For example, it may be used as the
1699 * primary text in a #GtkMessageDialog.
1704 * GMountOperation::ask-question:
1705 * @op: a #GMountOperation asking a question.
1706 * @message: string containing a message to display to the user.
1707 * @choices: an array of strings for each possible choice.
1709 * Emitted when asking the user a question and gives a list of
1710 * choices for the user to choose from.
1712 * If the message contains a line break, the first line should be
1713 * presented as a heading. For example, it may be used as the
1714 * primary text in a #GtkMessageDialog.
1719 * GMountOperation::reply:
1720 * @op: a #GMountOperation.
1721 * @result: a #GMountOperationResult indicating how the request was handled
1723 * Emitted when the user has replied to the mount operation.
1728 * GMountOperation::show-processes:
1729 * @op: a #GMountOperation.
1730 * @message: string containing a message to display to the user.
1731 * @processes: (element-type GPid): an array of #GPid for processes
1732 * blocking the operation.
1733 * @choices: an array of strings for each possible choice.
1735 * Emitted when one or more processes are blocking an operation
1736 * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
1738 * Note that this signal may be emitted several times to update the
1739 * list of blocking processes as processes close files. The
1740 * application should only respond with g_mount_operation_reply() to
1741 * the latest signal (setting #GMountOperation:choice to the choice
1744 * If the message contains a line break, the first line should be
1745 * presented as a heading. For example, it may be used as the
1746 * primary text in a #GtkMessageDialog.
1753 * GMountOperation::show-unmount-progress:
1754 * @op: a #GMountOperation:
1755 * @message: string containing a mesage to display to the user
1756 * @time_left: the estimated time left before the operation completes,
1757 * in microseconds, or -1
1758 * @bytes_left: the amount of bytes to be written before the operation
1759 * completes (or -1 if such amount is not known), or zero if the operation
1762 * Emitted when an unmount operation has been busy for more than some time
1763 * (typically 1.5 seconds).
1765 * When unmounting or ejecting a volume, the kernel might need to flush
1766 * pending data in its buffers to the volume stable storage, and this operation
1767 * can take a considerable amount of time. This signal may be emitted several
1768 * times as long as the unmount operation is outstanding, and then one
1769 * last time when the operation is completed, with @bytes_left set to zero.
1771 * Implementations of GMountOperation should handle this signal by
1772 * showing an UI notification, and then dismiss it, or show another notification
1773 * of completion, when @bytes_left reaches zero.
1775 * If the message contains a line break, the first line should be
1776 * presented as a heading. For example, it may be used as the
1777 * primary text in a #GtkMessageDialog.
1784 * GMountOperation:anonymous:
1786 * Whether to use an anonymous user when authenticating.
1791 * GMountOperation:choice:
1793 * The index of the user's choice when a question is asked during the
1794 * mount operation. See the #GMountOperation::ask-question signal.
1799 * GMountOperation:domain:
1801 * The domain to use for the mount operation.
1806 * GMountOperation:password:
1808 * The password that is used for authentication when carrying out
1809 * the mount operation.
1814 * GMountOperation:password-save:
1816 * Determines if and how the password information should be saved.
1821 * GMountOperation:username:
1823 * The user name that is used for authentication when carrying out
1824 * the mount operation.
1831 * A #GSocketConnectable for resolving a hostname and connecting to
1839 * #GNetworkMonitor monitors the status of network connections and
1840 * indicates when a possibly-user-visible change has occurred.
1847 * GNetworkMonitor::network-changed:
1848 * @monitor: a #GNetworkMonitor
1849 * @available: the current value of #GNetworkMonitor:network-available
1851 * Emitted when the network configuration changes. If @available is
1852 * %TRUE, then some hosts may be reachable that were not reachable
1853 * before, while others that were reachable before may no longer be
1854 * reachable. If @available is %FALSE, then no remote hosts are
1862 * GNetworkMonitor:network-available:
1864 * Whether the network is considered available. That is, whether the
1865 * system has a default route for at least one of IPv4 or IPv6.
1867 * Real-world networks are of course much more complicated than
1868 * this; the machine may be connected to a wifi hotspot that
1869 * requires payment before allowing traffic through, or may be
1870 * connected to a functioning router that has lost its own upstream
1871 * connectivity. Some hosts might only be accessible when a VPN is
1872 * active. Other hosts might only be accessible when the VPN is
1873 * <emphasis>not</emphasis> active. Thus, it is best to use
1874 * g_network_monitor_can_reach() or
1875 * g_network_monitor_can_reach_async() to test for reachability on a
1876 * host-by-host basis. (On the other hand, when the property is
1877 * %FALSE, the application can reasonably expect that no remote
1878 * hosts at all are reachable, and should indicate this to the user
1881 * See also #GNetworkMonitor::network-changed.
1890 * A #GSocketConnectable for resolving a SRV record and connecting to
1898 * This structure type is private and should only be accessed using the
1908 * #GPermission is an opaque data structure and can only be accessed
1909 * using the following functions.
1914 * GPermission:allowed:
1916 * %TRUE if the caller currently has permission to perform the action that
1917 * @permission represents the permission to perform.
1922 * GPermission:can-acquire:
1924 * %TRUE if it is generally possible to acquire the permission by calling
1925 * g_permission_acquire().
1930 * GPermission:can-release:
1932 * %TRUE if it is generally possible to release the permission by calling
1933 * g_permission_release().
1940 * This type is opaque.
1947 * GPropertyAction:enabled:
1949 * If @action is currently enabled.
1951 * If the action is disabled then calls to g_action_activate() and
1952 * g_action_change_state() have no effect.
1959 * GPropertyAction:name:
1961 * The name of the action. This is mostly meaningful for identifying
1962 * the action once it has been added to a #GActionMap.
1969 * GPropertyAction:object:
1971 * The object to wrap a property on.
1973 * The object must be a non-%NULL #GObject with properties.
1980 * GPropertyAction:parameter-type:
1982 * The type of the parameter that must be given when activating the
1990 * GPropertyAction:property-name:
1992 * The name of the property to wrap on the object.
1994 * The property must exist on the passed-in object and it must be
1995 * readable and writable (and not construct-only).
2002 * GPropertyAction:state:
2004 * The state of the action, or %NULL if the action is stateless.
2011 * GPropertyAction:state-type:
2013 * The #GVariantType of the state that the action has, or %NULL if the
2014 * action is stateless.
2023 * A #GInetSocketAddress representing a connection via a proxy server
2030 * GProxyAddress:destination-protocol:
2032 * The protocol being spoke to the destination host, or %NULL if
2033 * the #GProxyAddress doesn't know.
2040 * GProxyAddress:uri:
2042 * The URI string that the proxy was constructed from (or %NULL
2043 * if the creator didn't specify this).
2050 * GProxyAddressEnumerator:default-port:
2052 * The default port to use if #GProxyAddressEnumerator:uri does not
2060 * GProxyAddressEnumerator:proxy-resolver:
2062 * The proxy resolver to use.
2069 * GRemoteActionGroupInterface:
2070 * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
2071 * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
2073 * The virtual function table for #GRemoteActionGroup.
2082 * The object that handles DNS resolution. Use g_resolver_get_default()
2083 * to get the default resolver.
2088 * GResolver::reload:
2089 * @resolver: a #GResolver
2091 * Emitted when the resolver notices that the system resolver
2092 * configuration has changed.
2097 * GSettings::change-event:
2098 * @settings: the object on which the signal was emitted
2099 * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
2100 * an array of #GQuark<!-- -->s for the changed keys, or %NULL
2101 * @n_keys: the length of the @keys array, or 0
2103 * The "change-event" signal is emitted once per change event that
2104 * affects this settings object. You should connect to this signal
2105 * only if you are interested in viewing groups of changes before they
2106 * are split out into multiple emissions of the "changed" signal.
2107 * For most use cases it is more appropriate to use the "changed" signal.
2109 * In the event that the change event applies to one or more specified
2110 * keys, @keys will be an array of #GQuark of length @n_keys. In the
2111 * event that the change event applies to the #GSettings object as a
2112 * whole (ie: potentially every key has been changed) then @keys will
2113 * be %NULL and @n_keys will be 0.
2115 * The default handler for this signal invokes the "changed" signal
2116 * for each affected key. If any other connected handler returns
2117 * %TRUE then this default functionality will be suppressed.
2119 * Returns: %TRUE to stop other handlers from being invoked for the
2120 * event. FALSE to propagate the event further.
2125 * GSettings::changed:
2126 * @settings: the object on which the signal was emitted
2127 * @key: the name of the key that changed
2129 * The "changed" signal is emitted when a key has potentially changed.
2130 * You should call one of the g_settings_get() calls to check the new
2133 * This signal supports detailed connections. You can connect to the
2134 * detailed signal "changed::x" in order to only receive callbacks
2135 * when key "x" changes.
2140 * GSettings::writable-change-event:
2141 * @settings: the object on which the signal was emitted
2142 * @key: the quark of the key, or 0
2144 * The "writable-change-event" signal is emitted once per writability
2145 * change event that affects this settings object. You should connect
2146 * to this signal if you are interested in viewing groups of changes
2147 * before they are split out into multiple emissions of the
2148 * "writable-changed" signal. For most use cases it is more
2149 * appropriate to use the "writable-changed" signal.
2151 * In the event that the writability change applies only to a single
2152 * key, @key will be set to the #GQuark for that key. In the event
2153 * that the writability change affects the entire settings object,
2156 * The default handler for this signal invokes the "writable-changed"
2157 * and "changed" signals for each affected key. This is done because
2158 * changes in writability might also imply changes in value (if for
2159 * example, a new mandatory setting is introduced). If any other
2160 * connected handler returns %TRUE then this default functionality
2161 * will be suppressed.
2163 * Returns: %TRUE to stop other handlers from being invoked for the
2164 * event. FALSE to propagate the event further.
2169 * GSettings::writable-changed:
2170 * @settings: the object on which the signal was emitted
2173 * The "writable-changed" signal is emitted when the writability of a
2174 * key has potentially changed. You should call
2175 * g_settings_is_writable() in order to determine the new status.
2177 * This signal supports detailed connections. You can connect to the
2178 * detailed signal "writable-changed::x" in order to only receive
2179 * callbacks when the writability of "x" changes.
2184 * GSettings:context:
2186 * The name of the context that the settings are stored in.
2191 * GSettings:delay-apply:
2193 * Whether the #GSettings object is in 'delay-apply' mode. See
2194 * g_settings_delay() for details.
2201 * GSettings:has-unapplied:
2203 * If this property is %TRUE, the #GSettings object has outstanding
2204 * changes that will be applied when g_settings_apply() is called.
2211 * The path within the backend where the settings are stored.
2218 * The name of the schema that describes the types of keys
2219 * for this #GSettings object.
2221 * The type of this property is *not* #GSettingsSchema.
2222 * #GSettingsSchema has only existed since version 2.32 and
2223 * unfortunately this name was used in previous versions to refer to
2224 * the schema ID rather than the schema itself. Take care to use the
2225 * 'settings-schema' property if you wish to pass in a
2228 * Deprecated: 2.32: Use the 'schema-id' property instead. In a future
2229 * version, this property may instead refer to a #GSettingsSchema.
2234 * GSettings:schema-id:
2236 * The name of the schema that describes the types of keys
2237 * for this #GSettings object.
2242 * GSettings:settings-schema:
2244 * The #GSettingsSchema describing the types of keys for this
2245 * #GSettings object.
2247 * Ideally, this property would be called 'schema'. #GSettingsSchema
2248 * has only existed since version 2.32, however, and before then the
2249 * 'schema' property was used to refer to the ID of the schema rather
2250 * than the schema itself. Take care.
2257 * This is an opaque structure type. You may not access it directly.
2264 * GSettingsSchemaSource:
2266 * This is an opaque structure type. You may not access it directly.
2273 * GSimpleAction::activate:
2274 * @simple: the #GSimpleAction
2275 * @parameter: (allow-none): the parameter to the activation
2277 * Indicates that the action was just activated.
2279 * @parameter will always be of the expected type. In the event that
2280 * an incorrect type was given, no signal will be emitted.
2287 * GSimpleAction::change-state:
2288 * @simple: the #GSimpleAction
2289 * @value: (allow-none): the requested value for the state
2291 * Indicates that the action just received a request to change its
2294 * @value will always be of the correct state type. In the event that
2295 * an incorrect type was given, no signal will be emitted.
2297 * If no handler is connected to this signal then the default
2298 * behaviour is to call g_simple_action_set_state() to set the state
2299 * to the requested value. If you connect a signal handler then no
2300 * default action is taken. If the state should change then you must
2301 * call g_simple_action_set_state() from the handler.
2304 * <title>Example 'change-state' handler</title>
2307 * change_volume_state (GSimpleAction *action,
2309 * gpointer user_data)
2313 * requested = g_variant_get_int32 (value);
2315 * // Volume only goes from 0 to 10
2316 * if (0 <= requested && requested <= 10)
2317 * g_simple_action_set_state (action, value);
2322 * The handler need not set the state to the requested value. It
2323 * could set it to any value at all, or take some other action.
2330 * GSimpleAction:enabled:
2332 * If @action is currently enabled.
2334 * If the action is disabled then calls to g_action_activate() and
2335 * g_action_change_state() have no effect.
2342 * GSimpleAction:name:
2344 * The name of the action. This is mostly meaningful for identifying
2345 * the action once it has been added to a #GSimpleActionGroup.
2352 * GSimpleAction:parameter-type:
2354 * The type of the parameter that must be given when activating the
2362 * GSimpleAction:state:
2364 * The state of the action, or %NULL if the action is stateless.
2371 * GSimpleAction:state-type:
2373 * The #GVariantType of the state that the action has, or %NULL if the
2374 * action is stateless.
2381 * GSimplePermission:
2383 * #GSimplePermission is an opaque data structure. There are no methods
2384 * except for those defined by #GPermission.
2389 * GSimpleProxyResolver:default-proxy:
2391 * The default proxy URI that will be used for any URI that doesn't
2392 * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any
2393 * of the schemes set with g_simple_proxy_resolver_set_uri_proxy().
2395 * Note that as a special case, if this URI starts with
2396 * "<literal>socks://</literal>", #GSimpleProxyResolver will treat
2397 * it as referring to all three of the <literal>socks5</literal>,
2398 * <literal>socks4a</literal>, and <literal>socks4</literal> proxy
2404 * GSimpleProxyResolver:ignore-hosts:
2406 * A list of hostnames and IP addresses that the resolver should
2407 * allow direct connections to.
2409 * Entries can be in one of 4 formats:
2413 * A hostname, such as "<literal>example.com</literal>",
2414 * "<literal>.example.com</literal>", or
2415 * "<literal>*.example.com</literal>", any of which match
2416 * "<literal>example.com</literal>" or any subdomain of it.
2419 * An IPv4 or IPv6 address, such as
2420 * "<literal>192.168.1.1</literal>", which matches only
2424 * A hostname or IP address followed by a port, such as
2425 * "<literal>example.com:80</literal>", which matches whatever
2426 * the hostname or IP address would match, but only for URLs
2427 * with the (explicitly) indicated port. In the case of an IPv6
2428 * address, the address part must appear in brackets:
2429 * "<literal>[::1]:443</literal>"
2432 * An IP address range, given by a base address and prefix length,
2433 * such as "<literal>fe80::/10</literal>", which matches any
2434 * address in that range.
2438 * Note that when dealing with Unicode hostnames, the matching is
2439 * done against the ASCII form of the name.
2441 * Also note that hostname exclusions apply only to connections made
2442 * to hosts identified by name, and IP address exclusions apply only
2443 * to connections made to hosts identified by address. That is, if
2444 * <literal>example.com</literal> has an address of
2445 * <literal>192.168.1.1</literal>, and the :ignore-hosts list
2446 * contains only "<literal>192.168.1.1</literal>", then a connection
2447 * to "<literal>example.com</literal>" (eg, via a #GNetworkAddress)
2448 * will use the proxy, and a connection to
2449 * "<literal>192.168.1.1</literal>" (eg, via a #GInetSocketAddress)
2452 * These rules match the "ignore-hosts"/"noproxy" rules most
2453 * commonly used by other applications.
2458 * GSocket:broadcast:
2460 * Whether the socket should allow sending to broadcast addresses.
2467 * GSocket:multicast-loopback:
2469 * Whether outgoing multicast packets loop back to the local host.
2476 * GSocket:multicast-ttl:
2478 * Time-to-live out outgoing multicast packets
2487 * The timeout in seconds on socket I/O
2496 * Time-to-live for outgoing unicast packets
2505 * A socket endpoint address, corresponding to <type>struct sockaddr</type>
2506 * or one of its subtypes.
2511 * GSocketClient::event:
2512 * @client: the #GSocketClient
2513 * @event: the event that is occurring
2514 * @connectable: the #GSocketConnectable that @event is occurring on
2515 * @connection: the current representation of the connection
2517 * Emitted when @client's activity on @connectable changes state.
2518 * Among other things, this can be used to provide progress
2519 * information about a network connection in the UI. The meanings of
2520 * the different @event values are as follows:
2524 * <term>%G_SOCKET_CLIENT_RESOLVING:</term>
2526 * @client is about to look up @connectable in DNS.
2527 * @connection will be %NULL.
2528 * </para></listitem>
2531 * <term>%G_SOCKET_CLIENT_RESOLVED:</term>
2533 * @client has successfully resolved @connectable in DNS.
2534 * @connection will be %NULL.
2535 * </para></listitem>
2538 * <term>%G_SOCKET_CLIENT_CONNECTING:</term>
2540 * @client is about to make a connection to a remote host;
2541 * either a proxy server or the destination server itself.
2542 * @connection is the #GSocketConnection, which is not yet
2544 * </para></listitem>
2547 * <term>%G_SOCKET_CLIENT_CONNECTED:</term>
2549 * @client has successfully connected to a remote host.
2550 * @connection is the connected #GSocketConnection.
2551 * </para></listitem>
2554 * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
2556 * @client is about to negotiate with a proxy to get it to
2557 * connect to @connectable. @connection is the
2558 * #GSocketConnection to the proxy server.
2559 * </para></listitem>
2562 * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
2564 * @client has negotiated a connection to @connectable through
2565 * a proxy server. @connection is the stream returned from
2566 * g_proxy_connect(), which may or may not be a
2567 * #GSocketConnection.
2568 * </para></listitem>
2571 * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
2573 * @client is about to begin a TLS handshake. @connection is a
2574 * #GTlsClientConnection.
2575 * </para></listitem>
2578 * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
2580 * @client has successfully completed the TLS handshake.
2581 * @connection is a #GTlsClientConnection.
2582 * </para></listitem>
2585 * <term>%G_SOCKET_CLIENT_COMPLETE:</term>
2587 * @client has either successfully connected to @connectable
2588 * (in which case @connection is the #GSocketConnection that
2589 * it will be returning to the caller) or has failed (in which
2590 * case @connection is %NULL and the client is about to return
2592 * </para></listitem>
2596 * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
2597 * multiple times (or not at all) for a given connectable (in
2598 * particular, if @client ends up attempting to connect to more than
2599 * one address). However, if @client emits the #GSocketClient::event
2600 * signal at all for a given connectable, that it will always emit
2601 * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
2603 * Note that there may be additional #GSocketClientEvent values in
2604 * the future; unrecognized @event values should be ignored.
2611 * GSocketClient:proxy-resolver:
2613 * The proxy resolver to use
2620 * GSocketService::incoming:
2621 * @service: the #GSocketService
2622 * @connection: a new #GSocketConnection object
2623 * @source_object: (allow-none): the source_object passed to
2624 * g_socket_listener_add_address()
2626 * The ::incoming signal is emitted when a new incoming connection
2627 * to @service needs to be handled. The handler must initiate the
2628 * handling of @connection, but may not block; in essence,
2629 * asynchronous operations must be used.
2631 * @connection will be unreffed once the signal handler returns,
2632 * so you need to ref it yourself if you are planning to use it.
2634 * Returns: %TRUE to stop other handlers from being called
2642 * A single target host/port that a network service is running on.
2649 * The opaque object representing a synchronous or asynchronous task
2657 * @source_object: (type GObject): @task's source object
2658 * @task_data: @task's task data
2659 * @cancellable: @task's #GCancellable, or %NULL
2661 * The prototype for a task function to be run in a thread via
2662 * g_task_run_in_thread() or g_task_run_in_thread_sync().
2664 * If the return-on-cancel flag is set on @task, and @cancellable gets
2665 * cancelled, then the #GTask will be completed immediately (as though
2666 * g_task_return_error_if_cancelled() had been called), without
2667 * waiting for the task function to complete. However, the task
2668 * function will continue running in its thread in the background. The
2669 * function therefore needs to be careful about how it uses
2670 * externally-visible state in this case. See
2671 * g_task_set_return_on_cancel() for more details.
2673 * Other than in that case, @task will be completed when the
2674 * #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls
2675 * a <literal>g_task_return_</literal> function.
2684 * The #GTestDBus structure contains only private data and
2685 * should only be accessed using the provided API.
2694 * #GTestDBusFlags specifying the behaviour of the dbus session
2708 * GThemedIcon:names:
2710 * A %NULL-terminated array of icon names.
2715 * GThemedIcon:use-default-fallbacks:
2717 * Whether to use the default fallbacks found by shortening the icon name
2718 * at '-' characters. If the "names" array has more than one element,
2719 * ignores any past the first.
2721 * For example, if the icon name was "gnome-dev-cdrom-audio", the array
2725 * "gnome-dev-cdrom-audio",
2726 * "gnome-dev-cdrom",
2736 * GThreadedSocketService::run:
2737 * @service: the #GThreadedSocketService.
2738 * @connection: a new #GSocketConnection object.
2739 * @source_object: the source_object passed to g_socket_listener_add_address().
2741 * The ::run signal is emitted in a worker thread in response to an
2742 * incoming connection. This thread is dedicated to handling
2743 * @connection and may perform blocking IO. The signal handler need
2744 * not return until the connection is closed.
2746 * Returns: %TRUE to stop further signal handlers from being called
2753 * TLS (Transport Layer Security, aka SSL) backend. This is an
2754 * internal type used to coordinate the different classes implemented
2764 * Abstract base class for TLS certificate types.
2771 * GTlsCertificate:certificate:
2773 * The DER (binary) encoded representation of the certificate.
2774 * This property and the #GTlsCertificate:certificate-pem property
2775 * represent the same data, just in different forms.
2782 * GTlsCertificate:certificate-pem:
2784 * The PEM (ASCII) encoded representation of the certificate.
2785 * This property and the #GTlsCertificate:certificate
2786 * property represent the same data, just in different forms.
2793 * GTlsCertificate:issuer:
2795 * A #GTlsCertificate representing the entity that issued this
2796 * certificate. If %NULL, this means that the certificate is either
2797 * self-signed, or else the certificate of the issuer is not
2805 * GTlsCertificate:private-key:
2807 * The DER (binary) encoded representation of the certificate's
2808 * private key, in either PKCS#1 format or unencrypted PKCS#8
2809 * format. This property (or the #GTlsCertificate:private-key-pem
2810 * property) can be set when constructing a key (eg, from a file),
2811 * but cannot be read.
2813 * PKCS#8 format is supported since 2.32; earlier releases only
2814 * support PKCS#1. You can use the <literal>openssl rsa</literal>
2815 * tool to convert PKCS#8 keys to PKCS#1.
2822 * GTlsCertificate:private-key-pem:
2824 * The PEM (ASCII) encoded representation of the certificate's
2825 * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE
2826 * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN
2827 * PRIVATE KEY</literal>"). This property (or the
2828 * #GTlsCertificate:private-key property) can be set when
2829 * constructing a key (eg, from a file), but cannot be read.
2831 * PKCS#8 format is supported since 2.32; earlier releases only
2832 * support PKCS#1. You can use the <literal>openssl rsa</literal>
2833 * tool to convert PKCS#8 keys to PKCS#1.
2840 * GTlsClientConnection:
2842 * Abstract base class for the backend-specific client connection
2850 * GTlsClientConnection:accepted-cas:
2852 * A list of the distinguished names of the Certificate Authorities
2853 * that the server will accept client certificates signed by. If the
2854 * server requests a client certificate during the handshake, then
2855 * this property will be set after the handshake completes.
2857 * Each item in the list is a #GByteArray which contains the complete
2858 * subject DN of the certificate authority.
2865 * GTlsClientConnection:server-identity:
2867 * A #GSocketConnectable describing the identity of the server that
2868 * is expected on the other end of the connection.
2870 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
2871 * #GTlsClientConnection:validation-flags, this object will be used
2872 * to determine the expected identify of the remote end of the
2873 * connection; if #GTlsClientConnection:server-identity is not set,
2874 * or does not match the identity presented by the server, then the
2875 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
2877 * In addition to its use in verifying the server certificate,
2878 * this is also used to give a hint to the server about what
2879 * certificate we expect, which is useful for servers that serve
2887 * GTlsClientConnection:use-ssl3:
2889 * If %TRUE, tells the connection to use SSL 3.0 rather than trying
2890 * to negotiate the best version of TLS or SSL to use. This can be
2891 * used when talking to servers that don't implement version
2892 * negotiation correctly and therefore refuse to handshake at all with
2893 * a "modern" TLS handshake.
2900 * GTlsClientConnection:validation-flags:
2902 * What steps to perform when validating a certificate received from
2903 * a server. Server certificates that fail to validate in all of the
2904 * ways indicated here will be rejected unless the application
2905 * overrides the default via #GTlsConnection::accept-certificate.
2914 * Abstract base class for the backend-specific #GTlsClientConnection
2915 * and #GTlsServerConnection types.
2922 * GTlsConnection::accept-certificate:
2923 * @conn: a #GTlsConnection
2924 * @peer_cert: the peer's #GTlsCertificate
2925 * @errors: the problems with @peer_cert.
2927 * Emitted during the TLS handshake after the peer certificate has
2928 * been received. You can examine @peer_cert's certification path by
2929 * calling g_tls_certificate_get_issuer() on it.
2931 * For a client-side connection, @peer_cert is the server's
2932 * certificate, and the signal will only be emitted if the
2933 * certificate was not acceptable according to @conn's
2934 * #GTlsClientConnection:validation_flags. If you would like the
2935 * certificate to be accepted despite @errors, return %TRUE from the
2936 * signal handler. Otherwise, if no handler accepts the certificate,
2937 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
2939 * For a server-side connection, @peer_cert is the certificate
2940 * presented by the client, if this was requested via the server's
2941 * #GTlsServerConnection:authentication_mode. On the server side,
2942 * the signal is always emitted when the client presents a
2943 * certificate, and the certificate will only be accepted if a
2944 * handler returns %TRUE.
2946 * Note that if this signal is emitted as part of asynchronous I/O
2947 * in the main thread, then you should not attempt to interact with
2948 * the user before returning from the signal handler. If you want to
2949 * let the user decide whether or not to accept the certificate, you
2950 * would have to return %FALSE from the signal handler on the first
2951 * attempt, and then after the connection attempt returns a
2952 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
2953 * the user decides to accept the certificate, remember that fact,
2954 * create a new connection, and return %TRUE from the signal handler
2957 * If you are doing I/O in another thread, you do not
2958 * need to worry about this, and can simply block in the signal
2959 * handler until the UI thread returns an answer.
2961 * Returns: %TRUE to accept @peer_cert (which will also
2962 * immediately end the signal emission). %FALSE to allow the signal
2963 * emission to continue, which will cause the handshake to fail if
2964 * no one else overrides it.
2970 * GTlsConnection:base-io-stream:
2972 * The #GIOStream that the connection wraps
2979 * GTlsConnection:certificate:
2981 * The connection's certificate; see
2982 * g_tls_connection_set_certificate().
2989 * GTlsConnection:database:
2991 * The certificate database to use when verifying this TLS connection.
2992 * If no cerificate database is set, then the default database will be
2993 * used. See g_tls_backend_get_default_database().
3000 * GTlsConnection:interaction:
3002 * A #GTlsInteraction object to be used when the connection or certificate
3003 * database need to interact with the user. This will be used to prompt the
3004 * user for passwords where necessary.
3011 * GTlsConnection:peer-certificate:
3013 * The connection's peer's certificate, after the TLS handshake has
3014 * completed and the certificate has been accepted. Note in
3015 * particular that this is not yet set during the emission of
3016 * #GTlsConnection::accept-certificate.
3018 * (You can watch for a #GObject::notify signal on this property to
3019 * detect when a handshake has occurred.)
3026 * GTlsConnection:peer-certificate-errors:
3028 * The errors noticed-and-ignored while verifying
3029 * #GTlsConnection:peer-certificate. Normally this should be 0, but
3030 * it may not be if #GTlsClientConnection:validation-flags is not
3031 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
3032 * #GTlsConnection::accept-certificate overrode the default
3040 * GTlsConnection:rehandshake-mode:
3042 * The rehandshaking mode. See
3043 * g_tls_connection_set_rehandshake_mode().
3050 * GTlsConnection:require-close-notify:
3052 * Whether or not proper TLS close notification is required.
3053 * See g_tls_connection_set_require_close_notify().
3060 * GTlsConnection:use-system-certdb:
3062 * Whether or not the system certificate database will be used to
3063 * verify peer certificates. See
3064 * g_tls_connection_set_use_system_certdb().
3066 * Deprecated: 2.30: Use GTlsConnection:database instead
3073 * Abstract base class for the backend-specific database types.
3082 * Implemented by a #GTlsDatabase which allows you to load certificates
3090 * GTlsFileDatabase:anchors:
3092 * The path to a file containing PEM encoded certificate authority
3093 * root anchors. The certificates in this file will be treated as
3094 * root authorities for the purpose of verifying other certificates
3095 * via the g_tls_database_verify_chain() operation.
3104 * An object representing interaction that the TLS connection and database
3105 * might have with the user.
3112 * GTlsInteractionClass:
3113 * @ask_password: ask for a password synchronously. If the implementation
3114 * returns %G_TLS_INTERACTION_HANDLED, then the password argument should
3115 * have been filled in by using g_tls_password_set_value() or a similar
3117 * @ask_password_async: ask for a password asynchronously.
3118 * @ask_password_finish: complete operation to ask for a password asynchronously.
3119 * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the
3120 * password argument of the async method should have been filled in by using
3121 * g_tls_password_set_value() or a similar function.
3123 * The class for #GTlsInteraction. Derived classes implement the various
3124 * virtual interaction methods to handle TLS interactions.
3126 * Derived classes can choose to implement whichever interactions methods they'd
3127 * like to support by overriding those virtual methods in their class
3128 * initialization function. If a derived class implements an async method,
3129 * it must also implement the corresponding finish method.
3131 * The synchronous interaction methods should implement to display modal dialogs,
3132 * and the asynchronous methods to display modeless dialogs.
3134 * If the user cancels an interaction, then the result should be
3135 * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
3136 * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
3145 * An abstract interface representing a password used in TLS. Often used in
3146 * user interaction such as unlocking a key storage token.
3153 * GTlsServerConnection:authentication-mode:
3155 * The #GTlsAuthenticationMode for the server. This can be changed
3156 * before calling g_tls_connection_handshake() if you want to
3157 * rehandshake with a different mode from the initial handshake.
3164 * GUnixCredentialsMessage:credentials:
3166 * The credentials stored in the message.
3173 * GUnixInputStream:close-fd:
3175 * Whether to close the file descriptor when the stream is closed.
3182 * GUnixInputStream:fd:
3184 * The file descriptor that the stream reads from.
3191 * GUnixMountMonitor::mountpoints-changed:
3192 * @monitor: the object on which the signal is emitted
3194 * Emitted when the unix mount points have changed.
3199 * GUnixMountMonitor::mounts-changed:
3200 * @monitor: the object on which the signal is emitted
3202 * Emitted when the unix mounts have changed.
3207 * GUnixOutputStream:close-fd:
3209 * Whether to close the file descriptor when the stream is closed.
3216 * GUnixOutputStream:fd:
3218 * The file descriptor that the stream writes to.
3225 * GUnixSocketAddress:
3227 * A UNIX-domain (local) socket address, corresponding to a
3228 * <type>struct sockaddr_un</type>.
3233 * GUnixSocketAddress:abstract:
3235 * Whether or not this is an abstract address
3237 * Deprecated: Use #GUnixSocketAddress:address-type, which
3238 * distinguishes between zero-padded and non-zero-padded
3239 * abstract addresses.
3246 * Emitted when the volume has been changed.
3253 * This signal is emitted when the #GVolume have been removed. If
3254 * the recipient is holding references to the object they should
3255 * release them so the object can be finalized.
3260 * GVolumeMonitor::drive-changed:
3261 * @volume_monitor: The volume monitor emitting the signal.
3262 * @drive: the drive that changed
3264 * Emitted when a drive changes.
3269 * GVolumeMonitor::drive-connected:
3270 * @volume_monitor: The volume monitor emitting the signal.
3271 * @drive: a #GDrive that was connected.
3273 * Emitted when a drive is connected to the system.
3278 * GVolumeMonitor::drive-disconnected:
3279 * @volume_monitor: The volume monitor emitting the signal.
3280 * @drive: a #GDrive that was disconnected.
3282 * Emitted when a drive is disconnected from the system.
3287 * GVolumeMonitor::drive-eject-button:
3288 * @volume_monitor: The volume monitor emitting the signal.
3289 * @drive: the drive where the eject button was pressed
3291 * Emitted when the eject button is pressed on @drive.
3298 * GVolumeMonitor::drive-stop-button:
3299 * @volume_monitor: The volume monitor emitting the signal.
3300 * @drive: the drive where the stop button was pressed
3302 * Emitted when the stop button is pressed on @drive.
3309 * GVolumeMonitor::mount-added:
3310 * @volume_monitor: The volume monitor emitting the signal.
3311 * @mount: a #GMount that was added.
3313 * Emitted when a mount is added.
3318 * GVolumeMonitor::mount-changed:
3319 * @volume_monitor: The volume monitor emitting the signal.
3320 * @mount: a #GMount that changed.
3322 * Emitted when a mount changes.
3327 * GVolumeMonitor::mount-pre-unmount:
3328 * @volume_monitor: The volume monitor emitting the signal.
3329 * @mount: a #GMount that is being unmounted.
3331 * Emitted when a mount is about to be removed.
3336 * GVolumeMonitor::mount-removed:
3337 * @volume_monitor: The volume monitor emitting the signal.
3338 * @mount: a #GMount that was removed.
3340 * Emitted when a mount is removed.
3345 * GVolumeMonitor::volume-added:
3346 * @volume_monitor: The volume monitor emitting the signal.
3347 * @volume: a #GVolume that was added.
3349 * Emitted when a mountable volume is added to the system.
3354 * GVolumeMonitor::volume-changed:
3355 * @volume_monitor: The volume monitor emitting the signal.
3356 * @volume: a #GVolume that changed.
3358 * Emitted when mountable volume is changed.
3363 * GVolumeMonitor::volume-removed:
3364 * @volume_monitor: The volume monitor emitting the signal.
3365 * @volume: a #GVolume that was removed.
3367 * Emitted when a mountable volume is removed from the system.
3372 * GWin32InputStream:close-handle:
3374 * Whether to close the file handle when the stream is closed.
3381 * GWin32InputStream:handle:
3383 * The handle that the stream reads from.
3390 * GWin32OutputStream:close-handle:
3392 * Whether to close the file handle when the stream is closed.
3399 * GWin32OutputStream:handle:
3401 * The file handle that the stream writes to.
3410 * Zlib decompression
3415 * GZlibCompressor:file-info:
3417 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
3418 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
3419 * and modification time from the file info to the GZIP header.
3426 * GZlibDecompressor:
3428 * Zlib decompression
3433 * GZlibDecompressor:file-info:
3435 * A #GFileInfo containing the information found in the GZIP header
3436 * of the data stream processed, or %NULL if the header was not yet
3437 * fully processed, is not present at all, or the compressor's
3438 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
3445 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
3447 * The purpose used to verify the client certificate in a TLS connection.
3448 * Used by TLS servers.
3453 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
3455 * The purpose used to verify the server certificate in a TLS connection. This
3456 * is the most common purpose in use. Used by TLS clients.
3461 * G_TYPE_SETTINGS_SCHEMA:
3463 * A boxed #GType corresponding to #GSettingsSchema.
3470 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
3472 * A boxed #GType corresponding to #GSettingsSchemaSource.
3479 * SECTION:_GFreedesktopDBus
3480 * @title: _GFreedesktopDBus
3481 * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface
3483 * 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.
3488 * SECTION:extensionpoints
3489 * @short_description: Extension Points
3491 * @see_also: <link linkend="extending-gio">Extending GIO</link>
3493 * #GIOExtensionPoint provides a mechanism for modules to extend the
3494 * functionality of the library or application that loaded it in an
3495 * organized fashion.
3497 * An extension point is identified by a name, and it may optionally
3498 * require that any implementation must by of a certain type (or derived
3499 * thereof). Use g_io_extension_point_register() to register an
3500 * extension point, and g_io_extension_point_set_required_type() to
3501 * set a required type.
3503 * A module can implement an extension point by specifying the #GType
3504 * that implements the functionality. Additionally, each implementation
3505 * of an extension point has a name, and a priority. Use
3506 * g_io_extension_point_implement() to implement an extension point.
3509 * GIOExtensionPoint *ep;
3511 * /* Register an extension point */
3512 * ep = g_io_extension_point_register ("my-extension-point");
3513 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
3517 * /* Implement an extension point */
3518 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
3519 * g_io_extension_point_implement ("my-extension-point",
3520 * my_example_impl_get_type (),
3525 * It is up to the code that registered the extension point how
3526 * it uses the implementations that have been associated with it.
3527 * Depending on the use case, it may use all implementations, or
3528 * only the one with the highest priority, or pick a specific
3531 * To avoid opening all modules just to find out what extension
3532 * points they implement, GIO makes use of a caching mechanism,
3533 * see <link linkend="gio-querymodules">gio-querymodules</link>.
3534 * You are expected to run this command after installing a
3537 * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be
3538 * used to specify additional directories to automatically load modules
3539 * from. This environment variable has the same syntax as the
3540 * <envar>PATH</envar>. If two modules have the same base name in different
3541 * directories, then the latter one will be ignored. If additional
3542 * directories are specified GIO will load modules from the built-in
3550 * @short_description: An action interface
3552 * #GAction represents a single named action.
3554 * The main interface to an action is that it can be activated with
3555 * g_action_activate(). This results in the 'activate' signal being
3556 * emitted. An activation has a #GVariant parameter (which may be
3557 * %NULL). The correct type for the parameter is determined by a static
3558 * parameter type (which is given at construction time).
3560 * An action may optionally have a state, in which case the state may be
3561 * set with g_action_change_state(). This call takes a #GVariant. The
3562 * correct type for the state is determined by a static state type
3563 * (which is given at construction time).
3565 * The state may have a hint associated with it, specifying its valid
3568 * #GAction is merely the interface to the concept of an action, as
3569 * described above. Various implementations of actions exist, including
3570 * #GSimpleAction and #GtkAction.
3572 * In all cases, the implementing class is responsible for storing the
3573 * name of the action, the parameter type, the enabled state, the
3574 * optional state type and the state and emitting the appropriate
3575 * signals when these change. The implementor responsible for filtering
3576 * calls to g_action_activate() and g_action_change_state() for type
3577 * safety and for the state being enabled.
3579 * Probably the only useful thing to do with a #GAction is to put it
3580 * inside of a #GSimpleActionGroup.
3585 * SECTION:gactiongroup
3586 * @title: GActionGroup
3587 * @short_description: A group of actions
3588 * @see_also: #GAction
3590 * #GActionGroup represents a group of actions. Actions can be used to
3591 * expose functionality in a structured way, either from one part of a
3592 * program to another, or to the outside world. Action groups are often
3593 * used together with a #GMenuModel that provides additional
3594 * representation data for displaying the actions to the user, e.g. in
3597 * The main way to interact with the actions in a GActionGroup is to
3598 * activate them with g_action_group_activate_action(). Activating an
3599 * action may require a #GVariant parameter. The required type of the
3600 * parameter can be inquired with g_action_group_get_action_parameter_type().
3601 * Actions may be disabled, see g_action_group_get_action_enabled().
3602 * Activating a disabled action has no effect.
3604 * Actions may optionally have a state in the form of a #GVariant. The
3605 * current state of an action can be inquired with
3606 * g_action_group_get_action_state(). Activating a stateful action may
3607 * change its state, but it is also possible to set the state by calling
3608 * g_action_group_change_action_state().
3610 * As typical example, consider a text editing application which has an
3611 * option to change the current font to 'bold'. A good way to represent
3612 * this would be a stateful action, with a boolean state. Activating the
3613 * action would toggle the state.
3615 * Each action in the group has a unique name (which is a string). All
3616 * method calls, except g_action_group_list_actions() take the name of
3617 * an action as an argument.
3619 * The #GActionGroup API is meant to be the 'public' API to the action
3620 * group. The calls here are exactly the interaction that 'external
3621 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
3622 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
3623 * the action group implementation) are found on subclasses. This is
3624 * why you will find - for example - g_action_group_get_action_enabled()
3625 * but not an equivalent <function>set()</function> call.
3627 * Signals are emitted on the action group in response to state changes
3628 * on individual actions.
3630 * Implementations of #GActionGroup should provide implementations for
3631 * the virtual functions g_action_group_list_actions() and
3632 * g_action_group_query_action(). The other virtual functions should
3633 * not be implemented - their "wrappers" are actually implemented with
3634 * calls to g_action_group_query_action().
3639 * SECTION:gactiongroupexporter
3640 * @title: GActionGroup exporter
3641 * @short_description: Export GActionGroups on D-Bus
3642 * @see_also: #GActionGroup, #GDBusActionGroup
3644 * These functions support exporting a #GActionGroup on D-Bus.
3645 * The D-Bus interface that is used is a private implementation
3648 * To access an exported #GActionGroup remotely, use
3649 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
3654 * SECTION:gactionmap
3655 * @title: GActionMap
3656 * @short_description: Interface for action containers
3658 * The GActionMap interface is implemented by #GActionGroup
3659 * implementations that operate by containing a number of
3660 * named #GAction instances, such as #GSimpleActionGroup.
3662 * One useful application of this interface is to map the
3663 * names of actions from various action groups to unique,
3664 * prefixed names (e.g. by prepending "app." or "win.").
3665 * This is the motivation for the 'Map' part of the interface
3674 * @short_description: Application information and launch contexts
3675 * @include: gio/gio.h
3676 * @see_also: #GAppInfoMonitor
3678 * #GAppInfo and #GAppLaunchContext are used for describing and launching
3679 * applications installed on the system.
3681 * As of GLib 2.20, URIs will always be converted to POSIX paths
3682 * (using g_file_get_path()) when using g_app_info_launch() even if
3683 * the application requested an URI and not a POSIX path. For example
3684 * for an desktop-file based application with Exec key <literal>totem
3685 * %U</literal> and a single URI,
3686 * <literal>sftp://foo/file.avi</literal>, then
3687 * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
3688 * passed. This will only work if a set of suitable GIO extensions
3689 * (such as gvfs 2.26 compiled with FUSE support), is available and
3690 * operational; if this is not the case, the URI will be passed
3691 * unmodified to the application. Some URIs, such as
3692 * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
3693 * path (in gvfs there's no FUSE mount for it); such URIs will be
3694 * passed unmodified to the application.
3696 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
3697 * back to the GIO URI in the #GFile constructors (since gvfs
3698 * implements the #GVfs extension point). As such, if the application
3699 * needs to examine the URI, it needs to use g_file_get_uri() or
3700 * similar on #GFile. In other words, an application cannot assume
3701 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
3702 * equal to the result of g_file_get_uri(). The following snippet
3709 * file = g_file_new_for_commandline_arg (uri_from_commandline);
3711 * uri = g_file_get_uri (file);
3712 * strcmp (uri, uri_from_commandline) == 0; // FALSE
3715 * if (g_file_has_uri_scheme (file, "cdda"))
3717 * // do something special with uri
3719 * g_object_unref (file);
3722 * This code will work when both <literal>cdda://sr0/Track
3723 * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
3724 * 1.wav</literal> is passed to the application. It should be noted
3725 * that it's generally not safe for applications to rely on the format
3726 * of a particular URIs. Different launcher applications (e.g. file
3727 * managers) may have different ideas of what a given URI means.
3732 * SECTION:gappinfomonitor
3733 * @short_description: Monitor application information for changes
3735 * #GAppInfoMonitor is a very simple object used for monitoring the app
3736 * info database for changes (ie: newly installed or removed
3739 * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
3740 * to the "changed" signal.
3742 * In the usual case, applications should try to make note of the change
3743 * (doing things like invalidating caches) but not act on it. In
3744 * particular, applications should avoid making calls to #GAppInfo APIs
3745 * in response to the change signal, deferring these until the time that
3746 * the data is actually required. The exception to this case is when
3747 * application information is actually being displayed on the screen
3748 * (eg: during a search or when the list of all applications is shown).
3749 * The reason for this is that changes to the list of installed
3750 * applications often come in groups (like during system updates) and
3751 * rescanning the list on every change is pointless and expensive.
3758 * SECTION:gapplication
3759 * @title: GApplication
3760 * @short_description: Core application class
3762 * A #GApplication is the foundation of an application. It wraps some
3763 * low-level platform-specific services and is intended to act as the
3764 * foundation for higher-level application classes such as
3765 * #GtkApplication or #MxApplication. In general, you should not use
3766 * this class outside of a higher level framework.
3768 * GApplication provides convenient life cycle management by maintaining
3769 * a <firstterm>use count</firstterm> for the primary application instance.
3770 * The use count can be changed using g_application_hold() and
3771 * g_application_release(). If it drops to zero, the application exits.
3772 * Higher-level classes such as #GtkApplication employ the use count to
3773 * ensure that the application stays alive as long as it has any opened
3776 * Another feature that GApplication (optionally) provides is process
3777 * uniqueness. Applications can make use of this functionality by
3778 * providing a unique application ID. If given, only one application
3779 * with this ID can be running at a time per session. The session
3780 * concept is platform-dependent, but corresponds roughly to a graphical
3781 * desktop login. When your application is launched again, its
3782 * arguments are passed through platform communication to the already
3783 * running program. The already running instance of the program is
3784 * called the <firstterm>primary instance</firstterm>; for non-unique
3785 * applications this is the always the current instance.
3786 * On Linux, the D-Bus session bus is used for communication.
3788 * The use of #GApplication differs from some other commonly-used
3789 * uniqueness libraries (such as libunique) in important ways. The
3790 * application is not expected to manually register itself and check if
3791 * it is the primary instance. Instead, the <code>main()</code>
3792 * function of a #GApplication should do very little more than
3793 * instantiating the application instance, possibly connecting signal
3794 * handlers, then calling g_application_run(). All checks for
3795 * uniqueness are done internally. If the application is the primary
3796 * instance then the startup signal is emitted and the mainloop runs.
3797 * If the application is not the primary instance then a signal is sent
3798 * to the primary instance and g_application_run() promptly returns.
3799 * See the code examples below.
3801 * If used, the expected form of an application identifier is very close
3803 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
3804 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
3805 * For details on valid application identifiers, see g_application_id_is_valid().
3807 * On Linux, the application identifier is claimed as a well-known bus name
3808 * on the user's session bus. This means that the uniqueness of your
3809 * application is scoped to the current session. It also means that your
3810 * application may provide additional services (through registration of other
3811 * object paths) at that bus name. The registration of these object paths
3812 * should be done with the shared GDBus session bus. Note that due to the
3813 * internal architecture of GDBus, method calls can be dispatched at any time
3814 * (even if a main loop is not running). For this reason, you must ensure that
3815 * any object paths that you wish to register are registered before #GApplication
3816 * attempts to acquire the bus name of your application (which happens in
3817 * g_application_register()). Unfortunately, this means that you cannot use
3818 * g_application_get_is_remote() to decide if you want to register object paths.
3820 * GApplication also implements the #GActionGroup and #GActionMap
3821 * interfaces and lets you easily export actions by adding them with
3822 * g_action_map_add_action(). When invoking an action by calling
3823 * g_action_group_activate_action() on the application, it is always
3824 * invoked in the primary instance. The actions are also exported on
3825 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
3826 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
3827 * for remote access to exported #GMenuModels.
3829 * There is a number of different entry points into a GApplication:
3831 * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
3832 * <listitem>via 'Open' (i.e. opening some files)</listitem>
3833 * <listitem>by handling a command-line</listitem>
3834 * <listitem>via activating an action</listitem>
3836 * The #GApplication::startup signal lets you handle the application
3837 * initialization for all of these in a single place.
3839 * Regardless of which of these entry points is used to start the application,
3840 * GApplication passes some <firstterm id="platform-data">platform
3841 * data</firstterm> from the launching instance to the primary instance,
3842 * in the form of a #GVariant dictionary mapping strings to variants.
3843 * To use platform data, override the @before_emit or @after_emit virtual
3844 * functions in your #GApplication subclass. When dealing with
3845 * #GApplicationCommandLine objects, the platform data is directly
3846 * available via g_application_command_line_get_cwd(),
3847 * g_application_command_line_get_environ() and
3848 * g_application_command_line_get_platform_data().
3850 * As the name indicates, the platform data may vary depending on the
3851 * operating system, but it always includes the current directory (key
3852 * "cwd"), and optionally the environment (ie the set of environment
3853 * variables and their values) of the calling process (key "environ").
3854 * The environment is only added to the platform data if the
3855 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
3856 * can add their own platform data by overriding the @add_platform_data
3857 * virtual function. For instance, #GtkApplication adds startup notification
3860 * To parse commandline arguments you may handle the
3861 * #GApplication::command-line signal or override the local_command_line()
3862 * vfunc, to parse them in either the primary instance or the local instance,
3865 * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
3867 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c">
3868 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3873 * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
3875 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
3876 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3881 * <example id="gapplication-example-menu"><title>A GApplication with menus</title>
3883 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c">
3884 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3889 * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title>
3891 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-dbushooks.c">
3892 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3900 * SECTION:gapplicationcommandline
3901 * @title: GApplicationCommandLine
3902 * @short_description: A command-line invocation of an application
3903 * @see_also: #GApplication
3905 * #GApplicationCommandLine represents a command-line invocation of
3906 * an application. It is created by #GApplication and emitted
3907 * in the #GApplication::command-line signal and virtual function.
3909 * The class contains the list of arguments that the program was invoked
3910 * with. It is also possible to query if the commandline invocation was
3911 * local (ie: the current process is running in direct response to the
3912 * invocation) or remote (ie: some other process forwarded the
3913 * commandline to this process).
3915 * The GApplicationCommandLine object can provide the @argc and @argv
3916 * parameters for use with the #GOptionContext command-line parsing API,
3917 * with the g_application_command_line_get_arguments() function. See
3918 * <xref linkend="gapplication-example-cmdline3"/> for an example.
3920 * The exit status of the originally-invoked process may be set and
3921 * messages can be printed to stdout or stderr of that process. The
3922 * lifecycle of the originally-invoked process is tied to the lifecycle
3923 * of this object (ie: the process exits when the last reference is
3926 * The main use for #GApplicationCommandLine (and the
3927 * #GApplication::command-line signal) is 'Emacs server' like use cases:
3928 * You can set the <envar>EDITOR</envar> environment variable to have
3929 * e.g. git use your favourite editor to edit commit messages, and if you
3930 * already have an instance of the editor running, the editing will happen
3931 * in the running instance, instead of opening a new one. An important
3932 * aspect of this use case is that the process that gets started by git
3933 * does not return until the editing is done.
3935 * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
3937 * A simple example where the commandline is completely handled
3938 * in the #GApplication::command-line handler. The launching instance exits
3939 * once the signal handler in the primary instance has returned, and the
3940 * return value of the signal handler becomes the exit status of the launching
3944 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
3945 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3950 * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
3952 * An example of split commandline handling. Options that start with
3953 * <literal>--local-</literal> are handled locally, all other options are
3954 * passed to the #GApplication::command-line handler which runs in the primary
3958 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
3959 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3964 * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
3966 * An example of deferred commandline handling. Here, the commandline is
3967 * not completely handled before the #GApplication::command-line handler
3968 * returns. Instead, we keep a reference to the GApplicationCommandLine
3969 * object and handle it later(in this example, in an idle). Note that it
3970 * is necessary to hold the application until you are done with the
3974 * This example also shows how to use #GOptionContext for parsing the
3975 * commandline arguments. Note that it is necessary to disable the
3976 * built-in help-handling of #GOptionContext, since it calls exit()
3977 * after printing help, which is not what you want to happen in
3978 * the primary instance.
3981 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
3982 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
3990 * SECTION:gasyncinitable
3991 * @short_description: Asynchronously failable object initialization interface
3992 * @include: gio/gio.h
3993 * @see_also: #GInitable
3995 * This is the asynchronous version of #GInitable; it behaves the same
3996 * in all ways except that initialization is asynchronous. For more details
3997 * see the descriptions on #GInitable.
3999 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
4001 * Users of objects implementing this are not intended to use the interface
4002 * method directly; instead it will be used automatically in various ways.
4003 * For C applications you generally just call g_async_initable_new_async()
4004 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
4005 * g_async_initable_init_async() under the cover, calling back with %NULL and
4006 * a set %GError on failure.
4008 * A typical implementation might look something like this:
4018 * _foo_ready_cb (Foo *self)
4022 * self->priv->state = INITIALIZED;
4024 * for (l = self->priv->init_results; l != NULL; l = l->next)
4026 * GTask *task = l->data;
4028 * if (self->priv->success)
4029 * g_task_return_boolean (task, TRUE);
4031 * g_task_return_new_error (task, ...);
4032 * g_object_unref (task);
4035 * g_list_free (self->priv->init_results);
4036 * self->priv->init_results = NULL;
4040 * foo_init_async (GAsyncInitable *initable,
4042 * GCancellable *cancellable,
4043 * GAsyncReadyCallback callback,
4044 * gpointer user_data)
4046 * Foo *self = FOO (initable);
4049 * task = g_task_new (initable, cancellable, callback, user_data);
4051 * switch (self->priv->state)
4053 * case NOT_INITIALIZED:
4054 * _foo_get_ready (self);
4055 * self->priv->init_results = g_list_append (self->priv->init_results,
4057 * self->priv->state = INITIALIZING;
4059 * case INITIALIZING:
4060 * self->priv->init_results = g_list_append (self->priv->init_results,
4064 * if (!self->priv->success)
4065 * g_task_return_new_error (task, ...);
4067 * g_task_return_boolean (task, TRUE);
4068 * g_object_unref (task);
4074 * foo_init_finish (GAsyncInitable *initable,
4075 * GAsyncResult *result,
4078 * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
4080 * return g_task_propagate_boolean (G_TASK (result), error);
4084 * foo_async_initable_iface_init (gpointer g_iface,
4087 * GAsyncInitableIface *iface = g_iface;
4089 * iface->init_async = foo_init_async;
4090 * iface->init_finish = foo_init_finish;
4097 * SECTION:gasyncresult
4098 * @short_description: Asynchronous Function Results
4099 * @include: gio/gio.h
4102 * Provides a base class for implementing asynchronous function results.
4104 * Asynchronous operations are broken up into two separate operations
4105 * which are chained together by a #GAsyncReadyCallback. To begin
4106 * an asynchronous operation, provide a #GAsyncReadyCallback to the
4107 * asynchronous function. This callback will be triggered when the
4108 * operation has completed, and will be passed a #GAsyncResult instance
4109 * filled with the details of the operation's success or failure, the
4110 * object the asynchronous function was started for and any error codes
4111 * returned. The asynchronous callback function is then expected to call
4112 * the corresponding "_finish()" function, passing the object the
4113 * function was called for, the #GAsyncResult instance, and (optionally)
4114 * an @error to grab any error conditions that may have occurred.
4116 * The "_finish()" function for an operation takes the generic result
4117 * (of type #GAsyncResult) and returns the specific result that the
4118 * operation in question yields (e.g. a #GFileEnumerator for a
4119 * "enumerate children" operation). If the result or error status of the
4120 * operation is not needed, there is no need to call the "_finish()"
4121 * function; GIO will take care of cleaning up the result and error
4122 * information after the #GAsyncReadyCallback returns. You can pass
4123 * %NULL for the #GAsyncReadyCallback if you don't need to take any
4124 * action at all after the operation completes. Applications may also
4125 * take a reference to the #GAsyncResult and call "_finish()" later;
4126 * however, the "_finish()" function may be called at most once.
4128 * Example of a typical asynchronous operation flow:
4130 * void _theoretical_frobnitz_async (Theoretical *t,
4132 * GAsyncReadyCallback cb,
4135 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
4136 * GAsyncResult *res,
4140 * frobnitz_result_func (GObject *source_object,
4141 * GAsyncResult *res,
4142 * gpointer user_data)
4144 * gboolean success = FALSE;
4146 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
4149 * g_printf ("Hurray!\n");
4151 * g_printf ("Uh oh!\n");
4153 * /<!-- -->* ... *<!-- -->/
4157 * int main (int argc, void *argv[])
4159 * /<!-- -->* ... *<!-- -->/
4161 * _theoretical_frobnitz_async (theoretical_data,
4163 * frobnitz_result_func,
4166 * /<!-- -->* ... *<!-- -->/
4170 * The callback for an asynchronous operation is called only once, and is
4171 * always called, even in the case of a cancelled operation. On cancellation
4172 * the result is a %G_IO_ERROR_CANCELLED error.
4174 * <para id="io-priority"><indexterm><primary>I/O
4175 * priority</primary></indexterm> Many I/O-related asynchronous
4176 * operations have a priority parameter, which is used in certain
4177 * cases to determine the order in which operations are executed. They
4178 * are <emphasis>not</emphasis> used to determine system-wide I/O
4179 * scheduling. Priorities are integers, with lower numbers indicating
4180 * higher priority. It is recommended to choose priorities between
4181 * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a
4187 * SECTION:gbufferedinputstream
4188 * @short_description: Buffered Input Stream
4189 * @include: gio/gio.h
4190 * @see_also: #GFilterInputStream, #GInputStream
4192 * Buffered input stream implements #GFilterInputStream and provides
4193 * for buffered reads.
4195 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
4197 * To create a buffered input stream, use g_buffered_input_stream_new(),
4198 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
4201 * To get the size of a buffer within a buffered input stream, use
4202 * g_buffered_input_stream_get_buffer_size(). To change the size of a
4203 * buffered input stream's buffer, use
4204 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
4205 * cannot be reduced below the size of the data within the buffer.
4210 * SECTION:gbufferedoutputstream
4211 * @short_description: Buffered Output Stream
4212 * @include: gio/gio.h
4213 * @see_also: #GFilterOutputStream, #GOutputStream
4215 * Buffered output stream implements #GFilterOutputStream and provides
4216 * for buffered writes.
4218 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
4220 * To create a buffered output stream, use g_buffered_output_stream_new(),
4221 * or g_buffered_output_stream_new_sized() to specify the buffer's size
4224 * To get the size of a buffer within a buffered input stream, use
4225 * g_buffered_output_stream_get_buffer_size(). To change the size of a
4226 * buffered output stream's buffer, use
4227 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
4228 * size cannot be reduced below the size of the data within the buffer.
4233 * SECTION:gbytesicon
4234 * @short_description: An icon stored in memory as a GBytes
4235 * @include: gio/gio.h
4236 * @see_also: #GIcon, #GLoadableIcon, #GBytes
4238 * #GBytesIcon specifies an image held in memory in a common format (usually
4239 * png) to be used as icon.
4246 * SECTION:gcancellable
4247 * @short_description: Thread-safe Operation Cancellation Stack
4248 * @include: gio/gio.h
4250 * GCancellable is a thread-safe operation cancellation stack used
4251 * throughout GIO to allow for cancellation of synchronous and
4252 * asynchronous operations.
4257 * SECTION:gcharsetconverter
4258 * @short_description: Convert between charsets
4259 * @include: gio/gio.h
4261 * #GCharsetConverter is an implementation of #GConverter based on
4267 * SECTION:gcontenttype
4268 * @short_description: Platform-specific content typing
4269 * @include: gio/gio.h
4271 * A content type is a platform specific string that defines the type
4272 * 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".
4273 * On Win32 it is an extension string like ".doc", ".txt" or a perceived
4274 * string like "audio". Such strings can be looked up in the registry at
4275 * HKEY_CLASSES_ROOT.
4280 * SECTION:gconverter
4281 * @short_description: Data conversion interface
4282 * @include: gio/gio.h
4283 * @see_also: #GInputStream, #GOutputStream
4285 * #GConverter is implemented by objects that convert
4286 * binary data in various ways. The conversion can be
4287 * stateful and may fail at any place.
4289 * Some example conversions are: character set conversion,
4290 * compression, decompression and regular expression
4298 * SECTION:gconverterinputstream
4299 * @short_description: Converter Input Stream
4300 * @include: gio/gio.h
4301 * @see_also: #GInputStream, #GConverter
4303 * Converter input stream implements #GInputStream and allows
4304 * conversion of data of various types during reading.
4306 * As of GLib 2.34, #GConverterInputStream implements
4307 * #GPollableInputStream.
4312 * SECTION:gconverteroutputstream
4313 * @short_description: Converter Output Stream
4314 * @include: gio/gio.h
4315 * @see_also: #GOutputStream, #GConverter
4317 * Converter output stream implements #GOutputStream and allows
4318 * conversion of data of various types during reading.
4320 * As of GLib 2.34, #GConverterOutputStream implements
4321 * #GPollableOutputStream.
4326 * SECTION:gcredentials
4327 * @short_description: An object containing credentials
4328 * @include: gio/gio.h
4330 * The #GCredentials type is a reference-counted wrapper for native
4331 * credentials. This information is typically used for identifying,
4332 * authenticating and authorizing other processes.
4334 * Some operating systems supports looking up the credentials of the
4335 * remote peer of a communication endpoint - see e.g.
4336 * g_socket_get_credentials().
4338 * Some operating systems supports securely sending and receiving
4339 * credentials over a Unix Domain Socket, see
4340 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
4341 * g_unix_connection_receive_credentials() for details.
4343 * On Linux, the native credential type is a <type>struct ucred</type>
4345 * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
4346 * man page for details. This corresponds to
4347 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
4349 * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
4350 * credential type is a <type>struct cmsgcred</type>. This corresponds
4351 * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
4353 * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
4354 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
4356 * On Solaris (including OpenSolaris and its derivatives), the native
4357 * credential type is a <type>ucred_t</type>. This corresponds to
4358 * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
4363 * SECTION:gdatainputstream
4364 * @short_description: Data Input Stream
4365 * @include: gio/gio.h
4366 * @see_also: #GInputStream
4368 * Data input stream implements #GInputStream and includes functions for
4369 * reading structured data directly from a binary input stream.
4374 * SECTION:gdataoutputstream
4375 * @short_description: Data Output Stream
4376 * @include: gio/gio.h
4377 * @see_also: #GOutputStream
4379 * Data output stream implements #GOutputStream and includes functions for
4380 * writing data directly to an output stream.
4385 * SECTION:gdbusactiongroup
4386 * @title: GDBusActionGroup
4387 * @short_description: A D-Bus GActionGroup implementation
4388 * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
4390 * #GDBusActionGroup is an implementation of the #GActionGroup
4391 * interface that can be used as a proxy for an action group
4392 * that is exported over D-Bus with g_dbus_connection_export_action_group().
4397 * SECTION:gdbusaddress
4398 * @title: D-Bus Addresses
4399 * @short_description: D-Bus connection endpoints
4400 * @include: gio/gio.h
4402 * Routines for working with D-Bus addresses. A D-Bus address is a string
4403 * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
4404 * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>.
4409 * SECTION:gdbusauthobserver
4410 * @short_description: Object used for authenticating connections
4411 * @include: gio/gio.h
4413 * The #GDBusAuthObserver type provides a mechanism for participating
4414 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
4415 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
4416 * signals you are interested in. Note that new signals may be added
4419 * For example, if you only want to allow D-Bus connections from
4420 * processes owned by the same uid as the server, you would use a
4421 * signal handler like the following:
4422 * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
4424 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
4425 * GIOStream *stream,
4426 * GCredentials *credentials,
4427 * gpointer user_data)
4429 * gboolean authorized;
4431 * authorized = FALSE;
4432 * if (credentials != NULL)
4434 * GCredentials *own_credentials;
4435 * own_credentials = g_credentials_new ();
4436 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
4437 * authorized = TRUE;
4438 * g_object_unref (own_credentials);
4441 * return authorized;
4443 * </programlisting></example>
4448 * SECTION:gdbusconnection
4449 * @short_description: D-Bus Connections
4450 * @include: gio/gio.h
4452 * The #GDBusConnection type is used for D-Bus connections to remote
4453 * peers such as a message buses. It is a low-level API that offers a
4454 * lot of flexibility. For instance, it lets you establish a connection
4455 * over any transport that can by represented as an #GIOStream.
4457 * This class is rarely used directly in D-Bus clients. If you are writing
4458 * an D-Bus client, it is often easier to use the g_bus_own_name(),
4459 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
4461 * As an exception to the usual GLib rule that a particular object must not be
4462 * used by two threads at the same time, #GDBusConnection's methods may be
4463 * called from any thread<footnote>
4465 * This is so that g_bus_get() and g_bus_get_sync() can safely return the
4466 * same #GDBusConnection when called from any thread.
4470 * Most of the ways to obtain a #GDBusConnection automatically initialize it
4471 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
4472 * g_bus_get(), and the synchronous versions of those methods, give you an
4473 * initialized connection. Language bindings for GIO should use
4474 * g_initable_new() or g_async_initable_new_async(), which also initialize the
4477 * If you construct an uninitialized #GDBusConnection, such as via
4478 * g_object_new(), you must initialize it via g_initable_init() or
4479 * g_async_initable_init_async() before using its methods or properties.
4480 * Calling methods or accessing properties on a #GDBusConnection that has not
4481 * completed initialization successfully is considered to be invalid, and leads
4482 * to undefined behaviour. In particular, if initialization fails with a
4483 * #GError, the only valid thing you can do with that #GDBusConnection is to
4484 * free it with g_object_unref().
4486 * <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>
4488 * <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>
4490 * <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>
4492 * <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>
4497 * SECTION:gdbuserror
4498 * @title: GDBusError
4499 * @short_description: Mapping D-Bus errors to and from GError
4500 * @include: gio/gio.h
4502 * All facilities that return errors from remote methods (such as
4503 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
4504 * errors (e.g. errors returned from the other peer) and locally
4505 * in-process generated errors.
4507 * To check if a returned #GError is an error from a remote peer, use
4508 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
4509 * use g_dbus_error_get_remote_error(). Before presenting an error,
4510 * always use g_dbus_error_strip_remote_error().
4512 * In addition, facilities used to return errors to a remote peer also
4513 * use #GError. See g_dbus_method_invocation_return_error() for
4514 * discussion about how the D-Bus error name is set.
4516 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
4517 * automatically map from D-Bus errors to #GError and back. This
4518 * is typically done in the function returning the #GQuark for the
4520 * <example id="error-registration"><title>Error Registration</title><programlisting>
4521 * /<!-- -->* foo-bar-error.h: *<!-- -->/
4523 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
4524 * GQuark foo_bar_error_quark (void);
4528 * FOO_BAR_ERROR_FAILED,
4529 * FOO_BAR_ERROR_ANOTHER_ERROR,
4530 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
4531 * FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/
4534 * /<!-- -->* foo-bar-error.c: *<!-- -->/
4536 * static const GDBusErrorEntry foo_bar_error_entries[] =
4538 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
4539 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
4540 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
4543 * /<!-- -->* Ensure that every error code has an associated D-Bus error name *<!-- -->/
4544 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
4547 * foo_bar_error_quark (void)
4549 * static volatile gsize quark_volatile = 0;
4550 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
4552 * foo_bar_error_entries,
4553 * G_N_ELEMENTS (foo_bar_error_entries));
4554 * return (GQuark) quark_volatile;
4556 * </programlisting></example>
4557 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
4558 * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>.
4560 * If the other peer is using GDBus, and has registered the association with
4561 * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
4562 * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
4563 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
4564 * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
4566 * Note that errors in the %G_DBUS_ERROR error domain is intended only
4567 * for returning errors from a remote message bus process. Errors
4568 * generated locally in-process by e.g. #GDBusConnection is from the
4569 * %G_IO_ERROR domain.
4574 * SECTION:gdbusinterface
4575 * @short_description: Base type for D-Bus interfaces
4576 * @include: gio/gio.h
4578 * The #GDBusInterface type is the base type for D-Bus interfaces both
4579 * on the service side (see #GDBusInterfaceSkeleton) and client side
4580 * (see #GDBusProxy).
4585 * SECTION:gdbusinterfaceskeleton
4586 * @short_description: Service-side D-Bus interface
4587 * @include: gio/gio.h
4589 * Abstract base class for D-Bus interfaces on the service side.
4594 * SECTION:gdbusintrospection
4595 * @title: D-Bus Introspection Data
4596 * @short_description: Node and interface description data structures
4597 * @include: gio/gio.h
4599 * Various data structures and convenience routines to parse and
4600 * generate D-Bus introspection XML. Introspection information is
4601 * used when registering objects with g_dbus_connection_register_object().
4603 * The format of D-Bus introspection XML is specified in the
4604 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>.
4609 * SECTION:gdbusmenumodel
4610 * @title: GDBusMenuModel
4611 * @short_description: A D-Bus GMenuModel implementation
4612 * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
4614 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
4615 * as a proxy for a menu model that is exported over D-Bus with
4616 * g_dbus_connection_export_menu_model().
4621 * SECTION:gdbusmessage
4622 * @short_description: D-Bus Message
4623 * @include: gio/gio.h
4625 * A type for representing D-Bus messages that can be sent or received
4626 * on a #GDBusConnection.
4631 * SECTION:gdbusmethodinvocation
4632 * @short_description: Object for handling remote calls
4633 * @include: gio/gio.h
4635 * Instances of the #GDBusMethodInvocation class are used when
4636 * handling D-Bus method calls. It provides a way to asynchronously
4637 * return results and errors.
4639 * The normal way to obtain a #GDBusMethodInvocation object is to receive
4640 * it as an argument to the handle_method_call() function in a
4641 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
4646 * SECTION:gdbusnameowning
4647 * @title: Owning Bus Names
4648 * @short_description: Simple API for owning bus names
4649 * @include: gio/gio.h
4651 * Convenience API for owning bus names.
4653 * <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>
4658 * SECTION:gdbusnamewatching
4659 * @title: Watching Bus Names
4660 * @short_description: Simple API for watching bus names
4661 * @include: gio/gio.h
4663 * Convenience API for watching bus names.
4665 * <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>
4670 * SECTION:gdbusobject
4671 * @short_description: Base type for D-Bus objects
4672 * @include: gio/gio.h
4674 * The #GDBusObject type is the base type for D-Bus objects on both
4675 * the service side (see #GDBusObjectSkeleton) and the client side
4676 * (see #GDBusObjectProxy). It is essentially just a container of
4682 * SECTION:gdbusobjectmanager
4683 * @short_description: Base type for D-Bus object managers
4684 * @include: gio/gio.h
4686 * The #GDBusObjectManager type is the base type for service- and
4687 * client-side implementations of the standardized <ulink
4688 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
4691 * See #GDBusObjectManagerClient for the client-side implementation
4692 * and #GDBusObjectManagerServer for the service-side implementation.
4697 * SECTION:gdbusobjectmanagerclient
4698 * @short_description: Client-side object manager
4699 * @include: gio/gio.h
4701 * #GDBusObjectManagerClient is used to create, monitor and delete object
4702 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
4703 * code implementing the <ulink
4704 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
4707 * Once an instance of this type has been created, you can connect to
4708 * the #GDBusObjectManager::object-added and
4709 * #GDBusObjectManager::object-removed signals and inspect the
4710 * #GDBusObjectProxy objects returned by
4711 * g_dbus_object_manager_get_objects().
4713 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
4714 * object construction time, the default behavior is to request the
4715 * message bus to launch an owner for the name. This behavior can be
4716 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
4717 * flag. It's also worth noting that this only works if the name of
4718 * interest is activatable in the first place. E.g. in some cases it
4719 * is not possible to launch an owner for the requested name. In this
4720 * case, #GDBusObjectManagerClient object construction still succeeds but
4721 * there will be no object proxies
4722 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
4723 * the #GDBusObjectManagerClient:name-owner property is %NULL.
4725 * The owner of the requested name can come and go (for example
4726 * consider a system service being restarted) – #GDBusObjectManagerClient
4727 * handles this case too; simply connect to the #GObject::notify
4728 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
4729 * property. When the name owner vanishes, the behavior is that
4730 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
4731 * emission of the #GObject::notify signal) and then
4732 * #GDBusObjectManager::object-removed signals are synthesized
4733 * for all currently existing object proxies. Since
4734 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
4735 * use this information to disambiguate a synthesized signal from a
4736 * genuine signal caused by object removal on the remote
4737 * #GDBusObjectManager. Similarly, when a new name owner appears,
4738 * #GDBusObjectManager::object-added signals are synthesized
4739 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
4740 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
4741 * is set to the new name owner (this includes emission of the
4742 * #GObject::notify signal). Furthermore, you are guaranteed that
4743 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
4744 * (e.g. <literal>:1.42</literal>) and %NULL even in the case where
4745 * the name of interest is atomically replaced
4747 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
4748 * instances. All signals (including the
4749 * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
4750 * signal) delivered to #GDBusProxy instances are guaranteed to
4751 * originate from the name owner. This guarantee along with the
4752 * behavior described above, means that certain race conditions
4753 * including the <emphasis><quote>half the proxy is from the old owner
4754 * and the other half is from the new owner</quote></emphasis> problem
4757 * To avoid having the application connect to signals on the returned
4758 * #GDBusObjectProxy and #GDBusProxy objects, the
4759 * #GDBusObject::interface-added,
4760 * #GDBusObject::interface-removed,
4761 * #GDBusProxy::g-properties-changed and
4762 * #GDBusProxy::g-signal signals
4763 * are also emitted on the #GDBusObjectManagerClient instance managing these
4764 * objects. The signals emitted are
4765 * #GDBusObjectManager::interface-added,
4766 * #GDBusObjectManager::interface-removed,
4767 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
4768 * #GDBusObjectManagerClient::interface-proxy-signal.
4770 * Note that all callbacks and signals are emitted in the
4771 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
4772 * that the #GDBusObjectManagerClient object was constructed
4773 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
4774 * originating from the #GDBusObjectManagerClient object will be created in
4775 * the same context and, consequently, will deliver signals in the
4781 * SECTION:gdbusobjectmanagerserver
4782 * @short_description: Service-side object manager
4783 * @include: gio/gio.h
4785 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
4786 * the standardized <ulink
4787 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
4788 * interface. For example, remote D-Bus clients can get all objects
4789 * and properties in a single call. Additionally, any change in the
4790 * object hierarchy is broadcast using signals. This means that D-Bus
4791 * clients can keep caches up to date by only listening to D-Bus
4794 * See #GDBusObjectManagerClient for the client-side code that is
4795 * intended to be used with #GDBusObjectManagerServer or any D-Bus
4796 * object implementing the org.freedesktop.DBus.ObjectManager
4802 * SECTION:gdbusobjectproxy
4803 * @short_description: Client-side D-Bus object
4804 * @include: gio/gio.h
4806 * A #GDBusObjectProxy is an object used to represent a remote object
4807 * with one or more D-Bus interfaces. Normally, you don't instantiate
4808 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
4809 * is used to obtain it.
4816 * SECTION:gdbusobjectskeleton
4817 * @short_description: Service-side D-Bus object
4818 * @include: gio/gio.h
4820 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
4821 * interfaces. The set of exported interfaces on the object may be
4822 * dynamic and change at runtime.
4824 * This type is intended to be used with #GDBusObjectManager.
4829 * SECTION:gdbusproxy
4830 * @short_description: Client-side D-Bus interface proxy
4831 * @include: gio/gio.h
4833 * #GDBusProxy is a base class used for proxies to access a D-Bus
4834 * interface on a remote object. A #GDBusProxy can be constructed for
4835 * both well-known and unique names.
4837 * By default, #GDBusProxy will cache all properties (and listen to
4838 * changes) of the remote object, and proxy all signals that gets
4839 * emitted. This behaviour can be changed by passing suitable
4840 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
4841 * well-known name, the property cache is flushed when the name owner
4842 * vanishes and reloaded when a name owner appears.
4844 * If a #GDBusProxy is used for a well-known name, the owner of the
4845 * name is tracked and can be read from
4846 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
4847 * get notified of changes. Additionally, only signals and property
4848 * changes emitted from the current name owner are considered and
4849 * calls are always sent to the current name owner. This avoids a
4850 * number of race conditions when the name is lost by one owner and
4851 * claimed by another. However, if no name owner currently exists,
4852 * then calls will be sent to the well-known name which may result in
4853 * the message bus launching an owner (unless
4854 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
4856 * The generic #GDBusProxy::g-properties-changed and
4857 * #GDBusProxy::g-signal signals are not very convenient to work
4858 * with. Therefore, the recommended way of working with proxies is to
4859 * subclass #GDBusProxy, and have more natural properties and signals
4860 * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/>
4861 * for how this can easily be done using the
4862 * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command>
4865 * A #GDBusProxy instance can be used from multiple threads but note
4866 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
4867 * and #GObject::notify) are emitted in the
4868 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
4869 * of the thread where the instance was constructed.
4871 * <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>
4876 * SECTION:gdbusserver
4877 * @short_description: Helper for accepting connections
4878 * @include: gio/gio.h
4880 * #GDBusServer is a helper for listening to and accepting D-Bus
4881 * connections. This can be used to create a new D-Bus server, allowing two
4882 * peers to use the D-Bus protocol for their own specialized communication.
4883 * A server instance provided in this way will not perform message routing or
4884 * implement the org.freedesktop.DBus interface.
4886 * To just export an object on a well-known name on a message bus, such as the
4887 * session or system bus, you should instead use g_bus_own_name().
4889 * <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>
4894 * SECTION:gdbusutils
4895 * @title: D-Bus Utilities
4896 * @short_description: Various utilities related to D-Bus
4897 * @include: gio/gio.h
4899 * Various utility routines related to D-Bus.
4904 * SECTION:gdesktopappinfo
4905 * @title: GDesktopAppInfo
4906 * @short_description: Application information from desktop files
4907 * @include: gio/gdesktopappinfo.h
4909 * #GDesktopAppInfo is an implementation of #GAppInfo based on
4912 * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to
4913 * the UNIX-specific GIO interfaces, thus you have to use the
4914 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
4920 * @short_description: Drive management
4921 * @include: gio/gio.h
4923 * #GDrive - this represent a piece of hardware connected to the machine.
4924 * It's generally only created for removable hardware or hardware with
4927 * #GDrive is a container class for #GVolume objects that stem from
4928 * the same piece of media. As such, #GDrive abstracts a drive with
4929 * (or without) removable media and provides operations for querying
4930 * whether media is available, determining whether media change is
4931 * automatically detected and ejecting the media.
4933 * If the #GDrive reports that media isn't automatically detected, one
4934 * can poll for media; typically one should not do this periodically
4935 * as a poll for media operation is potententially expensive and may
4936 * spin up the drive creating noise.
4938 * #GDrive supports starting and stopping drives with authentication
4939 * support for the former. This can be used to support a diverse set
4940 * of use cases including connecting/disconnecting iSCSI devices,
4941 * powering down external disk enclosures and starting/stopping
4942 * multi-disk devices such as RAID devices. Note that the actual
4943 * semantics and side-effects of starting/stopping a #GDrive may vary
4944 * according to implementation. To choose the correct verbs in e.g. a
4945 * file manager, use g_drive_get_start_stop_type().
4947 * For porting from GnomeVFS note that there is no equivalent of
4948 * #GDrive in that API.
4954 * @short_description: An object for emblems
4955 * @include: gio/gio.h
4956 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
4958 * #GEmblem is an implementation of #GIcon that supports
4959 * having an emblem, which is an icon with additional properties.
4960 * It can than be added to a #GEmblemedIcon.
4962 * Currently, only metainformation about the emblem's origin is
4963 * supported. More may be added in the future.
4968 * SECTION:gemblemedicon
4969 * @short_description: Icon with emblems
4970 * @include: gio/gio.h
4971 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
4973 * #GEmblemedIcon is an implementation of #GIcon that supports
4974 * adding an emblem to an icon. Adding multiple emblems to an
4975 * icon is ensured via g_emblemed_icon_add_emblem().
4977 * Note that #GEmblemedIcon allows no control over the position
4978 * of the emblems. See also #GEmblem for more information.
4984 * @short_description: File and Directory Handling
4985 * @include: gio/gio.h
4986 * @see_also: #GFileInfo, #GFileEnumerator
4988 * #GFile is a high level abstraction for manipulating files on a
4989 * virtual file system. #GFiles are lightweight, immutable objects
4990 * that do no I/O upon creation. It is necessary to understand that
4991 * #GFile objects do not represent files, merely an identifier for a
4992 * file. All file content I/O is implemented as streaming operations
4993 * (see #GInputStream and #GOutputStream).
4995 * To construct a #GFile, you can use:
4997 * <member>g_file_new_for_path() if you have a path.</member>
4998 * <member>g_file_new_for_uri() if you have a URI.</member>
4999 * <member>g_file_new_for_commandline_arg() for a command line argument.</member>
5000 * <member>g_file_new_tmp() to create a temporary file from a template.</member>
5001 * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member>
5004 * One way to think of a #GFile is as an abstraction of a pathname. For
5005 * normal files the system pathname is what is stored internally, but as
5006 * #GFiles are extensible it could also be something else that corresponds
5007 * to a pathname in a userspace implementation of a filesystem.
5009 * #GFiles make up hierarchies of directories and files that correspond to
5010 * the files on a filesystem. You can move through the file system with
5011 * #GFile using g_file_get_parent() to get an identifier for the parent
5012 * directory, g_file_get_child() to get a child within a directory,
5013 * g_file_resolve_relative_path() to resolve a relative path between two
5014 * #GFiles. There can be multiple hierarchies, so you may not end up at
5015 * the same root if you repeatedly call g_file_get_parent() on two different
5018 * All #GFiles have a basename (get with g_file_get_basename()). These names
5019 * are byte strings that are used to identify the file on the filesystem
5020 * (relative to its parent directory) and there is no guarantees that they
5021 * have any particular charset encoding or even make any sense at all. If
5022 * you want to use filenames in a user interface you should use the display
5023 * name that you can get by requesting the
5024 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
5025 * This is guaranteed to be in UTF-8 and can be used in a user interface.
5026 * But always store the real basename or the #GFile to use to actually
5027 * access the file, because there is no way to go from a display name to
5030 * Using #GFile as an identifier has the same weaknesses as using a path
5031 * in that there may be multiple aliases for the same file. For instance,
5032 * hard or soft links may cause two different #GFiles to refer to the same
5033 * file. Other possible causes for aliases are: case insensitive filesystems,
5034 * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
5035 * check if two #GFiles point to the same file you can query for the
5036 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
5037 * canonicalization of pathnames passed in, so that trivial differences in
5038 * the path string used at creation (duplicated slashes, slash at end of
5039 * path, "." or ".." path segments, etc) does not create different #GFiles.
5041 * Many #GFile operations have both synchronous and asynchronous versions
5042 * to suit your application. Asynchronous versions of synchronous functions
5043 * simply have _async() appended to their function names. The asynchronous
5044 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
5045 * the operation, producing a GAsyncResult which is then passed to the
5046 * function's matching _finish() operation.
5048 * Some #GFile operations do not have synchronous analogs, as they may
5049 * take a very long time to finish, and blocking may leave an application
5050 * unusable. Notable cases include:
5052 * <member>g_file_mount_mountable() to mount a mountable file.</member>
5053 * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member>
5054 * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
5057 * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
5058 * One notable feature of #GFiles are entity tags, or "etags" for
5059 * short. Entity tags are somewhat like a more abstract version of the
5060 * traditional mtime, and can be used to quickly determine if the file has
5061 * been modified from the version on the file system. See the HTTP 1.1
5062 * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
5063 * for HTTP Etag headers, which are a very similar concept.
5069 * SECTION:gfileattribute
5070 * @short_description: Key-Value Paired File Attributes
5071 * @include: gio/gio.h
5072 * @see_also: #GFile, #GFileInfo
5074 * File attributes in GIO consist of a list of key-value pairs.
5076 * Keys are strings that contain a key namespace and a key name, separated
5077 * by a colon, e.g. "namespace::keyname". Namespaces are included to sort
5078 * key-value pairs by namespaces for relevance. Keys can be retrived
5079 * using wildcards, e.g. "standard::*" will return all of the keys in the
5080 * "standard" namespace.
5082 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
5083 * available as a #GFileAttributeInfoList. This list is queryable by key names
5084 * as indicated earlier.
5086 * Information is stored within the list in #GFileAttributeInfo structures.
5087 * The info structure can store different types, listed in the enum
5088 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
5089 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
5091 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
5092 * install default keys and values for their given file system, architecture,
5093 * and other possible implementation details (e.g., on a UNIX system, a file
5094 * attribute key will be registered for the user id for a given file).
5098 * <title>GFileAttributes Default Namespaces</title>
5099 * <tgroup cols='2' align='left'><thead>
5100 * <row><entry>Namspace</entry><entry>Description</entry></row>
5103 * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file
5104 * information that any application may need should be put in this namespace.
5105 * Examples include the file's name, type, and size.</entry></row>
5106 * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link>
5107 * namespace. Currently, the only key in this namespace is "value", which contains
5108 * the value of the current entity tag.</entry></row>
5109 * <row><entry>"id"</entry><entry>The "Identification" namespace. This
5110 * namespace is used by file managers and applications that list directories
5111 * to check for loops and to uniquely identify files.</entry></row>
5112 * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check
5113 * if a user has the proper privilidges to access files and perform
5114 * file operations. Keys in this namespace are made to be generic
5115 * and easily understood, e.g. the "can_read" key is %TRUE if
5116 * the current user has permission to read the file. UNIX permissions and
5117 * NTFS ACLs in Windows should be mapped to these values.</entry></row>
5118 * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
5119 * simple boolean keys for checking if a file or path supports mount operations, e.g.
5120 * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row>
5121 * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
5122 * access, changed, created times. </entry></row>
5123 * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
5124 * information and may not be available for all files. Examples include
5125 * the UNIX "UID", "GID", etc.</entry></row>
5126 * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific
5127 * information and may not be available for all files. Examples include
5128 * "is_system" for checking if a file is marked as a system file, and "is_archive"
5129 * for checking if a file is marked as an archive file.</entry></row>
5130 * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
5131 * about who owns a file. May not be available for all file systems. Examples include
5132 * "user" for getting the user name of the file owner. This information is often mapped from
5133 * some backend specific data such as a unix UID.</entry></row>
5134 * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
5135 * information about file thumbnails and their location within the file system. Examples of
5136 * keys in this namespace include "path" to get the location of a thumbnail, "failed"
5137 * to check if thumbnailing of the file failed, and "is-valid" to check if the thumbnail is
5138 * outdated.</entry></row>
5139 * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information
5140 * about the file system where a file is located, such as its type, how much
5141 * space is left available, and the overall size of the file system.</entry></row>
5142 * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
5143 * contain information about the current GVFS backend in use. </entry></row>
5144 * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information
5145 * about extended user attributes. See attr(5). The "user." prefix of the
5146 * extended user attribute name is stripped away when constructing keys in
5147 * this namespace, e.g. "xattr::mime_type" for the extended attribute with
5148 * the name "user.mime_type". Note that this information is only available
5149 * if GLib has been built with extended attribute support.</entry></row>
5150 * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace.
5151 * Gets information about extended attributes which are not user-specific.
5152 * See attr(5). Note that this information is only available if GLib
5153 * has been built with extended attribute support.</entry></row>
5154 * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes
5155 * information about the SELinux context of files. Note that this information
5156 * is only available if GLib has been built with SELinux support.</entry></row>
5162 * Please note that these are not all of the possible namespaces.
5163 * More namespaces can be added from GIO modules or by individual applications.
5164 * For more information about writing GIO modules, see #GIOModule.
5166 * <!-- TODO: Implementation note about using extended attributes on supported
5170 * <title>GFileAttributes Built-in Keys and Value Types</title>
5171 * <tgroup cols='3' align='left'><thead>
5172 * <row><entry>Enum Value</entry><entry>Namespace::Key</entry><entry>Value Type</entry></row>
5174 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row>
5175 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row>
5176 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row>
5177 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row>
5178 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row>
5179 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row>
5180 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row>
5181 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row>
5182 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row>
5183 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row>
5184 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row>
5185 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row>
5186 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row>
5187 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row>
5188 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row>
5189 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row>
5190 * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row>
5191 * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row>
5192 * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row>
5193 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row>
5194 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row>
5195 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row>
5196 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row>
5197 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row>
5198 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row>
5199 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row>
5200 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row>
5201 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row>
5202 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row>
5203 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row>
5204 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row>
5205 * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row>
5206 * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row>
5207 * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row>
5208 * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row>
5209 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row>
5210 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row>
5211 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row>
5212 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row>
5213 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row>
5214 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row>
5215 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row>
5216 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row>
5217 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row>
5218 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row>
5219 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row>
5220 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row>
5221 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row>
5222 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row>
5223 * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row>
5224 * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row>
5225 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row>
5226 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row>
5227 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row>
5228 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row>
5229 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row>
5230 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID</entry><entry>thumbnail::is-valid</entry><entry>boolean</entry></row>
5231 * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row>
5232 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row>
5233 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row>
5234 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_USED</entry><entry>filesystem::used</entry><entry>uint64</entry></row>
5235 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row>
5236 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row>
5237 * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
5238 * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
5239 * </tbody></tgroup></table></para>
5241 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
5242 * namespaces. Keys for the "xattr" namespace are constructed by stripping
5243 * away the "user." prefix from the extended user attribute, and prepending
5244 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
5245 * concatenating "xattr-sys::" with the extended attribute name. All extended
5246 * attribute values are returned as hex-encoded strings in which bytes outside
5247 * the ASCII range are encoded as hexadecimal escape sequences of the form
5248 * \x<replaceable>nn</replaceable>.
5253 * SECTION:gfiledescriptorbased
5254 * @short_description: Interface for file descriptor based IO
5255 * @include: gio/gfiledescriptorbased.h
5256 * @see_also: #GInputStream, #GOutputStream
5258 * #GFileDescriptorBased is implemented by streams (implementations of
5259 * #GInputStream or #GOutputStream) that are based on file descriptors.
5261 * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to
5262 * the UNIX-specific GIO interfaces, thus you have to use the
5263 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
5270 * SECTION:gfileenumerator
5271 * @short_description: Enumerated Files Routines
5272 * @include: gio/gio.h
5274 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
5275 * returning a #GFileInfo structure for each file enumerated (e.g.
5276 * g_file_enumerate_children() will return a #GFileEnumerator for each
5277 * of the children within a directory).
5279 * To get the next file's information from a #GFileEnumerator, use
5280 * g_file_enumerator_next_file() or its asynchronous version,
5281 * g_file_enumerator_next_files_async(). Note that the asynchronous
5282 * version will return a list of #GFileInfo<!---->s, whereas the
5283 * synchronous will only return the next file in the enumerator.
5285 * The ordering of returned files is unspecified for non-Unix
5286 * platforms; for more information, see g_dir_read_name(). On Unix,
5287 * when operating on local files, returned files will be sorted by
5288 * inode number. Effectively you can assume that the ordering of
5289 * returned files will be stable between successive calls (and
5290 * applications) assuming the directory is unchanged.
5292 * If your application needs a specific ordering, such as by name or
5293 * modification time, you will have to implement that in your
5296 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
5297 * its asynchronous version, g_file_enumerator_close_async(). Once
5298 * a #GFileEnumerator is closed, no further actions may be performed
5299 * on it, and it should be freed with g_object_unref().
5305 * @short_description: Icons pointing to an image file
5306 * @include: gio/gio.h
5307 * @see_also: #GIcon, #GLoadableIcon
5309 * #GFileIcon specifies an icon by pointing to an image file
5310 * to be used as icon.
5316 * @short_description: File Information and Attributes
5317 * @include: gio/gio.h
5318 * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
5320 * Functionality for manipulating basic metadata for files. #GFileInfo
5321 * implements methods for getting information that all files should
5322 * contain, and allows for manipulation of extended attributes.
5324 * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
5325 * information on how GIO handles file attributes.
5327 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
5328 * async variant). To obtain a #GFileInfo for a file input or output
5329 * stream, use g_file_input_stream_query_info() or
5330 * g_file_output_stream_query_info() (or their async variants).
5332 * To change the actual attributes of a file, you should then set the
5333 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
5334 * or g_file_set_attributes_async() on a GFile.
5336 * However, not all attributes can be changed in the file. For instance,
5337 * the actual size of a file cannot be changed via g_file_info_set_size().
5338 * You may call g_file_query_settable_attributes() and
5339 * g_file_query_writable_namespaces() to discover the settable attributes
5340 * of a particular file at runtime.
5342 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
5348 * SECTION:gfileinputstream
5349 * @short_description: File input streaming operations
5350 * @include: gio/gio.h
5351 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
5353 * GFileInputStream provides input streams that take their
5354 * content from a file.
5356 * GFileInputStream implements #GSeekable, which allows the input
5357 * stream to jump to arbitrary positions in the file, provided the
5358 * filesystem of the file allows it. To find the position of a file
5359 * input stream, use g_seekable_tell(). To find out if a file input
5360 * stream supports seeking, use g_seekable_can_seek().
5361 * To position a file input stream, use g_seekable_seek().
5366 * SECTION:gfileiostream
5367 * @short_description: File read and write streaming operations
5368 * @include: gio/gio.h
5369 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
5371 * GFileIOStream provides io streams that both read and write to the same
5374 * GFileIOStream implements #GSeekable, which allows the io
5375 * stream to jump to arbitrary positions in the file and to truncate
5376 * the file, provided the filesystem of the file supports these
5379 * To find the position of a file io stream, use
5380 * g_seekable_tell().
5382 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
5383 * To position a file io stream, use g_seekable_seek().
5384 * To find out if a file io stream supports truncating, use
5385 * g_seekable_can_truncate(). To truncate a file io
5386 * stream, use g_seekable_truncate().
5388 * The default implementation of all the #GFileIOStream operations
5389 * and the implementation of #GSeekable just call into the same operations
5390 * on the output stream.
5397 * SECTION:gfilemonitor
5398 * @short_description: File Monitor
5399 * @include: gio/gio.h
5401 * Monitors a file or directory for changes.
5403 * To obtain a #GFileMonitor for a file or directory, use
5404 * g_file_monitor(), g_file_monitor_file(), or
5405 * g_file_monitor_directory().
5407 * To get informed about changes to the file or directory you are
5408 * monitoring, connect to the #GFileMonitor::changed signal. The
5409 * signal will be emitted in the <link
5410 * linkend="g-main-context-push-thread-default">thread-default main
5411 * context</link> of the thread that the monitor was created in
5412 * (though if the global default main context is blocked, this may
5413 * cause notifications to be blocked even if the thread-default
5414 * context is still running).
5419 * SECTION:gfilenamecompleter
5420 * @short_description: Filename Completer
5421 * @include: gio/gio.h
5423 * Completes partial file and directory names given a partial string by
5424 * looking in the file system for clues. Can return a list of possible
5425 * completion strings for widget implementations.
5430 * SECTION:gfileoutputstream
5431 * @short_description: File output streaming operations
5432 * @include: gio/gio.h
5433 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
5435 * GFileOutputStream provides output streams that write their
5436 * content to a file.
5438 * GFileOutputStream implements #GSeekable, which allows the output
5439 * stream to jump to arbitrary positions in the file and to truncate
5440 * the file, provided the filesystem of the file supports these
5443 * To find the position of a file output stream, use g_seekable_tell().
5444 * To find out if a file output stream supports seeking, use
5445 * g_seekable_can_seek().To position a file output stream, use
5446 * g_seekable_seek(). To find out if a file output stream supports
5447 * truncating, use g_seekable_can_truncate(). To truncate a file output
5448 * stream, use g_seekable_truncate().
5453 * SECTION:gfilterinputstream
5454 * @short_description: Filter Input Stream
5455 * @include: gio/gio.h
5457 * Base class for input stream implementations that perform some
5458 * kind of filtering operation on a base stream. Typical examples
5459 * of filtering operations are character set conversion, compression
5460 * and byte order flipping.
5465 * SECTION:gfilteroutputstream
5466 * @short_description: Filter Output Stream
5467 * @include: gio/gio.h
5469 * Base class for output stream implementations that perform some
5470 * kind of filtering operation on a base stream. Typical examples
5471 * of filtering operations are character set conversion, compression
5472 * and byte order flipping.
5478 * @short_description: Interface for icons
5479 * @include: gio/gio.h
5481 * #GIcon is a very minimal interface for icons. It provides functions
5482 * for checking the equality of two icons, hashing of icons and
5483 * serializing an icon to and from strings.
5485 * #GIcon does not provide the actual pixmap for the icon as this is out
5486 * of GIO's scope, however implementations of #GIcon may contain the name
5487 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
5489 * To obtain a hash of a #GIcon, see g_icon_hash().
5491 * To check if two #GIcons are equal, see g_icon_equal().
5493 * For serializing a #GIcon, use g_icon_serialize() and
5494 * g_icon_deserialize().
5496 * If you want to consume #GIcon (for example, in a toolkit) you must
5497 * be prepared to handle at least the three following cases:
5498 * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make
5499 * sense to have fast-paths for other cases (like handling #GdkPixbuf
5500 * directly, for example) but all compliant #GIcon implementations
5501 * outside of GIO must implement #GLoadableIcon.
5503 * If your application or library provides one or more #GIcon
5504 * implementations you need to ensure that your new implementation also
5505 * implements #GLoadableIcon. Additionally, you must provide an
5506 * implementation of g_icon_serialize() that gives a result that is
5507 * understood by g_icon_deserialize(), yielding one of the built-in icon
5513 * SECTION:ginetaddress
5514 * @short_description: An IPv4/IPv6 address
5516 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
5517 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
5518 * look up the #GInetAddress for a hostname. Use
5519 * g_resolver_lookup_by_address() or
5520 * g_resolver_lookup_by_address_async() to look up the hostname for a
5523 * To actually connect to a remote host, you will need a
5524 * #GInetSocketAddress (which includes a #GInetAddress as well as a
5530 * SECTION:ginetaddressmask
5531 * @short_description: An IPv4/IPv6 address mask
5533 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
5534 * described by a base address and a length indicating how many bits
5535 * of the base address are relevant for matching purposes. These are
5536 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
5541 * SECTION:ginetsocketaddress
5542 * @short_description: Internet GSocketAddress
5544 * An IPv4 or IPv6 socket address; that is, the combination of a
5545 * #GInetAddress and a port number.
5551 * @short_description: Failable object initialization interface
5552 * @include: gio/gio.h
5553 * @see_also: #GAsyncInitable
5555 * #GInitable is implemented by objects that can fail during
5556 * initialization. If an object implements this interface then
5557 * it must be initialized as the first thing after construction,
5558 * either via g_initable_init() or g_async_initable_init_async()
5559 * (the latter is only available if it also implements #GAsyncInitable).
5561 * If the object is not initialized, or initialization returns with an
5562 * error, then all operations on the object except g_object_ref() and
5563 * g_object_unref() are considered to be invalid, and have undefined
5564 * behaviour. They will often fail with g_critical() or g_warning(), but
5565 * this must not be relied on.
5567 * Users of objects implementing this are not intended to use
5568 * the interface method directly, instead it will be used automatically
5569 * in various ways. For C applications you generally just call
5570 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
5571 * This will call g_initable_init() under the cover, returning %NULL and
5572 * setting a #GError on failure (at which point the instance is
5575 * For bindings in languages where the native constructor supports
5576 * exceptions the binding could check for objects implemention %GInitable
5577 * during normal construction and automatically initialize them, throwing
5578 * an exception on failure.
5583 * SECTION:ginputstream
5584 * @short_description: Base class for implementing streaming input
5585 * @include: gio/gio.h
5587 * #GInputStream has functions to read from a stream (g_input_stream_read()),
5588 * to close a stream (g_input_stream_close()) and to skip some content
5589 * (g_input_stream_skip()).
5591 * To copy the content of an input stream to an output stream without
5592 * manually handling the reads and writes, use g_output_stream_splice().
5594 * All of these functions have async variants too.
5600 * @short_description: Error helper functions
5601 * @include: gio/gio.h
5603 * Contains helper functions for reporting errors to the user.
5609 * @short_description: Loadable GIO Modules
5610 * @include: gio/gio.h
5612 * Provides an interface and default functions for loading and unloading
5613 * modules. This is used internally to make GIO extensible, but can also
5614 * be used by others to implement module loading.
5619 * SECTION:gioscheduler
5620 * @short_description: I/O Scheduler
5621 * @include: gio/gio.h
5624 * As of GLib 2.36, the <literal>g_io_scheduler</literal> methods
5625 * are deprecated in favor of #GThreadPool and #GTask.
5628 * Schedules asynchronous I/O operations. #GIOScheduler integrates
5629 * into the main event loop (#GMainLoop) and uses threads.
5635 * @short_description: Base class for implementing read/write streams
5636 * @include: gio/gio.h
5637 * @see_also: #GInputStream, #GOutputStream
5639 * GIOStream represents an object that has both read and write streams.
5640 * Generally the two streams acts as separate input and output streams,
5641 * but they share some common resources and state. For instance, for
5642 * seekable streams they may use the same position in both streams.
5644 * Examples of #GIOStream objects are #GSocketConnection which represents
5645 * a two-way network connection, and #GFileIOStream which represent a
5646 * file handle opened in read-write mode.
5648 * To do the actual reading and writing you need to get the substreams
5649 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
5651 * The #GIOStream object owns the input and the output streams, not the other
5652 * way around, so keeping the substreams alive will not keep the #GIOStream
5653 * object alive. If the #GIOStream object is freed it will be closed, thus
5654 * closing the substream, so even if the substreams stay alive they will
5655 * always just return a %G_IO_ERROR_CLOSED for all operations.
5657 * To close a stream use g_io_stream_close() which will close the common
5658 * stream object and also the individual substreams. You can also close
5659 * the substreams themselves. In most cases this only marks the
5660 * substream as closed, so further I/O on it fails. However, some streams
5661 * may support "half-closed" states where one direction of the stream
5662 * is actually shut down.
5669 * SECTION:gloadableicon
5670 * @short_description: Loadable Icons
5671 * @include: gio/gio.h
5672 * @see_also: #GIcon, #GThemedIcon
5674 * Extends the #GIcon interface and adds the ability to
5675 * load icons from streams.
5680 * SECTION:gmemoryinputstream
5681 * @short_description: Streaming input operations on memory chunks
5682 * @include: gio/gio.h
5683 * @see_also: #GMemoryOutputStream
5685 * #GMemoryInputStream is a class for using arbitrary
5686 * memory chunks as input for GIO streaming input operations.
5688 * As of GLib 2.34, #GMemoryInputStream implements
5689 * #GPollableInputStream.
5694 * SECTION:gmemoryoutputstream
5695 * @short_description: Streaming output operations on memory chunks
5696 * @include: gio/gio.h
5697 * @see_also: #GMemoryInputStream
5699 * #GMemoryOutputStream is a class for using arbitrary
5700 * memory chunks as output for GIO streaming output operations.
5702 * As of GLib 2.34, #GMemoryOutputStream trivially implements
5703 * #GPollableOutputStream: it always polls as ready.
5710 * @short_description: A simple implementation of GMenuModel
5712 * #GMenu is a simple implementation of #GMenuModel.
5713 * You populate a #GMenu by adding #GMenuItem instances to it.
5715 * There are some convenience functions to allow you to directly
5716 * add items (avoiding #GMenuItem) for the common cases. To add
5717 * a regular item, use g_menu_insert(). To add a section, use
5718 * g_menu_insert_section(). To add a submenu, use
5719 * g_menu_insert_submenu().
5724 * SECTION:gmenuexporter
5725 * @title: GMenuModel exporter
5726 * @short_description: Export GMenuModels on D-Bus
5727 * @see_also: #GMenuModel, #GDBusMenuModel
5729 * These functions support exporting a #GMenuModel on D-Bus.
5730 * The D-Bus interface that is used is a private implementation
5733 * To access an exported #GMenuModel remotely, use
5734 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
5739 * SECTION:gmenumodel
5740 * @title: GMenuModel
5741 * @short_description: An abstract class representing the contents of a menu
5742 * @see_also: #GActionGroup
5744 * #GMenuModel represents the contents of a menu -- an ordered list of
5745 * menu items. The items are associated with actions, which can be
5746 * activated through them. Items can be grouped in sections, and may
5747 * have submenus associated with them. Both items and sections usually
5748 * have some representation data, such as labels or icons. The type of
5749 * the associated action (ie whether it is stateful, and what kind of
5750 * state it has) can influence the representation of the item.
5752 * The conceptual model of menus in #GMenuModel is hierarchical:
5753 * sections and submenus are again represented by #GMenuModels.
5754 * Menus themselves do not define their own roles. Rather, the role
5755 * of a particular #GMenuModel is defined by the item that references
5756 * it (or, in the case of the 'root' menu, is defined by the context
5757 * in which it is used).
5759 * As an example, consider the visible portions of the menu in
5760 * <xref linkend="menu-example"/>.
5762 * <figure id="menu-example">
5763 * <title>An example menu</title>
5764 * <graphic fileref="menu-example.png" format="PNG"></graphic>
5767 * There are 8 "menus" visible in the screenshot: one menubar, two
5768 * submenus and 5 sections:
5770 * <listitem>the toplevel menubar (containing 4 items)</listitem>
5771 * <listitem>the View submenu (containing 3 sections)</listitem>
5772 * <listitem>the first section of the View submenu (containing 2 items)</listitem>
5773 * <listitem>the second section of the View submenu (containing 1 item)</listitem>
5774 * <listitem>the final section of the View submenu (containing 1 item)</listitem>
5775 * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
5776 * <listitem>the Sources section (containing 2 items)</listitem>
5777 * <listitem>the Markup section (containing 2 items)</listitem>
5780 * <xref linkend="menu-model"/> illustrates the conceptual connection between
5781 * these 8 menus. Each large block in the figure represents a menu and the
5782 * smaller blocks within the large block represent items in that menu. Some
5783 * items contain references to other menus.
5785 * <figure id="menu-model">
5786 * <title>A menu model</title>
5787 * <graphic fileref="menu-model.png" format="PNG"></graphic>
5790 * Notice that the separators visible in <xref linkend="menu-example"/>
5791 * appear nowhere in <xref linkend="menu-model"/>. This is because
5792 * separators are not explicitly represented in the menu model. Instead,
5793 * a separator is inserted between any two non-empty sections of a menu.
5794 * Section items can have labels just like any other item. In that case,
5795 * a display system may show a section header instead of a separator.
5797 * The motivation for this abstract model of application controls is
5798 * that modern user interfaces tend to make these controls available
5799 * outside the application. Examples include global menus, jumplists,
5800 * dash boards, etc. To support such uses, it is necessary to 'export'
5801 * information about actions and their representation in menus, which
5802 * is exactly what the
5803 * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
5805 * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
5806 * do for #GActionGroup and #GMenuModel. The client-side counterparts
5807 * to make use of the exported information are #GDBusActionGroup and
5810 * The API of #GMenuModel is very generic, with iterators for the
5811 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
5812 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
5813 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
5814 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
5815 * and %G_MENU_LINK_SUBMENU.
5817 * Items in a #GMenuModel represent active controls if they refer to
5818 * an action that can get activated when the user interacts with the
5819 * menu item. The reference to the action is encoded by the string id
5820 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
5821 * identifies an action in an action group. Which action group(s) provide
5822 * actions depends on the context in which the menu model is used.
5823 * E.g. when the model is exported as the application menu of a
5824 * #GtkApplication, actions can be application-wide or window-specific
5825 * (and thus come from two different action groups). By convention, the
5826 * application-wide actions have names that start with "app.", while the
5827 * names of window-specific actions start with "win.".
5829 * While a wide variety of stateful actions is possible, the following
5830 * is the minimum that is expected to be supported by all users of exported
5833 * <listitem>an action with no parameter type and no state</listitem>
5834 * <listitem>an action with no parameter type and boolean state</listitem>
5835 * <listitem>an action with string parameter type and string state</listitem>
5838 * <formalpara><title>Stateless</title>
5840 * A stateless action typically corresponds to an ordinary menu item.
5843 * Selecting such a menu item will activate the action (with no parameter).
5847 * <formalpara><title>Boolean State</title>
5849 * An action with a boolean state will most typically be used with a "toggle"
5850 * or "switch" menu item. The state can be set directly, but activating the
5851 * action (with no parameter) results in the state being toggled.
5854 * Selecting a toggle menu item will activate the action. The menu item should
5855 * be rendered as "checked" when the state is true.
5859 * <formalpara><title>String Parameter and State</title>
5861 * Actions with string parameters and state will most typically be used to
5862 * represent an enumerated choice over the items available for a group of
5863 * radio menu items. Activating the action with a string parameter is
5864 * equivalent to setting that parameter as the state.
5867 * Radio menu items, in addition to being associated with the action, will
5868 * have a target value. Selecting that menu item will result in activation
5869 * of the action with the target value as the parameter. The menu item should
5870 * be rendered as "selected" when the state of the action is equal to the
5871 * target value of the menu item.
5879 * @short_description: Mount management
5880 * @include: gio/gio.h
5881 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
5883 * The #GMount interface represents user-visible mounts. Note, when
5884 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
5886 * #GMount is a "mounted" filesystem that you can access. Mounted is in
5887 * quotes because it's not the same as a unix mount, it might be a gvfs
5888 * mount, but you can still access the files on it if you use GIO. Might or
5889 * might not be related to a volume object.
5891 * Unmounting a #GMount instance is an asynchronous operation. For
5892 * more information about asynchronous operations, see #GAsyncResult
5893 * and #GTask. To unmount a #GMount instance, first call
5894 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
5895 * #GAsyncReadyCallback. The callback will be fired when the
5896 * operation has resolved (either with success or failure), and a
5897 * #GAsyncReady structure will be passed to the callback. That
5898 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
5899 * and the #GAsyncReady data to see if the operation was completed
5900 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
5901 * is called, then it will be filled with any error information.
5906 * SECTION:gmountoperation
5907 * @short_description: Object used for authentication and user interaction
5908 * @include: gio/gio.h
5910 * #GMountOperation provides a mechanism for interacting with the user.
5911 * It can be used for authenticating mountable operations, such as loop
5912 * mounting files, hard drive partitions or server locations. It can
5913 * also be used to ask the user questions or show a list of applications
5914 * preventing unmount or eject operations from completing.
5916 * Note that #GMountOperation is used for more than just #GMount
5917 * objects – for example it is also used in g_drive_start() and
5920 * Users should instantiate a subclass of this that implements all the
5921 * various callbacks to show the required dialogs, such as
5922 * #GtkMountOperation. If no user interaction is desired (for example
5923 * when automounting filesystems at login time), usually %NULL can be
5924 * passed, see each method taking a #GMountOperation for details.
5929 * SECTION:gnetworkaddress
5930 * @short_description: A GSocketConnectable for resolving hostnames
5931 * @include: gio/gio.h
5933 * #GNetworkAddress provides an easy way to resolve a hostname and
5934 * then attempt to connect to that host, handling the possibility of
5935 * multiple IP addresses and multiple address families.
5937 * See #GSocketConnectable for and example of using the connectable
5943 * SECTION:gnetworking
5944 * @title: gnetworking.h
5945 * @short_description: System networking includes
5946 * @include: gio/gnetworking.h
5948 * The <literal>gnetworking.h</literal> header can be included to get
5949 * various low-level networking-related system headers, automatically
5950 * taking care of certain portability issues for you.
5952 * This can be used, for example, if you want to call setsockopt()
5955 * Note that while WinSock has many of the same APIs as the
5956 * traditional UNIX socket API, most of them behave at least slightly
5957 * differently (particularly with respect to error handling). If you
5958 * want your code to work under both UNIX and Windows, you will need
5959 * to take these differences into account.
5961 * Also, under glibc, certain non-portable functions are only visible
5962 * in the headers if you define <literal>_GNU_SOURCE</literal> before
5963 * including them. Note that this symbol must be defined before
5964 * including <emphasis>any</emphasis> headers, or it may not take
5970 * SECTION:gnetworkmonitor
5971 * @title: GNetworkMonitor
5972 * @short_description: Network status monitor
5973 * @include: gio/gio.h
5975 * #GNetworkMonitor provides an easy-to-use cross-platform API
5976 * for monitoring network connectivity. On Linux, the implementation
5977 * is based on the kernel's netlink interface.
5982 * SECTION:gnetworkservice
5983 * @short_description: A GSocketConnectable for resolving SRV records
5984 * @include: gio/gio.h
5986 * Like #GNetworkAddress does with hostnames, #GNetworkService
5987 * provides an easy way to resolve a SRV record, and then attempt to
5988 * connect to one of the hosts that implements that service, handling
5989 * service priority/weighting, multiple IP addresses, and multiple
5992 * See #GSrvTarget for more information about SRV records, and see
5993 * #GSocketConnectable for and example of using the connectable
5999 * SECTION:gnotification
6000 * @short_description: User Notifications (pop up messages)
6002 * #GNotification is a mechanism for creating a notification to be shown
6003 * to the user -- typically as a pop-up notification presented by the
6004 * desktop environment shell.
6006 * The key difference between #GNotification and other similar APIs is
6007 * that, if supported by the desktop environment, notifications sent
6008 * with #GNotification will persist after the application has exited,
6009 * and even across system reboots.
6011 * Since the user may click on a notification while the application is
6012 * not running, applications using #GNotification should be able to be
6013 * started as a D-Bus service, using #GApplication.
6015 * User interaction with a notification (either the default action, or
6016 * buttons) must be associated with actions on the application (ie:
6017 * "app." actions). It is not possible to route user interaction
6018 * through the notification itself, because the object will not exist if
6019 * the application is autostarted as a result of a notification being
6022 * A notification can be sent with g_application_send_notification().
6029 * SECTION:goutputstream
6030 * @short_description: Base class for implementing streaming output
6031 * @include: gio/gio.h
6033 * #GOutputStream has functions to write to a stream (g_output_stream_write()),
6034 * to close a stream (g_output_stream_close()) and to flush pending writes
6035 * (g_output_stream_flush()).
6037 * To copy the content of an input stream to an output stream without
6038 * manually handling the reads and writes, use g_output_stream_splice().
6040 * All of these functions have async variants too.
6045 * SECTION:gpermission
6046 * @title: GPermission
6047 * @short_description: An object representing the permission to perform
6050 * A #GPermission represents the status of the caller's permission to
6051 * perform a certain action.
6053 * You can query if the action is currently allowed and if it is
6054 * possible to acquire the permission so that the action will be allowed
6057 * There is also an API to actually acquire the permission and one to
6060 * As an example, a #GPermission might represent the ability for the
6061 * user to write to a #GSettings object. This #GPermission object could
6062 * then be used to decide if it is appropriate to show a "Click here to
6063 * unlock" button in a dialog and to provide the mechanism to invoke
6064 * when that button is clicked.
6069 * SECTION:gpollableinputstream
6070 * @short_description: Interface for pollable input streams
6071 * @include: gio/gio.h
6072 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
6074 * #GPollableInputStream is implemented by #GInputStreams that
6075 * can be polled for readiness to read. This can be used when
6076 * interfacing with a non-GIO API that expects
6077 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
6084 * SECTION:gpollableoutputstream
6085 * @short_description: Interface for pollable output streams
6086 * @include: gio/gio.h
6087 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
6089 * #GPollableOutputStream is implemented by #GOutputStreams that
6090 * can be polled for readiness to write. This can be used when
6091 * interfacing with a non-GIO API that expects
6092 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
6099 * SECTION:gpollableutils
6100 * @short_description: Utilities for pollable streams
6101 * @include: gio/gio.h
6103 * Utility functions for #GPollableInputStream and
6104 * #GPollableOutputStream implementations.
6109 * SECTION:gpropertyaction
6110 * @title: GPropertyAction
6111 * @short_description: A GAction reflecting a GObject property
6113 * A #GPropertyAction is a way to get a #GAction with a state value
6114 * reflecting and controlling the value of a #GObject property.
6116 * The state of the action will correspond to the value of the property.
6117 * Changing it will change the property (assuming the requested value
6118 * matches the requirements as specified in the #GParamSpec).
6120 * Only the most common types are presently supported. Booleans are
6121 * mapped to booleans, strings to strings, signed/unsigned integers to
6122 * int32/uint32 and floats and doubles to doubles.
6124 * If the property is an enum then the state will be string-typed and
6125 * conversion will automatically be performed between the enum value and
6126 * "nick" string as per the #GEnumValue table.
6128 * Flags types are not currently supported.
6130 * Properties of object types, boxed types and pointer types are not
6131 * supported and probably never will be.
6133 * Properties of #GVariant types are not currently supported.
6135 * If the property is boolean-valued then the action will have a NULL
6136 * parameter type, and activating the action (with no parameter) will
6137 * toggle the value of the property.
6139 * In all other cases, the parameter type will correspond to the type of
6142 * The general idea here is to reduce the number of locations where a
6143 * particular piece of state is kept (and therefore has to be
6144 * synchronised between). #GPropertyAction does not have a separate
6145 * state that is kept in sync with the property value -- its state
6146 * <em>is</em> the property value.
6148 * For example, it might be useful to create a #GAction corresponding to
6149 * the "visible-child-name" property of a #GtkStack so that the current
6150 * page can be switched from a menu. The active radio indication in the
6151 * menu is then directly determined from the active page of the
6154 * An anti-example would be binding the "active-id" property on a
6155 * #GtkComboBox. This is because the state of the combobox itself is
6156 * probably uninteresting and is actually being used to control
6159 * Another anti-example would be to bind to the "visible-child-name"
6160 * property of a #GtkStack if this value is actually stored in
6161 * #GSettings. In that case, the real source of the value is
6162 * #GSettings. If you want a #GAction to control a setting stored in
6163 * #GSettings, see g_settings_create_action() instead, and possibly
6164 * combine its use with g_settings_bind().
6172 * @short_description: Interface for proxy handling
6174 * A #GProxy handles connecting to a remote host via a given type of
6175 * proxy server. It is implemented by the 'gio-proxy' extension point.
6176 * The extensions are named after their proxy protocol name. As an
6177 * example, a SOCKS5 proxy implementation can be retrieved with the
6178 * name 'socks5' using the function
6179 * g_io_extension_point_get_extension_by_name().
6186 * SECTION:gproxyaddress
6187 * @short_description: An internet address with proxy information
6189 * Support for proxied #GInetSocketAddress.
6194 * SECTION:gproxyresolver
6195 * @short_description: Asynchronous and cancellable network proxy resolver
6196 * @include: gio/gio.h
6198 * #GProxyResolver provides synchronous and asynchronous network proxy
6199 * resolution. #GProxyResolver is used within #GSocketClient through
6200 * the method g_socket_connectable_proxy_enumerate().
6205 * SECTION:gremoteactiongroup
6206 * @title: GRemoteActionGroup
6207 * @short_description: A GActionGroup that interacts with other processes
6209 * The GRemoteActionGroup interface is implemented by #GActionGroup
6210 * instances that either transmit action invocations to other processes
6211 * or receive action invocations in the local process from other
6214 * The interface has <literal>_full</literal> variants of the two
6215 * methods on #GActionGroup used to activate actions:
6216 * g_action_group_activate_action() and
6217 * g_action_group_change_action_state(). These variants allow a
6218 * "platform data" #GVariant to be specified: a dictionary providing
6219 * context for the action invocation (for example: timestamps, startup
6220 * notification IDs, etc).
6222 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
6223 * mechanism to send platform data for action invocations over D-Bus.
6225 * Additionally, g_dbus_connection_export_action_group() will check if
6226 * the exported #GActionGroup implements #GRemoteActionGroup and use the
6227 * <literal>_full</literal> variants of the calls if available. This
6228 * provides a mechanism by which to receive platform data for action
6229 * invocations that arrive by way of D-Bus.
6237 * @short_description: Asynchronous and cancellable DNS resolver
6238 * @include: gio/gio.h
6240 * #GResolver provides cancellable synchronous and asynchronous DNS
6241 * resolution, for hostnames (g_resolver_lookup_by_address(),
6242 * g_resolver_lookup_by_name() and their async variants) and SRV
6243 * (service) records (g_resolver_lookup_service()).
6245 * #GNetworkAddress and #GNetworkService provide wrappers around
6246 * #GResolver functionality that also implement #GSocketConnectable,
6247 * making it easy to connect to a remote host/service.
6253 * @short_description: Resource framework
6254 * @include: gio/gio.h
6256 * Applications and libraries often contain binary or textual data that is really part of the
6257 * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
6258 * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
6259 * manually included as literal strings in the code.
6261 * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program
6262 * provide a convenient and efficient alternative to this which has some nice properties. You
6263 * maintain the files as normal files, so its easy to edit them, but during the build the files
6264 * are combined into a binary bundle that is linked into the executable. This means that loading
6265 * the resource files are efficient (as they are already in memory, shared with other instances) and
6266 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
6267 * also makes it easier to create relocatable applications.
6269 * Resource files can also be marked as compressed. Such files will be included in the resource bundle
6270 * in a compressed form, but will be automatically uncompressed when the resource is used. This
6271 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
6273 * Resource files can also be marked to be preprocessed, by setting the value of the
6274 * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
6275 * The only options currently supported are:
6277 * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip
6278 * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
6279 * environment variable must be set to the full path to the xmllint executable, or xmllint
6280 * must be in the PATH; otherwise the preprocessing step is skipped.
6282 * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert
6283 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
6284 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
6285 * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be
6286 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
6289 * Resource bundles are created by the <link linkend="glib-compile-resources">glib-compile-resources</link> program
6290 * which takes an xml file that describes the bundle, and a set of files that the xml references. These
6291 * are combined into a binary resource bundle.
6293 * <example id="resource-example"><title>Example resource description</title>
6294 * <programlisting><![CDATA[
6295 * <?xml version="1.0" encoding="UTF-8"?>
6297 * <gresource prefix="/org/gtk/Example">
6298 * <file>data/splashscreen.png</file>
6299 * <file compressed="true">dialog.ui</file>
6300 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
6303 * ]]></programlisting></example>
6305 * This will create a resource bundle with the following files:
6306 * <programlisting><![CDATA[
6307 * /org/gtk/Example/data/splashscreen.png
6308 * /org/gtk/Example/dialog.ui
6309 * /org/gtk/Example/menumarkup.xml
6310 * ]]></programlisting>
6312 * Note that all resources in the process share the same namespace, so use java-style
6313 * path prefixes (like in the above example) to avoid conflicts.
6315 * You can then use <link linkend="glib-compile-resources">glib-compile-resources</link> to compile the xml to a
6316 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
6317 * --generate-header arguments to create a source file and header to link directly into your application.
6319 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
6320 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
6321 * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
6322 * the resource data.
6324 * There are two forms of the generated source, the default version uses the compiler support for constructor
6325 * and destructor functions (where available) to automatically create and register the #GResource on startup
6326 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
6327 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
6328 * even on the minor ones where this is not available. (Constructor support is available for at least Win32, MacOS and Linux.)
6330 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
6331 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
6332 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
6333 * is for your own resources, and resource data is often used once, during parsing, and then released.
6341 * @short_description: Stream seeking interface
6342 * @include: gio/gio.h
6343 * @see_also: #GInputStream, #GOutputStream
6345 * #GSeekable is implemented by streams (implementations of
6346 * #GInputStream or #GOutputStream) that support seeking.
6348 * Seekable streams largely fall into two categories: resizable and
6351 * #GSeekable on fixed-sized streams is approximately the same as POSIX
6352 * lseek() on a block device (for example: attmepting to seek past the
6353 * end of the device is an error). Fixed streams typically cannot be
6356 * #GSeekable on resizable streams is approximately the same as POSIX
6357 * lseek() on a normal file. Seeking past the end and writing data will
6358 * usually cause the stream to resize by introducing zero bytes.
6364 * @short_description: High-level API for application settings
6366 * The #GSettings class provides a convenient API for storing and retrieving
6367 * application settings.
6369 * Reads and writes can be considered to be non-blocking. Reading
6370 * settings with #GSettings is typically extremely fast: on
6371 * approximately the same order of magnitude (but slower than) a
6372 * #GHashTable lookup. Writing settings is also extremely fast in terms
6373 * of time to return to your application, but can be extremely expensive
6374 * for other threads and other processes. Many settings backends
6375 * (including dconf) have lazy initialisation which means in the common
6376 * case of the user using their computer without modifying any settings
6377 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
6378 * even need to be started in this case. For this reason, you should
6379 * only ever modify #GSettings keys in response to explicit user action.
6380 * Particular care should be paid to ensure that modifications are not
6381 * made during startup -- for example, when setting the initial value
6382 * of preferences widgets. The built-in g_settings_bind() functionality
6383 * is careful not to write settings in response to notify signals as a
6384 * result of modifications that it makes to widgets.
6386 * When creating a GSettings instance, you have to specify a schema
6387 * that describes the keys in your settings and their types and default
6388 * values, as well as some other information.
6390 * Normally, a schema has as fixed path that determines where the settings
6391 * are stored in the conceptual global tree of settings. However, schemas
6392 * can also be 'relocatable', i.e. not equipped with a fixed path. This is
6393 * useful e.g. when the schema describes an 'account', and you want to be
6394 * able to store a arbitrary number of accounts.
6396 * Paths must start with and end with a forward slash character ('/')
6397 * and must not contain two sequential slash characters. Paths should
6398 * be chosen based on a domain name associated with the program or
6399 * library to which the settings belong. Examples of paths are
6400 * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
6401 * Paths should not start with "/apps/", "/desktop/" or "/system/" as
6402 * they often did in GConf.
6404 * Unlike other configuration systems (like GConf), GSettings does not
6405 * restrict keys to basic types like strings and numbers. GSettings stores
6406 * values as #GVariant, and allows any #GVariantType for keys. Key names
6407 * are restricted to lowercase characters, numbers and '-'. Furthermore,
6408 * the names must begin with a lowercase character, must not end
6409 * with a '-', and must not contain consecutive dashes.
6411 * Similar to GConf, the default values in GSettings schemas can be
6412 * localized, but the localized values are stored in gettext catalogs
6413 * and looked up with the domain that is specified in the
6414 * <tag class="attribute">gettext-domain</tag> attribute of the
6415 * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
6416 * elements and the category that is specified in the l10n attribute of the
6417 * <tag class="starttag">key</tag> element.
6419 * GSettings uses schemas in a compact binary form that is created
6420 * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
6421 * utility. The input is a schema description in an XML format that can be
6422 * described by the following DTD:
6423 * |[<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>]|
6425 * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
6427 * At runtime, schemas are identified by their id (as specified
6428 * in the <tag class="attribute">id</tag> attribute of the
6429 * <tag class="starttag">schema</tag> element). The
6430 * convention for schema ids is to use a dotted name, similar in
6431 * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
6432 * if the settings are for a specific service that owns a D-Bus bus name,
6433 * the D-Bus bus name and schema id should match. For schemas which deal
6434 * with settings not associated with one named application, the id should
6435 * not use StudlyCaps, e.g. "org.gnome.font-rendering".
6437 * In addition to #GVariant types, keys can have types that have enumerated
6438 * types. These can be described by a <tag class="starttag">choice</tag>,
6439 * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
6440 * <xref linkend="schema-enumerated"/>. The underlying type of
6441 * such a key is string, but you can use g_settings_get_enum(),
6442 * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
6443 * access the numeric values corresponding to the string value of enum
6446 * <example id="schema-default-values"><title>Default values</title>
6447 * <programlisting><![CDATA[
6449 * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
6451 * <key name="greeting" type="s">
6452 * <default l10n="messages">"Hello, earthlings"</default>
6453 * <summary>A greeting</summary>
6455 * Greeting of the invading martians
6459 * <key name="box" type="(ii)">
6460 * <default>(20,30)</default>
6465 * ]]></programlisting></example>
6467 * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
6468 * <programlisting><![CDATA[
6471 * <enum id="org.gtk.Test.myenum">
6472 * <value nick="first" value="1"/>
6473 * <value nick="second" value="2"/>
6476 * <flags id="org.gtk.Test.myflags">
6477 * <value nick="flag1" value="1"/>
6478 * <value nick="flag2" value="2"/>
6479 * <value nick="flag3" value="4"/>
6482 * <schema id="org.gtk.Test">
6484 * <key name="key-with-range" type="i">
6485 * <range min="1" max="100"/>
6486 * <default>10</default>
6489 * <key name="key-with-choices" type="s">
6491 * <choice value='Elisabeth'/>
6492 * <choice value='Annabeth'/>
6493 * <choice value='Joe'/>
6496 * <alias value='Anna' target='Annabeth'/>
6497 * <alias value='Beth' target='Elisabeth'/>
6499 * <default>'Joe'</default>
6502 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
6503 * <default>'first'</default>
6506 * <key name='flags-key' flags='org.gtk.Test.myflags'>
6507 * <default>["flag1",flag2"]</default>
6511 * ]]></programlisting></example>
6514 * <title>Vendor overrides</title>
6516 * Default values are defined in the schemas that get installed by
6517 * an application. Sometimes, it is necessary for a vendor or distributor
6518 * to adjust these defaults. Since patching the XML source for the schema
6519 * is inconvenient and error-prone,
6520 * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
6521 * so-called 'vendor override' files. These are keyfiles in the same
6522 * directory as the XML schema sources which can override default values.
6523 * The schema id serves as the group name in the key file, and the values
6524 * are expected in serialized GVariant form, as in the following example:
6525 * <informalexample><programlisting>
6529 * </programlisting></informalexample>
6532 * glib-compile-schemas expects schema files to have the extension
6533 * <filename>.gschema.override</filename>
6538 * <title>Binding</title>
6540 * A very convenient feature of GSettings lets you bind #GObject properties
6541 * directly to settings, using g_settings_bind(). Once a GObject property
6542 * has been bound to a setting, changes on either side are automatically
6543 * propagated to the other side. GSettings handles details like
6544 * mapping between GObject and GVariant types, and preventing infinite
6548 * This makes it very easy to hook up a preferences dialog to the
6549 * underlying settings. To make this even more convenient, GSettings
6550 * looks for a boolean property with the name "sensitivity" and
6551 * automatically binds it to the writability of the bound setting.
6552 * If this 'magic' gets in the way, it can be suppressed with the
6553 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
6560 * SECTION:gsettingsbackend
6561 * @title: GSettingsBackend
6562 * @short_description: Interface for settings backend implementations
6563 * @include: gio/gsettingsbackend.h
6564 * @see_also: #GSettings, #GIOExtensionPoint
6566 * The #GSettingsBackend interface defines a generic interface for
6567 * non-strictly-typed data that is stored in a hierarchy. To implement
6568 * an alternative storage backend for #GSettings, you need to implement
6569 * the #GSettingsBackend interface and then make it implement the
6570 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
6572 * The interface defines methods for reading and writing values, a
6573 * method for determining if writing of certain values will fail
6574 * (lockdown) and a change notification mechanism.
6576 * The semantics of the interface are very precisely defined and
6577 * implementations must carefully adhere to the expectations of
6578 * callers that are documented on each of the interface methods.
6580 * Some of the GSettingsBackend functions accept or return a #GTree.
6581 * These trees always have strings as keys and #GVariant as values.
6582 * g_settings_backend_create_tree() is a convenience function to create
6586 * The #GSettingsBackend API is exported to allow third-party
6587 * implementations, but does not carry the same stability guarantees
6588 * as the public GIO API. For this reason, you have to define the
6589 * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
6590 * <filename>gio/gsettingsbackend.h</filename>
6596 * SECTION:gsettingsschema
6597 * @short_description: Introspecting and controlling the loading of
6600 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
6601 * mechanism for advanced control over the loading of schemas and a
6602 * mechanism for introspecting their content.
6604 * Plugin loading systems that wish to provide plugins a way to access
6605 * settings face the problem of how to make the schemas for these
6606 * settings visible to GSettings. Typically, a plugin will want to ship
6607 * the schema along with itself and it won't be installed into the
6608 * standard system directories for schemas.
6610 * #GSettingsSchemaSource provides a mechanism for dealing with this by
6611 * allowing the creation of a new 'schema source' from which schemas can
6612 * be acquired. This schema source can then become part of the metadata
6613 * associated with the plugin and queried whenever the plugin requires
6614 * access to some settings.
6616 * Consider the following example:
6622 * GSettingsSchemaSource *schema_source;
6627 * initialise_plugin (const gchar *dir)
6633 * plugin->schema_source =
6634 * g_settings_new_schema_source_from_directory (dir,
6635 * g_settings_schema_source_get_default (), FALSE, NULL);
6645 * plugin_get_settings (Plugin *plugin,
6646 * const gchar *schema_id)
6648 * GSettingsSchema *schema;
6650 * if (schema_id == NULL)
6651 * schema_id = plugin->identifier;
6653 * schema = g_settings_schema_source_lookup (plugin->schema_source,
6654 * schema_id, FALSE);
6656 * if (schema == NULL)
6658 * ... disable the plugin or abort, etc ...
6661 * return g_settings_new_full (schema, NULL, NULL);
6665 * The code above shows how hooks should be added to the code that
6666 * initialises (or enables) the plugin to create the schema source and
6667 * how an API can be added to the plugin system to provide a convenient
6668 * way for the plugin to access its settings, using the schemas that it
6671 * From the standpoint of the plugin, it would need to ensure that it
6672 * ships a gschemas.compiled file as part of itself, and then simply do
6677 * GSettings *settings;
6680 * settings = plugin_get_settings (self, NULL);
6681 * some_value = g_settings_get_int (settings, "some-value");
6686 * It's also possible that the plugin system expects the schema source
6687 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
6688 * In that case, the plugin loading system must compile the schemas for
6689 * itself before attempting to create the settings source.
6696 * SECTION:gsimpleaction
6697 * @title: GSimpleAction
6698 * @short_description: A simple GAction implementation
6700 * A #GSimpleAction is the obvious simple implementation of the #GAction
6701 * interface. This is the easiest way to create an action for purposes of
6702 * adding it to a #GSimpleActionGroup.
6704 * See also #GtkAction.
6709 * SECTION:gsimpleactiongroup
6710 * @title: GSimpleActionGroup
6711 * @short_description: A simple GActionGroup implementation
6713 * #GSimpleActionGroup is a hash table filled with #GAction objects,
6714 * implementing the #GActionGroup and #GActionMap interfaces.
6719 * SECTION:gsimpleasyncresult
6720 * @short_description: Simple asynchronous results implementation
6721 * @include: gio/gio.h
6722 * @see_also: #GAsyncResult
6725 * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
6726 * #GTask, which provides a simpler API.
6729 * #GSimpleAsyncResult implements #GAsyncResult.
6731 * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
6732 * reporting, operation cancellation and the final state of an operation,
6733 * completely transparent to the application. Results can be returned
6734 * as a pointer e.g. for functions that return data that is collected
6735 * asynchronously, a boolean value for checking the success or failure
6736 * of an operation, or a #gssize for operations which return the number
6737 * of bytes modified by the operation; all of the simple return cases
6740 * Most of the time, an application will not need to know of the details
6741 * of this API; it is handled transparently, and any necessary operations
6742 * are handled by #GAsyncResult's interface. However, if implementing a
6743 * new GIO module, for writing language bindings, or for complex
6744 * applications that need better control of how asynchronous operations
6745 * are completed, it is important to understand this functionality.
6747 * GSimpleAsyncResults are tagged with the calling function to ensure
6748 * that asynchronous functions and their finishing functions are used
6749 * together correctly.
6751 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
6752 * If the result needs to be created for a #GError, use
6753 * g_simple_async_result_new_from_error() or
6754 * g_simple_async_result_new_take_error(). If a #GError is not available
6755 * (e.g. the asynchronous operation's doesn't take a #GError argument),
6756 * but the result still needs to be created for an error condition, use
6757 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
6758 * if your application or binding requires passing a variable argument list
6759 * directly), and the error can then be propagated through the use of
6760 * g_simple_async_result_propagate_error().
6762 * An asynchronous operation can be made to ignore a cancellation event by
6763 * calling g_simple_async_result_set_handle_cancellation() with a
6764 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
6765 * operations that are dangerous to cancel, such as close (which would
6766 * cause a leak if cancelled before being run).
6768 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
6769 * or it can use #GThread<!-- -->s.
6770 * g_simple_async_result_complete() will finish an I/O task directly
6771 * from the point where it is called. g_simple_async_result_complete_in_idle()
6772 * will finish it from an idle handler in the <link
6773 * linkend="g-main-context-push-thread-default">thread-default main
6774 * context</link>. g_simple_async_result_run_in_thread() will run the
6775 * job in a separate thread and then deliver the result to the
6776 * thread-default main context.
6778 * To set the results of an asynchronous function,
6779 * g_simple_async_result_set_op_res_gpointer(),
6780 * g_simple_async_result_set_op_res_gboolean(), and
6781 * g_simple_async_result_set_op_res_gssize()
6782 * are provided, setting the operation's result to a gpointer, gboolean, or
6783 * gssize, respectively.
6785 * Likewise, to get the result of an asynchronous function,
6786 * g_simple_async_result_get_op_res_gpointer(),
6787 * g_simple_async_result_get_op_res_gboolean(), and
6788 * g_simple_async_result_get_op_res_gssize() are
6789 * provided, getting the operation's result as a gpointer, gboolean, and
6790 * gssize, respectively.
6792 * For the details of the requirements implementations must respect, see
6793 * #GAsyncResult. A typical implementation of an asynchronous operation
6794 * using GSimpleAsyncResult looks something like this:
6798 * baked_cb (Cake *cake,
6799 * gpointer user_data)
6801 * /* In this example, this callback is not given a reference to the cake, so
6802 * * the GSimpleAsyncResult has to take a reference to it.
6804 * GSimpleAsyncResult *result = user_data;
6807 * g_simple_async_result_set_error (result,
6809 * BAKER_ERROR_NO_FLOUR,
6810 * "Go to the supermarket");
6812 * g_simple_async_result_set_op_res_gpointer (result,
6813 * g_object_ref (cake),
6817 * /* In this example, we assume that baked_cb is called as a callback from
6818 * * the mainloop, so it's safe to complete the operation synchronously here.
6819 * * If, however, _baker_prepare_cake () might call its callback without
6820 * * first returning to the mainloop — inadvisable, but some APIs do so —
6821 * * we would need to use g_simple_async_result_complete_in_idle().
6823 * g_simple_async_result_complete (result);
6824 * g_object_unref (result);
6828 * baker_bake_cake_async (Baker *self,
6830 * GAsyncReadyCallback callback,
6831 * gpointer user_data)
6833 * GSimpleAsyncResult *simple;
6838 * g_simple_async_report_error_in_idle (G_OBJECT (self),
6842 * BAKER_ERROR_TOO_SMALL,
6843 * "%ucm radius cakes are silly",
6848 * simple = g_simple_async_result_new (G_OBJECT (self),
6851 * baker_bake_cake_async);
6852 * cake = _baker_get_cached_cake (self, radius);
6856 * g_simple_async_result_set_op_res_gpointer (simple,
6857 * g_object_ref (cake),
6859 * g_simple_async_result_complete_in_idle (simple);
6860 * g_object_unref (simple);
6861 * /* Drop the reference returned by _baker_get_cached_cake(); the
6862 * * GSimpleAsyncResult has taken its own reference.
6864 * g_object_unref (cake);
6868 * _baker_prepare_cake (self, radius, baked_cb, simple);
6872 * baker_bake_cake_finish (Baker *self,
6873 * GAsyncResult *result,
6876 * GSimpleAsyncResult *simple;
6879 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
6881 * baker_bake_cake_async),
6884 * simple = (GSimpleAsyncResult *) result;
6886 * if (g_simple_async_result_propagate_error (simple, error))
6889 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
6890 * return g_object_ref (cake);
6897 * SECTION:gsimplepermission
6898 * @title: GSimplePermission
6899 * @short_description: A GPermission that doesn't change value
6901 * #GSimplePermission is a trivial implementation of #GPermission that
6902 * represents a permission that is either always or never allowed. The
6903 * value is given at construction and doesn't change.
6905 * Calling request or release will result in errors.
6910 * SECTION:gsimpleproxyresolver
6911 * @short_description: Simple proxy resolver implementation
6912 * @include: gio/gio.h
6913 * @see_also: g_socket_client_set_proxy_resolver()
6915 * #GSimpleProxyResolver is a simple #GProxyResolver implementation
6916 * that handles a single default proxy, multiple URI-scheme-specific
6917 * proxies, and a list of hosts that proxies should not be used for.
6919 * #GSimpleProxyResolver is never the default proxy resolver, but it
6920 * can be used as the base class for another proxy resolver
6921 * implementation, or it can be created and used manually, such as
6922 * with g_socket_client_set_proxy_resolver().
6930 * @short_description: Low-level socket object
6931 * @include: gio/gio.h
6932 * @see_also: #GInitable, <link linkend="gio-gnetworking.h">gnetworking.h</link>
6934 * A #GSocket is a low-level networking primitive. It is a more or less
6935 * direct mapping of the BSD socket API in a portable GObject based API.
6936 * It supports both the UNIX socket implementations and winsock2 on Windows.
6938 * #GSocket is the platform independent base upon which the higher level
6939 * network primitives are based. Applications are not typically meant to
6940 * use it directly, but rather through classes like #GSocketClient,
6941 * #GSocketService and #GSocketConnection. However there may be cases where
6942 * direct use of #GSocket is useful.
6944 * #GSocket implements the #GInitable interface, so if it is manually constructed
6945 * by e.g. g_object_new() you must call g_initable_init() and check the
6946 * results before using the object. This is done automatically in
6947 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
6950 * Sockets operate in two general modes, blocking or non-blocking. When
6951 * in blocking mode all operations block until the requested operation
6952 * is finished or there is an error. In non-blocking mode all calls that
6953 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
6954 * To know when a call would successfully run you can call g_socket_condition_check(),
6955 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
6956 * attach it to a #GMainContext to get callbacks when I/O is possible.
6957 * Note that all sockets are always set to non blocking mode in the system, and
6958 * blocking mode is emulated in GSocket.
6960 * When working in non-blocking mode applications should always be able to
6961 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
6962 * function said that I/O was possible. This can easily happen in case
6963 * of a race condition in the application, but it can also happen for other
6964 * reasons. For instance, on Windows a socket is always seen as writable
6965 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
6967 * #GSocket<!-- -->s can be either connection oriented or datagram based.
6968 * For connection oriented types you must first establish a connection by
6969 * either connecting to an address or accepting a connection from another
6970 * address. For connectionless socket types the target/source address is
6971 * specified or received in each I/O operation.
6973 * All socket file descriptors are set to be close-on-exec.
6975 * Note that creating a #GSocket causes the signal %SIGPIPE to be
6976 * ignored for the remainder of the program. If you are writing a
6977 * command-line utility that uses #GSocket, you may need to take into
6978 * account the fact that your program will not automatically be killed
6979 * if it tries to write to %stdout after it has been closed.
6986 * SECTION:gsocketaddress
6987 * @short_description: Abstract base class representing endpoints for
6988 * socket communication
6990 * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
6991 * in the BSD sockets API. This is an abstract class; use
6992 * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
6993 * for UNIX domain sockets.
6998 * SECTION:gsocketclient
6999 * @short_description: Helper for connecting to a network service
7000 * @include: gio/gio.h
7001 * @see_also: #GSocketConnection, #GSocketListener
7003 * #GSocketClient is a lightweight high-level utility class for connecting to
7004 * a network host using a connection oriented socket type.
7006 * You create a #GSocketClient object, set any options you want, and then
7007 * call a sync or async connect operation, which returns a #GSocketConnection
7008 * subclass on success.
7010 * The type of the #GSocketConnection object returned depends on the type of
7011 * the underlying socket that is in use. For instance, for a TCP/IP connection
7012 * it will be a #GTcpConnection.
7014 * As #GSocketClient is a lightweight object, you don't need to cache it. You
7015 * can just create a new one any time you need one.
7022 * SECTION:gsocketconnectable
7023 * @short_description: Interface for potential socket endpoints
7025 * Objects that describe one or more potential socket endpoints
7026 * implement #GSocketConnectable. Callers can then use
7027 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
7028 * to try out each socket address in turn until one succeeds, as shown
7029 * in the sample code below.
7032 * MyConnectionType *
7033 * connect_to_host (const char *hostname,
7035 * GCancellable *cancellable,
7038 * MyConnection *conn = NULL;
7039 * GSocketConnectable *addr;
7040 * GSocketAddressEnumerator *enumerator;
7041 * GSocketAddress *sockaddr;
7042 * GError *conn_error = NULL;
7044 * addr = g_network_address_new (hostname, port);
7045 * enumerator = g_socket_connectable_enumerate (addr);
7046 * g_object_unref (addr);
7048 * /<!-- -->* Try each sockaddr until we succeed. Record the first
7049 * * connection error, but not any further ones (since they'll probably
7050 * * be basically the same as the first).
7052 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
7054 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
7055 * g_object_unref (sockaddr);
7057 * g_object_unref (enumerator);
7063 * /<!-- -->* We couldn't connect to the first address, but we succeeded
7064 * * in connecting to a later address.
7066 * g_error_free (conn_error);
7072 * /<!-- -->* Either the initial lookup failed, or else the caller
7076 * g_error_free (conn_error);
7081 * g_error_propagate (error, conn_error);
7090 * SECTION:gsocketconnection
7091 * @short_description: A socket connection
7092 * @include: gio/gio.h
7093 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
7095 * #GSocketConnection is a #GIOStream for a connected socket. They
7096 * can be created either by #GSocketClient when connecting to a host,
7097 * or by #GSocketListener when accepting a new client.
7099 * The type of the #GSocketConnection object returned from these calls
7100 * depends on the type of the underlying socket that is in use. For
7101 * instance, for a TCP/IP connection it will be a #GTcpConnection.
7103 * Choosing what type of object to construct is done with the socket
7104 * connection factory, and it is possible for 3rd parties to register
7105 * custom socket connection types for specific combination of socket
7106 * family/type/protocol using g_socket_connection_factory_register_type().
7113 * SECTION:gsocketcontrolmessage
7114 * @title: GSocketControlMessage
7115 * @short_description: A GSocket control message
7116 * @see_also: #GSocket.
7118 * A #GSocketControlMessage is a special-purpose utility message that
7119 * can be sent to or received from a #GSocket. These types of
7120 * messages are often called "ancillary data".
7122 * The message can represent some sort of special instruction to or
7123 * information from the socket or can represent a special kind of
7124 * transfer to the peer (for example, sending a file descriptor over
7127 * These messages are sent with g_socket_send_message() and received
7128 * with g_socket_receive_message().
7130 * To extend the set of control message that can be sent, subclass this
7131 * class and override the get_size, get_level, get_type and serialize
7134 * To extend the set of control messages that can be received, subclass
7135 * this class and implement the deserialize method. Also, make sure your
7136 * class is registered with the GType typesystem before calling
7137 * g_socket_receive_message() to read such a message.
7144 * SECTION:gsocketlistener
7145 * @title: GSocketListener
7146 * @short_description: Helper for accepting network client connections
7147 * @see_also: #GThreadedSocketService, #GSocketService.
7149 * A #GSocketListener is an object that keeps track of a set
7150 * of server sockets and helps you accept sockets from any of the
7151 * socket, either sync or async.
7153 * If you want to implement a network server, also look at #GSocketService
7154 * and #GThreadedSocketService which are subclass of #GSocketListener
7155 * that makes this even easier.
7162 * SECTION:gsocketservice
7163 * @title: GSocketService
7164 * @short_description: Make it easy to implement a network service
7165 * @see_also: #GThreadedSocketService, #GSocketListener.
7167 * A #GSocketService is an object that represents a service that
7168 * is provided to the network or over local sockets. When a new
7169 * connection is made to the service the #GSocketService::incoming
7170 * signal is emitted.
7172 * A #GSocketService is a subclass of #GSocketListener and you need
7173 * to add the addresses you want to accept connections on with the
7174 * #GSocketListener APIs.
7176 * There are two options for implementing a network service based on
7177 * #GSocketService. The first is to create the service using
7178 * g_socket_service_new() and to connect to the #GSocketService::incoming
7179 * signal. The second is to subclass #GSocketService and override the
7180 * default signal handler implementation.
7182 * In either case, the handler must immediately return, or else it
7183 * will block additional incoming connections from being serviced.
7184 * If you are interested in writing connection handlers that contain
7185 * blocking code then see #GThreadedSocketService.
7187 * The socket service runs on the main loop of the <link
7188 * linkend="g-main-context-push-thread-default-context">thread-default
7189 * context</link> of the thread it is created in, and is not
7190 * threadsafe in general. However, the calls to start and stop the
7191 * service are thread-safe so these can be used from threads that
7192 * handle incoming clients.
7199 * SECTION:gsrvtarget
7200 * @short_description: DNS SRV record target
7201 * @include: gio/gio.h
7203 * SRV (service) records are used by some network protocols to provide
7204 * service-specific aliasing and load-balancing. For example, XMPP
7205 * (Jabber) uses SRV records to locate the XMPP server for a domain;
7206 * rather than connecting directly to "example.com" or assuming a
7207 * specific server hostname like "xmpp.example.com", an XMPP client
7208 * would look up the "xmpp-client" SRV record for "example.com", and
7209 * then connect to whatever host was pointed to by that record.
7211 * You can use g_resolver_lookup_service() or
7212 * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
7213 * for a given service. However, if you are simply planning to connect
7214 * to the remote service, you can use #GNetworkService's
7215 * #GSocketConnectable interface and not need to worry about
7216 * #GSrvTarget at all.
7221 * SECTION:gsubprocess
7222 * @title: GSubprocess
7223 * @short_description: Child processes
7224 * @see_also: #GSubprocessLauncher
7226 * #GSubprocess allows the creation of and interaction with child
7229 * Processes can be communicated with using standard GIO-style APIs (ie:
7230 * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
7231 * process termination (ie: cancellable and with an asynchronous
7234 * There is an API to force a process to terminate, as well as a
7235 * race-free API for sending UNIX signals to a subprocess.
7237 * One major advantage that GIO brings over the core GLib library is
7238 * comprehensive API for asynchronous I/O, such
7239 * g_output_stream_splice_async(). This makes GSubprocess
7240 * significantly more powerful and flexible than equivalent APIs in
7241 * some other languages such as the <literal>subprocess.py</literal>
7242 * included with Python. For example, using #GSubprocess one could
7243 * create two child processes, reading standard output from the first,
7244 * processing it, and writing to the input stream of the second, all
7245 * without blocking the main loop.
7247 * A powerful g_subprocess_communicate() API is provided similar to the
7248 * <literal>communicate()</literal> method of
7249 * <literal>subprocess.py</literal>. This enables very easy interaction
7250 * with a subprocess that has been opened with pipes.
7252 * #GSubprocess defaults to tight control over the file descriptors open
7253 * in the child process, avoiding dangling-fd issues that are caused by
7254 * a simple fork()/exec(). The only open file descriptors in the
7255 * spawned process are ones that were explicitly specified by the
7256 * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
7259 * #GSubprocess will quickly reap all child processes as they exit,
7260 * avoiding "zombie processes" remaining around for long periods of
7261 * time. g_subprocess_wait() can be used to wait for this to happen,
7262 * but it will happen even without the call being explicitly made.
7264 * As a matter of principle, #GSubprocess has no API that accepts
7265 * shell-style space-separated strings. It will, however, match the
7266 * typical shell behaviour of searching the PATH for executables that do
7267 * not contain a directory separator in their name.
7269 * #GSubprocess attempts to have a very simple API for most uses (ie:
7270 * spawning a subprocess with arguments and support for most typical
7271 * kinds of input and output redirection). See g_subprocess_new(). The
7272 * #GSubprocessLauncher API is provided for more complicated cases
7273 * (advanced types of redirection, environment variable manipulation,
7274 * change of working directory, child setup functions, etc).
7276 * A typical use of #GSubprocess will involve calling
7277 * g_subprocess_new(), followed by g_subprocess_wait() or
7278 * g_subprocess_wait_sync(). After the process exits, the status can be
7279 * checked using functions such as g_subprocess_get_if_exited() (which
7280 * are similar to the familiar WIFEXITED-style POSIX macros).
7287 * SECTION:gsubprocesslauncher
7288 * @title: GSubprocess Launcher
7289 * @short_description: Environment options for launching a child process
7291 * This class contains a set of options for launching child processes,
7292 * such as where its standard input and output will be directed, the
7293 * argument list, the environment, and more.
7295 * While the #GSubprocess class has high level functions covering
7296 * popular cases, use of this class allows access to more advanced
7297 * options. It can also be used to launch multiple subprocesses with
7298 * a similar configuration.
7306 * @short_description: Cancellable synchronous or asynchronous task and result
7307 * @include: gio/gio.h
7308 * @see_also: #GAsyncResult
7311 * A #GTask represents and manages a cancellable "task".
7314 * <title>Asynchronous operations</title>
7316 * The most common usage of #GTask is as a #GAsyncResult, to
7317 * manage data during an asynchronous operation. You call
7318 * g_task_new() in the "start" method, followed by
7319 * g_task_set_task_data() and the like if you need to keep some
7320 * additional data associated with the task, and then pass the
7321 * task object around through your asynchronous operation.
7322 * Eventually, you will call a method such as
7323 * g_task_return_pointer() or g_task_return_error(), which will
7324 * save the value you give it and then invoke the task's callback
7325 * function (waiting until the next iteration of the main
7326 * loop first, if necessary). The caller will pass the #GTask back
7327 * to the operation's finish function (as a #GAsyncResult), and
7328 * you can use g_task_propagate_pointer() or the like to extract
7331 * <example id="gtask-async"><title>GTask as a GAsyncResult</title>
7334 * CakeFrostingType frosting;
7339 * decoration_data_free (DecorationData *decoration)
7341 * g_free (decoration->message);
7342 * g_slice_free (DecorationData, decoration);
7346 * baked_cb (Cake *cake,
7347 * gpointer user_data)
7349 * GTask *task = user_data;
7350 * DecorationData *decoration = g_task_get_task_data (task);
7351 * GError *error = NULL;
7355 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
7356 * "Go to the supermarket");
7357 * g_object_unref (task);
7361 * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error))
7363 * g_object_unref (cake);
7364 * /* g_task_return_error() takes ownership of error */
7365 * g_task_return_error (task, error);
7366 * g_object_unref (task);
7370 * g_task_return_pointer (task, cake, g_object_unref);
7371 * g_object_unref (task);
7375 * baker_bake_cake_async (Baker *self,
7377 * CakeFlavor flavor,
7378 * CakeFrostingType frosting,
7379 * const char *message,
7380 * GCancellable *cancellable,
7381 * GAsyncReadyCallback callback,
7382 * gpointer user_data)
7385 * DecorationData *decoration;
7388 * task = g_task_new (self, cancellable, callback, user_data);
7391 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL,
7392 * "%ucm radius cakes are silly",
7394 * g_object_unref (task);
7398 * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message);
7401 * /* _baker_get_cached_cake() returns a reffed cake */
7402 * g_task_return_pointer (task, cake, g_object_unref);
7403 * g_object_unref (task);
7407 * decoration = g_slice_new (DecorationData);
7408 * decoration->frosting = frosting;
7409 * decoration->message = g_strdup (message);
7410 * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free);
7412 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
7416 * baker_bake_cake_finish (Baker *self,
7417 * GAsyncResult *result,
7420 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7422 * return g_task_propagate_pointer (G_TASK (result), error);
7428 * <title>Chained asynchronous operations</title>
7430 * #GTask also tries to simplify asynchronous operations that
7431 * internally chain together several smaller asynchronous
7432 * operations. g_task_get_cancellable(), g_task_get_context(), and
7433 * g_task_get_priority() allow you to get back the task's
7434 * #GCancellable, #GMainContext, and <link
7435 * linkend="io-priority">I/O priority</link> when starting a new
7436 * subtask, so you don't have to keep track of them yourself.
7437 * g_task_attach_source() simplifies the case of waiting for a
7438 * source to fire (automatically using the correct #GMainContext
7441 * <example id="gtask-chained"><title>Chained asynchronous operations</title>
7445 * CakeFrostingType frosting;
7450 * decoration_data_free (BakingData *bd)
7453 * g_object_unref (bd->cake);
7454 * g_free (bd->message);
7455 * g_slice_free (BakingData, bd);
7459 * decorated_cb (Cake *cake,
7460 * GAsyncResult *result,
7461 * gpointer user_data)
7463 * GTask *task = user_data;
7464 * GError *error = NULL;
7466 * if (!cake_decorate_finish (cake, result, &error))
7468 * g_object_unref (cake);
7469 * g_task_return_error (task, error);
7470 * g_object_unref (task);
7474 * /* baking_data_free() will drop its ref on the cake, so
7475 * * we have to take another here to give to the caller.
7477 * g_task_return_pointer (result, g_object_ref (cake), g_object_unref);
7478 * g_object_unref (task);
7482 * decorator_ready (gpointer user_data)
7484 * GTask *task = user_data;
7485 * BakingData *bd = g_task_get_task_data (task);
7487 * cake_decorate_async (bd->cake, bd->frosting, bd->message,
7488 * g_task_get_cancellable (task),
7489 * decorated_cb, task);
7493 * baked_cb (Cake *cake,
7494 * gpointer user_data)
7496 * GTask *task = user_data;
7497 * BakingData *bd = g_task_get_task_data (task);
7498 * GError *error = NULL;
7502 * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR,
7503 * "Go to the supermarket");
7504 * g_object_unref (task);
7510 * /* Bail out now if the user has already cancelled */
7511 * if (g_task_return_error_if_cancelled (g_task_get_cancellable (task)))
7513 * g_object_unref (task);
7517 * if (cake_decorator_available (cake))
7518 * decorator_ready (task);
7523 * source = cake_decorator_wait_source_new (cake);
7524 * /* Attach @source to @task's GMainContext and have it call
7525 * * decorator_ready() when it is ready.
7527 * g_task_attach_source (task, source,
7528 * G_CALLBACK (decorator_ready));
7529 * g_source_unref (source);
7534 * baker_bake_cake_async (Baker *self,
7536 * CakeFlavor flavor,
7537 * CakeFrostingType frosting,
7538 * const char *message,
7540 * GCancellable *cancellable,
7541 * GAsyncReadyCallback callback,
7542 * gpointer user_data)
7547 * task = g_task_new (self, cancellable, callback, user_data);
7548 * g_task_set_priority (task, priority);
7550 * bd = g_slice_new0 (BakingData);
7551 * bd->frosting = frosting;
7552 * bd->message = g_strdup (message);
7553 * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free);
7555 * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task);
7559 * baker_bake_cake_finish (Baker *self,
7560 * GAsyncResult *result,
7563 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7565 * return g_task_propagate_pointer (G_TASK (result), error);
7571 * <title>Asynchronous operations from synchronous ones</title>
7573 * You can use g_task_run_in_thread() to turn a synchronous
7574 * operation into an asynchronous one, by running it in a thread
7575 * which will then dispatch the result back to the caller's
7576 * #GMainContext when it completes.
7578 * <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title>
7582 * CakeFlavor flavor;
7583 * CakeFrostingType frosting;
7588 * cake_data_free (CakeData *cake_data)
7590 * g_free (cake_data->message);
7591 * g_slice_free (CakeData, cake_data);
7595 * bake_cake_thread (GTask *task,
7596 * gpointer source_object,
7597 * gpointer task_data,
7598 * GCancellable *cancellable)
7600 * Baker *self = source_object;
7601 * CakeData *cake_data = task_data;
7603 * GError *error = NULL;
7605 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7606 * cake_data->frosting, cake_data->message,
7607 * cancellable, &error);
7609 * g_task_return_pointer (task, cake, g_object_unref);
7611 * g_task_return_error (task, error);
7615 * baker_bake_cake_async (Baker *self,
7617 * CakeFlavor flavor,
7618 * CakeFrostingType frosting,
7619 * const char *message,
7620 * GCancellable *cancellable,
7621 * GAsyncReadyCallback callback,
7622 * gpointer user_data)
7624 * CakeData *cake_data;
7627 * cake_data = g_slice_new (CakeData);
7628 * cake_data->radius = radius;
7629 * cake_data->flavor = flavor;
7630 * cake_data->frosting = frosting;
7631 * cake_data->message = g_strdup (message);
7632 * task = g_task_new (self, cancellable, callback, user_data);
7633 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7634 * g_task_run_in_thread (task, bake_cake_thread);
7638 * baker_bake_cake_finish (Baker *self,
7639 * GAsyncResult *result,
7642 * g_return_val_if_fail (g_task_is_valid (result, self), NULL);
7644 * return g_task_propagate_pointer (G_TASK (result), error);
7650 * <title>Adding cancellability to uncancellable tasks</title>
7652 * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
7653 * can be used to turn an uncancellable operation into a
7654 * cancellable one. If you call g_task_set_return_on_cancel(),
7655 * passing %TRUE, then if the task's #GCancellable is cancelled,
7656 * it will return control back to the caller immediately, while
7657 * allowing the task thread to continue running in the background
7658 * (and simply discarding its result when it finally does finish).
7659 * Provided that the task thread is careful about how it uses
7660 * locks and other externally-visible resources, this allows you
7661 * to make "GLib-friendly" asynchronous and cancellable
7662 * synchronous variants of blocking APIs.
7664 * <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title>
7667 * bake_cake_thread (GTask *task,
7668 * gpointer source_object,
7669 * gpointer task_data,
7670 * GCancellable *cancellable)
7672 * Baker *self = source_object;
7673 * CakeData *cake_data = task_data;
7675 * GError *error = NULL;
7677 * cake = bake_cake (baker, cake_data->radius, cake_data->flavor,
7678 * cake_data->frosting, cake_data->message,
7682 * g_task_return_error (task, error);
7686 * /* If the task has already been cancelled, then we don't
7687 * * want to add the cake to the cake cache. Likewise, we don't
7688 * * want to have the task get cancelled in the middle of
7689 * * updating the cache. g_task_set_return_on_cancel() will
7690 * * return %TRUE here if it managed to disable return-on-cancel,
7691 * * or %FALSE if the task was cancelled before it could.
7693 * if (g_task_set_return_on_cancel (task, FALSE))
7695 * /* If the caller cancels at this point, their
7696 * * GAsyncReadyCallback won't be invoked until we return,
7697 * * so we don't have to worry that this code will run at
7698 * * the same time as that code does. But if there were
7699 * * other functions that might look at the cake cache,
7700 * * then we'd probably need a GMutex here as well.
7702 * baker_add_cake_to_cache (baker, cake);
7703 * g_task_return_pointer (task, cake, g_object_unref);
7708 * baker_bake_cake_async (Baker *self,
7710 * CakeFlavor flavor,
7711 * CakeFrostingType frosting,
7712 * const char *message,
7713 * GCancellable *cancellable,
7714 * GAsyncReadyCallback callback,
7715 * gpointer user_data)
7717 * CakeData *cake_data;
7720 * cake_data = g_slice_new (CakeData);
7723 * task = g_task_new (self, cancellable, callback, user_data);
7724 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7725 * g_task_set_return_on_cancel (task, TRUE);
7726 * g_task_run_in_thread (task, bake_cake_thread);
7730 * baker_bake_cake_sync (Baker *self,
7732 * CakeFlavor flavor,
7733 * CakeFrostingType frosting,
7734 * const char *message,
7735 * GCancellable *cancellable,
7738 * CakeData *cake_data;
7742 * cake_data = g_slice_new (CakeData);
7745 * task = g_task_new (self, cancellable, NULL, NULL);
7746 * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
7747 * g_task_set_return_on_cancel (task, TRUE);
7748 * g_task_run_in_thread_sync (task, bake_cake_thread);
7750 * cake = g_task_propagate_pointer (task, error);
7751 * g_object_unref (task);
7758 * <title>Porting from <literal>GSimpleAsyncResult</literal></title>
7760 * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
7765 * You can save task-specific data with g_task_set_task_data(), and
7766 * retrieve it later with g_task_get_task_data(). This replaces the
7767 * abuse of g_simple_async_result_set_op_res_gpointer() for the same
7768 * purpose with #GSimpleAsyncResult.
7769 * </para></listitem>
7771 * In addition to the task data, #GTask also keeps track of the
7772 * <link linkend="io-priority">priority</link>, #GCancellable, and
7773 * #GMainContext associated with the task, so tasks that consist of
7774 * a chain of simpler asynchronous operations will have easy access
7775 * to those values when starting each sub-task.
7776 * </para></listitem>
7778 * g_task_return_error_if_cancelled() provides simplified
7779 * handling for cancellation. In addition, cancellation
7780 * overrides any other #GTask return value by default, like
7781 * #GSimpleAsyncResult does when
7782 * g_simple_async_result_set_check_cancellable() is called.
7783 * (You can use g_task_set_check_cancellable() to turn off that
7784 * behavior.) On the other hand, g_task_run_in_thread()
7785 * guarantees that it will always run your
7786 * <literal>task_func</literal>, even if the task's #GCancellable
7787 * is already cancelled before the task gets a chance to run;
7788 * you can start your <literal>task_func</literal> with a
7789 * g_task_return_error_if_cancelled() check if you need the
7791 * </para></listitem>
7793 * The "return" methods (eg, g_task_return_pointer())
7794 * automatically cause the task to be "completed" as well, and
7795 * there is no need to worry about the "complete" vs "complete
7796 * in idle" distinction. (#GTask automatically figures out
7797 * whether the task's callback can be invoked directly, or
7798 * if it needs to be sent to another #GMainContext, or delayed
7799 * until the next iteration of the current #GMainContext.)
7800 * </para></listitem>
7802 * The "finish" functions for #GTask-based operations are generally
7803 * much simpler than #GSimpleAsyncResult ones, normally consisting
7804 * of only a single call to g_task_propagate_pointer() or the like.
7805 * Since g_task_propagate_pointer() "steals" the return value from
7806 * the #GTask, it is not necessary to juggle pointers around to
7807 * prevent it from being freed twice.
7808 * </para></listitem>
7810 * With #GSimpleAsyncResult, it was common to call
7811 * g_simple_async_result_propagate_error() from the
7812 * <literal>_finish()</literal> wrapper function, and have
7813 * virtual method implementations only deal with successful
7814 * returns. This behavior is deprecated, because it makes it
7815 * difficult for a subclass to chain to a parent class's async
7816 * methods. Instead, the wrapper function should just be a
7817 * simple wrapper, and the virtual method should call an
7818 * appropriate <literal>g_task_propagate_</literal> function.
7819 * Note that wrapper methods can now use
7820 * g_async_result_legacy_propagate_error() to do old-style
7821 * #GSimpleAsyncResult error-returning behavior, and
7822 * g_async_result_is_tagged() to check if a result is tagged as
7823 * having come from the <literal>_async()</literal> wrapper
7824 * function (for "short-circuit" results, such as when passing
7825 * 0 to g_input_stream_read_async()).
7826 * </para></listitem>
7833 * SECTION:gtcpconnection
7834 * @title: GTcpConnection
7835 * @short_description: A TCP GSocketConnection
7836 * @see_also: #GSocketConnection.
7838 * This is the subclass of #GSocketConnection that is created
7839 * for TCP/IP sockets.
7846 * SECTION:gtcpwrapperconnection
7847 * @title: GTcpWrapperConnection
7848 * @short_description: Wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
7849 * @see_also: #GSocketConnection.
7851 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
7852 * based on a #GSocket, but which is not actually a
7853 * #GSocketConnection. This is used by #GSocketClient so that it can
7854 * always return a #GSocketConnection, even when the connection it has
7855 * actually created is not directly a #GSocketConnection.
7863 * @short_description: D-Bus testing helper
7864 * @include: gio/gio.h
7866 * A helper class for testing code which uses D-Bus without touching the user's
7869 * <refsect2 id="gio-D-Bus-Test-Scaffolding">
7870 * <title>Creating unit tests using GTestDBus</title>
7872 * Testing of D-Bus services can be tricky because normally we only ever run
7873 * D-Bus services over an existing instance of the D-Bus daemon thus we
7874 * usually don't activate D-Bus services that are not yet installed into the
7875 * target system. The #GTestDBus object makes this easier for us by taking care
7876 * of the lower level tasks such as running a private D-Bus daemon and looking
7877 * up uninstalled services in customizable locations, typically in your source code tree.
7880 * The first thing you will need is a separate service description file for the
7881 * D-Bus daemon. Typically a 'services' subdirectory of your 'tests' directory
7882 * is a good place to put this file.
7885 * The service file should list your service along with an absolute path to the
7886 * uninstalled service executable in your source tree. Using autotools we would
7887 * achieve this by adding a file such as 'my-server.service.in' in the services
7888 * directory and have it processed by configure.
7889 * <informalexample><programlisting>
7891 * Name=org.gtk.GDBus.Examples.ObjectManager
7892 * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
7893 * </programlisting></informalexample>
7894 * You will also need to indicate this service directory in your test
7895 * fixtures, so you will need to pass the path while compiling your
7896 * test cases. Typically this is done with autotools with an added
7897 * preprocessor flag specified to compile your tests such as:
7898 * <informalexample><programlisting>
7899 * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
7900 * </programlisting></informalexample>
7903 * Once you have a service definition file which is local to your source tree,
7904 * you can proceed to setup a GTest fixture using the GTestDBus scaffolding.
7905 * <example id="gdbus-test-fixture">
7906 * <title>Test Fixture for D-Bus services</title>
7908 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-test-fixture.c">
7909 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
7915 * Note that these examples only deal with isolating the D-Bus aspect of your
7916 * service. To successfully run isolated unit tests on your service you may need
7917 * some additional modifications to your test case fixture. For example; if your
7918 * service uses GSettings and installs a schema then it is important that your test service
7919 * not load the schema in the ordinary installed location (chances are that your service
7920 * and schema files are not yet installed, or worse; there is an older version of the
7921 * schema file sitting in the install location).
7924 * Most of the time we can work around these obstacles using the environment. Since the
7925 * environment is inherited by the D-Bus daemon created by GTestDBus and then in turn
7926 * inherited by any services the D-Bus daemon activates, using the setup routine for your
7927 * fixture is a practical place to help sandbox your runtime environment. For the rather
7928 * typical GSettings case we can work around this by setting GSETTINGS_SCHEMA_DIR to the
7929 * in tree directory holding your schemas in the above fixture_setup() routine.
7932 * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
7933 * by compiling the schemas locally as a step before running test cases, an autotools setup might
7934 * do the following in the directory holding schemas:
7935 * <informalexample><programlisting>
7937 * $(GLIB_COMPILE_SCHEMAS) .
7939 * CLEANFILES += gschemas.compiled
7940 * </programlisting></informalexample>
7947 * SECTION:gthemedicon
7948 * @short_description: Icon theming support
7949 * @include: gio/gio.h
7950 * @see_also: #GIcon, #GLoadableIcon
7952 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
7953 * #GThemedIcon contains a list of all of the icons present in an icon
7954 * theme, so that icons can be looked up quickly. #GThemedIcon does
7955 * not provide actual pixmaps for icons, just the icon names.
7956 * Ideally something like gtk_icon_theme_choose_icon() should be used to
7957 * resolve the list of names so that fallback icons work nicely with
7958 * themes that inherit other themes.
7963 * SECTION:gthreadedsocketservice
7964 * @title: GThreadedSocketService
7965 * @short_description: A threaded GSocketService
7966 * @see_also: #GSocketService.
7968 * A #GThreadedSocketService is a simple subclass of #GSocketService
7969 * that handles incoming connections by creating a worker thread and
7970 * dispatching the connection to it by emitting the
7971 * #GThreadedSocketService::run signal in the new thread.
7973 * The signal handler may perform blocking IO and need not return
7974 * until the connection is closed.
7976 * The service is implemented using a thread pool, so there is a
7977 * limited amount of threads available to serve incoming requests.
7978 * The service automatically stops the #GSocketService from accepting
7979 * new connections when all threads are busy.
7981 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
7982 * or subclass and override the default handler.
7988 * @title: TLS Overview
7989 * @short_description: TLS (aka SSL) support for GSocketConnection
7990 * @include: gio/gio.h
7992 * #GTlsConnection and related classes provide TLS (Transport Layer
7993 * Security, previously known as SSL, Secure Sockets Layer) support for
7994 * gio-based network streams.
7996 * In the simplest case, for a client connection, you can just set the
7997 * #GSocketClient:tls flag on a #GSocketClient, and then any
7998 * connections created by that client will have TLS negotiated
7999 * automatically, using appropriate default settings, and rejecting
8000 * any invalid or self-signed certificates (unless you change that
8001 * default by setting the #GSocketClient:tls-validation-flags
8002 * property). The returned object will be a #GTcpWrapperConnection,
8003 * which wraps the underlying #GTlsClientConnection.
8005 * For greater control, you can create your own #GTlsClientConnection,
8006 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
8007 * pollable input and output streams) and then connect to its signals,
8008 * such as #GTlsConnection::accept-certificate, before starting the
8011 * Server-side TLS is similar, using #GTlsServerConnection. At the
8012 * moment, there is no support for automatically wrapping server-side
8013 * connections in the way #GSocketClient does for client-side
8019 * SECTION:gtlsbackend
8020 * @title: GTlsBackend
8021 * @short_description: TLS backend implementation
8022 * @include: gio/gio.h
8027 * SECTION:gtlscertificate
8028 * @title: GTlsCertificate
8029 * @short_description: TLS certificate
8030 * @see_also: #GTlsConnection
8032 * A certificate used for TLS authentication and encryption.
8033 * This can represent either a certificate only (eg, the certificate
8034 * received by a client from a server), or the combination of
8035 * a certificate and a private key (which is needed when acting as a
8036 * #GTlsServerConnection).
8043 * SECTION:gtlsclientconnection
8044 * @short_description: TLS client-side connection
8045 * @include: gio/gio.h
8047 * #GTlsClientConnection is the client-side subclass of
8048 * #GTlsConnection, representing a client-side TLS connection.
8053 * SECTION:gtlsconnection
8054 * @short_description: TLS connection type
8055 * @include: gio/gio.h
8057 * #GTlsConnection is the base TLS connection class type, which wraps
8058 * a #GIOStream and provides TLS encryption on top of it. Its
8059 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
8060 * implement client-side and server-side TLS, respectively.
8067 * SECTION:gtlsdatabase
8068 * @short_description: TLS database type
8069 * @include: gio/gio.h
8071 * #GTlsDatabase is used to lookup certificates and other information
8072 * from a certificate or key store. It is an abstract base class which
8073 * TLS library specific subtypes override.
8075 * Most common client applications will not directly interact with
8076 * #GTlsDatabase. It is used internally by #GTlsConnection.
8083 * SECTION:gtlsfiledatabase
8084 * @short_description: TLS file based database type
8085 * @include: gio/gio.h
8087 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
8088 * their certificate information from a file. It is an interface which
8089 * TLS library specific subtypes implement.
8096 * SECTION:gtlsinteraction
8097 * @short_description: Interaction with the user during TLS operations.
8098 * @include: gio/gio.h
8100 * #GTlsInteraction provides a mechanism for the TLS connection and database
8101 * code to interact with the user. It can be used to ask the user for passwords.
8103 * To use a #GTlsInteraction with a TLS connection use
8104 * g_tls_connection_set_interaction().
8106 * Callers should instantiate a derived class that implements the various
8107 * interaction methods to show the required dialogs.
8109 * Callers should use the 'invoke' functions like
8110 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
8111 * functions make sure that the interaction is invoked in the main loop
8112 * and not in the current thread, if the current thread is not running the
8115 * Derived classes can choose to implement whichever interactions methods they'd
8116 * like to support by overriding those virtual methods in their class
8117 * initialization function. Any interactions not implemented will return
8118 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
8119 * it must also implement the corresponding finish method.
8124 * SECTION:gtlspassword
8125 * @title: GTlsPassword
8126 * @short_description: TLS Passwords for prompting
8127 * @include: gio/gio.h
8129 * Holds a password used in TLS.
8134 * SECTION:gtlsserverconnection
8135 * @short_description: TLS server-side connection
8136 * @include: gio/gio.h
8138 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
8139 * representing a server-side TLS connection.
8146 * SECTION:gunixconnection
8147 * @title: GUnixConnection
8148 * @short_description: A UNIX domain GSocketConnection
8149 * @include: gio/gunixconnection.h
8150 * @see_also: #GSocketConnection.
8152 * This is the subclass of #GSocketConnection that is created
8153 * for UNIX domain sockets.
8155 * It contains functions to do some of the UNIX socket specific
8156 * functionality like passing file descriptors.
8158 * Note that <filename><gio/gunixconnection.h></filename> belongs to
8159 * the UNIX-specific GIO interfaces, thus you have to use the
8160 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8167 * SECTION:gunixcredentialsmessage
8168 * @title: GUnixCredentialsMessage
8169 * @short_description: A GSocketControlMessage containing credentials
8170 * @include: gio/gunixcredentialsmessage.h
8171 * @see_also: #GUnixConnection, #GSocketControlMessage
8173 * This #GSocketControlMessage contains a #GCredentials instance. It
8174 * may be sent using g_socket_send_message() and received using
8175 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
8176 * %G_SOCKET_FAMILY_UNIX family).
8178 * For an easier way to send and receive credentials over
8179 * stream-oriented UNIX sockets, see
8180 * g_unix_connection_send_credentials() and
8181 * g_unix_connection_receive_credentials(). To receive credentials of
8182 * a foreign process connected to a socket, use
8183 * g_socket_get_credentials().
8188 * SECTION:gunixfdlist
8189 * @title: GUnixFDList
8190 * @short_description: An object containing a set of UNIX file descriptors
8191 * @include: gio/gunixfdlist.h
8192 * @see_also: #GUnixFDMessage
8194 * A #GUnixFDList contains a list of file descriptors. It owns the file
8195 * descriptors that it contains, closing them when finalized.
8197 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
8198 * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
8199 * and received using g_socket_receive_message().
8201 * Note that <filename><gio/gunixfdlist.h></filename> belongs to
8202 * the UNIX-specific GIO interfaces, thus you have to use the
8203 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8208 * SECTION:gunixfdmessage
8209 * @title: GUnixFDMessage
8210 * @short_description: A GSocketControlMessage containing a GUnixFDList
8211 * @include: gio/gunixfdmessage.h
8212 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
8214 * This #GSocketControlMessage contains a #GUnixFDList.
8215 * It may be sent using g_socket_send_message() and received using
8216 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
8217 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
8218 * between processes by the kernel.
8220 * For an easier way to send and receive file descriptors over
8221 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
8222 * g_unix_connection_receive_fd().
8224 * Note that <filename><gio/gunixfdmessage.h></filename> belongs to
8225 * the UNIX-specific GIO interfaces, thus you have to use the
8226 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8231 * SECTION:gunixinputstream
8232 * @short_description: Streaming input operations for UNIX file descriptors
8233 * @include: gio/gunixinputstream.h
8234 * @see_also: #GInputStream
8236 * #GUnixInputStream implements #GInputStream for reading from a UNIX
8237 * file descriptor, including asynchronous operations. (If the file
8238 * descriptor refers to a socket or pipe, this will use poll() to do
8239 * asynchronous I/O. If it refers to a regular file, it will fall back
8240 * to doing asynchronous I/O in another thread.)
8242 * Note that <filename><gio/gunixinputstream.h></filename> belongs
8243 * to the UNIX-specific GIO interfaces, thus you have to use the
8244 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8249 * SECTION:gunixmounts
8250 * @include: gio/gunixmounts.h
8251 * @short_description: UNIX mounts
8253 * Routines for managing mounted UNIX mount points and paths.
8255 * Note that <filename><gio/gunixmounts.h></filename> belongs to the
8256 * UNIX-specific GIO interfaces, thus you have to use the
8257 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8262 * SECTION:gunixoutputstream
8263 * @short_description: Streaming output operations for UNIX file descriptors
8264 * @include: gio/gunixoutputstream.h
8265 * @see_also: #GOutputStream
8267 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
8268 * file descriptor, including asynchronous operations. (If the file
8269 * descriptor refers to a socket or pipe, this will use poll() to do
8270 * asynchronous I/O. If it refers to a regular file, it will fall back
8271 * to doing asynchronous I/O in another thread.)
8273 * Note that <filename><gio/gunixoutputstream.h></filename> belongs
8274 * to the UNIX-specific GIO interfaces, thus you have to use the
8275 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8280 * SECTION:gunixsocketaddress
8281 * @short_description: UNIX GSocketAddress
8282 * @include: gio/gunixsocketaddress.h
8284 * Support for UNIX-domain (also known as local) sockets.
8286 * UNIX domain sockets are generally visible in the filesystem.
8287 * However, some systems support abstract socket names which are not
8288 * visible in the filesystem and not affected by the filesystem
8289 * permissions, visibility, etc. Currently this is only supported
8290 * under Linux. If you attempt to use abstract sockets on other
8291 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
8292 * errors. You can use g_unix_socket_address_abstract_names_supported()
8293 * to see if abstract names are supported.
8295 * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to
8296 * the UNIX-specific GIO interfaces, thus you have to use the
8297 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
8303 * @short_description: Virtual File System
8304 * @include: gio/gio.h
8306 * Entry point for using GIO functionality.
8312 * @short_description: Volume management
8313 * @include: gio/gio.h
8315 * The #GVolume interface represents user-visible objects that can be
8316 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
8317 * equivalent of #GnomeVFSDrive.
8319 * Mounting a #GVolume instance is an asynchronous operation. For more
8320 * information about asynchronous operations, see #GAsyncResult and
8321 * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
8322 * least) the #GVolume instance, optionally a #GMountOperation object
8323 * and a #GAsyncReadyCallback.
8325 * Typically, one will only want to pass %NULL for the
8326 * #GMountOperation if automounting all volumes when a desktop session
8327 * starts since it's not desirable to put up a lot of dialogs asking
8330 * The callback will be fired when the operation has resolved (either
8331 * with success or failure), and a #GAsyncReady structure will be
8332 * passed to the callback. That callback should then call
8333 * g_volume_mount_finish() with the #GVolume instance and the
8334 * #GAsyncReady data to see if the operation was completed
8335 * successfully. If an @error is present when g_volume_mount_finish()
8336 * is called, then it will be filled with any error information.
8338 * <para id="volume-identifier">
8339 * It is sometimes necessary to directly access the underlying
8340 * operating system object behind a volume (e.g. for passing a volume
8341 * to an application via the commandline). For this purpose, GIO
8342 * allows to obtain an 'identifier' for the volume. There can be
8343 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
8344 * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
8345 * uuids. GIO uses predefind strings as names for the different kinds
8346 * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
8347 * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
8348 * to obtain an identifier for a volume.
8351 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
8352 * when the gvfs hal volume monitor is in use. Other volume monitors
8353 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
8354 * identifier, which can be used to obtain a hal device by means of
8355 * libhal_manager_find_device_string_match().
8360 * SECTION:gvolumemonitor
8361 * @short_description: Volume Monitor
8362 * @include: gio/gio.h
8363 * @see_also: #GFileMonitor
8365 * #GVolumeMonitor is for listing the user interesting devices and volumes
8366 * on the computer. In other words, what a file selector or file manager
8367 * would show in a sidebar.
8369 * #GVolumeMonitor is not <link
8370 * linkend="g-main-context-push-thread-default">thread-default-context
8371 * aware</link>, and so should not be used other than from the main
8372 * thread, with no thread-default-context active.
8377 * SECTION:gwin32inputstream
8378 * @short_description: Streaming input operations for Windows file handles
8379 * @include: gio/gwin32inputstream.h
8380 * @see_also: #GInputStream
8382 * #GWin32InputStream implements #GInputStream for reading from a
8383 * Windows file handle.
8385 * Note that <filename><gio/gwin32inputstream.h></filename> belongs
8386 * to the Windows-specific GIO interfaces, thus you have to use the
8387 * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
8392 * SECTION:gwin32outputstream
8393 * @short_description: Streaming output operations for Windows file handles
8394 * @include: gio/gwin32outputstream.h
8395 * @see_also: #GOutputStream
8397 * #GWin32OutputStream implements #GOutputStream for writing to a
8398 * Windows file handle.
8400 * Note that <filename><gio/gwin32outputstream.h></filename> belongs
8401 * to the Windows-specific GIO interfaces, thus you have to use the
8402 * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
8407 * SECTION:gzcompressor
8408 * @short_description: Zlib compressor
8409 * @include: gio/gio.h
8411 * #GZlibCompressor is an implementation of #GConverter that
8412 * compresses data using zlib.
8417 * SECTION:gzdecompressor
8418 * @short_description: Zlib decompressor
8419 * @include: gio/gio.h
8421 * #GZlibDecompressor is an implementation of #GConverter that
8422 * decompresses data compressed with zlib.
8427 * _GFreedesktopDBus:
8429 * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8434 * _GFreedesktopDBus::handle-add-match:
8435 * @object: A #_GFreedesktopDBus.
8436 * @invocation: A #GDBusMethodInvocation.
8437 * @arg_rule: Argument passed by remote caller.
8439 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method.
8441 * 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.
8443 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8448 * _GFreedesktopDBus::handle-get-connection-selinux-security-context:
8449 * @object: A #_GFreedesktopDBus.
8450 * @invocation: A #GDBusMethodInvocation.
8451 * @arg_name: Argument passed by remote caller.
8453 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method.
8455 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_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.
8457 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8462 * _GFreedesktopDBus::handle-get-connection-unix-process-id:
8463 * @object: A #_GFreedesktopDBus.
8464 * @invocation: A #GDBusMethodInvocation.
8465 * @arg_name: Argument passed by remote caller.
8467 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method.
8469 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_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.
8471 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8476 * _GFreedesktopDBus::handle-get-connection-unix-user:
8477 * @object: A #_GFreedesktopDBus.
8478 * @invocation: A #GDBusMethodInvocation.
8479 * @arg_name: Argument passed by remote caller.
8481 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method.
8483 * 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.
8485 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8490 * _GFreedesktopDBus::handle-get-id:
8491 * @object: A #_GFreedesktopDBus.
8492 * @invocation: A #GDBusMethodInvocation.
8494 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method.
8496 * 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.
8498 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8503 * _GFreedesktopDBus::handle-get-name-owner:
8504 * @object: A #_GFreedesktopDBus.
8505 * @invocation: A #GDBusMethodInvocation.
8506 * @arg_name: Argument passed by remote caller.
8508 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method.
8510 * 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.
8512 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8517 * _GFreedesktopDBus::handle-hello:
8518 * @object: A #_GFreedesktopDBus.
8519 * @invocation: A #GDBusMethodInvocation.
8521 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method.
8523 * 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.
8525 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8530 * _GFreedesktopDBus::handle-list-activatable-names:
8531 * @object: A #_GFreedesktopDBus.
8532 * @invocation: A #GDBusMethodInvocation.
8534 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method.
8536 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_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.
8538 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8543 * _GFreedesktopDBus::handle-list-names:
8544 * @object: A #_GFreedesktopDBus.
8545 * @invocation: A #GDBusMethodInvocation.
8547 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method.
8549 * 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.
8551 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8556 * _GFreedesktopDBus::handle-list-queued-owners:
8557 * @object: A #_GFreedesktopDBus.
8558 * @invocation: A #GDBusMethodInvocation.
8559 * @arg_name: Argument passed by remote caller.
8561 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method.
8563 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_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.
8565 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8570 * _GFreedesktopDBus::handle-name-has-owner:
8571 * @object: A #_GFreedesktopDBus.
8572 * @invocation: A #GDBusMethodInvocation.
8573 * @arg_name: Argument passed by remote caller.
8575 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method.
8577 * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_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.
8579 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8584 * _GFreedesktopDBus::handle-release-name:
8585 * @object: A #_GFreedesktopDBus.
8586 * @invocation: A #GDBusMethodInvocation.
8587 * @arg_name: Argument passed by remote caller.
8589 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method.
8591 * 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.
8593 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8598 * _GFreedesktopDBus::handle-reload-config:
8599 * @object: A #_GFreedesktopDBus.
8600 * @invocation: A #GDBusMethodInvocation.
8602 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method.
8604 * 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.
8606 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8611 * _GFreedesktopDBus::handle-remove-match:
8612 * @object: A #_GFreedesktopDBus.
8613 * @invocation: A #GDBusMethodInvocation.
8614 * @arg_rule: Argument passed by remote caller.
8616 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method.
8618 * 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.
8620 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8625 * _GFreedesktopDBus::handle-request-name:
8626 * @object: A #_GFreedesktopDBus.
8627 * @invocation: A #GDBusMethodInvocation.
8628 * @arg_name: Argument passed by remote caller.
8629 * @arg_flags: Argument passed by remote caller.
8631 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method.
8633 * 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.
8635 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8640 * _GFreedesktopDBus::handle-start-service-by-name:
8641 * @object: A #_GFreedesktopDBus.
8642 * @invocation: A #GDBusMethodInvocation.
8643 * @arg_name: Argument passed by remote caller.
8644 * @arg_flags: Argument passed by remote caller.
8646 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method.
8648 * 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.
8650 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8655 * _GFreedesktopDBus::handle-update-activation-environment:
8656 * @object: A #_GFreedesktopDBus.
8657 * @invocation: A #GDBusMethodInvocation.
8658 * @arg_environment: Argument passed by remote caller.
8660 * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method.
8662 * 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.
8664 * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
8669 * _GFreedesktopDBus::name-acquired:
8670 * @object: A #_GFreedesktopDBus.
8671 * @arg_name: Argument.
8673 * 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.
8675 * 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.
8680 * _GFreedesktopDBus::name-lost:
8681 * @object: A #_GFreedesktopDBus.
8682 * @arg_name: Argument.
8684 * 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.
8686 * 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.
8691 * _GFreedesktopDBus::name-owner-changed:
8692 * @object: A #_GFreedesktopDBus.
8693 * @arg_name: Argument.
8694 * @arg_old_owner: Argument.
8695 * @arg_new_owner: Argument.
8697 * 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.
8699 * 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.
8704 * _GFreedesktopDBusIface:
8705 * @parent_iface: The parent interface.
8706 * @handle_add_match: Handler for the #_GFreedesktopDBus::handle-add-match signal.
8707 * @handle_get_connection_selinux_security_context: Handler for the #_GFreedesktopDBus::handle-get-connection-selinux-security-context signal.
8708 * @handle_get_connection_unix_process_id: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-process-id signal.
8709 * @handle_get_connection_unix_user: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-user signal.
8710 * @handle_get_id: Handler for the #_GFreedesktopDBus::handle-get-id signal.
8711 * @handle_get_name_owner: Handler for the #_GFreedesktopDBus::handle-get-name-owner signal.
8712 * @handle_hello: Handler for the #_GFreedesktopDBus::handle-hello signal.
8713 * @handle_list_activatable_names: Handler for the #_GFreedesktopDBus::handle-list-activatable-names signal.
8714 * @handle_list_names: Handler for the #_GFreedesktopDBus::handle-list-names signal.
8715 * @handle_list_queued_owners: Handler for the #_GFreedesktopDBus::handle-list-queued-owners signal.
8716 * @handle_name_has_owner: Handler for the #_GFreedesktopDBus::handle-name-has-owner signal.
8717 * @handle_release_name: Handler for the #_GFreedesktopDBus::handle-release-name signal.
8718 * @handle_reload_config: Handler for the #_GFreedesktopDBus::handle-reload-config signal.
8719 * @handle_remove_match: Handler for the #_GFreedesktopDBus::handle-remove-match signal.
8720 * @handle_request_name: Handler for the #_GFreedesktopDBus::handle-request-name signal.
8721 * @handle_start_service_by_name: Handler for the #_GFreedesktopDBus::handle-start-service-by-name signal.
8722 * @handle_update_activation_environment: Handler for the #_GFreedesktopDBus::handle-update-activation-environment signal.
8723 * @name_acquired: Handler for the #_GFreedesktopDBus::name-acquired signal.
8724 * @name_lost: Handler for the #_GFreedesktopDBus::name-lost signal.
8725 * @name_owner_changed: Handler for the #_GFreedesktopDBus::name-owner-changed signal.
8727 * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
8732 * _GFreedesktopDBusProxy:
8734 * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API.
8739 * _GFreedesktopDBusProxyClass:
8740 * @parent_class: The parent class.
8742 * Class structure for #_GFreedesktopDBusProxy.
8747 * _GFreedesktopDBusSkeleton:
8749 * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API.
8754 * _GFreedesktopDBusSkeletonClass:
8755 * @parent_class: The parent class.
8757 * Class structure for #_GFreedesktopDBusSkeleton.
8762 * _g_freedesktop_dbus_call_add_match:
8763 * @proxy: A #_GFreedesktopDBusProxy.
8764 * @arg_rule: Argument to pass with the method invocation.
8765 * @cancellable: (allow-none): A #GCancellable or %NULL.
8766 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8767 * @user_data: User data to pass to @callback.
8769 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
8770 * 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.
8771 * You can then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
8773 * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
8778 * _g_freedesktop_dbus_call_add_match_finish:
8779 * @proxy: A #_GFreedesktopDBusProxy.
8780 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
8781 * @error: Return location for error or %NULL.
8783 * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
8785 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8790 * _g_freedesktop_dbus_call_add_match_sync:
8791 * @proxy: A #_GFreedesktopDBusProxy.
8792 * @arg_rule: Argument to pass with the method invocation.
8793 * @cancellable: (allow-none): A #GCancellable or %NULL.
8794 * @error: Return location for error or %NULL.
8796 * 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.
8798 * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
8800 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8805 * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
8806 * @proxy: A #_GFreedesktopDBusProxy.
8807 * @arg_name: Argument to pass with the method invocation.
8808 * @cancellable: (allow-none): A #GCancellable or %NULL.
8809 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8810 * @user_data: User data to pass to @callback.
8812 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
8813 * 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.
8814 * You can then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
8816 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
8821 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
8822 * @proxy: A #_GFreedesktopDBusProxy.
8823 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
8824 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
8825 * @error: Return location for error or %NULL.
8827 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
8829 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8834 * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
8835 * @proxy: A #_GFreedesktopDBusProxy.
8836 * @arg_name: Argument to pass with the method invocation.
8837 * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
8838 * @cancellable: (allow-none): A #GCancellable or %NULL.
8839 * @error: Return location for error or %NULL.
8841 * 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.
8843 * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
8845 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8850 * _g_freedesktop_dbus_call_get_connection_unix_process_id:
8851 * @proxy: A #_GFreedesktopDBusProxy.
8852 * @arg_name: Argument to pass with the method invocation.
8853 * @cancellable: (allow-none): A #GCancellable or %NULL.
8854 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8855 * @user_data: User data to pass to @callback.
8857 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
8858 * 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.
8859 * You can then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
8861 * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
8866 * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
8867 * @proxy: A #_GFreedesktopDBusProxy.
8868 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
8869 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
8870 * @error: Return location for error or %NULL.
8872 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
8874 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8879 * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
8880 * @proxy: A #_GFreedesktopDBusProxy.
8881 * @arg_name: Argument to pass with the method invocation.
8882 * @out_pid: (out): Return location for return parameter or %NULL to ignore.
8883 * @cancellable: (allow-none): A #GCancellable or %NULL.
8884 * @error: Return location for error or %NULL.
8886 * 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.
8888 * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
8890 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8895 * _g_freedesktop_dbus_call_get_connection_unix_user:
8896 * @proxy: A #_GFreedesktopDBusProxy.
8897 * @arg_name: Argument to pass with the method invocation.
8898 * @cancellable: (allow-none): A #GCancellable or %NULL.
8899 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8900 * @user_data: User data to pass to @callback.
8902 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
8903 * 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.
8904 * You can then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
8906 * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
8911 * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
8912 * @proxy: A #_GFreedesktopDBusProxy.
8913 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
8914 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
8915 * @error: Return location for error or %NULL.
8917 * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
8919 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8924 * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
8925 * @proxy: A #_GFreedesktopDBusProxy.
8926 * @arg_name: Argument to pass with the method invocation.
8927 * @out_uid: (out): Return location for return parameter or %NULL to ignore.
8928 * @cancellable: (allow-none): A #GCancellable or %NULL.
8929 * @error: Return location for error or %NULL.
8931 * 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.
8933 * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
8935 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8940 * _g_freedesktop_dbus_call_get_id:
8941 * @proxy: A #_GFreedesktopDBusProxy.
8942 * @cancellable: (allow-none): A #GCancellable or %NULL.
8943 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8944 * @user_data: User data to pass to @callback.
8946 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy.
8947 * 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.
8948 * You can then call _g_freedesktop_dbus_call_get_id_finish() to get the result of the operation.
8950 * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method.
8955 * _g_freedesktop_dbus_call_get_id_finish:
8956 * @proxy: A #_GFreedesktopDBusProxy.
8957 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
8958 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_id().
8959 * @error: Return location for error or %NULL.
8961 * Finishes an operation started with _g_freedesktop_dbus_call_get_id().
8963 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8968 * _g_freedesktop_dbus_call_get_id_sync:
8969 * @proxy: A #_GFreedesktopDBusProxy.
8970 * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
8971 * @cancellable: (allow-none): A #GCancellable or %NULL.
8972 * @error: Return location for error or %NULL.
8974 * 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.
8976 * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method.
8978 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
8983 * _g_freedesktop_dbus_call_get_name_owner:
8984 * @proxy: A #_GFreedesktopDBusProxy.
8985 * @arg_name: Argument to pass with the method invocation.
8986 * @cancellable: (allow-none): A #GCancellable or %NULL.
8987 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
8988 * @user_data: User data to pass to @callback.
8990 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy.
8991 * 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.
8992 * You can then call _g_freedesktop_dbus_call_get_name_owner_finish() to get the result of the operation.
8994 * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method.
8999 * _g_freedesktop_dbus_call_get_name_owner_finish:
9000 * @proxy: A #_GFreedesktopDBusProxy.
9001 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
9002 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_name_owner().
9003 * @error: Return location for error or %NULL.
9005 * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner().
9007 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9012 * _g_freedesktop_dbus_call_get_name_owner_sync:
9013 * @proxy: A #_GFreedesktopDBusProxy.
9014 * @arg_name: Argument to pass with the method invocation.
9015 * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
9016 * @cancellable: (allow-none): A #GCancellable or %NULL.
9017 * @error: Return location for error or %NULL.
9019 * 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.
9021 * See _g_freedesktop_dbus_call_get_name_owner() for the asynchronous version of this method.
9023 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9028 * _g_freedesktop_dbus_call_hello:
9029 * @proxy: A #_GFreedesktopDBusProxy.
9030 * @cancellable: (allow-none): A #GCancellable or %NULL.
9031 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9032 * @user_data: User data to pass to @callback.
9034 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy.
9035 * 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.
9036 * You can then call _g_freedesktop_dbus_call_hello_finish() to get the result of the operation.
9038 * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method.
9043 * _g_freedesktop_dbus_call_hello_finish:
9044 * @proxy: A #_GFreedesktopDBusProxy.
9045 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
9046 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_hello().
9047 * @error: Return location for error or %NULL.
9049 * Finishes an operation started with _g_freedesktop_dbus_call_hello().
9051 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9056 * _g_freedesktop_dbus_call_hello_sync:
9057 * @proxy: A #_GFreedesktopDBusProxy.
9058 * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
9059 * @cancellable: (allow-none): A #GCancellable or %NULL.
9060 * @error: Return location for error or %NULL.
9062 * 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.
9064 * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method.
9066 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9071 * _g_freedesktop_dbus_call_list_activatable_names:
9072 * @proxy: A #_GFreedesktopDBusProxy.
9073 * @cancellable: (allow-none): A #GCancellable or %NULL.
9074 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9075 * @user_data: User data to pass to @callback.
9077 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy.
9078 * 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.
9079 * You can then call _g_freedesktop_dbus_call_list_activatable_names_finish() to get the result of the operation.
9081 * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method.
9086 * _g_freedesktop_dbus_call_list_activatable_names_finish:
9087 * @proxy: A #_GFreedesktopDBusProxy.
9088 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
9089 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
9090 * @error: Return location for error or %NULL.
9092 * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names().
9094 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9099 * _g_freedesktop_dbus_call_list_activatable_names_sync:
9100 * @proxy: A #_GFreedesktopDBusProxy.
9101 * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
9102 * @cancellable: (allow-none): A #GCancellable or %NULL.
9103 * @error: Return location for error or %NULL.
9105 * 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.
9107 * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method.
9109 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9114 * _g_freedesktop_dbus_call_list_names:
9115 * @proxy: A #_GFreedesktopDBusProxy.
9116 * @cancellable: (allow-none): A #GCancellable or %NULL.
9117 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9118 * @user_data: User data to pass to @callback.
9120 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy.
9121 * 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.
9122 * You can then call _g_freedesktop_dbus_call_list_names_finish() to get the result of the operation.
9124 * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method.
9129 * _g_freedesktop_dbus_call_list_names_finish:
9130 * @proxy: A #_GFreedesktopDBusProxy.
9131 * @out_names: (out): Return location for return parameter or %NULL to ignore.
9132 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
9133 * @error: Return location for error or %NULL.
9135 * Finishes an operation started with _g_freedesktop_dbus_call_list_names().
9137 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9142 * _g_freedesktop_dbus_call_list_names_sync:
9143 * @proxy: A #_GFreedesktopDBusProxy.
9144 * @out_names: (out): Return location for return parameter or %NULL to ignore.
9145 * @cancellable: (allow-none): A #GCancellable or %NULL.
9146 * @error: Return location for error or %NULL.
9148 * 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.
9150 * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method.
9152 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9157 * _g_freedesktop_dbus_call_list_queued_owners:
9158 * @proxy: A #_GFreedesktopDBusProxy.
9159 * @arg_name: Argument to pass with the method invocation.
9160 * @cancellable: (allow-none): A #GCancellable or %NULL.
9161 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9162 * @user_data: User data to pass to @callback.
9164 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy.
9165 * 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.
9166 * You can then call _g_freedesktop_dbus_call_list_queued_owners_finish() to get the result of the operation.
9168 * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method.
9173 * _g_freedesktop_dbus_call_list_queued_owners_finish:
9174 * @proxy: A #_GFreedesktopDBusProxy.
9175 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
9176 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
9177 * @error: Return location for error or %NULL.
9179 * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners().
9181 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9186 * _g_freedesktop_dbus_call_list_queued_owners_sync:
9187 * @proxy: A #_GFreedesktopDBusProxy.
9188 * @arg_name: Argument to pass with the method invocation.
9189 * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
9190 * @cancellable: (allow-none): A #GCancellable or %NULL.
9191 * @error: Return location for error or %NULL.
9193 * 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.
9195 * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method.
9197 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9202 * _g_freedesktop_dbus_call_name_has_owner:
9203 * @proxy: A #_GFreedesktopDBusProxy.
9204 * @arg_name: Argument to pass with the method invocation.
9205 * @cancellable: (allow-none): A #GCancellable or %NULL.
9206 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9207 * @user_data: User data to pass to @callback.
9209 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy.
9210 * 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.
9211 * You can then call _g_freedesktop_dbus_call_name_has_owner_finish() to get the result of the operation.
9213 * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method.
9218 * _g_freedesktop_dbus_call_name_has_owner_finish:
9219 * @proxy: A #_GFreedesktopDBusProxy.
9220 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
9221 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_name_has_owner().
9222 * @error: Return location for error or %NULL.
9224 * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner().
9226 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9231 * _g_freedesktop_dbus_call_name_has_owner_sync:
9232 * @proxy: A #_GFreedesktopDBusProxy.
9233 * @arg_name: Argument to pass with the method invocation.
9234 * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
9235 * @cancellable: (allow-none): A #GCancellable or %NULL.
9236 * @error: Return location for error or %NULL.
9238 * 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.
9240 * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method.
9242 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9247 * _g_freedesktop_dbus_call_release_name:
9248 * @proxy: A #_GFreedesktopDBusProxy.
9249 * @arg_name: Argument to pass with the method invocation.
9250 * @cancellable: (allow-none): A #GCancellable or %NULL.
9251 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9252 * @user_data: User data to pass to @callback.
9254 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy.
9255 * 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.
9256 * You can then call _g_freedesktop_dbus_call_release_name_finish() to get the result of the operation.
9258 * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method.
9263 * _g_freedesktop_dbus_call_release_name_finish:
9264 * @proxy: A #_GFreedesktopDBusProxy.
9265 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9266 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_release_name().
9267 * @error: Return location for error or %NULL.
9269 * Finishes an operation started with _g_freedesktop_dbus_call_release_name().
9271 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9276 * _g_freedesktop_dbus_call_release_name_sync:
9277 * @proxy: A #_GFreedesktopDBusProxy.
9278 * @arg_name: Argument to pass with the method invocation.
9279 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9280 * @cancellable: (allow-none): A #GCancellable or %NULL.
9281 * @error: Return location for error or %NULL.
9283 * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
9285 * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method.
9287 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9292 * _g_freedesktop_dbus_call_reload_config:
9293 * @proxy: A #_GFreedesktopDBusProxy.
9294 * @cancellable: (allow-none): A #GCancellable or %NULL.
9295 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9296 * @user_data: User data to pass to @callback.
9298 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy.
9299 * 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.
9300 * You can then call _g_freedesktop_dbus_call_reload_config_finish() to get the result of the operation.
9302 * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method.
9307 * _g_freedesktop_dbus_call_reload_config_finish:
9308 * @proxy: A #_GFreedesktopDBusProxy.
9309 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_reload_config().
9310 * @error: Return location for error or %NULL.
9312 * Finishes an operation started with _g_freedesktop_dbus_call_reload_config().
9314 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9319 * _g_freedesktop_dbus_call_reload_config_sync:
9320 * @proxy: A #_GFreedesktopDBusProxy.
9321 * @cancellable: (allow-none): A #GCancellable or %NULL.
9322 * @error: Return location for error or %NULL.
9324 * 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.
9326 * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method.
9328 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9333 * _g_freedesktop_dbus_call_remove_match:
9334 * @proxy: A #_GFreedesktopDBusProxy.
9335 * @arg_rule: Argument to pass with the method invocation.
9336 * @cancellable: (allow-none): A #GCancellable or %NULL.
9337 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9338 * @user_data: User data to pass to @callback.
9340 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy.
9341 * 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.
9342 * You can then call _g_freedesktop_dbus_call_remove_match_finish() to get the result of the operation.
9344 * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method.
9349 * _g_freedesktop_dbus_call_remove_match_finish:
9350 * @proxy: A #_GFreedesktopDBusProxy.
9351 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_remove_match().
9352 * @error: Return location for error or %NULL.
9354 * Finishes an operation started with _g_freedesktop_dbus_call_remove_match().
9356 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9361 * _g_freedesktop_dbus_call_remove_match_sync:
9362 * @proxy: A #_GFreedesktopDBusProxy.
9363 * @arg_rule: Argument to pass with the method invocation.
9364 * @cancellable: (allow-none): A #GCancellable or %NULL.
9365 * @error: Return location for error or %NULL.
9367 * 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.
9369 * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method.
9371 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9376 * _g_freedesktop_dbus_call_request_name:
9377 * @proxy: A #_GFreedesktopDBusProxy.
9378 * @arg_name: Argument to pass with the method invocation.
9379 * @arg_flags: Argument to pass with the method invocation.
9380 * @cancellable: (allow-none): A #GCancellable or %NULL.
9381 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9382 * @user_data: User data to pass to @callback.
9384 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy.
9385 * 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.
9386 * You can then call _g_freedesktop_dbus_call_request_name_finish() to get the result of the operation.
9388 * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method.
9393 * _g_freedesktop_dbus_call_request_name_finish:
9394 * @proxy: A #_GFreedesktopDBusProxy.
9395 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9396 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_request_name().
9397 * @error: Return location for error or %NULL.
9399 * Finishes an operation started with _g_freedesktop_dbus_call_request_name().
9401 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9406 * _g_freedesktop_dbus_call_request_name_sync:
9407 * @proxy: A #_GFreedesktopDBusProxy.
9408 * @arg_name: Argument to pass with the method invocation.
9409 * @arg_flags: Argument to pass with the method invocation.
9410 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9411 * @cancellable: (allow-none): A #GCancellable or %NULL.
9412 * @error: Return location for error or %NULL.
9414 * 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.
9416 * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method.
9418 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9423 * _g_freedesktop_dbus_call_start_service_by_name:
9424 * @proxy: A #_GFreedesktopDBusProxy.
9425 * @arg_name: Argument to pass with the method invocation.
9426 * @arg_flags: Argument to pass with the method invocation.
9427 * @cancellable: (allow-none): A #GCancellable or %NULL.
9428 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9429 * @user_data: User data to pass to @callback.
9431 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy.
9432 * 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.
9433 * You can then call _g_freedesktop_dbus_call_start_service_by_name_finish() to get the result of the operation.
9435 * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method.
9440 * _g_freedesktop_dbus_call_start_service_by_name_finish:
9441 * @proxy: A #_GFreedesktopDBusProxy.
9442 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9443 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_start_service_by_name().
9444 * @error: Return location for error or %NULL.
9446 * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name().
9448 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9453 * _g_freedesktop_dbus_call_start_service_by_name_sync:
9454 * @proxy: A #_GFreedesktopDBusProxy.
9455 * @arg_name: Argument to pass with the method invocation.
9456 * @arg_flags: Argument to pass with the method invocation.
9457 * @out_value: (out): Return location for return parameter or %NULL to ignore.
9458 * @cancellable: (allow-none): A #GCancellable or %NULL.
9459 * @error: Return location for error or %NULL.
9461 * 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.
9463 * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method.
9465 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9470 * _g_freedesktop_dbus_call_update_activation_environment:
9471 * @proxy: A #_GFreedesktopDBusProxy.
9472 * @arg_environment: Argument to pass with the method invocation.
9473 * @cancellable: (allow-none): A #GCancellable or %NULL.
9474 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
9475 * @user_data: User data to pass to @callback.
9477 * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy.
9478 * 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.
9479 * You can then call _g_freedesktop_dbus_call_update_activation_environment_finish() to get the result of the operation.
9481 * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method.
9486 * _g_freedesktop_dbus_call_update_activation_environment_finish:
9487 * @proxy: A #_GFreedesktopDBusProxy.
9488 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_update_activation_environment().
9489 * @error: Return location for error or %NULL.
9491 * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment().
9493 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9498 * _g_freedesktop_dbus_call_update_activation_environment_sync:
9499 * @proxy: A #_GFreedesktopDBusProxy.
9500 * @arg_environment: Argument to pass with the method invocation.
9501 * @cancellable: (allow-none): A #GCancellable or %NULL.
9502 * @error: Return location for error or %NULL.
9504 * 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.
9506 * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method.
9508 * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
9513 * _g_freedesktop_dbus_complete_add_match:
9514 * @object: A #_GFreedesktopDBus.
9515 * @invocation: (transfer full): A #GDBusMethodInvocation.
9517 * 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.
9519 * This method will free @invocation, you cannot use it afterwards.
9524 * _g_freedesktop_dbus_complete_get_connection_selinux_security_context:
9525 * @object: A #_GFreedesktopDBus.
9526 * @invocation: (transfer full): A #GDBusMethodInvocation.
9527 * @security_context: Parameter to return.
9529 * 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.
9531 * This method will free @invocation, you cannot use it afterwards.
9536 * _g_freedesktop_dbus_complete_get_connection_unix_process_id:
9537 * @object: A #_GFreedesktopDBus.
9538 * @invocation: (transfer full): A #GDBusMethodInvocation.
9539 * @pid: Parameter to return.
9541 * 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.
9543 * This method will free @invocation, you cannot use it afterwards.
9548 * _g_freedesktop_dbus_complete_get_connection_unix_user:
9549 * @object: A #_GFreedesktopDBus.
9550 * @invocation: (transfer full): A #GDBusMethodInvocation.
9551 * @uid: Parameter to return.
9553 * 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.
9555 * This method will free @invocation, you cannot use it afterwards.
9560 * _g_freedesktop_dbus_complete_get_id:
9561 * @object: A #_GFreedesktopDBus.
9562 * @invocation: (transfer full): A #GDBusMethodInvocation.
9563 * @unique_id: Parameter to return.
9565 * 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.
9567 * This method will free @invocation, you cannot use it afterwards.
9572 * _g_freedesktop_dbus_complete_get_name_owner:
9573 * @object: A #_GFreedesktopDBus.
9574 * @invocation: (transfer full): A #GDBusMethodInvocation.
9575 * @unique_name: Parameter to return.
9577 * 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.
9579 * This method will free @invocation, you cannot use it afterwards.
9584 * _g_freedesktop_dbus_complete_hello:
9585 * @object: A #_GFreedesktopDBus.
9586 * @invocation: (transfer full): A #GDBusMethodInvocation.
9587 * @assigned_name: Parameter to return.
9589 * 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.
9591 * This method will free @invocation, you cannot use it afterwards.
9596 * _g_freedesktop_dbus_complete_list_activatable_names:
9597 * @object: A #_GFreedesktopDBus.
9598 * @invocation: (transfer full): A #GDBusMethodInvocation.
9599 * @activatable_names: Parameter to return.
9601 * 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.
9603 * This method will free @invocation, you cannot use it afterwards.
9608 * _g_freedesktop_dbus_complete_list_names:
9609 * @object: A #_GFreedesktopDBus.
9610 * @invocation: (transfer full): A #GDBusMethodInvocation.
9611 * @names: Parameter to return.
9613 * 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.
9615 * This method will free @invocation, you cannot use it afterwards.
9620 * _g_freedesktop_dbus_complete_list_queued_owners:
9621 * @object: A #_GFreedesktopDBus.
9622 * @invocation: (transfer full): A #GDBusMethodInvocation.
9623 * @queued_owners: Parameter to return.
9625 * 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.
9627 * This method will free @invocation, you cannot use it afterwards.
9632 * _g_freedesktop_dbus_complete_name_has_owner:
9633 * @object: A #_GFreedesktopDBus.
9634 * @invocation: (transfer full): A #GDBusMethodInvocation.
9635 * @has_owner: Parameter to return.
9637 * 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.
9639 * This method will free @invocation, you cannot use it afterwards.
9644 * _g_freedesktop_dbus_complete_release_name:
9645 * @object: A #_GFreedesktopDBus.
9646 * @invocation: (transfer full): A #GDBusMethodInvocation.
9647 * @value: Parameter to return.
9649 * 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.
9651 * This method will free @invocation, you cannot use it afterwards.
9656 * _g_freedesktop_dbus_complete_reload_config:
9657 * @object: A #_GFreedesktopDBus.
9658 * @invocation: (transfer full): A #GDBusMethodInvocation.
9660 * 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.
9662 * This method will free @invocation, you cannot use it afterwards.
9667 * _g_freedesktop_dbus_complete_remove_match:
9668 * @object: A #_GFreedesktopDBus.
9669 * @invocation: (transfer full): A #GDBusMethodInvocation.
9671 * 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.
9673 * This method will free @invocation, you cannot use it afterwards.
9678 * _g_freedesktop_dbus_complete_request_name:
9679 * @object: A #_GFreedesktopDBus.
9680 * @invocation: (transfer full): A #GDBusMethodInvocation.
9681 * @value: Parameter to return.
9683 * 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.
9685 * This method will free @invocation, you cannot use it afterwards.
9690 * _g_freedesktop_dbus_complete_start_service_by_name:
9691 * @object: A #_GFreedesktopDBus.
9692 * @invocation: (transfer full): A #GDBusMethodInvocation.
9693 * @value: Parameter to return.
9695 * 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.
9697 * This method will free @invocation, you cannot use it afterwards.
9702 * _g_freedesktop_dbus_complete_update_activation_environment:
9703 * @object: A #_GFreedesktopDBus.
9704 * @invocation: (transfer full): A #GDBusMethodInvocation.
9706 * 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.
9708 * This method will free @invocation, you cannot use it afterwards.
9713 * _g_freedesktop_dbus_emit_name_acquired:
9714 * @object: A #_GFreedesktopDBus.
9715 * @arg_name: Argument to pass with the signal.
9717 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> D-Bus signal.
9722 * _g_freedesktop_dbus_emit_name_lost:
9723 * @object: A #_GFreedesktopDBus.
9724 * @arg_name: Argument to pass with the signal.
9726 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> D-Bus signal.
9731 * _g_freedesktop_dbus_emit_name_owner_changed:
9732 * @object: A #_GFreedesktopDBus.
9733 * @arg_name: Argument to pass with the signal.
9734 * @arg_old_owner: Argument to pass with the signal.
9735 * @arg_new_owner: Argument to pass with the signal.
9737 * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> D-Bus signal.
9742 * _g_freedesktop_dbus_interface_info:
9744 * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface.
9746 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
9751 * _g_freedesktop_dbus_override_properties:
9752 * @klass: The class structure for a #GObject<!-- -->-derived class.
9753 * @property_id_begin: The property id to assign to the first overridden property.
9755 * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
9756 * The properties are overridden in the order they are defined.
9758 * Returns: The last property id.
9763 * _g_freedesktop_dbus_proxy_new:
9764 * @connection: A #GDBusConnection.
9765 * @flags: Flags from the #GDBusProxyFlags enumeration.
9766 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9767 * @object_path: An object path.
9768 * @cancellable: (allow-none): A #GCancellable or %NULL.
9769 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9770 * @user_data: User data to pass to @callback.
9772 * 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.
9774 * 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.
9775 * You can then call _g_freedesktop_dbus_proxy_new_finish() to get the result of the operation.
9777 * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor.
9782 * _g_freedesktop_dbus_proxy_new_finish:
9783 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new().
9784 * @error: Return location for error or %NULL
9786 * Finishes an operation started with _g_freedesktop_dbus_proxy_new().
9788 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9793 * _g_freedesktop_dbus_proxy_new_for_bus:
9794 * @bus_type: A #GBusType.
9795 * @flags: Flags from the #GDBusProxyFlags enumeration.
9796 * @name: A bus name (well-known or unique).
9797 * @object_path: An object path.
9798 * @cancellable: (allow-none): A #GCancellable or %NULL.
9799 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
9800 * @user_data: User data to pass to @callback.
9802 * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
9804 * 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.
9805 * You can then call _g_freedesktop_dbus_proxy_new_for_bus_finish() to get the result of the operation.
9807 * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
9812 * _g_freedesktop_dbus_proxy_new_for_bus_finish:
9813 * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new_for_bus().
9814 * @error: Return location for error or %NULL
9816 * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus().
9818 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9823 * _g_freedesktop_dbus_proxy_new_for_bus_sync:
9824 * @bus_type: A #GBusType.
9825 * @flags: Flags from the #GDBusProxyFlags enumeration.
9826 * @name: A bus name (well-known or unique).
9827 * @object_path: An object path.
9828 * @cancellable: (allow-none): A #GCancellable or %NULL.
9829 * @error: Return location for error or %NULL
9831 * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
9833 * The calling thread is blocked until a reply is received.
9835 * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor.
9837 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9842 * _g_freedesktop_dbus_proxy_new_sync:
9843 * @connection: A #GDBusConnection.
9844 * @flags: Flags from the #GDBusProxyFlags enumeration.
9845 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
9846 * @object_path: An object path.
9847 * @cancellable: (allow-none): A #GCancellable or %NULL.
9848 * @error: Return location for error or %NULL
9850 * 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.
9852 * The calling thread is blocked until a reply is received.
9854 * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor.
9856 * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
9861 * _g_freedesktop_dbus_skeleton_new:
9863 * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
9865 * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object.
9870 * _g_io_module_get_default:
9871 * @extension_point: the name of an extension point
9872 * @envvar: (allow-none): the name of an environment variable to
9873 * override the default implementation.
9874 * @verify_func: (allow-none): a function to call to verify that
9875 * a given implementation is usable in the current environment.
9877 * Retrieves the default object implementing @extension_point.
9879 * If @envvar is not %NULL, and the environment variable with that
9880 * name is set, then the implementation it specifies will be tried
9881 * first. After that, or if @envvar is not set, all other
9882 * implementations will be tried in order of decreasing priority.
9884 * If an extension point implementation implements #GInitable, then
9885 * that implementation will only be used if it initializes
9886 * successfully. Otherwise, if @verify_func is not %NULL, then it will
9887 * be called on each candidate implementation after construction, to
9888 * check if it is actually usable or not.
9890 * The result is cached after it is generated the first time, and
9891 * the function is thread-safe.
9893 * Returns: (transfer none): an object implementing
9894 * @extension_point, or %NULL if there are no usable
9900 * _g_io_module_get_default_type:
9901 * @extension_point: the name of an extension point
9902 * @envvar: (allow-none): the name of an environment variable to
9903 * override the default implementation.
9904 * @is_supported_offset: a vtable offset, or zero
9906 * Retrieves the default class implementing @extension_point.
9908 * If @envvar is not %NULL, and the environment variable with that
9909 * name is set, then the implementation it specifies will be tried
9910 * first. After that, or if @envvar is not set, all other
9911 * implementations will be tried in order of decreasing priority.
9913 * If @is_supported_offset is non-zero, then it is the offset into the
9914 * class vtable at which there is a function that takes no arguments and
9915 * returns a boolean. This function will be called on each candidate
9916 * implementation to check if it is actually usable or not.
9918 * The result is cached after it is generated the first time, and
9919 * the function is thread-safe.
9921 * Returns: (transfer none): an object implementing
9922 * @extension_point, or %NULL if there are no usable
9928 * g_action_activate:
9929 * @action: a #GAction
9930 * @parameter: (allow-none): the parameter to the activation
9932 * Activates the action.
9934 * @parameter must be the correct type of parameter for the action (ie:
9935 * the parameter type given at construction time). If the parameter
9936 * type was %NULL then @parameter must also be %NULL.
9938 * If the @parameter GVariant is floating, it is consumed.
9945 * g_action_change_state:
9946 * @action: a #GAction
9947 * @value: the new state
9949 * Request for the state of @action to be changed to @value.
9951 * The action must be stateful and @value must be of the correct type.
9952 * See g_action_get_state_type().
9954 * This call merely requests a change. The action may refuse to change
9955 * its state or may change its state to something other than @value.
9956 * See g_action_get_state_hint().
9958 * If the @value GVariant is floating, it is consumed.
9965 * g_action_get_enabled:
9966 * @action: a #GAction
9968 * Checks if @action is currently enabled.
9970 * An action must be enabled in order to be activated or in order to
9971 * have its state changed from outside callers.
9973 * Returns: whether the action is enabled
9979 * g_action_get_name:
9980 * @action: a #GAction
9982 * Queries the name of @action.
9984 * Returns: the name of the action
9990 * g_action_get_parameter_type:
9991 * @action: a #GAction
9993 * Queries the type of the parameter that must be given when activating
9996 * When activating the action using g_action_activate(), the #GVariant
9997 * given to that function must be of the type returned by this function.
9999 * In the case that this function returns %NULL, you must not give any
10000 * #GVariant, but %NULL instead.
10002 * Returns: (allow-none): the parameter type
10008 * g_action_get_state:
10009 * @action: a #GAction
10011 * Queries the current state of @action.
10013 * If the action is not stateful then %NULL will be returned. If the
10014 * action is stateful then the type of the return value is the type
10015 * given by g_action_get_state_type().
10017 * The return value (if non-%NULL) should be freed with
10018 * g_variant_unref() when it is no longer required.
10020 * Returns: (transfer full): the current state of the action
10026 * g_action_get_state_hint:
10027 * @action: a #GAction
10029 * Requests a hint about the valid range of values for the state of
10032 * If %NULL is returned it either means that the action is not stateful
10033 * or that there is no hint about the valid range of values for the
10034 * state of the action.
10036 * If a #GVariant array is returned then each item in the array is a
10037 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10038 * returned then the tuple specifies the inclusive lower and upper bound
10039 * of valid values for the state.
10041 * In any case, the information is merely a hint. It may be possible to
10042 * have a state value outside of the hinted range and setting a value
10043 * within the range may fail.
10045 * The return value (if non-%NULL) should be freed with
10046 * g_variant_unref() when it is no longer required.
10048 * Returns: (transfer full): the state range hint
10054 * g_action_get_state_type:
10055 * @action: a #GAction
10057 * Queries the type of the state of @action.
10059 * If the action is stateful (e.g. created with
10060 * g_simple_action_new_stateful()) then this function returns the
10061 * #GVariantType of the state. This is the type of the initial value
10062 * given as the state. All calls to g_action_change_state() must give a
10063 * #GVariant of this type and g_action_get_state() will return a
10064 * #GVariant of the same type.
10066 * If the action is not stateful (e.g. created with g_simple_action_new())
10067 * then this function will return %NULL. In that case, g_action_get_state()
10068 * will return %NULL and you must not call g_action_change_state().
10070 * Returns: (allow-none): the state type, if the action is stateful
10076 * g_action_group_action_added:
10077 * @action_group: a #GActionGroup
10078 * @action_name: the name of an action in the group
10080 * Emits the #GActionGroup::action-added signal on @action_group.
10082 * This function should only be called by #GActionGroup implementations.
10089 * g_action_group_action_enabled_changed:
10090 * @action_group: a #GActionGroup
10091 * @action_name: the name of an action in the group
10092 * @enabled: whether or not the action is now enabled
10094 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
10096 * This function should only be called by #GActionGroup implementations.
10103 * g_action_group_action_removed:
10104 * @action_group: a #GActionGroup
10105 * @action_name: the name of an action in the group
10107 * Emits the #GActionGroup::action-removed signal on @action_group.
10109 * This function should only be called by #GActionGroup implementations.
10116 * g_action_group_action_state_changed:
10117 * @action_group: a #GActionGroup
10118 * @action_name: the name of an action in the group
10119 * @state: the new state of the named action
10121 * Emits the #GActionGroup::action-state-changed signal on @action_group.
10123 * This function should only be called by #GActionGroup implementations.
10130 * g_action_group_activate_action:
10131 * @action_group: a #GActionGroup
10132 * @action_name: the name of the action to activate
10133 * @parameter: (allow-none): parameters to the activation
10135 * Activate the named action within @action_group.
10137 * If the action is expecting a parameter, then the correct type of
10138 * parameter must be given as @parameter. If the action is expecting no
10139 * parameters then @parameter must be %NULL. See
10140 * g_action_group_get_action_parameter_type().
10147 * g_action_group_change_action_state:
10148 * @action_group: a #GActionGroup
10149 * @action_name: the name of the action to request the change on
10150 * @value: the new state
10152 * Request for the state of the named action within @action_group to be
10153 * changed to @value.
10155 * The action must be stateful and @value must be of the correct type.
10156 * See g_action_group_get_action_state_type().
10158 * This call merely requests a change. The action may refuse to change
10159 * its state or may change its state to something other than @value.
10160 * See g_action_group_get_action_state_hint().
10162 * If the @value GVariant is floating, it is consumed.
10169 * g_action_group_get_action_enabled:
10170 * @action_group: a #GActionGroup
10171 * @action_name: the name of the action to query
10173 * Checks if the named action within @action_group is currently enabled.
10175 * An action must be enabled in order to be activated or in order to
10176 * have its state changed from outside callers.
10178 * Returns: whether or not the action is currently enabled
10184 * g_action_group_get_action_parameter_type:
10185 * @action_group: a #GActionGroup
10186 * @action_name: the name of the action to query
10188 * Queries the type of the parameter that must be given when activating
10189 * the named action within @action_group.
10191 * When activating the action using g_action_group_activate_action(),
10192 * the #GVariant given to that function must be of the type returned
10193 * by this function.
10195 * In the case that this function returns %NULL, you must not give any
10196 * #GVariant, but %NULL instead.
10198 * The parameter type of a particular action will never change but it is
10199 * possible for an action to be removed and for a new action to be added
10200 * with the same name but a different parameter type.
10202 * Returns: the parameter type
10208 * g_action_group_get_action_state:
10209 * @action_group: a #GActionGroup
10210 * @action_name: the name of the action to query
10212 * Queries the current state of the named action within @action_group.
10214 * If the action is not stateful then %NULL will be returned. If the
10215 * action is stateful then the type of the return value is the type
10216 * given by g_action_group_get_action_state_type().
10218 * The return value (if non-%NULL) should be freed with
10219 * g_variant_unref() when it is no longer required.
10221 * Returns: (allow-none): the current state of the action
10227 * g_action_group_get_action_state_hint:
10228 * @action_group: a #GActionGroup
10229 * @action_name: the name of the action to query
10231 * Requests a hint about the valid range of values for the state of the
10232 * named action within @action_group.
10234 * If %NULL is returned it either means that the action is not stateful
10235 * or that there is no hint about the valid range of values for the
10236 * state of the action.
10238 * If a #GVariant array is returned then each item in the array is a
10239 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
10240 * returned then the tuple specifies the inclusive lower and upper bound
10241 * of valid values for the state.
10243 * In any case, the information is merely a hint. It may be possible to
10244 * have a state value outside of the hinted range and setting a value
10245 * within the range may fail.
10247 * The return value (if non-%NULL) should be freed with
10248 * g_variant_unref() when it is no longer required.
10250 * Returns: (transfer full): the state range hint
10256 * g_action_group_get_action_state_type:
10257 * @action_group: a #GActionGroup
10258 * @action_name: the name of the action to query
10260 * Queries the type of the state of the named action within
10263 * If the action is stateful then this function returns the
10264 * #GVariantType of the state. All calls to
10265 * g_action_group_change_action_state() must give a #GVariant of this
10266 * type and g_action_group_get_action_state() will return a #GVariant
10267 * of the same type.
10269 * If the action is not stateful then this function will return %NULL.
10270 * In that case, g_action_group_get_action_state() will return %NULL
10271 * and you must not call g_action_group_change_action_state().
10273 * The state type of a particular action will never change but it is
10274 * possible for an action to be removed and for a new action to be added
10275 * with the same name but a different state type.
10277 * Returns: (transfer full): the state type, if the action is stateful
10283 * g_action_group_has_action:
10284 * @action_group: a #GActionGroup
10285 * @action_name: the name of the action to check for
10287 * Checks if the named action exists within @action_group.
10289 * Returns: whether the named action exists
10295 * g_action_group_list_actions:
10296 * @action_group: a #GActionGroup
10298 * Lists the actions contained within @action_group.
10300 * The caller is responsible for freeing the list with g_strfreev() when
10301 * it is no longer required.
10303 * Returns: (transfer full): a %NULL-terminated array of the names of the
10304 * actions in the groupb
10310 * g_action_group_query_action:
10311 * @action_group: a #GActionGroup
10312 * @action_name: the name of an action in the group
10313 * @enabled: (out): if the action is presently enabled
10314 * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
10315 * @state_type: (out) (allow-none): the state type, or %NULL if stateless
10316 * @state_hint: (out) (allow-none): the state hint, or %NULL if none
10317 * @state: (out) (allow-none): the current state, or %NULL if stateless
10319 * Queries all aspects of the named action within an @action_group.
10321 * This function acquires the information available from
10322 * g_action_group_has_action(), g_action_group_get_action_enabled(),
10323 * g_action_group_get_action_parameter_type(),
10324 * g_action_group_get_action_state_type(),
10325 * g_action_group_get_action_state_hint() and
10326 * g_action_group_get_action_state() with a single function call.
10328 * This provides two main benefits.
10330 * The first is the improvement in efficiency that comes with not having
10331 * to perform repeated lookups of the action in order to discover
10332 * different things about it. The second is that implementing
10333 * #GActionGroup can now be done by only overriding this one virtual
10336 * The interface provides a default implementation of this function that
10337 * calls the individual functions, as required, to fetch the
10338 * information. The interface also provides default implementations of
10339 * those functions that call this function. All implementations,
10340 * therefore, must override either this function or all of the others.
10342 * If the action exists, %TRUE is returned and any of the requested
10343 * fields (as indicated by having a non-%NULL reference passed in) are
10344 * filled. If the action doesn't exist, %FALSE is returned and the
10345 * fields may or may not have been modified.
10347 * Returns: %TRUE if the action exists, else %FALSE
10353 * g_action_map_add_action:
10354 * @action_map: a #GActionMap
10355 * @action: a #GAction
10357 * Adds an action to the @action_map.
10359 * If the action map already contains an action with the same name
10360 * as @action then the old action is dropped from the action map.
10362 * The action map takes its own reference on @action.
10369 * g_action_map_add_action_entries:
10370 * @action_map: a #GActionMap
10371 * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to
10372 * the first item in an array of #GActionEntry structs
10373 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
10374 * @user_data: the user data for signal connections
10376 * A convenience function for creating multiple #GSimpleAction instances
10377 * and adding them to a #GActionMap.
10379 * Each action is constructed as per one #GActionEntry.
10382 * <title>Using g_action_map_add_action_entries()</title>
10385 * activate_quit (GSimpleAction *simple,
10386 * GVariant *parameter,
10387 * gpointer user_data)
10393 * activate_print_string (GSimpleAction *simple,
10394 * GVariant *parameter,
10395 * gpointer user_data)
10397 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
10400 * static GActionGroup *
10401 * create_action_group (void)
10403 * const GActionEntry entries[] = {
10404 * { "quit", activate_quit },
10405 * { "print-string", activate_print_string, "s" }
10407 * GSimpleActionGroup *group;
10409 * group = g_simple_action_group_new ();
10410 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
10412 * return G_ACTION_GROUP (group);
10414 * </programlisting>
10422 * g_action_map_lookup_action:
10423 * @action_map: a #GActionMap
10424 * @action_name: the name of an action
10426 * Looks up the action with the name @action_name in @action_map.
10428 * If no such action exists, returns %NULL.
10430 * Returns: (transfer none): a #GAction, or %NULL
10436 * g_action_map_remove_action:
10437 * @action_map: a #GActionMap
10438 * @action_name: the name of the action
10440 * Removes the named action from the action map.
10442 * If no action of this name is in the map then nothing happens.
10449 * g_action_name_is_valid:
10450 * @action_name: an potential action name
10452 * Checks if @action_name is valid.
10454 * @action_name is valid if it consists only of alphanumeric characters,
10455 * plus '-' and '.'. The empty string is not a valid action name.
10457 * It is an error to call this function with a non-utf8 @action_name.
10458 * @action_name must not be %NULL.
10460 * Returns: %TRUE if @action_name is valid
10466 * g_action_parse_detailed_name:
10467 * @detailed_name: a detailed action name
10468 * @action_name: (out): the action name
10469 * @target_value: (out): the target value, or %NULL for no target
10470 * @error: a pointer to a %NULL #GError, or %NULL
10472 * Parses a detailed action name into its separate name and target
10475 * Detailed action names can have three formats.
10477 * The first format is used to represent an action name with no target
10478 * value and consists of just an action name containing no whitespace
10479 * nor the characters ':', '(' or ')'. For example: "app.action".
10481 * The second format is used to represent an action with a target value
10482 * that is a non-empty string consisting only of alphanumerics, plus '-'
10483 * and '.'. In that case, the action name and target value are
10484 * separated by a double colon ("::"). For example:
10485 * "app.action::target".
10487 * The third format is used to represent an action with any type of
10488 * target value, including strings. The target value follows the action
10489 * name, surrounded in parens. For example: "app.action(42)". The
10490 * target value is parsed using g_variant_parse(). If a tuple-typed
10491 * value is desired, it must be specified in the same way, resulting in
10492 * two sets of parens, for example: "app.action((1,2,3))". A string
10493 * target can be specified this way as well: "app.action('target')".
10494 * For strings, this third format must be used if * target value is
10495 * empty or contains characters other than alphanumerics, '-' and '.'.
10497 * Returns: %TRUE if successful, else %FALSE with @error set
10503 * g_action_print_detailed_name:
10504 * @action_name: a valid action name
10505 * @target_value: (allow-none): a #GVariant target value, or %NULL
10507 * Formats a detailed action name from @action_name and @target_value.
10509 * It is an error to call this function with an invalid action name.
10511 * This function is the opposite of
10512 * g_action_parse_detailed_action_name(). It will produce a string that
10513 * can be parsed back to the @action_name and @target_value by that
10516 * See that function for the types of strings that will be printed by
10519 * Returns: a detailed format string
10525 * g_app_info_add_supports_type:
10526 * @appinfo: a #GAppInfo.
10527 * @content_type: a string.
10528 * @error: a #GError.
10530 * Adds a content type to the application information to indicate the
10531 * application is capable of opening files with the given content type.
10533 * Returns: %TRUE on success, %FALSE on error.
10538 * g_app_info_can_delete:
10539 * @appinfo: a #GAppInfo
10541 * Obtains the information whether the #GAppInfo can be deleted.
10542 * See g_app_info_delete().
10544 * Returns: %TRUE if @appinfo can be deleted
10550 * g_app_info_can_remove_supports_type:
10551 * @appinfo: a #GAppInfo.
10553 * Checks if a supported content type can be removed from an application.
10555 * Returns: %TRUE if it is possible to remove supported
10556 * content types from a given @appinfo, %FALSE if not.
10561 * g_app_info_create_from_commandline:
10562 * @commandline: the commandline to use
10563 * @application_name: (allow-none): the application name, or %NULL to use @commandline
10564 * @flags: flags that can specify details of the created #GAppInfo
10565 * @error: a #GError location to store the error occurring, %NULL to ignore.
10567 * Creates a new #GAppInfo from the given information.
10569 * Note that for @commandline, the quoting rules of the Exec key of the
10570 * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">freedesktop.org Desktop
10571 * Entry Specification</ulink> are applied. For example, if the @commandline contains
10572 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
10573 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
10575 * Returns: (transfer full): new #GAppInfo for given command.
10580 * g_app_info_delete: (virtual do_delete)
10581 * @appinfo: a #GAppInfo
10583 * Tries to delete a #GAppInfo.
10585 * On some platforms, there may be a difference between user-defined
10586 * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
10587 * cannot. See g_app_info_can_delete().
10589 * Returns: %TRUE if @appinfo has been deleted
10596 * @appinfo: a #GAppInfo.
10598 * Creates a duplicate of a #GAppInfo.
10600 * Returns: (transfer full): a duplicate of @appinfo.
10605 * g_app_info_equal:
10606 * @appinfo1: the first #GAppInfo.
10607 * @appinfo2: the second #GAppInfo.
10609 * Checks if two #GAppInfo<!-- -->s are equal.
10611 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
10616 * g_app_info_get_all:
10618 * Gets a list of all of the applications currently registered
10621 * For desktop files, this includes applications that have
10622 * <literal>NoDisplay=true</literal> set or are excluded from
10623 * display by means of <literal>OnlyShowIn</literal> or
10624 * <literal>NotShowIn</literal>. See g_app_info_should_show().
10625 * The returned list does not include applications which have
10626 * the <literal>Hidden</literal> key set.
10628 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
10633 * g_app_info_get_all_for_type:
10634 * @content_type: the content type to find a #GAppInfo for
10636 * Gets a list of all #GAppInfos for a given content type,
10637 * including the recommended and fallback #GAppInfos. See
10638 * g_app_info_get_recommended_for_type() and
10639 * g_app_info_get_fallback_for_type().
10641 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10642 * for given @content_type or %NULL on error.
10647 * g_app_info_get_commandline:
10648 * @appinfo: a #GAppInfo
10650 * Gets the commandline with which the application will be
10653 * Returns: a string containing the @appinfo's commandline,
10654 * or %NULL if this information is not available
10660 * g_app_info_get_default_for_type:
10661 * @content_type: the content type to find a #GAppInfo for
10662 * @must_support_uris: if %TRUE, the #GAppInfo is expected to
10665 * Gets the default #GAppInfo for a given content type.
10667 * Returns: (transfer full): #GAppInfo for given @content_type or
10673 * g_app_info_get_default_for_uri_scheme:
10674 * @uri_scheme: a string containing a URI scheme.
10676 * Gets the default application for handling URIs with
10677 * the given URI scheme. A URI scheme is the initial part
10678 * of the URI, up to but not including the ':', e.g. "http",
10681 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
10686 * g_app_info_get_description:
10687 * @appinfo: a #GAppInfo.
10689 * Gets a human-readable description of an installed application.
10691 * Returns: a string containing a description of the
10692 * application @appinfo, or %NULL if none.
10697 * g_app_info_get_display_name:
10698 * @appinfo: a #GAppInfo.
10700 * Gets the display name of the application. The display name is often more
10701 * descriptive to the user than the name itself.
10703 * Returns: the display name of the application for @appinfo, or the name if
10704 * no display name is available.
10710 * g_app_info_get_executable:
10711 * @appinfo: a #GAppInfo
10713 * Gets the executable's name for the installed application.
10715 * Returns: a string containing the @appinfo's application
10721 * g_app_info_get_fallback_for_type:
10722 * @content_type: the content type to find a #GAppInfo for
10724 * Gets a list of fallback #GAppInfos for a given content type, i.e.
10725 * those applications which claim to support the given content type
10726 * by MIME type subclassing and not directly.
10728 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10729 * for given @content_type or %NULL on error.
10735 * g_app_info_get_icon:
10736 * @appinfo: a #GAppInfo.
10738 * Gets the icon for the application.
10740 * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
10741 * if there is no default icon.
10746 * g_app_info_get_id:
10747 * @appinfo: a #GAppInfo.
10749 * Gets the ID of an application. An id is a string that
10750 * identifies the application. The exact format of the id is
10751 * platform dependent. For instance, on Unix this is the
10752 * desktop file id from the xdg menu specification.
10754 * Note that the returned ID may be %NULL, depending on how
10755 * the @appinfo has been constructed.
10757 * Returns: a string containing the application's ID.
10762 * g_app_info_get_name:
10763 * @appinfo: a #GAppInfo.
10765 * Gets the installed name of the application.
10767 * Returns: the name of the application for @appinfo.
10772 * g_app_info_get_recommended_for_type:
10773 * @content_type: the content type to find a #GAppInfo for
10775 * Gets a list of recommended #GAppInfos for a given content type, i.e.
10776 * those applications which claim to support the given content type exactly,
10777 * and not by MIME type subclassing.
10778 * Note that the first application of the list is the last used one, i.e.
10779 * the last one for which g_app_info_set_as_last_used_for_type() has been
10782 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
10783 * for given @content_type or %NULL on error.
10789 * g_app_info_get_supported_types:
10790 * @appinfo: a #GAppInfo that can handle files
10792 * Retrieves the list of content types that @app_info claims to support.
10793 * If this information is not provided by the environment, this function
10794 * will return %NULL.
10795 * This function does not take in consideration associations added with
10796 * g_app_info_add_supports_type(), but only those exported directly by
10799 * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
10800 * a list of content types.
10806 * g_app_info_launch:
10807 * @appinfo: a #GAppInfo
10808 * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
10809 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
10810 * @error: a #GError
10812 * Launches the application. Passes @files to the launched application
10813 * as arguments, using the optional @launch_context to get information
10814 * about the details of the launcher (like what screen it is on).
10815 * On error, @error will be set accordingly.
10817 * To launch the application without arguments pass a %NULL @files list.
10819 * Note that even if the launch is successful the application launched
10820 * can fail to start if it runs into problems during startup. There is
10821 * no way to detect this.
10823 * Some URIs can be changed when passed through a GFile (for instance
10824 * unsupported URIs with strange formats like mailto:), so if you have
10825 * a textual URI you want to pass in as argument, consider using
10826 * g_app_info_launch_uris() instead.
10828 * The launched application inherits the environment of the launching
10829 * process, but it can be modified with g_app_launch_context_setenv() and
10830 * g_app_launch_context_unsetenv().
10832 * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
10833 * environment variable with the path of the launched desktop file and
10834 * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
10835 * id of the launched process. This can be used to ignore
10836 * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
10837 * by further processes. The <envar>DISPLAY</envar> and
10838 * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
10839 * set, based on information provided in @launch_context.
10841 * Returns: %TRUE on successful launch, %FALSE otherwise.
10846 * g_app_info_launch_default_for_uri:
10847 * @uri: the uri to show
10848 * @launch_context: (allow-none): an optional #GAppLaunchContext.
10849 * @error: a #GError.
10851 * Utility function that launches the default application
10852 * registered to handle the specified uri. Synchronous I/O
10853 * is done on the uri to detect the type of the file if
10856 * Returns: %TRUE on success, %FALSE on error.
10861 * g_app_info_launch_uris:
10862 * @appinfo: a #GAppInfo
10863 * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
10864 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
10865 * @error: a #GError
10867 * Launches the application. This passes the @uris to the launched application
10868 * as arguments, using the optional @launch_context to get information
10869 * about the details of the launcher (like what screen it is on).
10870 * On error, @error will be set accordingly.
10872 * To launch the application without arguments pass a %NULL @uris list.
10874 * Note that even if the launch is successful the application launched
10875 * can fail to start if it runs into problems during startup. There is
10876 * no way to detect this.
10878 * Returns: %TRUE on successful launch, %FALSE otherwise.
10883 * g_app_info_monitor_get:
10885 * Gets the #GAppInfoMonitor for the current thread-default main
10888 * The #GAppInfoMonitor will emit a "changed" signal in the
10889 * thread-default main context whenever the list of installed
10890 * applications (as reported by g_app_info_get_all()) may have changed.
10892 * You must only call g_object_unref() on the return value from under
10893 * the same main context as you created it.
10895 * Returns: (transfer full): a reference to a #GAppInfoMonitor
10901 * g_app_info_remove_supports_type:
10902 * @appinfo: a #GAppInfo.
10903 * @content_type: a string.
10904 * @error: a #GError.
10906 * Removes a supported type from an application, if possible.
10908 * Returns: %TRUE on success, %FALSE on error.
10913 * g_app_info_reset_type_associations:
10914 * @content_type: a content type
10916 * Removes all changes to the type associations done by
10917 * g_app_info_set_as_default_for_type(),
10918 * g_app_info_set_as_default_for_extension(),
10919 * g_app_info_add_supports_type() or
10920 * g_app_info_remove_supports_type().
10927 * g_app_info_set_as_default_for_extension:
10928 * @appinfo: a #GAppInfo.
10929 * @extension: a string containing the file extension (without the dot).
10930 * @error: a #GError.
10932 * Sets the application as the default handler for the given file extension.
10934 * Returns: %TRUE on success, %FALSE on error.
10939 * g_app_info_set_as_default_for_type:
10940 * @appinfo: a #GAppInfo.
10941 * @content_type: the content type.
10942 * @error: a #GError.
10944 * Sets the application as the default handler for a given type.
10946 * Returns: %TRUE on success, %FALSE on error.
10951 * g_app_info_set_as_last_used_for_type:
10952 * @appinfo: a #GAppInfo.
10953 * @content_type: the content type.
10954 * @error: a #GError.
10956 * Sets the application as the last used application for a given type.
10957 * This will make the application appear as first in the list returned
10958 * by g_app_info_get_recommended_for_type(), regardless of the default
10959 * application for that content type.
10961 * Returns: %TRUE on success, %FALSE on error.
10966 * g_app_info_should_show:
10967 * @appinfo: a #GAppInfo.
10969 * Checks if the application info should be shown in menus that
10970 * list available applications.
10972 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
10977 * g_app_info_supports_files:
10978 * @appinfo: a #GAppInfo.
10980 * Checks if the application accepts files as arguments.
10982 * Returns: %TRUE if the @appinfo supports files.
10987 * g_app_info_supports_uris:
10988 * @appinfo: a #GAppInfo.
10990 * Checks if the application supports reading files and directories from URIs.
10992 * Returns: %TRUE if the @appinfo supports URIs.
10997 * g_app_launch_context_get_display:
10998 * @context: a #GAppLaunchContext
10999 * @info: a #GAppInfo
11000 * @files: (element-type GFile): a #GList of #GFile objects
11002 * Gets the display string for the @context. This is used to ensure new
11003 * applications are started on the same display as the launching
11004 * application, by setting the <envar>DISPLAY</envar> environment variable.
11006 * Returns: a display string for the display.
11011 * g_app_launch_context_get_environment:
11012 * @context: a #GAppLaunchContext
11014 * Gets the complete environment variable list to be passed to
11015 * the child process when @context is used to launch an application.
11016 * This is a %NULL-terminated array of strings, where each string has
11017 * the form <literal>KEY=VALUE</literal>.
11019 * Returns: (array zero-terminated=1) (transfer full): the
11020 * child's environment
11026 * g_app_launch_context_get_startup_notify_id:
11027 * @context: a #GAppLaunchContext
11028 * @info: a #GAppInfo
11029 * @files: (element-type GFile): a #GList of of #GFile objects
11031 * Initiates startup notification for the application and returns the
11032 * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
11035 * Startup notification IDs are defined in the <ulink
11036 * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
11037 * FreeDesktop.Org Startup Notifications standard</ulink>.
11039 * Returns: a startup notification ID for the application, or %NULL if
11045 * g_app_launch_context_launch_failed:
11046 * @context: a #GAppLaunchContext.
11047 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
11049 * Called when an application has failed to launch, so that it can cancel
11050 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
11055 * g_app_launch_context_new:
11057 * Creates a new application launch context. This is not normally used,
11058 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
11060 * Returns: a #GAppLaunchContext.
11065 * g_app_launch_context_setenv:
11066 * @context: a #GAppLaunchContext
11067 * @variable: the environment variable to set
11068 * @value: the value for to set the variable to.
11070 * Arranges for @variable to be set to @value in the child's
11071 * environment when @context is used to launch an application.
11078 * g_app_launch_context_unsetenv:
11079 * @context: a #GAppLaunchContext
11080 * @variable: the environment variable to remove
11082 * Arranges for @variable to be unset in the child's environment
11083 * when @context is used to launch an application.
11090 * g_application_activate:
11091 * @application: a #GApplication
11093 * Activates the application.
11095 * In essence, this results in the #GApplication::activate signal being
11096 * emitted in the primary instance.
11098 * The application must be registered before calling this function.
11105 * g_application_command_line_create_file_for_arg:
11106 * @cmdline: a #GApplicationCommandLine
11107 * @arg: an argument from @cmdline
11109 * Creates a #GFile corresponding to a filename that was given as part
11110 * of the invocation of @cmdline.
11112 * This differs from g_file_new_for_commandline_arg() in that it
11113 * resolves relative pathnames using the current working directory of
11114 * the invoking process rather than the local process.
11116 * Returns: (transfer full): a new #GFile
11122 * g_application_command_line_get_arguments:
11123 * @cmdline: a #GApplicationCommandLine
11124 * @argc: (out) (allow-none): the length of the arguments array, or %NULL
11126 * Gets the list of arguments that was passed on the command line.
11128 * The strings in the array may contain non-utf8 data.
11130 * The return value is %NULL-terminated and should be freed using
11133 * Returns: (array length=argc) (transfer full): the string array
11134 * containing the arguments (the argv)
11140 * g_application_command_line_get_cwd:
11141 * @cmdline: a #GApplicationCommandLine
11143 * Gets the working directory of the command line invocation.
11144 * The string may contain non-utf8 data.
11146 * It is possible that the remote application did not send a working
11147 * directory, so this may be %NULL.
11149 * The return value should not be modified or freed and is valid for as
11150 * long as @cmdline exists.
11152 * Returns: the current directory, or %NULL
11158 * g_application_command_line_get_environ:
11159 * @cmdline: a #GApplicationCommandLine
11161 * Gets the contents of the 'environ' variable of the command line
11162 * invocation, as would be returned by g_get_environ(), ie as a
11163 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
11164 * The strings may contain non-utf8 data.
11166 * The remote application usually does not send an environment. Use
11167 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
11168 * set it is possible that the environment is still not available (due
11169 * to invocation messages from other applications).
11171 * The return value should not be modified or freed and is valid for as
11172 * long as @cmdline exists.
11174 * See g_application_command_line_getenv() if you are only interested
11175 * in the value of a single environment variable.
11177 * Returns: (array zero-terminated=1) (transfer none): the environment
11178 * strings, or %NULL if they were not sent
11184 * g_application_command_line_get_exit_status:
11185 * @cmdline: a #GApplicationCommandLine
11187 * Gets the exit status of @cmdline. See
11188 * g_application_command_line_set_exit_status() for more information.
11190 * Returns: the exit status
11196 * g_application_command_line_get_is_remote:
11197 * @cmdline: a #GApplicationCommandLine
11199 * Determines if @cmdline represents a remote invocation.
11201 * Returns: %TRUE if the invocation was remote
11207 * g_application_command_line_get_platform_data:
11208 * @cmdline: #GApplicationCommandLine
11210 * Gets the platform data associated with the invocation of @cmdline.
11212 * This is a #GVariant dictionary containing information about the
11213 * context in which the invocation occurred. It typically contains
11214 * information like the current working directory and the startup
11217 * For local invocation, it will be %NULL.
11219 * Returns: (allow-none): the platform data, or %NULL
11225 * g_application_command_line_get_stdin:
11226 * @cmdline: a #GApplicationCommandLine
11228 * Gets the stdin of the invoking process.
11230 * The #GInputStream can be used to read data passed to the standard
11231 * input of the invoking process.
11232 * This doesn't work on all platforms. Presently, it is only available
11233 * on UNIX when using a DBus daemon capable of passing file descriptors.
11234 * If stdin is not available then %NULL will be returned. In the
11235 * future, support may be expanded to other platforms.
11237 * You must only call this function once per commandline invocation.
11239 * Returns: (transfer full): a #GInputStream for stdin
11245 * g_application_command_line_getenv:
11246 * @cmdline: a #GApplicationCommandLine
11247 * @name: the environment variable to get
11249 * Gets the value of a particular environment variable of the command
11250 * line invocation, as would be returned by g_getenv(). The strings may
11251 * contain non-utf8 data.
11253 * The remote application usually does not send an environment. Use
11254 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
11255 * set it is possible that the environment is still not available (due
11256 * to invocation messages from other applications).
11258 * The return value should not be modified or freed and is valid for as
11259 * long as @cmdline exists.
11261 * Returns: the value of the variable, or %NULL if unset or unsent
11267 * g_application_command_line_print:
11268 * @cmdline: a #GApplicationCommandLine
11269 * @format: a printf-style format string
11270 * @...: arguments, as per @format
11272 * Formats a message and prints it using the stdout print handler in the
11273 * invoking process.
11275 * If @cmdline is a local invocation then this is exactly equivalent to
11276 * g_print(). If @cmdline is remote then this is equivalent to calling
11277 * g_print() in the invoking process.
11284 * g_application_command_line_printerr:
11285 * @cmdline: a #GApplicationCommandLine
11286 * @format: a printf-style format string
11287 * @...: arguments, as per @format
11289 * Formats a message and prints it using the stderr print handler in the
11290 * invoking process.
11292 * If @cmdline is a local invocation then this is exactly equivalent to
11293 * g_printerr(). If @cmdline is remote then this is equivalent to
11294 * calling g_printerr() in the invoking process.
11301 * g_application_command_line_set_exit_status:
11302 * @cmdline: a #GApplicationCommandLine
11303 * @exit_status: the exit status
11305 * Sets the exit status that will be used when the invoking process
11308 * The return value of the #GApplication::command-line signal is
11309 * passed to this function when the handler returns. This is the usual
11310 * way of setting the exit status.
11312 * In the event that you want the remote invocation to continue running
11313 * and want to decide on the exit status in the future, you can use this
11314 * call. For the case of a remote invocation, the remote process will
11315 * typically exit when the last reference is dropped on @cmdline. The
11316 * exit status of the remote process will be equal to the last value
11317 * that was set with this function.
11319 * In the case that the commandline invocation is local, the situation
11320 * is slightly more complicated. If the commandline invocation results
11321 * in the mainloop running (ie: because the use-count of the application
11322 * increased to a non-zero value) then the application is considered to
11323 * have been 'successful' in a certain sense, and the exit status is
11324 * always zero. If the application use count is zero, though, the exit
11325 * status of the local #GApplicationCommandLine is used.
11332 * g_application_get_application_id:
11333 * @application: a #GApplication
11335 * Gets the unique identifier for @application.
11337 * Returns: the identifier for @application, owned by @application
11343 * g_application_get_dbus_connection:
11344 * @application: a #GApplication
11346 * Gets the #GDBusConnection being used by the application, or %NULL.
11348 * If #GApplication is using its D-Bus backend then this function will
11349 * return the #GDBusConnection being used for uniqueness and
11350 * communication with the desktop environment and other instances of the
11353 * If #GApplication is not using D-Bus then this function will return
11354 * %NULL. This includes the situation where the D-Bus backend would
11355 * normally be in use but we were unable to connect to the bus.
11357 * This function must not be called before the application has been
11358 * registered. See g_application_get_is_registered().
11360 * Returns: (transfer none): a #GDBusConnection, or %NULL
11366 * g_application_get_dbus_object_path:
11367 * @application: a #GApplication
11369 * Gets the D-Bus object path being used by the application, or %NULL.
11371 * If #GApplication is using its D-Bus backend then this function will
11372 * return the D-Bus object path that #GApplication is using. If the
11373 * application is the primary instance then there is an object published
11374 * at this path. If the application is not the primary instance then
11375 * the result of this function is undefined.
11377 * If #GApplication is not using D-Bus then this function will return
11378 * %NULL. This includes the situation where the D-Bus backend would
11379 * normally be in use but we were unable to connect to the bus.
11381 * This function must not be called before the application has been
11382 * registered. See g_application_get_is_registered().
11384 * Returns: the object path, or %NULL
11390 * g_application_get_default:
11392 * Returns the default #GApplication instance for this process.
11394 * Normally there is only one #GApplication per process and it becomes
11395 * the default when it is created. You can exercise more control over
11396 * this by using g_application_set_default().
11398 * If there is no default application then %NULL is returned.
11400 * Returns: (transfer none): the default application for this process, or %NULL
11406 * g_application_get_flags:
11407 * @application: a #GApplication
11409 * Gets the flags for @application.
11411 * See #GApplicationFlags.
11413 * Returns: the flags for @application
11419 * g_application_get_inactivity_timeout:
11420 * @application: a #GApplication
11422 * Gets the current inactivity timeout for the application.
11424 * This is the amount of time (in milliseconds) after the last call to
11425 * g_application_release() before the application stops running.
11427 * Returns: the timeout, in milliseconds
11433 * g_application_get_is_registered:
11434 * @application: a #GApplication
11436 * Checks if @application is registered.
11438 * An application is registered if g_application_register() has been
11439 * successfully called.
11441 * Returns: %TRUE if @application is registered
11447 * g_application_get_is_remote:
11448 * @application: a #GApplication
11450 * Checks if @application is remote.
11452 * If @application is remote then it means that another instance of
11453 * application already exists (the 'primary' instance). Calls to
11454 * perform actions on @application will result in the actions being
11455 * performed by the primary instance.
11457 * The value of this property cannot be accessed before
11458 * g_application_register() has been called. See
11459 * g_application_get_is_registered().
11461 * Returns: %TRUE if @application is remote
11467 * g_application_hold:
11468 * @application: a #GApplication
11470 * Increases the use count of @application.
11472 * Use this function to indicate that the application has a reason to
11473 * continue to run. For example, g_application_hold() is called by GTK+
11474 * when a toplevel window is on the screen.
11476 * To cancel the hold, call g_application_release().
11481 * g_application_id_is_valid:
11482 * @application_id: a potential application identifier
11484 * Checks if @application_id is a valid application identifier.
11486 * A valid ID is required for calls to g_application_new() and
11487 * g_application_set_application_id().
11489 * For convenience, the restrictions on application identifiers are
11492 * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
11493 * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
11494 * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
11495 * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
11496 * <listitem>Application identifiers must not exceed 255 characters.</listitem>
11499 * Returns: %TRUE if @application_id is valid
11504 * g_application_mark_busy:
11505 * @application: a #GApplication
11507 * Increases the busy count of @application.
11509 * Use this function to indicate that the application is busy, for instance
11510 * while a long running operation is pending.
11512 * The busy state will be exposed to other processes, so a session shell will
11513 * use that information to indicate the state to the user (e.g. with a
11516 * To cancel the busy indication, use g_application_unmark_busy().
11523 * g_application_new:
11524 * @application_id: (allow-none): the application id
11525 * @flags: the application flags
11527 * Creates a new #GApplication instance.
11529 * If non-%NULL, the application id must be valid. See
11530 * g_application_id_is_valid().
11532 * If no application ID is given then some features of #GApplication
11533 * (most notably application uniqueness) will be disabled.
11535 * Returns: a new #GApplication instance
11540 * g_application_open:
11541 * @application: a #GApplication
11542 * @files: (array length=n_files): an array of #GFiles to open
11543 * @n_files: the length of the @files array
11544 * @hint: a hint (or ""), but never %NULL
11546 * Opens the given files.
11548 * In essence, this results in the #GApplication::open signal being emitted
11549 * in the primary instance.
11551 * @n_files must be greater than zero.
11553 * @hint is simply passed through to the ::open signal. It is
11554 * intended to be used by applications that have multiple modes for
11555 * opening files (eg: "view" vs "edit", etc). Unless you have a need
11556 * for this functionality, you should use "".
11558 * The application must be registered before calling this function
11559 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
11566 * g_application_quit:
11567 * @application: a #GApplication
11569 * Immediately quits the application.
11571 * Upon return to the mainloop, g_application_run() will return,
11572 * calling only the 'shutdown' function before doing so.
11574 * The hold count is ignored.
11576 * The result of calling g_application_run() again after it returns is
11584 * g_application_register:
11585 * @application: a #GApplication
11586 * @cancellable: (allow-none): a #GCancellable, or %NULL
11587 * @error: a pointer to a NULL #GError, or %NULL
11589 * Attempts registration of the application.
11591 * This is the point at which the application discovers if it is the
11592 * primary instance or merely acting as a remote for an already-existing
11593 * primary instance. This is implemented by attempting to acquire the
11594 * application identifier as a unique bus name on the session bus using
11597 * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
11598 * given, then this process will always become the primary instance.
11600 * Due to the internal architecture of GDBus, method calls can be
11601 * dispatched at any time (even if a main loop is not running). For
11602 * this reason, you must ensure that any object paths that you wish to
11603 * register are registered before calling this function.
11605 * If the application has already been registered then %TRUE is
11606 * returned with no work performed.
11608 * The #GApplication::startup signal is emitted if registration succeeds
11609 * and @application is the primary instance (including the non-unique
11612 * In the event of an error (such as @cancellable being cancelled, or a
11613 * failure to connect to the session bus), %FALSE is returned and @error
11614 * is set appropriately.
11616 * Note: the return value of this function is not an indicator that this
11617 * instance is or is not the primary instance of the application. See
11618 * g_application_get_is_remote() for that.
11620 * Returns: %TRUE if registration succeeded
11626 * g_application_release:
11627 * @application: a #GApplication
11629 * Decrease the use count of @application.
11631 * When the use count reaches zero, the application will stop running.
11633 * Never call this function except to cancel the effect of a previous
11634 * call to g_application_hold().
11639 * g_application_run:
11640 * @application: a #GApplication
11641 * @argc: the argc from main() (or 0 if @argv is %NULL)
11642 * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
11644 * Runs the application.
11646 * This function is intended to be run from main() and its return value
11647 * is intended to be returned by main(). Although you are expected to pass
11648 * the @argc, @argv parameters from main() to this function, it is possible
11649 * to pass %NULL if @argv is not available or commandline handling is not
11652 * First, the local_command_line() virtual function is invoked.
11653 * This function always runs on the local instance. It gets passed a pointer
11654 * to a %NULL-terminated copy of @argv and is expected to remove the arguments
11655 * that it handled (shifting up remaining arguments). See
11656 * <xref linkend="gapplication-example-cmdline2"/> for an example of
11657 * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
11658 * after setting <literal>argc = g_strv_length (argv);</literal>.
11660 * The last argument to local_command_line() is a pointer to the @status
11661 * variable which can used to set the exit status that is returned from
11662 * g_application_run().
11664 * If local_command_line() returns %TRUE, the command line is expected
11665 * to be completely handled, including possibly registering as the primary
11666 * instance, calling g_application_activate() or g_application_open(), etc.
11668 * If local_command_line() returns %FALSE then the application is registered
11669 * and the #GApplication::command-line signal is emitted in the primary
11670 * instance (which may or may not be this instance). The signal handler
11671 * gets passed a #GApplicationCommandLine object that (among other things)
11672 * contains the remaining commandline arguments that have not been handled
11673 * by local_command_line().
11675 * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
11676 * flag set then the default implementation of local_command_line()
11677 * always returns %FALSE immediately, resulting in the commandline
11678 * always being handled in the primary instance.
11680 * Otherwise, the default implementation of local_command_line() tries
11681 * to do a couple of things that are probably reasonable for most
11682 * applications. First, g_application_register() is called to attempt
11683 * to register the application. If that works, then the command line
11684 * arguments are inspected. If no commandline arguments are given, then
11685 * g_application_activate() is called. If commandline arguments are
11686 * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
11687 * are assumed to be filenames and g_application_open() is called.
11689 * If you need to handle commandline arguments that are not filenames,
11690 * and you don't mind commandline handling to happen in the primary
11691 * instance, you should set %G_APPLICATION_HANDLES_COMMAND_LINE and
11692 * process the commandline arguments in your #GApplication::command-line
11693 * signal handler, either manually or using the #GOptionContext API.
11695 * If you are interested in doing more complicated local handling of the
11696 * commandline then you should implement your own #GApplication subclass
11697 * and override local_command_line(). In this case, you most likely want
11698 * to return %TRUE from your local_command_line() implementation to
11699 * suppress the default handling. See
11700 * <xref linkend="gapplication-example-cmdline2"/> for an example.
11702 * If, after the above is done, the use count of the application is zero
11703 * then the exit status is returned immediately. If the use count is
11704 * non-zero then the default main context is iterated until the use count
11705 * falls to zero, at which point 0 is returned.
11707 * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will
11708 * run for as much as 10 seconds with a use count of zero while waiting
11709 * for the message that caused the activation to arrive. After that,
11710 * if the use count falls to zero the application will exit immediately,
11711 * except in the case that g_application_set_inactivity_timeout() is in
11714 * This function sets the prgname (g_set_prgname()), if not already set,
11715 * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE
11716 * is specified, the prgname is set to the application ID. The main
11717 * impact of this is is that the wmclass of windows created by Gtk+ will
11718 * be set accordingly, which helps the window manager determine which
11719 * application is showing the window.
11721 * Returns: the exit status
11727 * g_application_send_notification:
11728 * @application: a #GApplication
11729 * @id: (allow-none): id of the notification, or %NULL
11730 * @notification: the #GNotification to send
11732 * Sends a notification on behalf of @application to the desktop shell.
11733 * There is no guarantee that the notification is displayed immediately,
11736 * Notifications may persist after the application exits. It will be
11737 * D-Bus-activated when the notification or one of its actions is
11740 * Modifying @notification after this call has no effect. However, the
11741 * object can be reused for a later call to this function.
11743 * @id may be any string that uniquely identifies the event for the
11744 * application. It does not need to be in any special format. For
11745 * example, "new-message" might be appropriate for a notification about
11748 * If a previous notification was sent with the same @id, it will be
11749 * replaced with @notification and shown again as if it was a new
11750 * notification. This works even for notifications sent from a previous
11751 * execution of the application, as long as @id is the same string.
11753 * @id may be %NULL, but it is impossible to replace or withdraw
11754 * notifications without an id.
11756 * If @notification is no longer relevant, it can be withdrawn with
11757 * g_application_withdraw_notification().
11764 * g_application_set_action_group:
11765 * @application: a #GApplication
11766 * @action_group: (allow-none): a #GActionGroup, or %NULL
11768 * This used to be how actions were associated with a #GApplication.
11769 * Now there is #GActionMap for that.
11772 * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever
11773 * mix use of this API with use of #GActionMap on the same @application
11774 * or things will go very badly wrong. This function is known to
11775 * introduce buggy behaviour (ie: signals not emitted on changes to the
11776 * action group), so you should really use #GActionMap instead.
11781 * g_application_set_application_id:
11782 * @application: a #GApplication
11783 * @application_id: (allow-none): the identifier for @application
11785 * Sets the unique identifier for @application.
11787 * The application id can only be modified if @application has not yet
11790 * If non-%NULL, the application id must be valid. See
11791 * g_application_id_is_valid().
11798 * g_application_set_default:
11799 * @application: (allow-none): the application to set as default, or %NULL
11801 * Sets or unsets the default application for the process, as returned
11802 * by g_application_get_default().
11804 * This function does not take its own reference on @application. If
11805 * @application is destroyed then the default application will revert
11813 * g_application_set_flags:
11814 * @application: a #GApplication
11815 * @flags: the flags for @application
11817 * Sets the flags for @application.
11819 * The flags can only be modified if @application has not yet been
11822 * See #GApplicationFlags.
11829 * g_application_set_inactivity_timeout:
11830 * @application: a #GApplication
11831 * @inactivity_timeout: the timeout, in milliseconds
11833 * Sets the current inactivity timeout for the application.
11835 * This is the amount of time (in milliseconds) after the last call to
11836 * g_application_release() before the application stops running.
11838 * This call has no side effects of its own. The value set here is only
11839 * used for next time g_application_release() drops the use count to
11840 * zero. Any timeouts currently in progress are not impacted.
11847 * g_application_unmark_busy:
11848 * @application: a #GApplication
11850 * Decreases the busy count of @application.
11852 * When the busy count reaches zero, the new state will be propagated
11853 * to other processes.
11855 * This function must only be called to cancel the effect of a previous
11856 * call to g_application_mark_busy().
11863 * g_application_withdraw_notification:
11864 * @application: a #GApplication
11865 * @id: id of a previously sent notification
11867 * Withdraws a notification that was sent with
11868 * g_application_send_notification().
11870 * This call does nothing if a notification with @id doesn't exist or
11871 * the notification was never sent.
11873 * This function works even for notifications sent in previous
11874 * executions of this application, as long @id is the same as it was for
11875 * the sent notification.
11877 * Note that notifications are dismissed when the user clicks on one
11878 * of the buttons in a notification or triggers its default action, so
11879 * there is no need to explicitly withdraw the notification in that case.
11886 * g_async_initable_init_async:
11887 * @initable: a #GAsyncInitable.
11888 * @io_priority: the <link linkend="io-priority">I/O priority</link>
11889 * of the operation.
11890 * @cancellable: optional #GCancellable object, %NULL to ignore.
11891 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
11892 * @user_data: the data to pass to callback function
11894 * Starts asynchronous initialization of the object implementing the
11895 * interface. This must be done before any real use of the object after
11896 * initial construction. If the object also implements #GInitable you can
11897 * optionally call g_initable_init() instead.
11899 * When the initialization is finished, @callback will be called. You can
11900 * then call g_async_initable_init_finish() to get the result of the
11903 * Implementations may also support cancellation. If @cancellable is not
11904 * %NULL, then initialization can be cancelled by triggering the cancellable
11905 * object from another thread. If the operation was cancelled, the error
11906 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
11907 * the object doesn't support cancellable initialization, the error
11908 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
11910 * As with #GInitable, if the object is not initialized, or initialization
11911 * returns with an error, then all operations on the object except
11912 * g_object_ref() and g_object_unref() are considered to be invalid, and
11913 * have undefined behaviour. They will often fail with g_critical() or
11914 * g_warning(), but this must not be relied on.
11916 * Implementations of this method must be idempotent: i.e. multiple calls
11917 * to this function with the same argument should return the same results.
11918 * Only the first call initializes the object; further calls return the result
11919 * of the first call. This is so that it's safe to implement the singleton
11920 * pattern in the GObject constructor function.
11922 * For classes that also support the #GInitable interface, the default
11923 * implementation of this method will run the g_initable_init() function
11924 * in a thread, so if you want to support asynchronous initialization via
11925 * threads, just implement the #GAsyncInitable interface without overriding
11926 * any interface methods.
11933 * g_async_initable_init_finish:
11934 * @initable: a #GAsyncInitable.
11935 * @res: a #GAsyncResult.
11936 * @error: a #GError location to store the error occurring, or %NULL to
11939 * Finishes asynchronous initialization and returns the result.
11940 * See g_async_initable_init_async().
11942 * Returns: %TRUE if successful. If an error has occurred, this function
11943 * will return %FALSE and set @error appropriately if present.
11949 * g_async_initable_new_async:
11950 * @object_type: a #GType supporting #GAsyncInitable.
11951 * @io_priority: the <link linkend="io-priority">I/O priority</link>
11952 * of the operation.
11953 * @cancellable: optional #GCancellable object, %NULL to ignore.
11954 * @callback: a #GAsyncReadyCallback to call when the initialization is
11956 * @user_data: the data to pass to callback function
11957 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
11959 * @...: the value of the first property, followed by other property
11960 * value pairs, and ended by %NULL.
11962 * Helper function for constructing #GAsyncInitable object. This is
11963 * similar to g_object_new() but also initializes the object asynchronously.
11965 * When the initialization is finished, @callback will be called. You can
11966 * then call g_async_initable_new_finish() to get the new object and check
11974 * g_async_initable_new_finish:
11975 * @initable: the #GAsyncInitable from the callback
11976 * @res: the #GAsyncResult from the callback
11977 * @error: return location for errors, or %NULL to ignore
11979 * Finishes the async construction for the various g_async_initable_new
11980 * calls, returning the created object or %NULL on error.
11982 * Returns: (type GObject.Object) (transfer full): a newly created #GObject,
11983 * or %NULL on error. Free with g_object_unref().
11989 * g_async_initable_new_valist_async:
11990 * @object_type: a #GType supporting #GAsyncInitable.
11991 * @first_property_name: the name of the first property, followed by
11992 * the value, and other property value pairs, and ended by %NULL.
11993 * @var_args: The var args list generated from @first_property_name.
11994 * @io_priority: the <link linkend="io-priority">I/O priority</link>
11995 * of the operation.
11996 * @cancellable: optional #GCancellable object, %NULL to ignore.
11997 * @callback: a #GAsyncReadyCallback to call when the initialization is
11999 * @user_data: the data to pass to callback function
12001 * Helper function for constructing #GAsyncInitable object. This is
12002 * similar to g_object_new_valist() but also initializes the object
12005 * When the initialization is finished, @callback will be called. You can
12006 * then call g_async_initable_new_finish() to get the new object and check
12014 * g_async_initable_newv_async:
12015 * @object_type: a #GType supporting #GAsyncInitable.
12016 * @n_parameters: the number of parameters in @parameters
12017 * @parameters: the parameters to use to construct the object
12018 * @io_priority: the <link linkend="io-priority">I/O priority</link>
12019 * of the operation.
12020 * @cancellable: optional #GCancellable object, %NULL to ignore.
12021 * @callback: a #GAsyncReadyCallback to call when the initialization is
12023 * @user_data: the data to pass to callback function
12025 * Helper function for constructing #GAsyncInitable object. This is
12026 * similar to g_object_newv() but also initializes the object asynchronously.
12028 * When the initialization is finished, @callback will be called. You can
12029 * then call g_async_initable_new_finish() to get the new object and check
12037 * g_async_result_get_source_object:
12038 * @res: a #GAsyncResult
12040 * Gets the source object from a #GAsyncResult.
12042 * Returns: (transfer full): a new reference to the source object for the @res,
12043 * or %NULL if there is none.
12048 * g_async_result_get_user_data:
12049 * @res: a #GAsyncResult.
12051 * Gets the user data from a #GAsyncResult.
12053 * Returns: (transfer full): the user data for @res.
12058 * g_async_result_is_tagged:
12059 * @res: a #GAsyncResult
12060 * @source_tag: an application-defined tag
12062 * Checks if @res has the given @source_tag (generally a function
12063 * pointer indicating the function @res was created by).
12065 * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
12072 * g_async_result_legacy_propagate_error:
12073 * @res: a #GAsyncResult
12074 * @error: (out): a location to propagate the error to.
12076 * If @res is a #GSimpleAsyncResult, this is equivalent to
12077 * g_simple_async_result_propagate_error(). Otherwise it returns
12080 * This can be used for legacy error handling in async
12081 * <literal>_finish ()</literal> wrapper functions that traditionally
12082 * handled #GSimpleAsyncResult error returns themselves rather than
12083 * calling into the virtual method. This should not be used in new
12084 * code; #GAsyncResult errors that are set by virtual methods should
12085 * also be extracted by virtual methods, to enable subclasses to chain
12088 * Returns: %TRUE if @error is has been filled in with an error from
12089 * @res, %FALSE if not.
12095 * g_buffered_input_stream_fill:
12096 * @stream: a #GBufferedInputStream
12097 * @count: the number of bytes that will be read from the stream
12098 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12099 * @error: location to store the error occurring, or %NULL to ignore
12101 * Tries to read @count bytes from the stream into the buffer.
12102 * Will block during this read.
12104 * If @count is zero, returns zero and does nothing. A value of @count
12105 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
12107 * On success, the number of bytes read into the buffer is returned.
12108 * It is not an error if this is not the same as the requested size, as it
12109 * can happen e.g. near the end of a file. Zero is returned on end of file
12110 * (or if @count is zero), but never otherwise.
12112 * If @count is -1 then the attempted read size is equal to the number of
12113 * bytes that are required to fill the buffer.
12115 * If @cancellable is not %NULL, then the operation can be cancelled by
12116 * triggering the cancellable object from another thread. If the operation
12117 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
12118 * operation was partially finished when the operation was cancelled the
12119 * partial result will be returned, without an error.
12121 * On error -1 is returned and @error is set accordingly.
12123 * For the asynchronous, non-blocking, version of this function, see
12124 * g_buffered_input_stream_fill_async().
12126 * Returns: the number of bytes read into @stream's buffer, up to @count,
12132 * g_buffered_input_stream_fill_async:
12133 * @stream: a #GBufferedInputStream
12134 * @count: the number of bytes that will be read from the stream
12135 * @io_priority: the <link linkend="io-priority">I/O priority</link>
12137 * @cancellable: (allow-none): optional #GCancellable object
12138 * @callback: (scope async): a #GAsyncReadyCallback
12139 * @user_data: (closure): a #gpointer
12141 * Reads data into @stream's buffer asynchronously, up to @count size.
12142 * @io_priority can be used to prioritize reads. For the synchronous
12143 * version of this function, see g_buffered_input_stream_fill().
12145 * If @count is -1 then the attempted read size is equal to the number
12146 * of bytes that are required to fill the buffer.
12151 * g_buffered_input_stream_fill_finish:
12152 * @stream: a #GBufferedInputStream
12153 * @result: a #GAsyncResult
12154 * @error: a #GError
12156 * Finishes an asynchronous read.
12158 * Returns: a #gssize of the read stream, or %-1 on an error.
12163 * g_buffered_input_stream_get_available:
12164 * @stream: #GBufferedInputStream
12166 * Gets the size of the available data within the stream.
12168 * Returns: size of the available stream.
12173 * g_buffered_input_stream_get_buffer_size:
12174 * @stream: a #GBufferedInputStream
12176 * Gets the size of the input buffer.
12178 * Returns: the current buffer size.
12183 * g_buffered_input_stream_new:
12184 * @base_stream: a #GInputStream
12186 * Creates a new #GInputStream from the given @base_stream, with
12187 * a buffer set to the default size (4 kilobytes).
12189 * Returns: a #GInputStream for the given @base_stream.
12194 * g_buffered_input_stream_new_sized:
12195 * @base_stream: a #GInputStream
12198 * Creates a new #GBufferedInputStream from the given @base_stream,
12199 * with a buffer set to @size.
12201 * Returns: a #GInputStream.
12206 * g_buffered_input_stream_peek:
12207 * @stream: a #GBufferedInputStream
12208 * @buffer: (array length=count) (element-type guint8): a pointer to
12209 * an allocated chunk of memory
12210 * @offset: a #gsize
12213 * Peeks in the buffer, copying data of size @count into @buffer,
12214 * offset @offset bytes.
12216 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
12221 * g_buffered_input_stream_peek_buffer:
12222 * @stream: a #GBufferedInputStream
12223 * @count: (out): a #gsize to get the number of bytes available in the buffer
12225 * Returns the buffer with the currently available bytes. The returned
12226 * buffer must not be modified and will become invalid when reading from
12227 * the stream or filling the buffer.
12229 * Returns: (array length=count) (element-type guint8) (transfer none):
12235 * g_buffered_input_stream_read_byte:
12236 * @stream: a #GBufferedInputStream
12237 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
12238 * @error: location to store the error occurring, or %NULL to ignore
12240 * Tries to read a single byte from the stream or the buffer. Will block
12241 * during this read.
12243 * On success, the byte read from the stream is returned. On end of stream
12244 * -1 is returned but it's not an exceptional error and @error is not set.
12246 * If @cancellable is not %NULL, then the operation can be cancelled by
12247 * triggering the cancellable object from another thread. If the operation
12248 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
12249 * operation was partially finished when the operation was cancelled the
12250 * partial result will be returned, without an error.
12252 * On error -1 is returned and @error is set accordingly.
12254 * Returns: the byte read from the @stream, or -1 on end of stream or error.
12259 * g_buffered_input_stream_set_buffer_size:
12260 * @stream: a #GBufferedInputStream
12263 * Sets the size of the internal buffer of @stream to @size, or to the
12264 * size of the contents of the buffer. The buffer can never be resized
12265 * smaller than its current contents.
12270 * g_buffered_output_stream_get_auto_grow:
12271 * @stream: a #GBufferedOutputStream.
12273 * Checks if the buffer automatically grows as data is added.
12275 * Returns: %TRUE if the @stream's buffer automatically grows,
12276 * %FALSE otherwise.
12281 * g_buffered_output_stream_get_buffer_size:
12282 * @stream: a #GBufferedOutputStream.
12284 * Gets the size of the buffer in the @stream.
12286 * Returns: the current size of the buffer.
12291 * g_buffered_output_stream_new:
12292 * @base_stream: a #GOutputStream.
12294 * Creates a new buffered output stream for a base stream.
12296 * Returns: a #GOutputStream for the given @base_stream.
12301 * g_buffered_output_stream_new_sized:
12302 * @base_stream: a #GOutputStream.
12305 * Creates a new buffered output stream with a given buffer size.
12307 * Returns: a #GOutputStream with an internal buffer set to @size.
12312 * g_buffered_output_stream_set_auto_grow:
12313 * @stream: a #GBufferedOutputStream.
12314 * @auto_grow: a #gboolean.
12316 * Sets whether or not the @stream's buffer should automatically grow.
12317 * If @auto_grow is true, then each write will just make the buffer
12318 * larger, and you must manually flush the buffer to actually write out
12319 * the data to the underlying stream.
12324 * g_buffered_output_stream_set_buffer_size:
12325 * @stream: a #GBufferedOutputStream.
12328 * Sets the size of the internal buffer to @size.
12334 * @bus_type: A #GBusType.
12335 * @cancellable: (allow-none): A #GCancellable or %NULL.
12336 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
12337 * @user_data: The data to pass to @callback.
12339 * Asynchronously connects to the message bus specified by @bus_type.
12341 * When the operation is finished, @callback will be invoked. You can
12342 * then call g_bus_get_finish() to get the result of the operation.
12344 * This is a asynchronous failable function. See g_bus_get_sync() for
12345 * the synchronous version.
12352 * g_bus_get_finish:
12353 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
12354 * @error: Return location for error or %NULL.
12356 * Finishes an operation started with g_bus_get().
12358 * The returned object is a singleton, that is, shared with other
12359 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
12360 * event that you need a private message bus connection, use
12361 * g_dbus_address_get_for_bus_sync() and
12362 * g_dbus_connection_new_for_address().
12364 * Note that the returned #GDBusConnection object will (usually) have
12365 * the #GDBusConnection:exit-on-close property set to %TRUE.
12367 * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
12374 * @bus_type: A #GBusType.
12375 * @cancellable: (allow-none): A #GCancellable or %NULL.
12376 * @error: Return location for error or %NULL.
12378 * Synchronously connects to the message bus specified by @bus_type.
12379 * Note that the returned object may shared with other callers,
12380 * e.g. if two separate parts of a process calls this function with
12381 * the same @bus_type, they will share the same object.
12383 * This is a synchronous failable function. See g_bus_get() and
12384 * g_bus_get_finish() for the asynchronous version.
12386 * The returned object is a singleton, that is, shared with other
12387 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
12388 * event that you need a private message bus connection, use
12389 * g_dbus_address_get_for_bus_sync() and
12390 * g_dbus_connection_new_for_address().
12392 * Note that the returned #GDBusConnection object will (usually) have
12393 * the #GDBusConnection:exit-on-close property set to %TRUE.
12395 * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
12402 * @bus_type: The type of bus to own a name on.
12403 * @name: The well-known name to own.
12404 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
12405 * @bus_acquired_handler: (allow-none): Handler to invoke when connected to the bus of type @bus_type or %NULL.
12406 * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL.
12407 * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL.
12408 * @user_data: User data to pass to handlers.
12409 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12411 * Starts acquiring @name on the bus specified by @bus_type and calls
12412 * @name_acquired_handler and @name_lost_handler when the name is
12413 * acquired respectively lost. Callbacks will be invoked in the <link
12414 * linkend="g-main-context-push-thread-default">thread-default main
12415 * loop</link> of the thread you are calling this function from.
12417 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
12418 * callbacks will be invoked after calling this function - there are three
12422 * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
12423 * </para></listitem>
12425 * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
12426 * </para></listitem>
12428 * @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
12429 * </para></listitem>
12431 * When you are done owning the name, just call g_bus_unown_name()
12432 * with the owner id this function returns.
12434 * If the name is acquired or lost (for example another application
12435 * could acquire the name if you allow replacement or the application
12436 * currently owning the name exits), the handlers are also invoked. If the
12437 * #GDBusConnection that is used for attempting to own the name
12438 * closes, then @name_lost_handler is invoked since it is no
12439 * longer possible for other processes to access the process.
12441 * You cannot use g_bus_own_name() several times for the same name (unless
12442 * interleaved with calls to g_bus_unown_name()) - only the first call
12445 * Another guarantee is that invocations of @name_acquired_handler
12446 * and @name_lost_handler are guaranteed to alternate; that
12447 * is, if @name_acquired_handler is invoked then you are
12448 * guaranteed that the next time one of the handlers is invoked, it
12449 * will be @name_lost_handler. The reverse is also true.
12451 * If you plan on exporting objects (using e.g.
12452 * g_dbus_connection_register_object()), note that it is generally too late
12453 * to export the objects in @name_acquired_handler. Instead, you can do this
12454 * in @bus_acquired_handler since you are guaranteed that this will run
12455 * before @name is requested from the bus.
12457 * This behavior makes it very simple to write applications that wants
12458 * to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
12459 * Simply register objects to be exported in @bus_acquired_handler and
12460 * unregister the objects (if any) in @name_lost_handler.
12462 * Returns: An identifier (never 0) that an be used with
12463 * g_bus_unown_name() to stop owning the name.
12469 * g_bus_own_name_on_connection:
12470 * @connection: A #GDBusConnection.
12471 * @name: The well-known name to own.
12472 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
12473 * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL.
12474 * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL.
12475 * @user_data: User data to pass to handlers.
12476 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12478 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
12481 * Returns: An identifier (never 0) that an be used with
12482 * g_bus_unown_name() to stop owning the name.
12488 * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
12489 * @connection: A #GDBusConnection.
12490 * @name: The well-known name to own.
12491 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
12492 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
12493 * acquired or %NULL.
12494 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
12497 * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
12498 * easier binding in other languages.
12500 * Returns: An identifier (never 0) that an be used with
12501 * g_bus_unown_name() to stop owning the name.
12507 * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
12508 * @bus_type: The type of bus to own a name on.
12509 * @name: The well-known name to own.
12510 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
12511 * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to
12512 * the bus of type @bus_type or %NULL.
12513 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
12514 * acquired or %NULL.
12515 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
12518 * Version of g_bus_own_name() using closures instead of callbacks for
12519 * easier binding in other languages.
12521 * Returns: An identifier (never 0) that an be used with
12522 * g_bus_unown_name() to stop owning the name.
12528 * g_bus_unown_name:
12529 * @owner_id: An identifier obtained from g_bus_own_name()
12531 * Stops owning a name.
12538 * g_bus_unwatch_name:
12539 * @watcher_id: An identifier obtained from g_bus_watch_name()
12541 * Stops watching a name.
12548 * g_bus_watch_name:
12549 * @bus_type: The type of bus to watch a name on.
12550 * @name: The name (well-known or unique) to watch.
12551 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12552 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
12553 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
12554 * @user_data: User data to pass to handlers.
12555 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12557 * Starts watching @name on the bus specified by @bus_type and calls
12558 * @name_appeared_handler and @name_vanished_handler when the name is
12559 * known to have a owner respectively known to lose its
12560 * owner. Callbacks will be invoked in the <link
12561 * linkend="g-main-context-push-thread-default">thread-default main
12562 * loop</link> of the thread you are calling this function from.
12564 * You are guaranteed that one of the handlers will be invoked after
12565 * calling this function. When you are done watching the name, just
12566 * call g_bus_unwatch_name() with the watcher id this function
12569 * If the name vanishes or appears (for example the application owning
12570 * the name could restart), the handlers are also invoked. If the
12571 * #GDBusConnection that is used for watching the name disconnects, then
12572 * @name_vanished_handler is invoked since it is no longer
12573 * possible to access the name.
12575 * Another guarantee is that invocations of @name_appeared_handler
12576 * and @name_vanished_handler are guaranteed to alternate; that
12577 * is, if @name_appeared_handler is invoked then you are
12578 * guaranteed that the next time one of the handlers is invoked, it
12579 * will be @name_vanished_handler. The reverse is also true.
12581 * This behavior makes it very simple to write applications that wants
12582 * to take action when a certain name exists, see <xref
12583 * linkend="gdbus-watching-names"/>. Basically, the application
12584 * should create object proxies in @name_appeared_handler and destroy
12585 * them again (if any) in @name_vanished_handler.
12587 * Returns: An identifier (never 0) that an be used with
12588 * g_bus_unwatch_name() to stop watching the name.
12594 * g_bus_watch_name_on_connection:
12595 * @connection: A #GDBusConnection.
12596 * @name: The name (well-known or unique) to watch.
12597 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12598 * @name_appeared_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
12599 * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
12600 * @user_data: User data to pass to handlers.
12601 * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
12603 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
12606 * Returns: An identifier (never 0) that an be used with
12607 * g_bus_unwatch_name() to stop watching the name.
12613 * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection)
12614 * @connection: A #GDBusConnection.
12615 * @name: The name (well-known or unique) to watch.
12616 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12617 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
12618 * to exist or %NULL.
12619 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
12620 * to not exist or %NULL.
12622 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
12623 * easier binding in other languages.
12625 * Returns: An identifier (never 0) that an be used with
12626 * g_bus_unwatch_name() to stop watching the name.
12632 * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name)
12633 * @bus_type: The type of bus to watch a name on.
12634 * @name: The name (well-known or unique) to watch.
12635 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
12636 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known
12637 * to exist or %NULL.
12638 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known
12639 * to not exist or %NULL.
12641 * Version of g_bus_watch_name() using closures instead of callbacks for
12642 * easier binding in other languages.
12644 * Returns: An identifier (never 0) that an be used with
12645 * g_bus_unwatch_name() to stop watching the name.
12651 * g_bytes_icon_get_bytes:
12654 * Gets the #GBytes associated with the given @icon.
12656 * Returns: (transfer none): a #GBytes, or %NULL.
12662 * g_bytes_icon_new:
12663 * @bytes: a #GBytes.
12665 * Creates a new icon for a bytes.
12667 * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given
12668 * @bytes, or %NULL on error.
12674 * g_cancellable_cancel:
12675 * @cancellable: a #GCancellable object.
12677 * Will set @cancellable to cancelled, and will emit the
12678 * #GCancellable::cancelled signal. (However, see the warning about
12679 * race conditions in the documentation for that signal if you are
12680 * planning to connect to it.)
12682 * This function is thread-safe. In other words, you can safely call
12683 * it from a thread other than the one running the operation that was
12684 * passed the @cancellable.
12686 * The convention within gio is that cancelling an asynchronous
12687 * operation causes it to complete asynchronously. That is, if you
12688 * cancel the operation from the same thread in which it is running,
12689 * then the operation's #GAsyncReadyCallback will not be invoked until
12690 * the application returns to the main loop.
12695 * g_cancellable_connect:
12696 * @cancellable: A #GCancellable.
12697 * @callback: The #GCallback to connect.
12698 * @data: Data to pass to @callback.
12699 * @data_destroy_func: (allow-none): Free function for @data or %NULL.
12701 * Convenience function to connect to the #GCancellable::cancelled
12702 * signal. Also handles the race condition that may happen
12703 * if the cancellable is cancelled right before connecting.
12705 * @callback is called at most once, either directly at the
12706 * time of the connect if @cancellable is already cancelled,
12707 * or when @cancellable is cancelled in some thread.
12709 * @data_destroy_func will be called when the handler is
12710 * disconnected, or immediately if the cancellable is already
12713 * See #GCancellable::cancelled for details on how to use this.
12715 * Since GLib 2.40, the lock protecting @cancellable is not held when
12716 * @callback is invoked. This lifts a restriction in place for
12717 * earlier GLib versions which now makes it easier to write cleanup
12718 * code that unconditionally invokes e.g. g_cancellable_cancel().
12720 * Returns: The id of the signal handler or 0 if @cancellable has already
12727 * g_cancellable_disconnect:
12728 * @cancellable: (allow-none): A #GCancellable or %NULL.
12729 * @handler_id: Handler id of the handler to be disconnected, or %0.
12731 * Disconnects a handler from a cancellable instance similar to
12732 * g_signal_handler_disconnect(). Additionally, in the event that a
12733 * signal handler is currently running, this call will block until the
12734 * handler has finished. Calling this function from a
12735 * #GCancellable::cancelled signal handler will therefore result in a
12738 * This avoids a race condition where a thread cancels at the
12739 * same time as the cancellable operation is finished and the
12740 * signal handler is removed. See #GCancellable::cancelled for
12741 * details on how to use this.
12743 * If @cancellable is %NULL or @handler_id is %0 this function does
12751 * g_cancellable_get_current:
12753 * Gets the top cancellable from the stack.
12755 * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
12756 * if the stack is empty.
12761 * g_cancellable_get_fd:
12762 * @cancellable: a #GCancellable.
12764 * Gets the file descriptor for a cancellable job. This can be used to
12765 * implement cancellable operations on Unix systems. The returned fd will
12766 * turn readable when @cancellable is cancelled.
12768 * You are not supposed to read from the fd yourself, just check for
12769 * readable status. Reading to unset the readable status is done
12770 * with g_cancellable_reset().
12772 * After a successful return from this function, you should use
12773 * g_cancellable_release_fd() to free up resources allocated for
12774 * the returned file descriptor.
12776 * See also g_cancellable_make_pollfd().
12778 * Returns: A valid file descriptor. %-1 if the file descriptor
12779 * is not supported, or on errors.
12784 * g_cancellable_is_cancelled:
12785 * @cancellable: (allow-none): a #GCancellable or %NULL
12787 * Checks if a cancellable job has been cancelled.
12789 * Returns: %TRUE if @cancellable is cancelled,
12790 * FALSE if called with %NULL or if item is not cancelled.
12795 * g_cancellable_make_pollfd:
12796 * @cancellable: (allow-none): a #GCancellable or %NULL
12797 * @pollfd: a pointer to a #GPollFD
12799 * Creates a #GPollFD corresponding to @cancellable; this can be passed
12800 * to g_poll() and used to poll for cancellation. This is useful both
12801 * for unix systems without a native poll and for portability to
12804 * When this function returns %TRUE, you should use
12805 * g_cancellable_release_fd() to free up resources allocated for the
12806 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
12808 * If this function returns %FALSE, either no @cancellable was given or
12809 * resource limits prevent this function from allocating the necessary
12810 * structures for polling. (On Linux, you will likely have reached
12811 * the maximum number of file descriptors.) The suggested way to handle
12812 * these cases is to ignore the @cancellable.
12814 * You are not supposed to read from the fd yourself, just check for
12815 * readable status. Reading to unset the readable status is done
12816 * with g_cancellable_reset().
12818 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
12819 * failure to prepare the cancellable.
12825 * g_cancellable_new:
12827 * Creates a new #GCancellable object.
12829 * Applications that want to start one or more operations
12830 * that should be cancellable should create a #GCancellable
12831 * and pass it to the operations.
12833 * One #GCancellable can be used in multiple consecutive
12834 * operations or in multiple concurrent operations.
12836 * Returns: a #GCancellable.
12841 * g_cancellable_pop_current:
12842 * @cancellable: a #GCancellable object
12844 * Pops @cancellable off the cancellable stack (verifying that @cancellable
12845 * is on the top of the stack).
12850 * g_cancellable_push_current:
12851 * @cancellable: a #GCancellable object
12853 * Pushes @cancellable onto the cancellable stack. The current
12854 * cancellable can then be received using g_cancellable_get_current().
12856 * This is useful when implementing cancellable operations in
12857 * code that does not allow you to pass down the cancellable object.
12859 * This is typically called automatically by e.g. #GFile operations,
12860 * so you rarely have to call this yourself.
12865 * g_cancellable_release_fd:
12866 * @cancellable: a #GCancellable
12868 * Releases a resources previously allocated by g_cancellable_get_fd()
12869 * or g_cancellable_make_pollfd().
12871 * For compatibility reasons with older releases, calling this function
12872 * is not strictly required, the resources will be automatically freed
12873 * when the @cancellable is finalized. However, the @cancellable will
12874 * block scarce file descriptors until it is finalized if this function
12875 * is not called. This can cause the application to run out of file
12876 * descriptors when many #GCancellables are used at the same time.
12883 * g_cancellable_reset:
12884 * @cancellable: a #GCancellable object.
12886 * Resets @cancellable to its uncancelled state.
12888 * If cancellable is currently in use by any cancellable operation
12889 * then the behavior of this function is undefined.
12894 * g_cancellable_set_error_if_cancelled:
12895 * @cancellable: (allow-none): a #GCancellable or %NULL
12896 * @error: #GError to append error state to
12898 * If the @cancellable is cancelled, sets the error to notify
12899 * that the operation was cancelled.
12901 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
12906 * g_cancellable_source_new: (skip)
12907 * @cancellable: (allow-none): a #GCancellable, or %NULL
12909 * Creates a source that triggers if @cancellable is cancelled and
12910 * calls its callback of type #GCancellableSourceFunc. This is
12911 * primarily useful for attaching to another (non-cancellable) source
12912 * with g_source_add_child_source() to add cancellability to it.
12914 * For convenience, you can call this with a %NULL #GCancellable,
12915 * in which case the source will never trigger.
12917 * Returns: (transfer full): the new #GSource.
12923 * g_charset_converter_get_num_fallbacks:
12924 * @converter: a #GCharsetConverter
12926 * Gets the number of fallbacks that @converter has applied so far.
12928 * Returns: the number of fallbacks that @converter has applied
12934 * g_charset_converter_get_use_fallback:
12935 * @converter: a #GCharsetConverter
12937 * Gets the #GCharsetConverter:use-fallback property.
12939 * Returns: %TRUE if fallbacks are used by @converter
12945 * g_charset_converter_new:
12946 * @to_charset: destination charset
12947 * @from_charset: source charset
12948 * @error: #GError for error reporting, or %NULL to ignore.
12950 * Creates a new #GCharsetConverter.
12952 * Returns: a new #GCharsetConverter or %NULL on error.
12958 * g_charset_converter_set_use_fallback:
12959 * @converter: a #GCharsetConverter
12960 * @use_fallback: %TRUE to use fallbacks
12962 * Sets the #GCharsetConverter:use-fallback property.
12969 * g_content_type_can_be_executable:
12970 * @type: a content type string
12972 * Checks if a content type can be executable. Note that for instance
12973 * things like text files can be executables (i.e. scripts and batch files).
12975 * Returns: %TRUE if the file type corresponds to a type that
12976 * can be executable, %FALSE otherwise.
12981 * g_content_type_equals:
12982 * @type1: a content type string
12983 * @type2: a content type string
12985 * Compares two content types for equality.
12987 * Returns: %TRUE if the two strings are identical or equivalent,
12988 * %FALSE otherwise.
12993 * g_content_type_from_mime_type:
12994 * @mime_type: a mime type string
12996 * Tries to find a content type based on the mime type name.
12998 * Returns: (allow-none): Newly allocated string with content type
12999 * or %NULL. Free with g_free()
13005 * g_content_type_get_description:
13006 * @type: a content type string
13008 * Gets the human readable description of the content type.
13010 * Returns: a short description of the content type @type. Free the
13011 * returned string with g_free()
13016 * g_content_type_get_generic_icon_name:
13017 * @type: a content type string
13019 * Gets the generic icon name for a content type.
13021 * See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
13022 * specification for more on the generic icon name.
13024 * Returns: (allow-none): the registered generic icon name for the given @type,
13025 * or %NULL if unknown. Free with g_free()
13031 * g_content_type_get_icon:
13032 * @type: a content type string
13034 * Gets the icon for a content type.
13036 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
13037 * object with g_object_unref()
13042 * g_content_type_get_mime_type:
13043 * @type: a content type string
13045 * Gets the mime type for the content type, if one is registered.
13047 * Returns: (allow-none): the registered mime type for the given @type,
13048 * or %NULL if unknown.
13053 * g_content_type_get_symbolic_icon:
13054 * @type: a content type string
13056 * Gets the symbolic icon for a content type.
13058 * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
13059 * Free the returned object with g_object_unref()
13065 * g_content_type_guess:
13066 * @filename: (allow-none): a string, or %NULL
13067 * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
13068 * @data_size: the size of @data
13069 * @result_uncertain: (allow-none) (out): return location for the certainty
13070 * of the result, or %NULL
13072 * Guesses the content type based on example data. If the function is
13073 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
13074 * or @data may be %NULL, in which case the guess will be based solely
13075 * on the other argument.
13077 * Returns: a string indicating a guessed content type for the
13078 * given data. Free with g_free()
13083 * g_content_type_guess_for_tree:
13084 * @root: the root of the tree to guess a type for
13086 * Tries to guess the type of the tree with root @root, by
13087 * looking at the files it contains. The result is an array
13088 * of content types, with the best guess coming first.
13090 * The types returned all have the form x-content/foo, e.g.
13091 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
13092 * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
13093 * specification for more on x-content types.
13095 * This function is useful in the implementation of
13096 * g_mount_guess_content_type().
13098 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
13099 * array of zero or more content types. Free with g_strfreev()
13105 * g_content_type_is_a:
13106 * @type: a content type string
13107 * @supertype: a content type string
13109 * Determines if @type is a subset of @supertype.
13111 * Returns: %TRUE if @type is a kind of @supertype,
13112 * %FALSE otherwise.
13117 * g_content_type_is_unknown:
13118 * @type: a content type string
13120 * Checks if the content type is the generic "unknown" type.
13121 * On UNIX this is the "application/octet-stream" mimetype,
13122 * while on win32 it is "*".
13124 * Returns: %TRUE if the type is the unknown type.
13129 * g_content_types_get_registered:
13131 * Gets a list of strings containing all the registered content types
13132 * known to the system. The list and its data should be freed using
13134 * g_list_free_full (list, g_free);
13135 * </programlisting>
13137 * Returns: (element-type utf8) (transfer full): #GList of the registered content types
13142 * g_converter_convert:
13143 * @converter: a #GConverter.
13144 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
13145 * containing the data to convert.
13146 * @inbuf_size: the number of bytes in @inbuf
13147 * @outbuf: a buffer to write converted data in.
13148 * @outbuf_size: the number of bytes in @outbuf, must be at least one
13149 * @flags: a #GConverterFlags controlling the conversion details
13150 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
13151 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
13152 * @error: location to store the error occurring, or %NULL to ignore
13154 * This is the main operation used when converting data. It is to be called
13155 * multiple times in a loop, and each time it will do some work, i.e.
13156 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
13157 * both. If its not possible to do any work an error is returned.
13159 * Note that a single call may not consume all input (or any input at all).
13160 * Also a call may produce output even if given no input, due to state stored
13161 * in the converter producing output.
13163 * If any data was either produced or consumed, and then an error happens, then
13164 * only the successful conversion is reported and the error is returned on the
13167 * A full conversion loop involves calling this method repeatedly, each time
13168 * giving it new input and space output space. When there is no more input
13169 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
13170 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
13171 * each time until all data is consumed and all output is produced, then
13172 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
13173 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
13174 * in a decompression converter where the end of data is detectable from the
13175 * data (and there might even be other data after the end of the compressed data).
13177 * When some data has successfully been converted @bytes_read and is set to
13178 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
13179 * how many bytes was written to @outbuf. If there are more data to output
13180 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
13181 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
13182 * then %G_CONVERTER_FINISHED is returned.
13184 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
13185 * Some errors need special handling:
13187 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
13188 * to write the resulting converted data, the application should
13189 * call the function again with a larger @outbuf to continue.
13191 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
13192 * input to fully determine what the conversion should produce,
13193 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
13194 * example with an incomplete multibyte sequence when converting text,
13195 * or when a regexp matches up to the end of the input (and may match
13196 * further input). It may also happen when @inbuf_size is zero and
13197 * there is no more data to produce.
13199 * When this happens the application should read more input and then
13200 * call the function again. If further input shows that there is no
13201 * more data call the function again with the same data but with
13202 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
13203 * to finish as e.g. in the regexp match case (or, to fail again with
13204 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
13205 * input is actually partial).
13207 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
13208 * converter object is in an invalid state where its not allowed
13209 * to call g_converter_convert() anymore. At this time you can only
13210 * free the object or call g_converter_reset() to reset it to the
13213 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
13214 * to try to write out all internal state to the output. The application
13215 * has to call the function multiple times with the flag set, and when
13216 * the available input has been consumed and all internal state has
13217 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
13218 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
13219 * This is somewhat similar to what happens at the end of the input stream,
13220 * but done in the middle of the data.
13222 * This has different meanings for different conversions. For instance
13223 * in a compression converter it would mean that we flush all the
13224 * compression state into output such that if you uncompress the
13225 * compressed data you get back all the input data. Doing this may
13226 * make the final file larger due to padding though. Another example
13227 * is a regexp conversion, where if you at the end of the flushed data
13228 * have a match, but there is also a potential longer match. In the
13229 * non-flushed case we would ask for more input, but when flushing we
13230 * treat this as the end of input and do the match.
13232 * Flushing is not always possible (like if a charset converter flushes
13233 * at a partial multibyte sequence). Converters are supposed to try
13234 * to produce as much output as possible and then return an error
13235 * (typically %G_IO_ERROR_PARTIAL_INPUT).
13237 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
13243 * g_converter_input_stream_get_converter:
13244 * @converter_stream: a #GConverterInputStream
13246 * Gets the #GConverter that is used by @converter_stream.
13248 * Returns: (transfer none): the converter of the converter input stream
13254 * g_converter_input_stream_new:
13255 * @base_stream: a #GInputStream
13256 * @converter: a #GConverter
13258 * Creates a new converter input stream for the @base_stream.
13260 * Returns: a new #GInputStream.
13265 * g_converter_output_stream_get_converter:
13266 * @converter_stream: a #GConverterOutputStream
13268 * Gets the #GConverter that is used by @converter_stream.
13270 * Returns: (transfer none): the converter of the converter output stream
13276 * g_converter_output_stream_new:
13277 * @base_stream: a #GOutputStream
13278 * @converter: a #GConverter
13280 * Creates a new converter output stream for the @base_stream.
13282 * Returns: a new #GOutputStream.
13287 * g_converter_reset:
13288 * @converter: a #GConverter.
13290 * Resets all internal state in the converter, making it behave
13291 * as if it was just created. If the converter has any internal
13292 * state that would produce output then that output is lost.
13299 * g_credentials_get_native: (skip)
13300 * @credentials: A #GCredentials.
13301 * @native_type: The type of native credentials to get.
13303 * Gets a pointer to native credentials of type @native_type from
13306 * It is a programming error (which will cause an warning to be
13307 * logged) to use this method if there is no #GCredentials support for
13308 * the OS or if @native_type isn't supported by the OS.
13310 * Returns: The pointer to native credentials or %NULL if the
13311 * operation there is no #GCredentials support for the OS or if
13312 * @native_type isn't supported by the OS. Do not free the returned
13313 * data, it is owned by @credentials.
13319 * g_credentials_get_unix_pid:
13320 * @credentials: A #GCredentials
13321 * @error: Return location for error or %NULL.
13323 * Tries to get the UNIX process identifier from @credentials. This
13324 * method is only available on UNIX platforms.
13326 * This operation can fail if #GCredentials is not supported on the
13327 * OS or if the native credentials type does not contain information
13328 * about the UNIX process ID.
13330 * Returns: The UNIX process ID, or -1 if @error is set.
13336 * g_credentials_get_unix_user:
13337 * @credentials: A #GCredentials
13338 * @error: Return location for error or %NULL.
13340 * Tries to get the UNIX user identifier from @credentials. This
13341 * method is only available on UNIX platforms.
13343 * This operation can fail if #GCredentials is not supported on the
13344 * OS or if the native credentials type does not contain information
13345 * about the UNIX user.
13347 * Returns: The UNIX user identifier or -1 if @error is set.
13353 * g_credentials_is_same_user:
13354 * @credentials: A #GCredentials.
13355 * @other_credentials: A #GCredentials.
13356 * @error: Return location for error or %NULL.
13358 * Checks if @credentials and @other_credentials is the same user.
13360 * This operation can fail if #GCredentials is not supported on the
13363 * Returns: %TRUE if @credentials and @other_credentials has the same
13364 * user, %FALSE otherwise or if @error is set.
13370 * g_credentials_new:
13372 * Creates a new #GCredentials object with credentials matching the
13373 * the current process.
13375 * Returns: A #GCredentials. Free with g_object_unref().
13381 * g_credentials_set_native:
13382 * @credentials: A #GCredentials.
13383 * @native_type: The type of native credentials to set.
13384 * @native: A pointer to native credentials.
13386 * Copies the native credentials of type @native_type from @native
13387 * into @credentials.
13389 * It is a programming error (which will cause an warning to be
13390 * logged) to use this method if there is no #GCredentials support for
13391 * the OS or if @native_type isn't supported by the OS.
13398 * g_credentials_set_unix_user:
13399 * @credentials: A #GCredentials.
13400 * @uid: The UNIX user identifier to set.
13401 * @error: Return location for error or %NULL.
13403 * Tries to set the UNIX user identifier on @credentials. This method
13404 * is only available on UNIX platforms.
13406 * This operation can fail if #GCredentials is not supported on the
13407 * OS or if the native credentials type does not contain information
13408 * about the UNIX user. It can also fail if the OS does not allow the
13409 * use of "spoofed" credentials.
13411 * Returns: %TRUE if @uid was set, %FALSE if error is set.
13417 * g_credentials_to_string:
13418 * @credentials: A #GCredentials object.
13420 * Creates a human-readable textual representation of @credentials
13421 * that can be used in logging and debug messages. The format of the
13422 * returned string may change in future GLib release.
13424 * Returns: A string that should be freed with g_free().
13430 * g_data_input_stream_get_byte_order:
13431 * @stream: a given #GDataInputStream.
13433 * Gets the byte order for the data input stream.
13435 * Returns: the @stream's current #GDataStreamByteOrder.
13440 * g_data_input_stream_get_newline_type:
13441 * @stream: a given #GDataInputStream.
13443 * Gets the current newline type for the @stream.
13445 * Returns: #GDataStreamNewlineType for the given @stream.
13450 * g_data_input_stream_new:
13451 * @base_stream: a #GInputStream.
13453 * Creates a new data input stream for the @base_stream.
13455 * Returns: a new #GDataInputStream.
13460 * g_data_input_stream_read_byte:
13461 * @stream: a given #GDataInputStream.
13462 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13463 * @error: #GError for error reporting.
13465 * Reads an unsigned 8-bit/1-byte value from @stream.
13467 * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
13468 * if an error occurred.
13473 * g_data_input_stream_read_int16:
13474 * @stream: a given #GDataInputStream.
13475 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13476 * @error: #GError for error reporting.
13478 * Reads a 16-bit/2-byte value from @stream.
13480 * In order to get the correct byte order for this read operation,
13481 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13483 * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
13484 * an error occurred.
13489 * g_data_input_stream_read_int32:
13490 * @stream: a given #GDataInputStream.
13491 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13492 * @error: #GError for error reporting.
13494 * Reads a signed 32-bit/4-byte value from @stream.
13496 * In order to get the correct byte order for this read operation,
13497 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13499 * If @cancellable is not %NULL, then the operation can be cancelled by
13500 * triggering the cancellable object from another thread. If the operation
13501 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13503 * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
13504 * an error occurred.
13509 * g_data_input_stream_read_int64:
13510 * @stream: a given #GDataInputStream.
13511 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13512 * @error: #GError for error reporting.
13514 * Reads a 64-bit/8-byte value from @stream.
13516 * In order to get the correct byte order for this read operation,
13517 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13519 * If @cancellable is not %NULL, then the operation can be cancelled by
13520 * triggering the cancellable object from another thread. If the operation
13521 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13523 * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
13524 * an error occurred.
13529 * g_data_input_stream_read_line:
13530 * @stream: a given #GDataInputStream.
13531 * @length: (out): a #gsize to get the length of the data read in.
13532 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13533 * @error: #GError for error reporting.
13535 * Reads a line from the data input stream. Note that no encoding
13536 * checks or conversion is performed; the input is not guaranteed to
13537 * be UTF-8, and may in fact have embedded NUL characters.
13539 * If @cancellable is not %NULL, then the operation can be cancelled by
13540 * triggering the cancellable object from another thread. If the operation
13541 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13543 * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
13544 * NUL terminated byte array with the line that was read in (without
13545 * the newlines). Set @length to a #gsize to get the length of the
13546 * read line. On an error, it will return %NULL and @error will be
13547 * set. If there's no content to read, it will still return %NULL,
13548 * but @error won't be set.
13553 * g_data_input_stream_read_line_async:
13554 * @stream: a given #GDataInputStream.
13555 * @io_priority: the <link linkend="io-priority">I/O priority</link>
13557 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13558 * @callback: (scope async): callback to call when the request is satisfied.
13559 * @user_data: (closure): the data to pass to callback function.
13561 * The asynchronous version of g_data_input_stream_read_line(). It is
13562 * an error to have two outstanding calls to this function.
13564 * When the operation is finished, @callback will be called. You
13565 * can then call g_data_input_stream_read_line_finish() to get
13566 * the result of the operation.
13573 * g_data_input_stream_read_line_finish:
13574 * @stream: a given #GDataInputStream.
13575 * @result: the #GAsyncResult that was provided to the callback.
13576 * @length: (out): a #gsize to get the length of the data read in.
13577 * @error: #GError for error reporting.
13579 * Finish an asynchronous call started by
13580 * g_data_input_stream_read_line_async(). Note the warning about
13581 * string encoding in g_data_input_stream_read_line() applies here as
13584 * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
13585 * NUL-terminated byte array with the line that was read in
13586 * (without the newlines). Set @length to a #gsize to get the
13587 * length of the read line. On an error, it will return %NULL and
13588 * @error will be set. If there's no content to read, it will
13589 * still return %NULL, but @error won't be set.
13595 * g_data_input_stream_read_line_finish_utf8:
13596 * @stream: a given #GDataInputStream.
13597 * @result: the #GAsyncResult that was provided to the callback.
13598 * @length: (out): a #gsize to get the length of the data read in.
13599 * @error: #GError for error reporting.
13601 * Finish an asynchronous call started by
13602 * g_data_input_stream_read_line_async().
13604 * Returns: (transfer full): a string with the line that was read in
13605 * (without the newlines). Set @length to a #gsize to get the length
13606 * of the read line. On an error, it will return %NULL and @error
13607 * will be set. For UTF-8 conversion errors, the set error domain is
13608 * %G_CONVERT_ERROR. If there's no content to read, it will still
13609 * return %NULL, but @error won't be set.
13615 * g_data_input_stream_read_line_utf8:
13616 * @stream: a given #GDataInputStream.
13617 * @length: (out): a #gsize to get the length of the data read in.
13618 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13619 * @error: #GError for error reporting.
13621 * Reads a UTF-8 encoded line from the data input stream.
13623 * If @cancellable is not %NULL, then the operation can be cancelled by
13624 * triggering the cancellable object from another thread. If the operation
13625 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13627 * Returns: (transfer full): a NUL terminated UTF-8 string with the
13628 * line that was read in (without the newlines). Set @length to a
13629 * #gsize to get the length of the read line. On an error, it will
13630 * return %NULL and @error will be set. For UTF-8 conversion errors,
13631 * the set error domain is %G_CONVERT_ERROR. If there's no content to
13632 * read, it will still return %NULL, but @error won't be set.
13638 * g_data_input_stream_read_uint16:
13639 * @stream: a given #GDataInputStream.
13640 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13641 * @error: #GError for error reporting.
13643 * Reads an unsigned 16-bit/2-byte value from @stream.
13645 * In order to get the correct byte order for this read operation,
13646 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13648 * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
13649 * an error occurred.
13654 * g_data_input_stream_read_uint32:
13655 * @stream: a given #GDataInputStream.
13656 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13657 * @error: #GError for error reporting.
13659 * Reads an unsigned 32-bit/4-byte value from @stream.
13661 * In order to get the correct byte order for this read operation,
13662 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
13664 * If @cancellable is not %NULL, then the operation can be cancelled by
13665 * triggering the cancellable object from another thread. If the operation
13666 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13668 * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
13669 * an error occurred.
13674 * g_data_input_stream_read_uint64:
13675 * @stream: a given #GDataInputStream.
13676 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13677 * @error: #GError for error reporting.
13679 * Reads an unsigned 64-bit/8-byte value from @stream.
13681 * In order to get the correct byte order for this read operation,
13682 * see g_data_input_stream_get_byte_order().
13684 * If @cancellable is not %NULL, then the operation can be cancelled by
13685 * triggering the cancellable object from another thread. If the operation
13686 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
13688 * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
13689 * an error occurred.
13694 * g_data_input_stream_read_until:
13695 * @stream: a given #GDataInputStream.
13696 * @stop_chars: characters to terminate the read.
13697 * @length: (out): a #gsize to get the length of the data read in.
13698 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13699 * @error: #GError for error reporting.
13701 * Reads a string from the data input stream, up to the first
13702 * occurrence of any of the stop characters.
13704 * Note that, in contrast to g_data_input_stream_read_until_async(),
13705 * this function consumes the stop character that it finds.
13707 * Don't use this function in new code. Its functionality is
13708 * inconsistent with g_data_input_stream_read_until_async(). Both
13709 * functions will be marked as deprecated in a future release. Use
13710 * g_data_input_stream_read_upto() instead, but note that that function
13711 * does not consume the stop character.
13713 * Returns: (transfer full): a string with the data that was read
13714 * before encountering any of the stop characters. Set @length to
13715 * a #gsize to get the length of the string. This function will
13716 * return %NULL on an error.
13721 * g_data_input_stream_read_until_async:
13722 * @stream: a given #GDataInputStream.
13723 * @stop_chars: characters to terminate the read.
13724 * @io_priority: the <link linkend="io-priority">I/O priority</link>
13726 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13727 * @callback: (scope async): callback to call when the request is satisfied.
13728 * @user_data: (closure): the data to pass to callback function.
13730 * The asynchronous version of g_data_input_stream_read_until().
13731 * It is an error to have two outstanding calls to this function.
13733 * Note that, in contrast to g_data_input_stream_read_until(),
13734 * this function does not consume the stop character that it finds. You
13735 * must read it for yourself.
13737 * When the operation is finished, @callback will be called. You
13738 * can then call g_data_input_stream_read_until_finish() to get
13739 * the result of the operation.
13741 * Don't use this function in new code. Its functionality is
13742 * inconsistent with g_data_input_stream_read_until(). Both functions
13743 * will be marked as deprecated in a future release. Use
13744 * g_data_input_stream_read_upto_async() instead.
13751 * g_data_input_stream_read_until_finish:
13752 * @stream: a given #GDataInputStream.
13753 * @result: the #GAsyncResult that was provided to the callback.
13754 * @length: (out): a #gsize to get the length of the data read in.
13755 * @error: #GError for error reporting.
13757 * Finish an asynchronous call started by
13758 * g_data_input_stream_read_until_async().
13761 * Returns: (transfer full): a string with the data that was read
13762 * before encountering any of the stop characters. Set @length to
13763 * a #gsize to get the length of the string. This function will
13764 * return %NULL on an error.
13769 * g_data_input_stream_read_upto:
13770 * @stream: a #GDataInputStream
13771 * @stop_chars: characters to terminate the read
13772 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
13774 * @length: (out): a #gsize to get the length of the data read in
13775 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
13776 * @error: #GError for error reporting
13778 * Reads a string from the data input stream, up to the first
13779 * occurrence of any of the stop characters.
13781 * In contrast to g_data_input_stream_read_until(), this function
13782 * does <emphasis>not</emphasis> consume the stop character. You have
13783 * to use g_data_input_stream_read_byte() to get it before calling
13784 * g_data_input_stream_read_upto() again.
13786 * Note that @stop_chars may contain '\0' if @stop_chars_len is
13789 * Returns: (transfer full): a string with the data that was read
13790 * before encountering any of the stop characters. Set @length to
13791 * a #gsize to get the length of the string. This function will
13792 * return %NULL on an error
13798 * g_data_input_stream_read_upto_async:
13799 * @stream: a #GDataInputStream
13800 * @stop_chars: characters to terminate the read
13801 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
13803 * @io_priority: the <link linkend="io-priority">I/O priority</link>
13805 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
13806 * @callback: (scope async): callback to call when the request is satisfied
13807 * @user_data: (closure): the data to pass to callback function
13809 * The asynchronous version of g_data_input_stream_read_upto().
13810 * It is an error to have two outstanding calls to this function.
13812 * In contrast to g_data_input_stream_read_until(), this function
13813 * does <emphasis>not</emphasis> consume the stop character. You have
13814 * to use g_data_input_stream_read_byte() to get it before calling
13815 * g_data_input_stream_read_upto() again.
13817 * Note that @stop_chars may contain '\0' if @stop_chars_len is
13820 * When the operation is finished, @callback will be called. You
13821 * can then call g_data_input_stream_read_upto_finish() to get
13822 * the result of the operation.
13829 * g_data_input_stream_read_upto_finish:
13830 * @stream: a #GDataInputStream
13831 * @result: the #GAsyncResult that was provided to the callback
13832 * @length: (out): a #gsize to get the length of the data read in
13833 * @error: #GError for error reporting
13835 * Finish an asynchronous call started by
13836 * g_data_input_stream_read_upto_async().
13838 * Note that this function does <emphasis>not</emphasis> consume the
13839 * stop character. You have to use g_data_input_stream_read_byte() to
13840 * get it before calling g_data_input_stream_read_upto_async() again.
13842 * Returns: (transfer full): a string with the data that was read
13843 * before encountering any of the stop characters. Set @length to
13844 * a #gsize to get the length of the string. This function will
13845 * return %NULL on an error.
13851 * g_data_input_stream_set_byte_order:
13852 * @stream: a given #GDataInputStream.
13853 * @order: a #GDataStreamByteOrder to set.
13855 * This function sets the byte order for the given @stream. All subsequent
13856 * reads from the @stream will be read in the given @order.
13861 * g_data_input_stream_set_newline_type:
13862 * @stream: a #GDataInputStream.
13863 * @type: the type of new line return as #GDataStreamNewlineType.
13865 * Sets the newline type for the @stream.
13867 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
13868 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
13869 * "CR LF", and this might block if there is no more data available.
13874 * g_data_output_stream_get_byte_order:
13875 * @stream: a #GDataOutputStream.
13877 * Gets the byte order for the stream.
13879 * Returns: the #GDataStreamByteOrder for the @stream.
13884 * g_data_output_stream_new:
13885 * @base_stream: a #GOutputStream.
13887 * Creates a new data output stream for @base_stream.
13889 * Returns: #GDataOutputStream.
13894 * g_data_output_stream_put_byte:
13895 * @stream: a #GDataOutputStream.
13896 * @data: a #guchar.
13897 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13898 * @error: a #GError, %NULL to ignore.
13900 * Puts a byte into the output stream.
13902 * Returns: %TRUE if @data was successfully added to the @stream.
13907 * g_data_output_stream_put_int16:
13908 * @stream: a #GDataOutputStream.
13909 * @data: a #gint16.
13910 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13911 * @error: a #GError, %NULL to ignore.
13913 * Puts a signed 16-bit integer into the output stream.
13915 * Returns: %TRUE if @data was successfully added to the @stream.
13920 * g_data_output_stream_put_int32:
13921 * @stream: a #GDataOutputStream.
13922 * @data: a #gint32.
13923 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13924 * @error: a #GError, %NULL to ignore.
13926 * Puts a signed 32-bit integer into the output stream.
13928 * Returns: %TRUE if @data was successfully added to the @stream.
13933 * g_data_output_stream_put_int64:
13934 * @stream: a #GDataOutputStream.
13935 * @data: a #gint64.
13936 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13937 * @error: a #GError, %NULL to ignore.
13939 * Puts a signed 64-bit integer into the stream.
13941 * Returns: %TRUE if @data was successfully added to the @stream.
13946 * g_data_output_stream_put_string:
13947 * @stream: a #GDataOutputStream.
13949 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13950 * @error: a #GError, %NULL to ignore.
13952 * Puts a string into the output stream.
13954 * Returns: %TRUE if @string was successfully added to the @stream.
13959 * g_data_output_stream_put_uint16:
13960 * @stream: a #GDataOutputStream.
13961 * @data: a #guint16.
13962 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13963 * @error: a #GError, %NULL to ignore.
13965 * Puts an unsigned 16-bit integer into the output stream.
13967 * Returns: %TRUE if @data was successfully added to the @stream.
13972 * g_data_output_stream_put_uint32:
13973 * @stream: a #GDataOutputStream.
13974 * @data: a #guint32.
13975 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13976 * @error: a #GError, %NULL to ignore.
13978 * Puts an unsigned 32-bit integer into the stream.
13980 * Returns: %TRUE if @data was successfully added to the @stream.
13985 * g_data_output_stream_put_uint64:
13986 * @stream: a #GDataOutputStream.
13987 * @data: a #guint64.
13988 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
13989 * @error: a #GError, %NULL to ignore.
13991 * Puts an unsigned 64-bit integer into the stream.
13993 * Returns: %TRUE if @data was successfully added to the @stream.
13998 * g_data_output_stream_set_byte_order:
13999 * @stream: a #GDataOutputStream.
14000 * @order: a %GDataStreamByteOrder.
14002 * Sets the byte order of the data output stream to @order.
14007 * g_dbus_action_group_get:
14008 * @connection: A #GDBusConnection
14009 * @bus_name: the bus name which exports the action group
14010 * @object_path: the object path at which the action group is exported
14012 * Obtains a #GDBusActionGroup for the action group which is exported at
14013 * the given @bus_name and @object_path.
14015 * The thread default main context is taken at the time of this call.
14016 * All signals on the menu model (and any linked models) are reported
14017 * with respect to this context. All calls on the returned menu model
14018 * (and linked models) must also originate from this same context, with
14019 * the thread default main context unchanged.
14021 * This call is non-blocking. The returned action group may or may not
14022 * already be filled in. The correct thing to do is connect the signals
14023 * for the action group to monitor for changes and then to call
14024 * g_action_group_list_actions() to get the initial list.
14026 * Returns: (transfer full): a #GDBusActionGroup
14032 * g_dbus_address_escape_value:
14033 * @string: an unescaped string to be included in a D-Bus address
14034 * as the value in a key-value pair
14036 * Escape @string so it can appear in a D-Bus address as the value
14037 * part of a key-value pair.
14039 * For instance, if @string is <code>/run/bus-for-:0</code>,
14040 * this function would return <code>/run/bus-for-%3A0</code>,
14041 * which could be used in a D-Bus address like
14042 * <code>unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0</code>.
14044 * Returns: (transfer full): a copy of @string with all
14045 * non-optionally-escaped bytes escaped
14051 * g_dbus_address_get_for_bus_sync:
14052 * @bus_type: A #GBusType.
14053 * @cancellable: (allow-none): A #GCancellable or %NULL.
14054 * @error: Return location for error or %NULL.
14056 * Synchronously looks up the D-Bus address for the well-known message
14057 * bus instance specified by @bus_type. This may involve using various
14058 * platform specific mechanisms.
14060 * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
14066 * g_dbus_address_get_stream:
14067 * @address: A valid D-Bus address.
14068 * @cancellable: (allow-none): A #GCancellable or %NULL.
14069 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
14070 * @user_data: Data to pass to @callback.
14072 * Asynchronously connects to an endpoint specified by @address and
14073 * sets up the connection so it is in a state to run the client-side
14074 * of the D-Bus authentication conversation.
14076 * When the operation is finished, @callback will be invoked. You can
14077 * then call g_dbus_address_get_stream_finish() to get the result of
14080 * This is an asynchronous failable function. See
14081 * g_dbus_address_get_stream_sync() for the synchronous version.
14088 * g_dbus_address_get_stream_finish:
14089 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
14090 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
14091 * @error: Return location for error or %NULL.
14093 * Finishes an operation started with g_dbus_address_get_stream().
14095 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
14101 * g_dbus_address_get_stream_sync:
14102 * @address: A valid D-Bus address.
14103 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
14104 * @cancellable: (allow-none): A #GCancellable or %NULL.
14105 * @error: Return location for error or %NULL.
14107 * Synchronously connects to an endpoint specified by @address and
14108 * sets up the connection so it is in a state to run the client-side
14109 * of the D-Bus authentication conversation.
14111 * This is a synchronous failable function. See
14112 * g_dbus_address_get_stream() for the asynchronous version.
14114 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
14120 * g_dbus_annotation_info_lookup:
14121 * @annotations: (array zero-terminated=1) (allow-none): A %NULL-terminated array of annotations or %NULL.
14122 * @name: The name of the annotation to look up.
14124 * Looks up the value of an annotation.
14126 * The cost of this function is O(n) in number of annotations.
14128 * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
14134 * g_dbus_annotation_info_ref:
14135 * @info: A #GDBusNodeInfo
14137 * If @info is statically allocated does nothing. Otherwise increases
14138 * the reference count.
14140 * Returns: The same @info.
14146 * g_dbus_annotation_info_unref:
14147 * @info: A #GDBusAnnotationInfo.
14149 * If @info is statically allocated, does nothing. Otherwise decreases
14150 * the reference count of @info. When its reference count drops to 0,
14151 * the memory used is freed.
14158 * g_dbus_arg_info_ref:
14159 * @info: A #GDBusArgInfo
14161 * If @info is statically allocated does nothing. Otherwise increases
14162 * the reference count.
14164 * Returns: The same @info.
14170 * g_dbus_arg_info_unref:
14171 * @info: A #GDBusArgInfo.
14173 * If @info is statically allocated, does nothing. Otherwise decreases
14174 * the reference count of @info. When its reference count drops to 0,
14175 * the memory used is freed.
14182 * g_dbus_auth_observer_allow_mechanism:
14183 * @observer: A #GDBusAuthObserver.
14184 * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
14186 * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
14188 * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
14194 * g_dbus_auth_observer_authorize_authenticated_peer:
14195 * @observer: A #GDBusAuthObserver.
14196 * @stream: A #GIOStream for the #GDBusConnection.
14197 * @credentials: (allow-none): Credentials received from the peer or %NULL.
14199 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
14201 * Returns: %TRUE if the peer is authorized, %FALSE if not.
14207 * g_dbus_auth_observer_new:
14209 * Creates a new #GDBusAuthObserver object.
14211 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
14217 * g_dbus_connection_add_filter:
14218 * @connection: A #GDBusConnection.
14219 * @filter_function: A filter function.
14220 * @user_data: User data to pass to @filter_function.
14221 * @user_data_free_func: Function to free @user_data with when filter
14222 * is removed or %NULL.
14224 * Adds a message filter. Filters are handlers that are run on all
14225 * incoming and outgoing messages, prior to standard dispatch. Filters
14226 * are run in the order that they were added. The same handler can be
14227 * added as a filter more than once, in which case it will be run more
14228 * than once. Filters added during a filter callback won't be run on
14229 * the message being processed. Filter functions are allowed to modify
14230 * and even drop messages.
14232 * Note that filters are run in a dedicated message handling thread so
14233 * they can't block and, generally, can't do anything but signal a
14234 * worker thread. Also note that filters are rarely needed - use API
14235 * such as g_dbus_connection_send_message_with_reply(),
14236 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
14238 * If a filter consumes an incoming message the message is not
14239 * dispatched anywhere else - not even the standard dispatch machinery
14240 * (that API such as g_dbus_connection_signal_subscribe() and
14241 * g_dbus_connection_send_message_with_reply() relies on) will see the
14242 * message. Similary, if a filter consumes an outgoing message, the
14243 * message will not be sent to the other peer.
14245 * Returns: A filter identifier that can be used with
14246 * g_dbus_connection_remove_filter().
14252 * g_dbus_connection_call:
14253 * @connection: A #GDBusConnection.
14254 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
14255 * @connection is not a message bus connection.
14256 * @object_path: Path of remote object.
14257 * @interface_name: D-Bus interface to invoke method on.
14258 * @method_name: The name of the method to invoke.
14259 * @parameters: (allow-none): A #GVariant tuple with parameters for the method
14260 * or %NULL if not passing parameters.
14261 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
14262 * @flags: Flags from the #GDBusCallFlags enumeration.
14263 * @timeout_msec: The timeout in milliseconds, -1 to use the default
14264 * timeout or %G_MAXINT for no timeout.
14265 * @cancellable: (allow-none): A #GCancellable or %NULL.
14266 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
14267 * satisfied or %NULL if you don't care about the result of the
14268 * method invocation.
14269 * @user_data: The data to pass to @callback.
14271 * Asynchronously invokes the @method_name method on the
14272 * @interface_name D-Bus interface on the remote object at
14273 * @object_path owned by @bus_name.
14275 * If @connection is closed then the operation will fail with
14276 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
14277 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
14278 * not compatible with the D-Bus protocol, the operation fails with
14279 * %G_IO_ERROR_INVALID_ARGUMENT.
14281 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
14282 * error will be raised if it does not match. Said another way, if you give a @reply_type
14283 * then any non-%NULL return value will be of this type.
14285 * If the @parameters #GVariant is floating, it is consumed. This allows
14286 * convenient 'inline' use of g_variant_new(), e.g.:
14288 * g_dbus_connection_call (connection,
14289 * "org.freedesktop.StringThings",
14290 * "/org/freedesktop/StringThings",
14291 * "org.freedesktop.StringThings",
14293 * g_variant_new ("(ss)",
14297 * G_DBUS_CALL_FLAGS_NONE,
14300 * (GAsyncReadyCallback) two_strings_done,
14304 * This is an asynchronous method. When the operation is finished, @callback will be invoked
14305 * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
14306 * of the thread you are calling this method from. You can then call
14307 * g_dbus_connection_call_finish() to get the result of the operation.
14308 * See g_dbus_connection_call_sync() for the synchronous version of this
14311 * If @callback is %NULL then the D-Bus method call message will be sent with
14312 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
14319 * g_dbus_connection_call_finish:
14320 * @connection: A #GDBusConnection.
14321 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call().
14322 * @error: Return location for error or %NULL.
14324 * Finishes an operation started with g_dbus_connection_call().
14326 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14327 * return values. Free with g_variant_unref().
14333 * g_dbus_connection_call_sync:
14334 * @connection: A #GDBusConnection.
14335 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
14336 * @connection is not a message bus connection.
14337 * @object_path: Path of remote object.
14338 * @interface_name: D-Bus interface to invoke method on.
14339 * @method_name: The name of the method to invoke.
14340 * @parameters: (allow-none): A #GVariant tuple with parameters for the method
14341 * or %NULL if not passing parameters.
14342 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
14343 * @flags: Flags from the #GDBusCallFlags enumeration.
14344 * @timeout_msec: The timeout in milliseconds, -1 to use the default
14345 * timeout or %G_MAXINT for no timeout.
14346 * @cancellable: (allow-none): A #GCancellable or %NULL.
14347 * @error: Return location for error or %NULL.
14349 * Synchronously invokes the @method_name method on the
14350 * @interface_name D-Bus interface on the remote object at
14351 * @object_path owned by @bus_name.
14353 * If @connection is closed then the operation will fail with
14354 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
14355 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
14356 * contains a value not compatible with the D-Bus protocol, the operation
14357 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
14359 * If @reply_type is non-%NULL then the reply will be checked for having
14360 * this type and an error will be raised if it does not match. Said
14361 * another way, if you give a @reply_type then any non-%NULL return
14362 * value will be of this type.
14364 * If the @parameters #GVariant is floating, it is consumed.
14365 * This allows convenient 'inline' use of g_variant_new(), e.g.:
14367 * g_dbus_connection_call_sync (connection,
14368 * "org.freedesktop.StringThings",
14369 * "/org/freedesktop/StringThings",
14370 * "org.freedesktop.StringThings",
14372 * g_variant_new ("(ss)",
14376 * G_DBUS_CALL_FLAGS_NONE,
14382 * The calling thread is blocked until a reply is received. See
14383 * g_dbus_connection_call() for the asynchronous version of
14386 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14387 * return values. Free with g_variant_unref().
14393 * g_dbus_connection_call_with_unix_fd_list:
14394 * @connection: A #GDBusConnection.
14395 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
14396 * @connection is not a message bus connection.
14397 * @object_path: Path of remote object.
14398 * @interface_name: D-Bus interface to invoke method on.
14399 * @method_name: The name of the method to invoke.
14400 * @parameters: (allow-none): A #GVariant tuple with parameters for the method
14401 * or %NULL if not passing parameters.
14402 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
14403 * @flags: Flags from the #GDBusCallFlags enumeration.
14404 * @timeout_msec: The timeout in milliseconds, -1 to use the default
14405 * timeout or %G_MAXINT for no timeout.
14406 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
14407 * @cancellable: (allow-none): A #GCancellable or %NULL.
14408 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
14409 * satisfied or %NULL if you don't * care about the result of the
14410 * method invocation.
14411 * @user_data: The data to pass to @callback.
14413 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
14415 * This method is only available on UNIX.
14422 * g_dbus_connection_call_with_unix_fd_list_finish:
14423 * @connection: A #GDBusConnection.
14424 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
14425 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list().
14426 * @error: Return location for error or %NULL.
14428 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
14430 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14431 * return values. Free with g_variant_unref().
14437 * g_dbus_connection_call_with_unix_fd_list_sync:
14438 * @connection: A #GDBusConnection.
14439 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
14440 * @connection is not a message bus connection.
14441 * @object_path: Path of remote object.
14442 * @interface_name: D-Bus interface to invoke method on.
14443 * @method_name: The name of the method to invoke.
14444 * @parameters: (allow-none): A #GVariant tuple with parameters for the method
14445 * or %NULL if not passing parameters.
14446 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
14447 * @flags: Flags from the #GDBusCallFlags enumeration.
14448 * @timeout_msec: The timeout in milliseconds, -1 to use the default
14449 * timeout or %G_MAXINT for no timeout.
14450 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
14451 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
14452 * @cancellable: (allow-none): A #GCancellable or %NULL.
14453 * @error: Return location for error or %NULL.
14455 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
14457 * This method is only available on UNIX.
14459 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
14460 * return values. Free with g_variant_unref().
14466 * g_dbus_connection_close:
14467 * @connection: A #GDBusConnection.
14468 * @cancellable: (allow-none): A #GCancellable or %NULL.
14469 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
14470 * satisfied or %NULL if you don't care about the result.
14471 * @user_data: The data to pass to @callback.
14473 * Closes @connection. Note that this never causes the process to
14474 * exit (this might only happen if the other end of a shared message
14475 * bus connection disconnects, see #GDBusConnection:exit-on-close).
14477 * Once the connection is closed, operations such as sending a message
14478 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
14479 * will not automatically flush the connection so queued messages may
14480 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
14482 * If @connection is already closed, this method fails with
14483 * %G_IO_ERROR_CLOSED.
14485 * When @connection has been closed, the #GDBusConnection::closed
14486 * signal is emitted in the <link
14487 * linkend="g-main-context-push-thread-default">thread-default main
14488 * loop</link> of the thread that @connection was constructed in.
14490 * This is an asynchronous method. When the operation is finished,
14491 * @callback will be invoked in the <link
14492 * linkend="g-main-context-push-thread-default">thread-default main
14493 * loop</link> of the thread you are calling this method from. You can
14494 * then call g_dbus_connection_close_finish() to get the result of the
14495 * operation. See g_dbus_connection_close_sync() for the synchronous
14503 * g_dbus_connection_close_finish:
14504 * @connection: A #GDBusConnection.
14505 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close().
14506 * @error: Return location for error or %NULL.
14508 * Finishes an operation started with g_dbus_connection_close().
14510 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
14516 * g_dbus_connection_close_sync:
14517 * @connection: A #GDBusConnection.
14518 * @cancellable: (allow-none): A #GCancellable or %NULL.
14519 * @error: Return location for error or %NULL.
14521 * Synchronously closees @connection. The calling thread is blocked
14522 * until this is done. See g_dbus_connection_close() for the
14523 * asynchronous version of this method and more details about what it
14526 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
14532 * g_dbus_connection_emit_signal:
14533 * @connection: A #GDBusConnection.
14534 * @destination_bus_name: (allow-none): The unique bus name for the destination
14535 * for the signal or %NULL to emit to all listeners.
14536 * @object_path: Path of remote object.
14537 * @interface_name: D-Bus interface to emit a signal on.
14538 * @signal_name: The name of the signal to emit.
14539 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
14540 * or %NULL if not passing parameters.
14541 * @error: Return location for error or %NULL.
14545 * If the parameters GVariant is floating, it is consumed.
14547 * This can only fail if @parameters is not compatible with the D-Bus protocol.
14549 * Returns: %TRUE unless @error is set.
14555 * g_dbus_connection_export_action_group:
14556 * @connection: a #GDBusConnection
14557 * @object_path: a D-Bus object path
14558 * @action_group: a #GActionGroup
14559 * @error: a pointer to a %NULL #GError, or %NULL
14561 * Exports @action_group on @connection at @object_path.
14563 * The implemented D-Bus API should be considered private. It is
14564 * subject to change in the future.
14566 * A given object path can only have one action group exported on it.
14567 * If this constraint is violated, the export will fail and 0 will be
14568 * returned (with @error set accordingly).
14570 * You can unexport the action group using
14571 * g_dbus_connection_unexport_action_group() with the return value of
14574 * The thread default main context is taken at the time of this call.
14575 * All incoming action activations and state change requests are
14576 * reported from this context. Any changes on the action group that
14577 * cause it to emit signals must also come from this same context.
14578 * Since incoming action activations and state change requests are
14579 * rather likely to cause changes on the action group, this effectively
14580 * limits a given action group to being exported from only one main
14583 * Returns: the ID of the export (never zero), or 0 in case of failure
14589 * g_dbus_connection_export_menu_model:
14590 * @connection: a #GDBusConnection
14591 * @object_path: a D-Bus object path
14592 * @menu: a #GMenuModel
14593 * @error: return location for an error, or %NULL
14595 * Exports @menu on @connection at @object_path.
14597 * The implemented D-Bus API should be considered private.
14598 * It is subject to change in the future.
14600 * An object path can only have one menu model exported on it. If this
14601 * constraint is violated, the export will fail and 0 will be
14602 * returned (with @error set accordingly).
14604 * You can unexport the menu model using
14605 * g_dbus_connection_unexport_menu_model() with the return value of
14608 * Returns: the ID of the export (never zero), or 0 in case of failure
14614 * g_dbus_connection_flush:
14615 * @connection: A #GDBusConnection.
14616 * @cancellable: (allow-none): A #GCancellable or %NULL.
14617 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
14618 * satisfied or %NULL if you don't care about the result.
14619 * @user_data: The data to pass to @callback.
14621 * Asynchronously flushes @connection, that is, writes all queued
14622 * outgoing message to the transport and then flushes the transport
14623 * (using g_output_stream_flush_async()). This is useful in programs
14624 * that wants to emit a D-Bus signal and then exit
14625 * immediately. Without flushing the connection, there is no guarantee
14626 * that the message has been sent to the networking buffers in the OS
14629 * This is an asynchronous method. When the operation is finished,
14630 * @callback will be invoked in the <link
14631 * linkend="g-main-context-push-thread-default">thread-default main
14632 * loop</link> of the thread you are calling this method from. You can
14633 * then call g_dbus_connection_flush_finish() to get the result of the
14634 * operation. See g_dbus_connection_flush_sync() for the synchronous
14642 * g_dbus_connection_flush_finish:
14643 * @connection: A #GDBusConnection.
14644 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush().
14645 * @error: Return location for error or %NULL.
14647 * Finishes an operation started with g_dbus_connection_flush().
14649 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
14655 * g_dbus_connection_flush_sync:
14656 * @connection: A #GDBusConnection.
14657 * @cancellable: (allow-none): A #GCancellable or %NULL.
14658 * @error: Return location for error or %NULL.
14660 * Synchronously flushes @connection. The calling thread is blocked
14661 * until this is done. See g_dbus_connection_flush() for the
14662 * asynchronous version of this method and more details about what it
14665 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
14671 * g_dbus_connection_get_capabilities:
14672 * @connection: A #GDBusConnection.
14674 * Gets the capabilities negotiated with the remote peer
14676 * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
14682 * g_dbus_connection_get_exit_on_close:
14683 * @connection: A #GDBusConnection.
14685 * Gets whether the process is terminated when @connection is
14686 * closed by the remote peer. See
14687 * #GDBusConnection:exit-on-close for more details.
14689 * Returns: Whether the process is terminated when @connection is
14690 * closed by the remote peer.
14696 * g_dbus_connection_get_guid:
14697 * @connection: A #GDBusConnection.
14699 * The GUID of the peer performing the role of server when
14700 * authenticating. See #GDBusConnection:guid for more details.
14702 * Returns: The GUID. Do not free this string, it is owned by
14709 * g_dbus_connection_get_last_serial:
14710 * @connection: A #GDBusConnection.
14712 * Retrieves the last serial number assigned to a #GDBusMessage on
14713 * the current thread. This includes messages sent via both low-level
14714 * API such as g_dbus_connection_send_message() as well as
14715 * high-level API such as g_dbus_connection_emit_signal(),
14716 * g_dbus_connection_call() or g_dbus_proxy_call().
14718 * Returns: the last used serial or zero when no message has been sent
14719 * within the current thread.
14725 * g_dbus_connection_get_peer_credentials:
14726 * @connection: A #GDBusConnection.
14728 * Gets the credentials of the authenticated peer. This will always
14729 * return %NULL unless @connection acted as a server
14730 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
14731 * when set up and the client passed credentials as part of the
14732 * authentication process.
14734 * In a message bus setup, the message bus is always the server and
14735 * each application is a client. So this method will always return
14736 * %NULL for message bus clients.
14738 * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
14739 * this object, it is owned by @connection.
14745 * g_dbus_connection_get_stream:
14746 * @connection: a #GDBusConnection
14748 * Gets the underlying stream used for IO.
14750 * While the #GDBusConnection is active, it will interact with this
14751 * stream from a worker thread, so it is not safe to interact with
14752 * the stream directly.
14754 * Returns: (transfer none): the stream used for IO
14760 * g_dbus_connection_get_unique_name:
14761 * @connection: A #GDBusConnection.
14763 * Gets the unique name of @connection as assigned by the message
14764 * bus. This can also be used to figure out if @connection is a
14765 * message bus connection.
14767 * Returns: The unique name or %NULL if @connection is not a message
14768 * bus connection. Do not free this string, it is owned by
14775 * g_dbus_connection_is_closed:
14776 * @connection: A #GDBusConnection.
14778 * Gets whether @connection is closed.
14780 * Returns: %TRUE if the connection is closed, %FALSE otherwise.
14786 * g_dbus_connection_new:
14787 * @stream: A #GIOStream.
14788 * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
14789 * @flags: Flags describing how to make the connection.
14790 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
14791 * @cancellable: (allow-none): A #GCancellable or %NULL.
14792 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
14793 * @user_data: The data to pass to @callback.
14795 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
14796 * with the end represented by @stream.
14798 * If @stream is a #GSocketConnection, then the corresponding #GSocket
14799 * will be put into non-blocking mode.
14801 * The D-Bus connection will interact with @stream from a worker thread.
14802 * As a result, the caller should not interact with @stream after this
14803 * method has been called, except by calling g_object_unref() on it.
14805 * If @observer is not %NULL it may be used to control the
14806 * authentication process.
14808 * When the operation is finished, @callback will be invoked. You can
14809 * then call g_dbus_connection_new_finish() to get the result of the
14812 * This is a asynchronous failable constructor. See
14813 * g_dbus_connection_new_sync() for the synchronous
14821 * g_dbus_connection_new_finish:
14822 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
14823 * @error: Return location for error or %NULL.
14825 * Finishes an operation started with g_dbus_connection_new().
14827 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
14833 * g_dbus_connection_new_for_address:
14834 * @address: A D-Bus address.
14835 * @flags: Flags describing how to make the connection.
14836 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
14837 * @cancellable: (allow-none): A #GCancellable or %NULL.
14838 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
14839 * @user_data: The data to pass to @callback.
14841 * Asynchronously connects and sets up a D-Bus client connection for
14842 * exchanging D-Bus messages with an endpoint specified by @address
14843 * which must be in the D-Bus address format.
14845 * This constructor can only be used to initiate client-side
14846 * connections - use g_dbus_connection_new() if you need to act as the
14847 * server. In particular, @flags cannot contain the
14848 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
14849 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
14851 * When the operation is finished, @callback will be invoked. You can
14852 * then call g_dbus_connection_new_finish() to get the result of the
14855 * If @observer is not %NULL it may be used to control the
14856 * authentication process.
14858 * This is a asynchronous failable constructor. See
14859 * g_dbus_connection_new_for_address_sync() for the synchronous
14867 * g_dbus_connection_new_for_address_finish:
14868 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
14869 * @error: Return location for error or %NULL.
14871 * Finishes an operation started with g_dbus_connection_new_for_address().
14873 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
14879 * g_dbus_connection_new_for_address_sync:
14880 * @address: A D-Bus address.
14881 * @flags: Flags describing how to make the connection.
14882 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
14883 * @cancellable: (allow-none): A #GCancellable or %NULL.
14884 * @error: Return location for error or %NULL.
14886 * Synchronously connects and sets up a D-Bus client connection for
14887 * exchanging D-Bus messages with an endpoint specified by @address
14888 * which must be in the D-Bus address format.
14890 * This constructor can only be used to initiate client-side
14891 * connections - use g_dbus_connection_new_sync() if you need to act
14892 * as the server. In particular, @flags cannot contain the
14893 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
14894 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
14896 * This is a synchronous failable constructor. See
14897 * g_dbus_connection_new_for_address() for the asynchronous version.
14899 * If @observer is not %NULL it may be used to control the
14900 * authentication process.
14902 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
14908 * g_dbus_connection_new_sync:
14909 * @stream: A #GIOStream.
14910 * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
14911 * @flags: Flags describing how to make the connection.
14912 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
14913 * @cancellable: (allow-none): A #GCancellable or %NULL.
14914 * @error: Return location for error or %NULL.
14916 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
14917 * with the end represented by @stream.
14919 * If @stream is a #GSocketConnection, then the corresponding #GSocket
14920 * will be put into non-blocking mode.
14922 * The D-Bus connection will interact with @stream from a worker thread.
14923 * As a result, the caller should not interact with @stream after this
14924 * method has been called, except by calling g_object_unref() on it.
14926 * If @observer is not %NULL it may be used to control the
14927 * authentication process.
14929 * This is a synchronous failable constructor. See
14930 * g_dbus_connection_new() for the asynchronous version.
14932 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
14938 * g_dbus_connection_register_object:
14939 * @connection: A #GDBusConnection.
14940 * @object_path: The object path to register at.
14941 * @interface_info: Introspection data for the interface.
14942 * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL.
14943 * @user_data: (allow-none): Data to pass to functions in @vtable.
14944 * @user_data_free_func: Function to call when the object path is unregistered.
14945 * @error: Return location for error or %NULL.
14947 * Registers callbacks for exported objects at @object_path with the
14948 * D-Bus interface that is described in @interface_info.
14950 * Calls to functions in @vtable (and @user_data_free_func) will
14951 * happen in the <link linkend="g-main-context-push-thread-default">thread-default main
14952 * loop</link> of the thread you are calling this method from.
14954 * Note that all #GVariant values passed to functions in @vtable will match
14955 * the signature given in @interface_info - if a remote caller passes
14956 * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
14957 * is returned to the remote caller.
14959 * Additionally, if the remote caller attempts to invoke methods or
14960 * access properties not mentioned in @interface_info the
14961 * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
14962 * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
14963 * are returned to the caller.
14965 * It is considered a programming error if the
14966 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
14967 * #GVariant of incorrect type.
14969 * If an existing callback is already registered at @object_path and
14970 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
14972 * GDBus automatically implements the standard D-Bus interfaces
14973 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
14974 * and org.freedesktop.Peer, so you don't have to implement those for
14975 * the objects you export. You <emphasis>can</emphasis> implement
14976 * org.freedesktop.DBus.Properties yourself, e.g. to handle getting
14977 * and setting of properties asynchronously.
14979 * Note that the reference count on @interface_info will be
14980 * incremented by 1 (unless allocated statically, e.g. if the
14981 * reference count is -1, see g_dbus_interface_info_ref()) for as long
14982 * as the object is exported. Also note that @vtable will be copied.
14984 * See <xref linkend="gdbus-server"/> for an example of how to use this method.
14986 * Returns: 0 if @error is set, otherwise a registration id (never 0)
14987 * that can be used with g_dbus_connection_unregister_object() .
14993 * g_dbus_connection_register_subtree:
14994 * @connection: A #GDBusConnection.
14995 * @object_path: The object path to register the subtree at.
14996 * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
14997 * @flags: Flags used to fine tune the behavior of the subtree.
14998 * @user_data: Data to pass to functions in @vtable.
14999 * @user_data_free_func: Function to call when the subtree is unregistered.
15000 * @error: Return location for error or %NULL.
15002 * Registers a whole subtree of <quote>dynamic</quote> objects.
15004 * The @enumerate and @introspection functions in @vtable are used to
15005 * convey, to remote callers, what nodes exist in the subtree rooted
15008 * When handling remote calls into any node in the subtree, first the
15009 * @enumerate function is used to check if the node exists. If the node exists
15010 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
15011 * the @introspection function is used to check if the node supports the
15012 * requested method. If so, the @dispatch function is used to determine
15013 * where to dispatch the call. The collected #GDBusInterfaceVTable and
15014 * #gpointer will be used to call into the interface vtable for processing
15017 * All calls into user-provided code will be invoked in the <link
15018 * linkend="g-main-context-push-thread-default">thread-default main
15019 * loop</link> of the thread you are calling this method from.
15021 * If an existing subtree is already registered at @object_path or
15022 * then @error is set to #G_IO_ERROR_EXISTS.
15024 * Note that it is valid to register regular objects (using
15025 * g_dbus_connection_register_object()) in a subtree registered with
15026 * g_dbus_connection_register_subtree() - if so, the subtree handler
15027 * is tried as the last resort. One way to think about a subtree
15028 * handler is to consider it a <quote>fallback handler</quote>
15029 * for object paths not registered via g_dbus_connection_register_object()
15030 * or other bindings.
15032 * Note that @vtable will be copied so you cannot change it after
15035 * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
15037 * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
15038 * that can be used with g_dbus_connection_unregister_subtree() .
15044 * g_dbus_connection_remove_filter:
15045 * @connection: a #GDBusConnection
15046 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
15048 * Removes a filter.
15055 * g_dbus_connection_send_message:
15056 * @connection: A #GDBusConnection.
15057 * @message: A #GDBusMessage
15058 * @flags: Flags affecting how the message is sent.
15059 * @out_serial: (out) (allow-none): Return location for serial number assigned
15060 * to @message when sending it or %NULL.
15061 * @error: Return location for error or %NULL.
15063 * Asynchronously sends @message to the peer represented by @connection.
15065 * Unless @flags contain the
15066 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15067 * will be assigned by @connection and set on @message via
15068 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15069 * serial number used will be written to this location prior to
15070 * submitting the message to the underlying transport.
15072 * If @connection is closed then the operation will fail with
15073 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
15074 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15076 * See <xref linkend="gdbus-server"/> and <xref
15077 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
15078 * low-level API to send and receive UNIX file descriptors.
15080 * Note that @message must be unlocked, unless @flags contain the
15081 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15083 * Returns: %TRUE if the message was well-formed and queued for
15084 * transmission, %FALSE if @error is set.
15090 * g_dbus_connection_send_message_with_reply:
15091 * @connection: A #GDBusConnection.
15092 * @message: A #GDBusMessage.
15093 * @flags: Flags affecting how the message is sent.
15094 * @timeout_msec: The timeout in milliseconds, -1 to use the default
15095 * timeout or %G_MAXINT for no timeout.
15096 * @out_serial: (out) (allow-none): Return location for serial number assigned
15097 * to @message when sending it or %NULL.
15098 * @cancellable: (allow-none): A #GCancellable or %NULL.
15099 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
15100 * satisfied or %NULL if you don't care about the result.
15101 * @user_data: The data to pass to @callback.
15103 * Asynchronously sends @message to the peer represented by @connection.
15105 * Unless @flags contain the
15106 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15107 * will be assigned by @connection and set on @message via
15108 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15109 * serial number used will be written to this location prior to
15110 * submitting the message to the underlying transport.
15112 * If @connection is closed then the operation will fail with
15113 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15114 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
15115 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15117 * This is an asynchronous method. When the operation is finished, @callback will be invoked
15118 * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
15119 * of the thread you are calling this method from. You can then call
15120 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
15121 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
15123 * Note that @message must be unlocked, unless @flags contain the
15124 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15126 * See <xref linkend="gdbus-server"/> and <xref
15127 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
15128 * low-level API to send and receive UNIX file descriptors.
15135 * g_dbus_connection_send_message_with_reply_finish:
15136 * @connection: a #GDBusConnection
15137 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
15138 * @error: Return location for error or %NULL.
15140 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
15142 * Note that @error is only set if a local in-process error
15143 * occurred. That is to say that the returned #GDBusMessage object may
15144 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
15145 * g_dbus_message_to_gerror() to transcode this to a #GError.
15147 * See <xref linkend="gdbus-server"/> and <xref
15148 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
15149 * low-level API to send and receive UNIX file descriptors.
15151 * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
15157 * g_dbus_connection_send_message_with_reply_sync:
15158 * @connection: A #GDBusConnection.
15159 * @message: A #GDBusMessage.
15160 * @flags: Flags affecting how the message is sent.
15161 * @timeout_msec: The timeout in milliseconds, -1 to use the default
15162 * timeout or %G_MAXINT for no timeout.
15163 * @out_serial: (out) (allow-none): Return location for serial number assigned
15164 * to @message when sending it or %NULL.
15165 * @cancellable: (allow-none): A #GCancellable or %NULL.
15166 * @error: Return location for error or %NULL.
15168 * Synchronously sends @message to the peer represented by @connection
15169 * and blocks the calling thread until a reply is received or the
15170 * timeout is reached. See g_dbus_connection_send_message_with_reply()
15171 * for the asynchronous version of this method.
15173 * Unless @flags contain the
15174 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
15175 * will be assigned by @connection and set on @message via
15176 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
15177 * serial number used will be written to this location prior to
15178 * submitting the message to the underlying transport.
15180 * If @connection is closed then the operation will fail with
15181 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
15182 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
15183 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
15185 * Note that @error is only set if a local in-process error
15186 * occurred. That is to say that the returned #GDBusMessage object may
15187 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
15188 * g_dbus_message_to_gerror() to transcode this to a #GError.
15190 * See <xref linkend="gdbus-server"/> and <xref
15191 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
15192 * low-level API to send and receive UNIX file descriptors.
15194 * Note that @message must be unlocked, unless @flags contain the
15195 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
15197 * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
15203 * g_dbus_connection_set_exit_on_close:
15204 * @connection: A #GDBusConnection.
15205 * @exit_on_close: Whether the process should be terminated
15206 * when @connection is closed by the remote peer.
15208 * Sets whether the process should be terminated when @connection is
15209 * closed by the remote peer. See #GDBusConnection:exit-on-close for
15212 * Note that this function should be used with care. Most modern UNIX
15213 * desktops tie the notion of a user session the session bus, and expect
15214 * all of a users applications to quit when their bus connection goes away.
15215 * If you are setting @exit_on_close to %FALSE for the shared session
15216 * bus connection, you should make sure that your application exits
15217 * when the user session ends.
15224 * g_dbus_connection_signal_subscribe:
15225 * @connection: A #GDBusConnection.
15226 * @sender: (allow-none): Sender name to match on (unique or well-known name)
15227 * or %NULL to listen from all senders.
15228 * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to
15229 * match on all interfaces.
15230 * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals.
15231 * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths.
15232 * @arg0: (allow-none): Contents of first string argument to match on or %NULL
15233 * to match on all kinds of arguments.
15234 * @flags: Flags describing how to subscribe to the signal (currently unused).
15235 * @callback: Callback to invoke when there is a signal matching the requested data.
15236 * @user_data: User data to pass to @callback.
15237 * @user_data_free_func: (allow-none): Function to free @user_data with when
15238 * subscription is removed or %NULL.
15240 * Subscribes to signals on @connection and invokes @callback with a
15241 * whenever the signal is received. Note that @callback
15242 * will be invoked in the <link
15243 * linkend="g-main-context-push-thread-default">thread-default main
15244 * loop</link> of the thread you are calling this method from.
15246 * If @connection is not a message bus connection, @sender must be
15249 * If @sender is a well-known name note that @callback is invoked with
15250 * the unique name for the owner of @sender, not the well-known name
15251 * as one would expect. This is because the message bus rewrites the
15252 * name. As such, to avoid certain race conditions, users should be
15253 * tracking the name owner of the well-known name and use that when
15254 * processing the received signal.
15256 * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
15257 * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is
15258 * interpreted as part of a namespace or path. The first argument
15259 * of a signal is matched against that part as specified by D-Bus.
15261 * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
15267 * g_dbus_connection_signal_unsubscribe:
15268 * @connection: A #GDBusConnection.
15269 * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
15271 * Unsubscribes from signals.
15278 * g_dbus_connection_start_message_processing:
15279 * @connection: A #GDBusConnection.
15281 * If @connection was created with
15282 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
15283 * starts processing messages. Does nothing on if @connection wasn't
15284 * created with this flag or if the method has already been called.
15291 * g_dbus_connection_unexport_action_group:
15292 * @connection: a #GDBusConnection
15293 * @export_id: the ID from g_dbus_connection_export_action_group()
15295 * Reverses the effect of a previous call to
15296 * g_dbus_connection_export_action_group().
15298 * It is an error to call this function with an ID that wasn't returned
15299 * from g_dbus_connection_export_action_group() or to call it with the
15300 * same ID more than once.
15307 * g_dbus_connection_unexport_menu_model:
15308 * @connection: a #GDBusConnection
15309 * @export_id: the ID from g_dbus_connection_export_menu_model()
15311 * Reverses the effect of a previous call to
15312 * g_dbus_connection_export_menu_model().
15314 * It is an error to call this function with an ID that wasn't returned
15315 * from g_dbus_connection_export_menu_model() or to call it with the
15316 * same ID more than once.
15323 * g_dbus_connection_unregister_object:
15324 * @connection: A #GDBusConnection.
15325 * @registration_id: A registration id obtained from g_dbus_connection_register_object().
15327 * Unregisters an object.
15329 * Returns: %TRUE if the object was unregistered, %FALSE otherwise.
15335 * g_dbus_connection_unregister_subtree:
15336 * @connection: A #GDBusConnection.
15337 * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree().
15339 * Unregisters a subtree.
15341 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
15347 * g_dbus_error_encode_gerror:
15348 * @error: A #GError.
15350 * Creates a D-Bus error name to use for @error. If @error matches
15351 * a registered error (cf. g_dbus_error_register_error()), the corresponding
15352 * D-Bus error name will be returned.
15354 * Otherwise the a name of the form
15355 * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
15356 * will be used. This allows other GDBus applications to map the error
15357 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
15359 * This function is typically only used in object mappings to put a
15360 * #GError on the wire. Regular applications should not use it.
15362 * Returns: A D-Bus error name (never %NULL). Free with g_free().
15368 * g_dbus_error_get_remote_error:
15369 * @error: A #GError.
15371 * Gets the D-Bus error name used for @error, if any.
15373 * This function is guaranteed to return a D-Bus error name for all
15374 * #GError<!-- -->s returned from functions handling remote method
15375 * calls (e.g. g_dbus_connection_call_finish()) unless
15376 * g_dbus_error_strip_remote_error() has been used on @error.
15378 * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
15384 * g_dbus_error_is_remote_error:
15385 * @error: A #GError.
15387 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
15388 * use g_dbus_error_get_remote_error() to get the name of the error.
15390 * Returns: %TRUE if @error represents an error from a remote peer,
15391 * %FALSE otherwise.
15397 * g_dbus_error_new_for_dbus_error:
15398 * @dbus_error_name: D-Bus error name.
15399 * @dbus_error_message: D-Bus error message.
15401 * Creates a #GError based on the contents of @dbus_error_name and
15402 * @dbus_error_message.
15404 * Errors registered with g_dbus_error_register_error() will be looked
15405 * up using @dbus_error_name and if a match is found, the error domain
15406 * and code is used. Applications can use g_dbus_error_get_remote_error()
15407 * to recover @dbus_error_name.
15409 * If a match against a registered error is not found and the D-Bus
15410 * error name is in a form as returned by g_dbus_error_encode_gerror()
15411 * the error domain and code encoded in the name is used to
15412 * create the #GError. Also, @dbus_error_name is added to the error message
15413 * such that it can be recovered with g_dbus_error_get_remote_error().
15415 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
15416 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
15417 * added to the error message such that it can be recovered with
15418 * g_dbus_error_get_remote_error().
15420 * In all three cases, @dbus_error_name can always be recovered from the
15421 * returned #GError using the g_dbus_error_get_remote_error() function
15422 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
15424 * This function is typically only used in object mappings to prepare
15425 * #GError instances for applications. Regular applications should not use
15428 * Returns: An allocated #GError. Free with g_error_free().
15434 * g_dbus_error_register_error:
15435 * @error_domain: A #GQuark for a error domain.
15436 * @error_code: An error code.
15437 * @dbus_error_name: A D-Bus error name.
15439 * Creates an association to map between @dbus_error_name and
15440 * #GError<!-- -->s specified by @error_domain and @error_code.
15442 * This is typically done in the routine that returns the #GQuark for
15445 * Returns: %TRUE if the association was created, %FALSE if it already
15452 * g_dbus_error_register_error_domain:
15453 * @error_domain_quark_name: The error domain name.
15454 * @quark_volatile: A pointer where to store the #GQuark.
15455 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
15456 * @num_entries: Number of items to register.
15458 * Helper function for associating a #GError error domain with D-Bus error names.
15465 * g_dbus_error_set_dbus_error:
15466 * @error: A pointer to a #GError or %NULL.
15467 * @dbus_error_name: D-Bus error name.
15468 * @dbus_error_message: D-Bus error message.
15469 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
15470 * @...: Arguments for @format.
15472 * Does nothing if @error is %NULL. Otherwise sets *@error to
15473 * a new #GError created with g_dbus_error_new_for_dbus_error()
15474 * with @dbus_error_message prepend with @format (unless %NULL).
15481 * g_dbus_error_set_dbus_error_valist:
15482 * @error: A pointer to a #GError or %NULL.
15483 * @dbus_error_name: D-Bus error name.
15484 * @dbus_error_message: D-Bus error message.
15485 * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
15486 * @var_args: Arguments for @format.
15488 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
15495 * g_dbus_error_strip_remote_error:
15496 * @error: A #GError.
15498 * Looks for extra information in the error message used to recover
15499 * the D-Bus error name and strips it if found. If stripped, the
15500 * message field in @error will correspond exactly to what was
15501 * received on the wire.
15503 * This is typically used when presenting errors to the end user.
15505 * Returns: %TRUE if information was stripped, %FALSE otherwise.
15511 * g_dbus_error_unregister_error:
15512 * @error_domain: A #GQuark for a error domain.
15513 * @error_code: An error code.
15514 * @dbus_error_name: A D-Bus error name.
15516 * Destroys an association previously set up with g_dbus_error_register_error().
15518 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
15524 * g_dbus_generate_guid:
15526 * Generate a D-Bus GUID that can be used with
15527 * e.g. g_dbus_connection_new().
15529 * See the D-Bus specification regarding what strings are valid D-Bus
15530 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
15532 * Returns: A valid D-Bus GUID. Free with g_free().
15538 * g_dbus_gvalue_to_gvariant:
15539 * @gvalue: A #GValue to convert to a #GVariant.
15540 * @type: A #GVariantType.
15542 * Converts a #GValue to a #GVariant of the type indicated by the @type parameter.
15544 * The conversion is using the following rules:
15545 * <table frame='all'>
15546 * <title>#GValue / #GVariant conversion rules</title>
15547 * <tgroup cols='2' align='left' colsep='1' rowsep='1'>
15550 * <entry>If the #GType for @gvalue is...</entry>
15551 * <entry>... then @type must be</entry>
15556 * <entry>#G_TYPE_STRING</entry>
15557 * <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>
15560 * <entry>#G_TYPE_STRV</entry>
15561 * <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>
15564 * <entry>#G_TYPE_BOOLEAN</entry>
15565 * <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
15568 * <entry>#G_TYPE_UCHAR</entry>
15569 * <entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry>
15572 * <entry>#G_TYPE_INT</entry>
15573 * <entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry>
15576 * <entry>#G_TYPE_UINT</entry>
15577 * <entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry>
15580 * <entry>#G_TYPE_INT64</entry>
15581 * <entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry>
15584 * <entry>#G_TYPE_UINT64</entry>
15585 * <entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry>
15588 * <entry>#G_TYPE_DOUBLE</entry>
15589 * <entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry>
15592 * <entry>#G_TYPE_VARIANT</entry>
15593 * <entry>Any #GVariantType</entry>
15598 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
15599 * is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will
15600 * also fail for any #GType (including e.g. #G_TYPE_OBJECT and
15601 * #G_TYPE_BOXED derived-types) not in the table above.
15603 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
15604 * %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
15605 * %NULL) for @type is returned (e.g. 0 for scalar types, the empty
15606 * string for string types, <literal>'/'</literal> for object path
15607 * types, the empty array for any array type and so on).
15609 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
15610 * #GVariant to a #GValue.
15612 * Returns: A #GVariant (never floating) of #GVariantType
15613 * @type holding the data from @gvalue or %NULL in case of
15614 * failure. Free with g_variant_unref().
15620 * g_dbus_gvariant_to_gvalue:
15621 * @value: A #GVariant.
15622 * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
15624 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
15626 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
15627 * used - this function is essentially its reverse form.
15629 * The conversion never fails - a valid #GValue is always returned in
15637 * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object)
15638 * @interface_: An exported D-Bus interface.
15640 * Gets the #GDBusObject that @interface_ belongs to, if any.
15642 * Returns: (transfer full): A #GDBusObject or %NULL. The returned
15643 * reference should be freed with g_object_unref().
15649 * g_dbus_interface_get_info:
15650 * @interface_: An exported D-Bus interface.
15652 * Gets D-Bus introspection information for the D-Bus interface
15653 * implemented by @interface_.
15655 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
15661 * g_dbus_interface_get_object: (skip)
15662 * @interface_: An exported D-Bus interface.
15664 * Gets the #GDBusObject that @interface_ belongs to, if any.
15666 * <warning>It is not safe to use the returned object if @interface_
15667 * or the returned object is being used from other threads. See
15668 * g_dbus_interface_dup_object() for a thread-safe
15669 * alternative.</warning>
15671 * Returns: (transfer none): A #GDBusObject or %NULL. The returned
15672 * reference belongs to @interface_ and should not be freed.
15678 * g_dbus_interface_info_cache_build:
15679 * @info: A #GDBusInterfaceInfo.
15681 * Builds a lookup-cache to speed up
15682 * g_dbus_interface_info_lookup_method(),
15683 * g_dbus_interface_info_lookup_signal() and
15684 * g_dbus_interface_info_lookup_property().
15686 * If this has already been called with @info, the existing cache is
15687 * used and its use count is increased.
15689 * Note that @info cannot be modified until
15690 * g_dbus_interface_info_cache_release() is called.
15697 * g_dbus_interface_info_cache_release:
15698 * @info: A GDBusInterfaceInfo
15700 * Decrements the usage count for the cache for @info built by
15701 * g_dbus_interface_info_cache_build() (if any) and frees the
15702 * resources used by the cache if the usage count drops to zero.
15709 * g_dbus_interface_info_generate_xml:
15710 * @info: A #GDBusNodeInfo
15711 * @indent: Indentation level.
15712 * @string_builder: (out): A #GString to to append XML data to.
15714 * Appends an XML representation of @info (and its children) to @string_builder.
15716 * This function is typically used for generating introspection XML
15717 * documents at run-time for handling the
15718 * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
15726 * g_dbus_interface_info_lookup_method:
15727 * @info: A #GDBusInterfaceInfo.
15728 * @name: A D-Bus method name (typically in CamelCase)
15730 * Looks up information about a method.
15732 * The cost of this function is O(n) in number of methods unless
15733 * g_dbus_interface_info_cache_build() has been used on @info.
15735 * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
15741 * g_dbus_interface_info_lookup_property:
15742 * @info: A #GDBusInterfaceInfo.
15743 * @name: A D-Bus property name (typically in CamelCase).
15745 * Looks up information about a property.
15747 * The cost of this function is O(n) in number of properties unless
15748 * g_dbus_interface_info_cache_build() has been used on @info.
15750 * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
15756 * g_dbus_interface_info_lookup_signal:
15757 * @info: A #GDBusInterfaceInfo.
15758 * @name: A D-Bus signal name (typically in CamelCase)
15760 * Looks up information about a signal.
15762 * The cost of this function is O(n) in number of signals unless
15763 * g_dbus_interface_info_cache_build() has been used on @info.
15765 * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
15771 * g_dbus_interface_info_ref:
15772 * @info: A #GDBusInterfaceInfo
15774 * If @info is statically allocated does nothing. Otherwise increases
15775 * the reference count.
15777 * Returns: The same @info.
15783 * g_dbus_interface_info_unref:
15784 * @info: A #GDBusInterfaceInfo.
15786 * If @info is statically allocated, does nothing. Otherwise decreases
15787 * the reference count of @info. When its reference count drops to 0,
15788 * the memory used is freed.
15795 * g_dbus_interface_set_object:
15796 * @interface_: An exported D-Bus interface.
15797 * @object: (allow-none): A #GDBusObject or %NULL.
15799 * Sets the #GDBusObject for @interface_ to @object.
15801 * Note that @interface_ will hold a weak reference to @object.
15808 * g_dbus_interface_skeleton_export:
15809 * @interface_: The D-Bus interface to export.
15810 * @connection: A #GDBusConnection to export @interface_ on.
15811 * @object_path: The path to export the interface at.
15812 * @error: Return location for error or %NULL.
15814 * Exports @interface_ at @object_path on @connection.
15816 * This can be called multiple times to export the same @interface_
15817 * onto multiple connections however the @object_path provided must be
15818 * the same for all connections.
15820 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
15822 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
15829 * g_dbus_interface_skeleton_flush:
15830 * @interface_: A #GDBusInterfaceSkeleton.
15832 * If @interface_ has outstanding changes, request for these changes to be
15833 * emitted immediately.
15835 * For example, an exported D-Bus interface may queue up property
15836 * changes and emit the
15837 * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
15838 * signal later (e.g. in an idle handler). This technique is useful
15839 * for collapsing multiple property changes into one.
15846 * g_dbus_interface_skeleton_get_connection:
15847 * @interface_: A #GDBusInterfaceSkeleton.
15849 * Gets the first connection that @interface_ is exported on, if any.
15851 * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
15852 * not exported anywhere. Do not free, the object belongs to @interface_.
15858 * g_dbus_interface_skeleton_get_connections:
15859 * @interface_: A #GDBusInterfaceSkeleton.
15861 * Gets a list of the connections that @interface_ is exported on.
15863 * Returns: (element-type GDBusConnection) (transfer full): A list of
15864 * all the connections that @interface_ is exported on. The returned
15865 * list should be freed with g_list_free() after each element has
15866 * been freed with g_object_unref().
15872 * g_dbus_interface_skeleton_get_flags:
15873 * @interface_: A #GDBusInterfaceSkeleton.
15875 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
15878 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
15884 * g_dbus_interface_skeleton_get_info:
15885 * @interface_: A #GDBusInterfaceSkeleton.
15887 * Gets D-Bus introspection information for the D-Bus interface
15888 * implemented by @interface_.
15890 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
15896 * g_dbus_interface_skeleton_get_object_path:
15897 * @interface_: A #GDBusInterfaceSkeleton.
15899 * Gets the object path that @interface_ is exported on, if any.
15901 * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
15902 * anywhere. Do not free, the string belongs to @interface_.
15908 * g_dbus_interface_skeleton_get_properties:
15909 * @interface_: A #GDBusInterfaceSkeleton.
15911 * Gets all D-Bus properties for @interface_.
15913 * Returns: (transfer full): A #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref().
15919 * g_dbus_interface_skeleton_get_vtable: (skip)
15920 * @interface_: A #GDBusInterfaceSkeleton.
15922 * Gets the interface vtable for the D-Bus interface implemented by
15923 * @interface_. The returned function pointers should expect @interface_
15924 * itself to be passed as @user_data.
15926 * Returns: A #GDBusInterfaceVTable (never %NULL).
15932 * g_dbus_interface_skeleton_has_connection:
15933 * @interface_: A #GDBusInterfaceSkeleton.
15934 * @connection: A #GDBusConnection.
15936 * Checks if @interface_ is exported on @connection.
15938 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
15944 * g_dbus_interface_skeleton_set_flags:
15945 * @interface_: A #GDBusInterfaceSkeleton.
15946 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
15948 * Sets flags describing what the behavior of @skeleton should be.
15955 * g_dbus_interface_skeleton_unexport:
15956 * @interface_: A #GDBusInterfaceSkeleton.
15958 * Stops exporting @interface_ on all connections it is exported on.
15960 * To unexport @interface_ from only a single connection, use
15961 * g_dbus_interface_skeleton_unexport_from_connection()
15968 * g_dbus_interface_skeleton_unexport_from_connection:
15969 * @interface_: A #GDBusInterfaceSkeleton.
15970 * @connection: A #GDBusConnection.
15972 * Stops exporting @interface_ on @connection.
15974 * To stop exporting on all connections the interface is exported on,
15975 * use g_dbus_interface_skeleton_unexport().
15982 * g_dbus_is_address:
15983 * @string: A string.
15985 * Checks if @string is a D-Bus address.
15987 * This doesn't check if @string is actually supported by #GDBusServer
15988 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
15991 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
15998 * @string: The string to check.
16000 * Checks if @string is a D-Bus GUID.
16002 * See the D-Bus specification regarding what strings are valid D-Bus
16003 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
16005 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
16011 * g_dbus_is_interface_name:
16012 * @string: The string to check.
16014 * Checks if @string is a valid D-Bus interface name.
16016 * Returns: %TRUE if valid, %FALSE otherwise.
16022 * g_dbus_is_member_name:
16023 * @string: The string to check.
16025 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
16027 * Returns: %TRUE if valid, %FALSE otherwise.
16034 * @string: The string to check.
16036 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
16038 * Returns: %TRUE if valid, %FALSE otherwise.
16044 * g_dbus_is_supported_address:
16045 * @string: A string.
16046 * @error: Return location for error or %NULL.
16048 * Like g_dbus_is_address() but also checks if the library suppors the
16049 * transports in @string and that key/value pairs for each transport
16052 * Returns: %TRUE if @string is a valid D-Bus address that is
16053 * supported by this library, %FALSE if @error is set.
16059 * g_dbus_is_unique_name:
16060 * @string: The string to check.
16062 * Checks if @string is a valid D-Bus unique bus name.
16064 * Returns: %TRUE if valid, %FALSE otherwise.
16070 * g_dbus_menu_model_get:
16071 * @connection: a #GDBusConnection
16072 * @bus_name: the bus name which exports the menu model
16073 * @object_path: the object path at which the menu model is exported
16075 * Obtains a #GDBusMenuModel for the menu model which is exported
16076 * at the given @bus_name and @object_path.
16078 * The thread default main context is taken at the time of this call.
16079 * All signals on the menu model (and any linked models) are reported
16080 * with respect to this context. All calls on the returned menu model
16081 * (and linked models) must also originate from this same context, with
16082 * the thread default main context unchanged.
16084 * Returns: (transfer full): a #GDBusMenuModel object. Free with
16085 * g_object_unref().
16091 * g_dbus_message_bytes_needed:
16092 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
16093 * @blob_len: The length of @blob (must be at least 16).
16094 * @error: Return location for error or %NULL.
16096 * Utility function to calculate how many bytes are needed to
16097 * completely deserialize the D-Bus message stored at @blob.
16099 * Returns: Number of bytes needed or -1 if @error is set (e.g. if
16100 * @blob contains invalid data or not enough data is available to
16101 * determine the size).
16107 * g_dbus_message_copy:
16108 * @message: A #GDBusMessage.
16109 * @error: Return location for error or %NULL.
16111 * Copies @message. The copy is a deep copy and the returned
16112 * #GDBusMessage is completely identical except that it is guaranteed
16113 * to not be locked.
16115 * This operation can fail if e.g. @message contains file descriptors
16116 * and the per-process or system-wide open files limit is reached.
16118 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
16119 * Free with g_object_unref().
16125 * g_dbus_message_get_arg0:
16126 * @message: A #GDBusMessage.
16128 * Convenience to get the first item in the body of @message.
16130 * Returns: The string item or %NULL if the first item in the body of
16131 * @message is not a string.
16137 * g_dbus_message_get_body:
16138 * @message: A #GDBusMessage.
16140 * Gets the body of a message.
16142 * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
16148 * g_dbus_message_get_byte_order:
16149 * @message: A #GDBusMessage.
16151 * Gets the byte order of @message.
16153 * Returns: The byte order.
16158 * g_dbus_message_get_destination:
16159 * @message: A #GDBusMessage.
16161 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
16163 * Returns: The value.
16169 * g_dbus_message_get_error_name:
16170 * @message: A #GDBusMessage.
16172 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
16174 * Returns: The value.
16180 * g_dbus_message_get_flags:
16181 * @message: A #GDBusMessage.
16183 * Gets the flags for @message.
16185 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
16191 * g_dbus_message_get_header:
16192 * @message: A #GDBusMessage.
16193 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
16195 * Gets a header field on @message.
16197 * Returns: A #GVariant with the value if the header was found, %NULL
16198 * otherwise. Do not free, it is owned by @message.
16204 * g_dbus_message_get_header_fields:
16205 * @message: A #GDBusMessage.
16207 * Gets an array of all header fields on @message that are set.
16209 * Returns: (array zero-terminated=1): An array of header fields
16210 * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
16211 * is a #guchar. Free with g_free().
16217 * g_dbus_message_get_interface:
16218 * @message: A #GDBusMessage.
16220 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
16222 * Returns: The value.
16228 * g_dbus_message_get_locked:
16229 * @message: A #GDBusMessage.
16231 * Checks whether @message is locked. To monitor changes to this
16232 * value, conncet to the #GObject::notify signal to listen for changes
16233 * on the #GDBusMessage:locked property.
16235 * Returns: %TRUE if @message is locked, %FALSE otherwise.
16241 * g_dbus_message_get_member:
16242 * @message: A #GDBusMessage.
16244 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
16246 * Returns: The value.
16252 * g_dbus_message_get_message_type:
16253 * @message: A #GDBusMessage.
16255 * Gets the type of @message.
16257 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
16263 * g_dbus_message_get_num_unix_fds:
16264 * @message: A #GDBusMessage.
16266 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
16268 * Returns: The value.
16274 * g_dbus_message_get_path:
16275 * @message: A #GDBusMessage.
16277 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
16279 * Returns: The value.
16285 * g_dbus_message_get_reply_serial:
16286 * @message: A #GDBusMessage.
16288 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
16290 * Returns: The value.
16296 * g_dbus_message_get_sender:
16297 * @message: A #GDBusMessage.
16299 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
16301 * Returns: The value.
16307 * g_dbus_message_get_serial:
16308 * @message: A #GDBusMessage.
16310 * Gets the serial for @message.
16312 * Returns: A #guint32.
16318 * g_dbus_message_get_signature:
16319 * @message: A #GDBusMessage.
16321 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
16323 * Returns: The value.
16329 * g_dbus_message_get_unix_fd_list:
16330 * @message: A #GDBusMessage.
16332 * Gets the UNIX file descriptors associated with @message, if any.
16334 * This method is only available on UNIX.
16336 * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
16337 * associated. Do not free, this object is owned by @message.
16343 * g_dbus_message_lock:
16344 * @message: A #GDBusMessage.
16346 * If @message is locked, does nothing. Otherwise locks the message.
16353 * g_dbus_message_new:
16355 * Creates a new empty #GDBusMessage.
16357 * Returns: A #GDBusMessage. Free with g_object_unref().
16363 * g_dbus_message_new_from_blob:
16364 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
16365 * @blob_len: The length of @blob.
16366 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
16367 * @error: Return location for error or %NULL.
16369 * Creates a new #GDBusMessage from the data stored at @blob. The byte
16370 * order that the message was in can be retrieved using
16371 * g_dbus_message_get_byte_order().
16373 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
16374 * g_object_unref().
16380 * g_dbus_message_new_method_call:
16381 * @name: (allow-none): A valid D-Bus name or %NULL.
16382 * @path: A valid object path.
16383 * @interface_: (allow-none): A valid D-Bus interface name or %NULL.
16384 * @method: A valid method name.
16386 * Creates a new #GDBusMessage for a method call.
16388 * Returns: A #GDBusMessage. Free with g_object_unref().
16394 * g_dbus_message_new_method_error:
16395 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16396 * create a reply message to.
16397 * @error_name: A valid D-Bus error name.
16398 * @error_message_format: The D-Bus error message in a printf() format.
16399 * @...: Arguments for @error_message_format.
16401 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
16403 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16409 * g_dbus_message_new_method_error_literal:
16410 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16411 * create a reply message to.
16412 * @error_name: A valid D-Bus error name.
16413 * @error_message: The D-Bus error message.
16415 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
16417 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16423 * g_dbus_message_new_method_error_valist:
16424 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16425 * create a reply message to.
16426 * @error_name: A valid D-Bus error name.
16427 * @error_message_format: The D-Bus error message in a printf() format.
16428 * @var_args: Arguments for @error_message_format.
16430 * Like g_dbus_message_new_method_error() but intended for language bindings.
16432 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
16438 * g_dbus_message_new_method_reply:
16439 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to
16440 * create a reply message to.
16442 * Creates a new #GDBusMessage that is a reply to @method_call_message.
16444 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
16450 * g_dbus_message_new_signal:
16451 * @path: A valid object path.
16452 * @interface_: A valid D-Bus interface name.
16453 * @signal: A valid signal name.
16455 * Creates a new #GDBusMessage for a signal emission.
16457 * Returns: A #GDBusMessage. Free with g_object_unref().
16463 * g_dbus_message_print:
16464 * @message: A #GDBusMessage.
16465 * @indent: Indentation level.
16467 * Produces a human-readable multi-line description of @message.
16469 * The contents of the description has no ABI guarantees, the contents
16470 * and formatting is subject to change at any time. Typical output
16471 * looks something like this:
16473 * Type: method-call
16474 * Flags: none
16478 * path -> objectpath '/org/gtk/GDBus/TestObject'
16479 * interface -> 'org.gtk.GDBus.TestInterface'
16480 * member -> 'GimmeStdout'
16481 * destination -> ':1.146'
16483 * UNIX File Descriptors:
16485 * </programlisting>
16488 * Type: method-return
16489 * Flags: no-reply-expected
16491 * Serial: 477
16493 * reply-serial -> uint32 4
16494 * destination -> ':1.159'
16495 * sender -> ':1.146'
16496 * num-unix-fds -> uint32 1
16498 * UNIX File Descriptors:
16499 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
16500 * </programlisting>
16502 * Returns: A string that should be freed with g_free().
16508 * g_dbus_message_set_body:
16509 * @message: A #GDBusMessage.
16510 * @body: Either %NULL or a #GVariant that is a tuple.
16512 * Sets the body @message. As a side-effect the
16513 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
16514 * type string of @body (or cleared if @body is %NULL).
16516 * If @body is floating, @message assumes ownership of @body.
16523 * g_dbus_message_set_byte_order:
16524 * @message: A #GDBusMessage.
16525 * @byte_order: The byte order.
16527 * Sets the byte order of @message.
16532 * g_dbus_message_set_destination:
16533 * @message: A #GDBusMessage.
16534 * @value: The value to set.
16536 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
16543 * g_dbus_message_set_error_name:
16544 * @message: A #GDBusMessage.
16545 * @value: The value to set.
16547 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
16554 * g_dbus_message_set_flags:
16555 * @message: A #GDBusMessage.
16556 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
16557 * enumeration bitwise ORed together).
16559 * Sets the flags to set on @message.
16566 * g_dbus_message_set_header:
16567 * @message: A #GDBusMessage.
16568 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
16569 * @value: (allow-none): A #GVariant to set the header field or %NULL to clear the header field.
16571 * Sets a header field on @message.
16573 * If @value is floating, @message assumes ownership of @value.
16580 * g_dbus_message_set_interface:
16581 * @message: A #GDBusMessage.
16582 * @value: The value to set.
16584 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
16591 * g_dbus_message_set_member:
16592 * @message: A #GDBusMessage.
16593 * @value: The value to set.
16595 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
16602 * g_dbus_message_set_message_type:
16603 * @message: A #GDBusMessage.
16604 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
16606 * Sets @message to be of @type.
16613 * g_dbus_message_set_num_unix_fds:
16614 * @message: A #GDBusMessage.
16615 * @value: The value to set.
16617 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
16624 * g_dbus_message_set_path:
16625 * @message: A #GDBusMessage.
16626 * @value: The value to set.
16628 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
16635 * g_dbus_message_set_reply_serial:
16636 * @message: A #GDBusMessage.
16637 * @value: The value to set.
16639 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
16646 * g_dbus_message_set_sender:
16647 * @message: A #GDBusMessage.
16648 * @value: The value to set.
16650 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
16657 * g_dbus_message_set_serial:
16658 * @message: A #GDBusMessage.
16659 * @serial: A #guint32.
16661 * Sets the serial for @message.
16668 * g_dbus_message_set_signature:
16669 * @message: A #GDBusMessage.
16670 * @value: The value to set.
16672 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
16679 * g_dbus_message_set_unix_fd_list:
16680 * @message: A #GDBusMessage.
16681 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
16683 * Sets the UNIX file descriptors associated with @message. As a
16684 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
16685 * field is set to the number of fds in @fd_list (or cleared if
16686 * @fd_list is %NULL).
16688 * This method is only available on UNIX.
16695 * g_dbus_message_to_blob:
16696 * @message: A #GDBusMessage.
16697 * @out_size: Return location for size of generated blob.
16698 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
16699 * @error: Return location for error.
16701 * Serializes @message to a blob. The byte order returned by
16702 * g_dbus_message_get_byte_order() will be used.
16704 * Returns: (array length=out_size) (transfer full): A pointer to a
16705 * valid binary D-Bus message of @out_size bytes generated by @message
16706 * or %NULL if @error is set. Free with g_free().
16712 * g_dbus_message_to_gerror:
16713 * @message: A #GDBusMessage.
16714 * @error: The #GError to set.
16716 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
16717 * nothing and returns %FALSE.
16719 * Otherwise this method encodes the error in @message as a #GError
16720 * using g_dbus_error_set_dbus_error() using the information in the
16721 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
16722 * well as the first string item in @message's body.
16724 * Returns: %TRUE if @error was set, %FALSE otherwise.
16730 * g_dbus_method_info_ref:
16731 * @info: A #GDBusMethodInfo
16733 * If @info is statically allocated does nothing. Otherwise increases
16734 * the reference count.
16736 * Returns: The same @info.
16742 * g_dbus_method_info_unref:
16743 * @info: A #GDBusMethodInfo.
16745 * If @info is statically allocated, does nothing. Otherwise decreases
16746 * the reference count of @info. When its reference count drops to 0,
16747 * the memory used is freed.
16754 * g_dbus_method_invocation_get_connection:
16755 * @invocation: A #GDBusMethodInvocation.
16757 * Gets the #GDBusConnection the method was invoked on.
16759 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
16765 * g_dbus_method_invocation_get_interface_name:
16766 * @invocation: A #GDBusMethodInvocation.
16768 * Gets the name of the D-Bus interface the method was invoked on.
16770 * If this method call is a property Get, Set or GetAll call that has
16771 * been redirected to the method call handler then
16772 * "org.freedesktop.DBus.Properties" will be returned. See
16773 * #GDBusInterfaceVTable for more information.
16775 * Returns: A string. Do not free, it is owned by @invocation.
16781 * g_dbus_method_invocation_get_message:
16782 * @invocation: A #GDBusMethodInvocation.
16784 * Gets the #GDBusMessage for the method invocation. This is useful if
16785 * you need to use low-level protocol features, such as UNIX file
16786 * descriptor passing, that cannot be properly expressed in the
16789 * See <xref linkend="gdbus-server"/> and <xref
16790 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
16791 * low-level API to send and receive UNIX file descriptors.
16793 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
16799 * g_dbus_method_invocation_get_method_info:
16800 * @invocation: A #GDBusMethodInvocation.
16802 * Gets information about the method call, if any.
16804 * If this method invocation is a property Get, Set or GetAll call that
16805 * has been redirected to the method call handler then %NULL will be
16806 * returned. See g_dbus_method_invocation_get_property_info() and
16807 * #GDBusInterfaceVTable for more information.
16809 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
16815 * g_dbus_method_invocation_get_method_name:
16816 * @invocation: A #GDBusMethodInvocation.
16818 * Gets the name of the method that was invoked.
16820 * Returns: A string. Do not free, it is owned by @invocation.
16826 * g_dbus_method_invocation_get_object_path:
16827 * @invocation: A #GDBusMethodInvocation.
16829 * Gets the object path the method was invoked on.
16831 * Returns: A string. Do not free, it is owned by @invocation.
16837 * g_dbus_method_invocation_get_parameters:
16838 * @invocation: A #GDBusMethodInvocation.
16840 * Gets the parameters of the method invocation. If there are no input
16841 * parameters then this will return a GVariant with 0 children rather than NULL.
16843 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
16849 * g_dbus_method_invocation_get_property_info:
16850 * @invocation: A #GDBusMethodInvocation
16852 * Gets information about the property that this method call is for, if
16855 * This will only be set in the case of an invocation in response to a
16856 * property Get or Set call that has been directed to the method call
16857 * handler for an object on account of its property_get() or
16858 * property_set() vtable pointers being unset.
16860 * See #GDBusInterfaceVTable for more information.
16862 * If the call was GetAll, %NULL will be returned.
16864 * Returns: (transfer none): a #GDBusPropertyInfo or %NULL
16870 * g_dbus_method_invocation_get_sender:
16871 * @invocation: A #GDBusMethodInvocation.
16873 * Gets the bus name that invoked the method.
16875 * Returns: A string. Do not free, it is owned by @invocation.
16881 * g_dbus_method_invocation_get_user_data: (skip)
16882 * @invocation: A #GDBusMethodInvocation.
16884 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
16886 * Returns: A #gpointer.
16892 * g_dbus_method_invocation_return_dbus_error:
16893 * @invocation: (transfer full): A #GDBusMethodInvocation.
16894 * @error_name: A valid D-Bus error name.
16895 * @error_message: A valid D-Bus error message.
16897 * Finishes handling a D-Bus method call by returning an error.
16899 * This method will free @invocation, you cannot use it afterwards.
16906 * g_dbus_method_invocation_return_error:
16907 * @invocation: (transfer full): A #GDBusMethodInvocation.
16908 * @domain: A #GQuark for the #GError error domain.
16909 * @code: The error code.
16910 * @format: printf()-style format.
16911 * @...: Parameters for @format.
16913 * Finishes handling a D-Bus method call by returning an error.
16915 * See g_dbus_error_encode_gerror() for details about what error name
16916 * will be returned on the wire. In a nutshell, if the given error is
16917 * registered using g_dbus_error_register_error() the name given
16918 * during registration is used. Otherwise, a name of the form
16919 * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
16920 * used. This provides transparent mapping of #GError between
16921 * applications using GDBus.
16923 * If you are writing an application intended to be portable,
16924 * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
16925 * or use g_dbus_method_invocation_return_dbus_error().
16927 * This method will free @invocation, you cannot use it afterwards.
16934 * g_dbus_method_invocation_return_error_literal:
16935 * @invocation: (transfer full): A #GDBusMethodInvocation.
16936 * @domain: A #GQuark for the #GError error domain.
16937 * @code: The error code.
16938 * @message: The error message.
16940 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
16942 * This method will free @invocation, you cannot use it afterwards.
16949 * g_dbus_method_invocation_return_error_valist:
16950 * @invocation: (transfer full): A #GDBusMethodInvocation.
16951 * @domain: A #GQuark for the #GError error domain.
16952 * @code: The error code.
16953 * @format: printf()-style format.
16954 * @var_args: #va_list of parameters for @format.
16956 * Like g_dbus_method_invocation_return_error() but intended for
16957 * language bindings.
16959 * This method will free @invocation, you cannot use it afterwards.
16966 * g_dbus_method_invocation_return_gerror:
16967 * @invocation: (transfer full): A #GDBusMethodInvocation.
16968 * @error: A #GError.
16970 * Like g_dbus_method_invocation_return_error() but takes a #GError
16971 * instead of the error domain, error code and message.
16973 * This method will free @invocation, you cannot use it afterwards.
16980 * g_dbus_method_invocation_return_value:
16981 * @invocation: (transfer full): A #GDBusMethodInvocation.
16982 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
16984 * Finishes handling a D-Bus method call by returning @parameters.
16985 * If the @parameters GVariant is floating, it is consumed.
16987 * It is an error if @parameters is not of the right format.
16989 * This method will free @invocation, you cannot use it afterwards.
16996 * g_dbus_method_invocation_return_value_with_unix_fd_list:
16997 * @invocation: (transfer full): A #GDBusMethodInvocation.
16998 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
16999 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17001 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
17003 * This method is only available on UNIX.
17005 * This method will free @invocation, you cannot use it afterwards.
17012 * g_dbus_method_invocation_take_error: (skip)
17013 * @invocation: (transfer full): A #GDBusMethodInvocation.
17014 * @error: (transfer full): A #GError.
17016 * Like g_dbus_method_invocation_return_gerror() but takes ownership
17017 * of @error so the caller does not need to free it.
17019 * This method will free @invocation, you cannot use it afterwards.
17026 * g_dbus_node_info_generate_xml:
17027 * @info: A #GDBusNodeInfo.
17028 * @indent: Indentation level.
17029 * @string_builder: (out): A #GString to to append XML data to.
17031 * Appends an XML representation of @info (and its children) to @string_builder.
17033 * This function is typically used for generating introspection XML documents at run-time for
17034 * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
17041 * g_dbus_node_info_lookup_interface:
17042 * @info: A #GDBusNodeInfo.
17043 * @name: A D-Bus interface name.
17045 * Looks up information about an interface.
17047 * The cost of this function is O(n) in number of interfaces.
17049 * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
17055 * g_dbus_node_info_new_for_xml:
17056 * @xml_data: Valid D-Bus introspection XML.
17057 * @error: Return location for error.
17059 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
17061 * The introspection XML must contain exactly one top-level
17062 * <tag class="starttag">node</tag> element.
17064 * Note that this routine is using a
17065 * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
17066 * parser that only accepts a subset of valid XML documents.
17068 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
17069 * with g_dbus_node_info_unref().
17075 * g_dbus_node_info_ref:
17076 * @info: A #GDBusNodeInfo
17078 * If @info is statically allocated does nothing. Otherwise increases
17079 * the reference count.
17081 * Returns: The same @info.
17087 * g_dbus_node_info_unref:
17088 * @info: A #GDBusNodeInfo.
17090 * If @info is statically allocated, does nothing. Otherwise decreases
17091 * the reference count of @info. When its reference count drops to 0,
17092 * the memory used is freed.
17099 * g_dbus_object_get_interface:
17100 * @object: A #GDBusObject.
17101 * @interface_name: A D-Bus interface name.
17103 * Gets the D-Bus interface with name @interface_name associated with
17106 * Returns: (transfer full): %NULL if not found, otherwise a
17107 * #GDBusInterface that must be freed with g_object_unref().
17113 * g_dbus_object_get_interfaces:
17114 * @object: A #GDBusObject.
17116 * Gets the D-Bus interfaces associated with @object.
17118 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
17119 * The returned list must be freed by g_list_free() after each element has been freed
17120 * with g_object_unref().
17126 * g_dbus_object_get_object_path:
17127 * @object: A #GDBusObject.
17129 * Gets the object path for @object.
17131 * Returns: A string owned by @object. Do not free.
17137 * g_dbus_object_manager_client_get_connection:
17138 * @manager: A #GDBusObjectManagerClient
17140 * Gets the #GDBusConnection used by @manager.
17142 * Returns: (transfer none): A #GDBusConnection object. Do not free,
17143 * the object belongs to @manager.
17149 * g_dbus_object_manager_client_get_flags:
17150 * @manager: A #GDBusObjectManagerClient
17152 * Gets the flags that @manager was constructed with.
17154 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
17161 * g_dbus_object_manager_client_get_name:
17162 * @manager: A #GDBusObjectManagerClient
17164 * Gets the name that @manager is for, or %NULL if not a message bus
17167 * Returns: A unique or well-known name. Do not free, the string
17168 * belongs to @manager.
17174 * g_dbus_object_manager_client_get_name_owner:
17175 * @manager: A #GDBusObjectManagerClient.
17177 * The unique name that owns the name that @manager is for or %NULL if
17178 * no-one currently owns that name. You can connect to the
17179 * #GObject::notify signal to track changes to the
17180 * #GDBusObjectManagerClient:name-owner property.
17182 * Returns: The name owner or %NULL if no name owner exists. Free with
17189 * g_dbus_object_manager_client_new:
17190 * @connection: A #GDBusConnection.
17191 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17192 * @name: The owner of the control object (unique or well-known name).
17193 * @object_path: The object path of the control object.
17194 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17195 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17196 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17197 * @cancellable: (allow-none): A #GCancellable or %NULL
17198 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
17199 * @user_data: The data to pass to @callback.
17201 * Asynchronously creates a new #GDBusObjectManagerClient object.
17203 * This is an asynchronous failable constructor. When the result is
17204 * ready, @callback will be invoked in the
17205 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
17206 * of the thread you are calling this method from. You can
17207 * then call g_dbus_object_manager_client_new_finish() to get the result. See
17208 * g_dbus_object_manager_client_new_sync() for the synchronous version.
17215 * g_dbus_object_manager_client_new_finish:
17216 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
17217 * @error: Return location for error or %NULL.
17219 * Finishes an operation started with g_dbus_object_manager_client_new().
17221 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17222 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17223 * with g_object_unref().
17229 * g_dbus_object_manager_client_new_for_bus:
17230 * @bus_type: A #GBusType.
17231 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17232 * @name: The owner of the control object (unique or well-known name).
17233 * @object_path: The object path of the control object.
17234 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17235 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17236 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17237 * @cancellable: (allow-none): A #GCancellable or %NULL
17238 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
17239 * @user_data: The data to pass to @callback.
17241 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
17242 * #GDBusConnection.
17244 * This is an asynchronous failable constructor. When the result is
17245 * ready, @callback will be invoked in the
17246 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
17247 * of the thread you are calling this method from. You can
17248 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
17249 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
17256 * g_dbus_object_manager_client_new_for_bus_finish:
17257 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
17258 * @error: Return location for error or %NULL.
17260 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
17262 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17263 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17264 * with g_object_unref().
17270 * g_dbus_object_manager_client_new_for_bus_sync:
17271 * @bus_type: A #GBusType.
17272 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17273 * @name: The owner of the control object (unique or well-known name).
17274 * @object_path: The object path of the control object.
17275 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17276 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17277 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17278 * @cancellable: (allow-none): A #GCancellable or %NULL
17279 * @error: Return location for error or %NULL.
17281 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
17282 * of a #GDBusConnection.
17284 * This is a synchronous failable constructor - the calling thread is
17285 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
17286 * for the asynchronous version.
17288 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17289 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17290 * with g_object_unref().
17296 * g_dbus_object_manager_client_new_sync:
17297 * @connection: A #GDBusConnection.
17298 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
17299 * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
17300 * @object_path: The object path of the control object.
17301 * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
17302 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
17303 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
17304 * @cancellable: (allow-none): A #GCancellable or %NULL
17305 * @error: Return location for error or %NULL.
17307 * Creates a new #GDBusObjectManagerClient object.
17309 * This is a synchronous failable constructor - the calling thread is
17310 * blocked until a reply is received. See g_dbus_object_manager_client_new()
17311 * for the asynchronous version.
17313 * Returns: (transfer full) (type GDBusObjectManagerClient): A
17314 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
17315 * with g_object_unref().
17321 * g_dbus_object_manager_get_interface:
17322 * @manager: A #GDBusObjectManager.
17323 * @object_path: Object path to lookup.
17324 * @interface_name: D-Bus interface name to lookup.
17326 * Gets the interface proxy for @interface_name at @object_path, if
17329 * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
17330 * with g_object_unref().
17336 * g_dbus_object_manager_get_object:
17337 * @manager: A #GDBusObjectManager.
17338 * @object_path: Object path to lookup.
17340 * Gets the #GDBusObjectProxy at @object_path, if any.
17342 * Returns: (transfer full): A #GDBusObject or %NULL. Free with
17343 * g_object_unref().
17349 * g_dbus_object_manager_get_object_path:
17350 * @manager: A #GDBusObjectManager.
17352 * Gets the object path that @manager is for.
17354 * Returns: A string owned by @manager. Do not free.
17360 * g_dbus_object_manager_get_objects:
17361 * @manager: A #GDBusObjectManager.
17363 * Gets all #GDBusObject objects known to @manager.
17365 * Returns: (transfer full) (element-type GDBusObject): A list of
17366 * #GDBusObject objects. The returned list should be freed with
17367 * g_list_free() after each element has been freed with
17368 * g_object_unref().
17374 * g_dbus_object_manager_server_export:
17375 * @manager: A #GDBusObjectManagerServer.
17376 * @object: A #GDBusObjectSkeleton.
17378 * Exports @object on @manager.
17380 * If there is already a #GDBusObject exported at the object path,
17381 * then the old object is removed.
17383 * The object path for @object must be in the hierarchy rooted by the
17384 * object path for @manager.
17386 * Note that @manager will take a reference on @object for as long as
17394 * g_dbus_object_manager_server_export_uniquely:
17395 * @manager: A #GDBusObjectManagerServer.
17396 * @object: An object.
17398 * Like g_dbus_object_manager_server_export() but appends a string of
17399 * the form <literal>_N</literal> (with N being a natural number) to
17400 * @object<!-- -->'s object path if an object with the given path
17401 * already exists. As such, the #GDBusObjectProxy:g-object-path property
17402 * of @object may be modified.
17409 * g_dbus_object_manager_server_get_connection:
17410 * @manager: A #GDBusObjectManagerServer
17412 * Gets the #GDBusConnection used by @manager.
17414 * Returns: (transfer full): A #GDBusConnection object or %NULL if
17415 * @manager isn't exported on a connection. The returned object should
17416 * be freed with g_object_unref().
17422 * g_dbus_object_manager_server_is_exported:
17423 * @manager: A #GDBusObjectManagerServer.
17424 * @object: An object.
17426 * Returns whether @object is currently exported on @manager.
17428 * Returns: %TRUE if @object is exported
17434 * g_dbus_object_manager_server_new:
17435 * @object_path: The object path to export the manager object at.
17437 * Creates a new #GDBusObjectManagerServer object.
17439 * The returned server isn't yet exported on any connection. To do so,
17440 * use g_dbus_object_manager_server_set_connection(). Normally you
17441 * want to export all of your objects before doing so to avoid <ulink
17442 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
17443 * signals being emitted.
17445 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
17451 * g_dbus_object_manager_server_set_connection:
17452 * @manager: A #GDBusObjectManagerServer.
17453 * @connection: (allow-none): A #GDBusConnection or %NULL.
17455 * Exports all objects managed by @manager on @connection. If
17456 * @connection is %NULL, stops exporting objects.
17461 * g_dbus_object_manager_server_unexport:
17462 * @manager: A #GDBusObjectManagerServer.
17463 * @object_path: An object path.
17465 * If @manager has an object at @path, removes the object. Otherwise
17468 * Note that @object_path must be in the hierarchy rooted by the
17469 * object path for @manager.
17471 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
17477 * g_dbus_object_proxy_get_connection:
17478 * @proxy: a #GDBusObjectProxy
17480 * Gets the connection that @proxy is for.
17482 * Returns: (transfer none): A #GDBusConnection. Do not free, the
17483 * object is owned by @proxy.
17489 * g_dbus_object_proxy_new:
17490 * @connection: a #GDBusConnection
17491 * @object_path: the object path
17493 * Creates a new #GDBusObjectProxy for the given connection and
17496 * Returns: a new #GDBusObjectProxy
17502 * g_dbus_object_skeleton_add_interface:
17503 * @object: A #GDBusObjectSkeleton.
17504 * @interface_: A #GDBusInterfaceSkeleton.
17506 * Adds @interface_ to @object.
17508 * If @object already contains a #GDBusInterfaceSkeleton with the same
17509 * interface name, it is removed before @interface_ is added.
17511 * Note that @object takes its own reference on @interface_ and holds
17512 * it until removed.
17519 * g_dbus_object_skeleton_flush:
17520 * @object: A #GDBusObjectSkeleton.
17522 * This method simply calls g_dbus_interface_skeleton_flush() on all
17523 * interfaces belonging to @object. See that method for when flushing
17531 * g_dbus_object_skeleton_new:
17532 * @object_path: An object path.
17534 * Creates a new #GDBusObjectSkeleton.
17536 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
17542 * g_dbus_object_skeleton_remove_interface:
17543 * @object: A #GDBusObjectSkeleton.
17544 * @interface_: A #GDBusInterfaceSkeleton.
17546 * Removes @interface_ from @object.
17553 * g_dbus_object_skeleton_remove_interface_by_name:
17554 * @object: A #GDBusObjectSkeleton.
17555 * @interface_name: A D-Bus interface name.
17557 * Removes the #GDBusInterface with @interface_name from @object.
17559 * If no D-Bus interface of the given interface exists, this function
17567 * g_dbus_object_skeleton_set_object_path:
17568 * @object: A #GDBusObjectSkeleton.
17569 * @object_path: A valid D-Bus object path.
17571 * Sets the object path for @object.
17578 * g_dbus_property_info_ref:
17579 * @info: A #GDBusPropertyInfo
17581 * If @info is statically allocated does nothing. Otherwise increases
17582 * the reference count.
17584 * Returns: The same @info.
17590 * g_dbus_property_info_unref:
17591 * @info: A #GDBusPropertyInfo.
17593 * If @info is statically allocated, does nothing. Otherwise decreases
17594 * the reference count of @info. When its reference count drops to 0,
17595 * the memory used is freed.
17602 * g_dbus_proxy_call:
17603 * @proxy: A #GDBusProxy.
17604 * @method_name: Name of method to invoke.
17605 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
17606 * @flags: Flags from the #GDBusCallFlags enumeration.
17607 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17608 * "infinite") or -1 to use the proxy default timeout.
17609 * @cancellable: (allow-none): A #GCancellable or %NULL.
17610 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
17611 * care about the result of the method invocation.
17612 * @user_data: The data to pass to @callback.
17614 * Asynchronously invokes the @method_name method on @proxy.
17616 * If @method_name contains any dots, then @name is split into interface and
17617 * method name parts. This allows using @proxy for invoking methods on
17618 * other interfaces.
17620 * If the #GDBusConnection associated with @proxy is closed then
17621 * the operation will fail with %G_IO_ERROR_CLOSED. If
17622 * @cancellable is canceled, the operation will fail with
17623 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
17624 * compatible with the D-Bus protocol, the operation fails with
17625 * %G_IO_ERROR_INVALID_ARGUMENT.
17627 * If the @parameters #GVariant is floating, it is consumed. This allows
17628 * convenient 'inline' use of g_variant_new(), e.g.:
17630 * g_dbus_proxy_call (proxy,
17632 * g_variant_new ("(ss)",
17635 * G_DBUS_CALL_FLAGS_NONE,
17638 * (GAsyncReadyCallback) two_strings_done,
17642 * If @proxy has an expected interface (see
17643 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
17644 * then the return value is checked against the return type.
17646 * This is an asynchronous method. When the operation is finished,
17647 * @callback will be invoked in the
17648 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
17649 * of the thread you are calling this method from.
17650 * You can then call g_dbus_proxy_call_finish() to get the result of
17651 * the operation. See g_dbus_proxy_call_sync() for the synchronous
17652 * version of this method.
17654 * If @callback is %NULL then the D-Bus method call message will be sent with
17655 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
17662 * g_dbus_proxy_call_finish:
17663 * @proxy: A #GDBusProxy.
17664 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
17665 * @error: Return location for error or %NULL.
17667 * Finishes an operation started with g_dbus_proxy_call().
17669 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17670 * return values. Free with g_variant_unref().
17676 * g_dbus_proxy_call_sync:
17677 * @proxy: A #GDBusProxy.
17678 * @method_name: Name of method to invoke.
17679 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
17680 * or %NULL if not passing parameters.
17681 * @flags: Flags from the #GDBusCallFlags enumeration.
17682 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17683 * "infinite") or -1 to use the proxy default timeout.
17684 * @cancellable: (allow-none): A #GCancellable or %NULL.
17685 * @error: Return location for error or %NULL.
17687 * Synchronously invokes the @method_name method on @proxy.
17689 * If @method_name contains any dots, then @name is split into interface and
17690 * method name parts. This allows using @proxy for invoking methods on
17691 * other interfaces.
17693 * If the #GDBusConnection associated with @proxy is disconnected then
17694 * the operation will fail with %G_IO_ERROR_CLOSED. If
17695 * @cancellable is canceled, the operation will fail with
17696 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
17697 * compatible with the D-Bus protocol, the operation fails with
17698 * %G_IO_ERROR_INVALID_ARGUMENT.
17700 * If the @parameters #GVariant is floating, it is consumed. This allows
17701 * convenient 'inline' use of g_variant_new(), e.g.:
17703 * g_dbus_proxy_call_sync (proxy,
17705 * g_variant_new ("(ss)",
17708 * G_DBUS_CALL_FLAGS_NONE,
17714 * The calling thread is blocked until a reply is received. See
17715 * g_dbus_proxy_call() for the asynchronous version of this
17718 * If @proxy has an expected interface (see
17719 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
17720 * then the return value is checked against the return type.
17722 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17723 * return values. Free with g_variant_unref().
17729 * g_dbus_proxy_call_with_unix_fd_list:
17730 * @proxy: A #GDBusProxy.
17731 * @method_name: Name of method to invoke.
17732 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
17733 * @flags: Flags from the #GDBusCallFlags enumeration.
17734 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17735 * "infinite") or -1 to use the proxy default timeout.
17736 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17737 * @cancellable: (allow-none): A #GCancellable or %NULL.
17738 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't
17739 * care about the result of the method invocation.
17740 * @user_data: The data to pass to @callback.
17742 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
17744 * This method is only available on UNIX.
17751 * g_dbus_proxy_call_with_unix_fd_list_finish:
17752 * @proxy: A #GDBusProxy.
17753 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
17754 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
17755 * @error: Return location for error or %NULL.
17757 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
17759 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17760 * return values. Free with g_variant_unref().
17766 * g_dbus_proxy_call_with_unix_fd_list_sync:
17767 * @proxy: A #GDBusProxy.
17768 * @method_name: Name of method to invoke.
17769 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
17770 * or %NULL if not passing parameters.
17771 * @flags: Flags from the #GDBusCallFlags enumeration.
17772 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning
17773 * "infinite") or -1 to use the proxy default timeout.
17774 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
17775 * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
17776 * @cancellable: (allow-none): A #GCancellable or %NULL.
17777 * @error: Return location for error or %NULL.
17779 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
17781 * This method is only available on UNIX.
17783 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
17784 * return values. Free with g_variant_unref().
17790 * g_dbus_proxy_get_cached_property:
17791 * @proxy: A #GDBusProxy.
17792 * @property_name: Property name.
17794 * Looks up the value for a property from the cache. This call does no
17797 * If @proxy has an expected interface (see
17798 * #GDBusProxy:g-interface-info) and @property_name is referenced by
17799 * it, then @value is checked against the type of the property.
17801 * Returns: A reference to the #GVariant instance that holds the value
17802 * for @property_name or %NULL if the value is not in the cache. The
17803 * returned reference must be freed with g_variant_unref().
17809 * g_dbus_proxy_get_cached_property_names:
17810 * @proxy: A #GDBusProxy.
17812 * Gets the names of all cached properties on @proxy.
17814 * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
17815 * @proxy has no cached properties. Free the returned array with
17822 * g_dbus_proxy_get_connection:
17823 * @proxy: A #GDBusProxy.
17825 * Gets the connection @proxy is for.
17827 * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
17833 * g_dbus_proxy_get_default_timeout:
17834 * @proxy: A #GDBusProxy.
17836 * Gets the timeout to use if -1 (specifying default timeout) is
17837 * passed as @timeout_msec in the g_dbus_proxy_call() and
17838 * g_dbus_proxy_call_sync() functions.
17840 * See the #GDBusProxy:g-default-timeout property for more details.
17842 * Returns: Timeout to use for @proxy.
17848 * g_dbus_proxy_get_flags:
17849 * @proxy: A #GDBusProxy.
17851 * Gets the flags that @proxy was constructed with.
17853 * Returns: Flags from the #GDBusProxyFlags enumeration.
17859 * g_dbus_proxy_get_interface_info:
17860 * @proxy: A #GDBusProxy
17862 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
17863 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
17864 * property for more details.
17866 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
17867 * object, it is owned by @proxy.
17873 * g_dbus_proxy_get_interface_name:
17874 * @proxy: A #GDBusProxy.
17876 * Gets the D-Bus interface name @proxy is for.
17878 * Returns: A string owned by @proxy. Do not free.
17884 * g_dbus_proxy_get_name:
17885 * @proxy: A #GDBusProxy.
17887 * Gets the name that @proxy was constructed for.
17889 * Returns: A string owned by @proxy. Do not free.
17895 * g_dbus_proxy_get_name_owner:
17896 * @proxy: A #GDBusProxy.
17898 * The unique name that owns the name that @proxy is for or %NULL if
17899 * no-one currently owns that name. You may connect to the
17900 * #GObject::notify signal to track changes to the
17901 * #GDBusProxy:g-name-owner property.
17903 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
17909 * g_dbus_proxy_get_object_path:
17910 * @proxy: A #GDBusProxy.
17912 * Gets the object path @proxy is for.
17914 * Returns: A string owned by @proxy. Do not free.
17920 * g_dbus_proxy_new:
17921 * @connection: A #GDBusConnection.
17922 * @flags: Flags used when constructing the proxy.
17923 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
17924 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
17925 * @object_path: An object path.
17926 * @interface_name: A D-Bus interface name.
17927 * @cancellable: (allow-none): A #GCancellable or %NULL.
17928 * @callback: Callback function to invoke when the proxy is ready.
17929 * @user_data: User data to pass to @callback.
17931 * Creates a proxy for accessing @interface_name on the remote object
17932 * at @object_path owned by @name at @connection and asynchronously
17933 * loads D-Bus properties unless the
17934 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
17935 * the #GDBusProxy::g-properties-changed signal to get notified about
17936 * property changes.
17938 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
17939 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
17940 * to handle signals from the remote object.
17942 * If @name is a well-known name and the
17943 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
17944 * flags aren't set and no name owner currently exists, the message bus
17945 * will be requested to launch a name owner for the name.
17947 * This is a failable asynchronous constructor - when the proxy is
17948 * ready, @callback will be invoked and you can use
17949 * g_dbus_proxy_new_finish() to get the result.
17951 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
17953 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
17960 * g_dbus_proxy_new_finish:
17961 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
17962 * @error: Return location for error or %NULL.
17964 * Finishes creating a #GDBusProxy.
17966 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
17972 * g_dbus_proxy_new_for_bus:
17973 * @bus_type: A #GBusType.
17974 * @flags: Flags used when constructing the proxy.
17975 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
17976 * @name: A bus name (well-known or unique).
17977 * @object_path: An object path.
17978 * @interface_name: A D-Bus interface name.
17979 * @cancellable: (allow-none): A #GCancellable or %NULL.
17980 * @callback: Callback function to invoke when the proxy is ready.
17981 * @user_data: User data to pass to @callback.
17983 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
17985 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
17992 * g_dbus_proxy_new_for_bus_finish:
17993 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
17994 * @error: Return location for error or %NULL.
17996 * Finishes creating a #GDBusProxy.
17998 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
18004 * g_dbus_proxy_new_for_bus_sync:
18005 * @bus_type: A #GBusType.
18006 * @flags: Flags used when constructing the proxy.
18007 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface
18008 * that @proxy conforms to or %NULL.
18009 * @name: A bus name (well-known or unique).
18010 * @object_path: An object path.
18011 * @interface_name: A D-Bus interface name.
18012 * @cancellable: (allow-none): A #GCancellable or %NULL.
18013 * @error: Return location for error or %NULL.
18015 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
18017 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
18019 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
18025 * g_dbus_proxy_new_sync:
18026 * @connection: A #GDBusConnection.
18027 * @flags: Flags used when constructing the proxy.
18028 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
18029 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
18030 * @object_path: An object path.
18031 * @interface_name: A D-Bus interface name.
18032 * @cancellable: (allow-none): A #GCancellable or %NULL.
18033 * @error: (allow-none): Return location for error or %NULL.
18035 * Creates a proxy for accessing @interface_name on the remote object
18036 * at @object_path owned by @name at @connection and synchronously
18037 * loads D-Bus properties unless the
18038 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
18040 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
18041 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
18042 * to handle signals from the remote object.
18044 * If @name is a well-known name and the
18045 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
18046 * flags aren't set and no name owner currently exists, the message bus
18047 * will be requested to launch a name owner for the name.
18049 * This is a synchronous failable constructor. See g_dbus_proxy_new()
18050 * and g_dbus_proxy_new_finish() for the asynchronous version.
18052 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
18054 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
18060 * g_dbus_proxy_set_cached_property:
18061 * @proxy: A #GDBusProxy
18062 * @property_name: Property name.
18063 * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
18065 * If @value is not %NULL, sets the cached value for the property with
18066 * name @property_name to the value in @value.
18068 * If @value is %NULL, then the cached value is removed from the
18071 * If @proxy has an expected interface (see
18072 * #GDBusProxy:g-interface-info) and @property_name is referenced by
18073 * it, then @value is checked against the type of the property.
18075 * If the @value #GVariant is floating, it is consumed. This allows
18076 * convenient 'inline' use of g_variant_new(), e.g.
18078 * g_dbus_proxy_set_cached_property (proxy,
18080 * g_variant_new ("(si)",
18085 * Normally you will not need to use this method since @proxy is
18086 * tracking changes using the
18087 * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
18088 * D-Bus signal. However, for performance reasons an object may decide
18089 * to not use this signal for some properties and instead use a
18090 * proprietary out-of-band mechanism to transmit changes.
18092 * As a concrete example, consider an object with a property
18093 * <literal>ChatroomParticipants</literal> which is an array of
18094 * strings. Instead of transmitting the same (long) array every time
18095 * the property changes, it is more efficient to only transmit the
18096 * delta using e.g. signals <literal>ChatroomParticipantJoined(String
18097 * name)</literal> and <literal>ChatroomParticipantParted(String
18105 * g_dbus_proxy_set_default_timeout:
18106 * @proxy: A #GDBusProxy.
18107 * @timeout_msec: Timeout in milliseconds.
18109 * Sets the timeout to use if -1 (specifying default timeout) is
18110 * passed as @timeout_msec in the g_dbus_proxy_call() and
18111 * g_dbus_proxy_call_sync() functions.
18113 * See the #GDBusProxy:g-default-timeout property for more details.
18120 * g_dbus_proxy_set_interface_info:
18121 * @proxy: A #GDBusProxy
18122 * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
18124 * Ensure that interactions with @proxy conform to the given
18125 * interface. See the #GDBusProxy:g-interface-info property for more
18133 * g_dbus_server_get_client_address:
18134 * @server: A #GDBusServer.
18136 * Gets a D-Bus address string that can be used by clients to connect
18139 * Returns: A D-Bus address string. Do not free, the string is owned
18146 * g_dbus_server_get_flags:
18147 * @server: A #GDBusServer.
18149 * Gets the flags for @server.
18151 * Returns: A set of flags from the #GDBusServerFlags enumeration.
18157 * g_dbus_server_get_guid:
18158 * @server: A #GDBusServer.
18160 * Gets the GUID for @server.
18162 * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
18168 * g_dbus_server_is_active:
18169 * @server: A #GDBusServer.
18171 * Gets whether @server is active.
18173 * Returns: %TRUE if server is active, %FALSE otherwise.
18179 * g_dbus_server_new_sync:
18180 * @address: A D-Bus address.
18181 * @flags: Flags from the #GDBusServerFlags enumeration.
18182 * @guid: A D-Bus GUID.
18183 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
18184 * @cancellable: (allow-none): A #GCancellable or %NULL.
18185 * @error: Return location for server or %NULL.
18187 * Creates a new D-Bus server that listens on the first address in
18188 * @address that works.
18190 * Once constructed, you can use g_dbus_server_get_client_address() to
18191 * get a D-Bus address string that clients can use to connect.
18193 * Connect to the #GDBusServer::new-connection signal to handle
18194 * incoming connections.
18196 * The returned #GDBusServer isn't active - you have to start it with
18197 * g_dbus_server_start().
18199 * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
18202 * This is a synchronous failable constructor. See
18203 * g_dbus_server_new() for the asynchronous version.
18205 * Returns: A #GDBusServer or %NULL if @error is set. Free with
18206 * g_object_unref().
18212 * g_dbus_server_start:
18213 * @server: A #GDBusServer.
18222 * g_dbus_server_stop:
18223 * @server: A #GDBusServer.
18232 * g_dbus_signal_info_ref:
18233 * @info: A #GDBusSignalInfo
18235 * If @info is statically allocated does nothing. Otherwise increases
18236 * the reference count.
18238 * Returns: The same @info.
18244 * g_dbus_signal_info_unref:
18245 * @info: A #GDBusSignalInfo.
18247 * If @info is statically allocated, does nothing. Otherwise decreases
18248 * the reference count of @info. When its reference count drops to 0,
18249 * the memory used is freed.
18256 * g_desktop_app_info_get_action_name:
18257 * @info: a #GDesktopAppInfo
18258 * @action_name: the name of the action as from
18259 * g_desktop_app_info_list_actions()
18261 * Gets the user-visible display name of the "additional application
18262 * action" specified by @action_name.
18264 * This corresponds to the "Name" key within the keyfile group for the
18267 * Returns: (transfer full): the locale-specific action name
18273 * g_desktop_app_info_get_boolean:
18274 * @info: a #GDesktopAppInfo
18275 * @key: the key to look up
18277 * Looks up a boolean value in the keyfile backing @info.
18279 * The @key is looked up in the "Desktop Entry" group.
18281 * Returns: the boolean value, or %FALSE if the key
18288 * g_desktop_app_info_get_categories:
18289 * @info: a #GDesktopAppInfo
18291 * Gets the categories from the desktop file.
18293 * Returns: The unparsed Categories key from the desktop file;
18294 * i.e. no attempt is made to split it by ';' or validate it.
18299 * g_desktop_app_info_get_filename:
18300 * @info: a #GDesktopAppInfo
18302 * When @info was created from a known filename, return it. In some
18303 * situations such as the #GDesktopAppInfo returned from
18304 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
18306 * Returns: The full path to the file for @info, or %NULL if not known.
18312 * g_desktop_app_info_get_generic_name:
18313 * @info: a #GDesktopAppInfo
18315 * Gets the generic name from the destkop file.
18317 * Returns: The value of the GenericName key
18322 * g_desktop_app_info_get_is_hidden:
18323 * @info: a #GDesktopAppInfo.
18325 * A desktop file is hidden if the Hidden key in it is
18328 * Returns: %TRUE if hidden, %FALSE otherwise.
18333 * g_desktop_app_info_get_keywords:
18334 * @info: a #GDesktopAppInfo
18336 * Gets the keywords from the desktop file.
18338 * Returns: (transfer none): The value of the Keywords key
18344 * g_desktop_app_info_get_nodisplay:
18345 * @info: a #GDesktopAppInfo
18347 * Gets the value of the NoDisplay key, which helps determine if the
18348 * application info should be shown in menus. See
18349 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
18351 * Returns: The value of the NoDisplay key
18357 * g_desktop_app_info_get_show_in:
18358 * @info: a #GDesktopAppInfo
18359 * @desktop_env: a string specifying a desktop name
18361 * Checks if the application info should be shown in menus that list available
18362 * applications for a specific name of the desktop, based on the
18363 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys.
18365 * If @desktop_env is %NULL, then the name of the desktop set with
18366 * g_desktop_app_info_set_desktop_env() is used.
18368 * Note that g_app_info_should_show() for @info will include this check (with
18369 * %NULL for @desktop_env) as well as additional checks.
18371 * Returns: %TRUE if the @info should be shown in @desktop_env according to the
18372 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
18379 * g_desktop_app_info_get_startup_wm_class:
18380 * @info: a #GDesktopAppInfo that supports startup notify
18382 * Retrieves the StartupWMClass field from @info. This represents the
18383 * WM_CLASS property of the main window of the application, if launched
18386 * Returns: (transfer none): the startup WM class, or %NULL if none is set
18387 * in the desktop file.
18393 * g_desktop_app_info_get_string:
18394 * @info: a #GDesktopAppInfo
18395 * @key: the key to look up
18397 * Looks up a string value in the keyfile backing @info.
18399 * The @key is looked up in the "Desktop Entry" group.
18401 * Returns: a newly allocated string, or %NULL if the key
18408 * g_desktop_app_info_has_key:
18409 * @info: a #GDesktopAppInfo
18410 * @key: the key to look up
18412 * Returns whether @key exists in the "Desktop Entry" group
18413 * of the keyfile backing @info.
18415 * Returns: %TRUE if the @key exists
18421 * g_desktop_app_info_launch_action:
18422 * @info: a #GDesktopAppInfo
18423 * @action_name: the name of the action as from
18424 * g_desktop_app_info_list_actions()
18425 * @launch_context: (allow-none): a #GAppLaunchContext
18427 * Activates the named application action.
18429 * You may only call this function on action names that were
18430 * returned from g_desktop_app_info_list_actions().
18432 * Note that if the main entry of the desktop file indicates that the
18433 * application supports startup notification, and @launch_context is
18434 * non-%NULL, then startup notification will be used when activating the
18435 * action (and as such, invocation of the action on the receiving side
18436 * must signal the end of startup notification when it is completed).
18437 * This is the expected behaviour of applications declaring additional
18438 * actions, as per the desktop file specification.
18440 * As with g_app_info_launch() there is no way to detect failures that
18441 * occur while using this function.
18448 * g_desktop_app_info_launch_uris_as_manager:
18449 * @appinfo: a #GDesktopAppInfo
18450 * @uris: (element-type utf8): List of URIs
18451 * @launch_context: a #GAppLaunchContext
18452 * @spawn_flags: #GSpawnFlags, used for each process
18453 * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for
18455 * @user_setup_data: (closure user_setup): User data for @user_setup
18456 * @pid_callback: (scope call): Callback for child processes
18457 * @pid_callback_data: (closure pid_callback): User data for @callback
18458 * @error: return location for a #GError, or %NULL
18460 * This function performs the equivalent of g_app_info_launch_uris(),
18461 * but is intended primarily for operating system components that
18462 * launch applications. Ordinary applications should use
18463 * g_app_info_launch_uris().
18465 * If the application is launched via traditional UNIX fork()/exec()
18466 * then @spawn_flags, @user_setup and @user_setup_data are used for the
18467 * call to g_spawn_async(). Additionally, @pid_callback (with
18468 * @pid_callback_data) will be called to inform about the PID of the
18471 * If application launching occurs via some other mechanism (eg: D-Bus
18472 * activation) then @spawn_flags, @user_setup, @user_setup_data,
18473 * @pid_callback and @pid_callback_data are ignored.
18475 * Returns: %TRUE on successful launch, %FALSE otherwise.
18480 * g_desktop_app_info_list_actions:
18481 * @info: a #GDesktopAppInfo
18483 * Returns the list of "additional application actions" supported on the
18484 * desktop file, as per the desktop file specification.
18486 * As per the specification, this is the list of actions that are
18487 * explicitly listed in the "Actions" key of the [Desktop Entry] group.
18489 * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL
18495 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
18496 * @lookup: a #GDesktopAppInfoLookup
18497 * @uri_scheme: a string containing a URI scheme.
18499 * Gets the default application for launching applications
18500 * using this URI scheme for a particular GDesktopAppInfoLookup
18503 * The GDesktopAppInfoLookup interface and this function is used
18504 * to implement g_app_info_get_default_for_uri_scheme() backends
18505 * in a GIO module. There is no reason for applications to use it
18506 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
18508 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
18509 * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
18514 * g_desktop_app_info_new:
18515 * @desktop_id: the desktop file id
18517 * Creates a new #GDesktopAppInfo based on a desktop file id.
18519 * A desktop file id is the basename of the desktop file, including the
18520 * .desktop extension. GIO is looking for a desktop file with this name
18521 * in the <filename>applications</filename> subdirectories of the XDG data
18522 * directories (i.e. the directories specified in the
18523 * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment
18524 * variables). GIO also supports the prefix-to-subdirectory mapping that is
18525 * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink>
18526 * (i.e. a desktop id of kde-foo.desktop will match
18527 * <filename>/usr/share/applications/kde/foo.desktop</filename>).
18529 * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
18534 * g_desktop_app_info_new_from_filename:
18535 * @filename: the path of a desktop file, in the GLib filename encoding
18537 * Creates a new #GDesktopAppInfo.
18539 * Returns: a new #GDesktopAppInfo or %NULL on error.
18544 * g_desktop_app_info_new_from_keyfile:
18545 * @key_file: an opened #GKeyFile
18547 * Creates a new #GDesktopAppInfo.
18549 * Returns: a new #GDesktopAppInfo or %NULL on error.
18555 * g_desktop_app_info_search:
18556 * @search_string: the search string to use
18558 * Searches desktop files for ones that match @search_string.
18560 * The return value is an array of strvs. Each strv contains a list of
18561 * applications that matched @search_string with an equal score. The
18562 * outer list is sorted by score so that the first strv contains the
18563 * best-matching applications, and so on.
18565 * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a
18566 * list of strvs. Free each item with g_strfreev() and free the outer
18567 * list with g_free().
18572 * g_desktop_app_info_set_desktop_env:
18573 * @desktop_env: a string specifying what desktop this is
18575 * Sets the name of the desktop that the application is running in.
18576 * This is used by g_app_info_should_show() and
18577 * g_desktop_app_info_get_show_in() to evaluate the
18578 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
18579 * desktop entry fields.
18581 * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop
18582 * Menu specification</ulink> recognizes the following:
18584 * <member>GNOME</member>
18585 * <member>KDE</member>
18586 * <member>ROX</member>
18587 * <member>XFCE</member>
18588 * <member>LXDE</member>
18589 * <member>Unity</member>
18590 * <member>Old</member>
18593 * Should be called only once; subsequent calls are ignored.
18598 * g_drive_can_eject:
18599 * @drive: a #GDrive.
18601 * Checks if a drive can be ejected.
18603 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
18608 * g_drive_can_poll_for_media:
18609 * @drive: a #GDrive.
18611 * Checks if a drive can be polled for media changes.
18613 * Returns: %TRUE if the @drive can be polled for media changes,
18614 * %FALSE otherwise.
18619 * g_drive_can_start:
18620 * @drive: a #GDrive.
18622 * Checks if a drive can be started.
18624 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
18630 * g_drive_can_start_degraded:
18631 * @drive: a #GDrive.
18633 * Checks if a drive can be started degraded.
18635 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
18641 * g_drive_can_stop:
18642 * @drive: a #GDrive.
18644 * Checks if a drive can be stopped.
18646 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
18653 * @drive: a #GDrive.
18654 * @flags: flags affecting the unmount if required for eject
18655 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18656 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18657 * @user_data: user data to pass to @callback
18659 * Asynchronously ejects a drive.
18661 * When the operation is finished, @callback will be called.
18662 * You can then call g_drive_eject_finish() to obtain the
18663 * result of the operation.
18665 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
18670 * g_drive_eject_finish:
18671 * @drive: a #GDrive.
18672 * @result: a #GAsyncResult.
18673 * @error: a #GError, or %NULL
18675 * Finishes ejecting a drive.
18677 * Returns: %TRUE if the drive has been ejected successfully,
18678 * %FALSE otherwise.
18679 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
18684 * g_drive_eject_with_operation:
18685 * @drive: a #GDrive.
18686 * @flags: flags affecting the unmount if required for eject
18687 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
18688 * user interaction.
18689 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18690 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18691 * @user_data: user data passed to @callback.
18693 * Ejects a drive. This is an asynchronous operation, and is
18694 * finished by calling g_drive_eject_with_operation_finish() with the @drive
18695 * and #GAsyncResult data returned in the @callback.
18702 * g_drive_eject_with_operation_finish:
18703 * @drive: a #GDrive.
18704 * @result: a #GAsyncResult.
18705 * @error: a #GError location to store the error occurring, or %NULL to
18708 * Finishes ejecting a drive. If any errors occurred during the operation,
18709 * @error will be set to contain the errors and %FALSE will be returned.
18711 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
18717 * g_drive_enumerate_identifiers:
18718 * @drive: a #GDrive
18720 * Gets the kinds of identifiers that @drive has.
18721 * Use g_drive_get_identifier() to obtain the identifiers
18724 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
18725 * array of strings containing kinds of identifiers. Use g_strfreev()
18731 * g_drive_get_icon:
18732 * @drive: a #GDrive.
18734 * Gets the icon for @drive.
18736 * Returns: (transfer full): #GIcon for the @drive.
18737 * Free the returned object with g_object_unref().
18742 * g_drive_get_identifier:
18743 * @drive: a #GDrive
18744 * @kind: the kind of identifier to return
18746 * Gets the identifier of the given kind for @drive.
18748 * Returns: a newly allocated string containing the
18749 * requested identfier, or %NULL if the #GDrive
18750 * doesn't have this kind of identifier.
18755 * g_drive_get_name:
18756 * @drive: a #GDrive.
18758 * Gets the name of @drive.
18760 * Returns: a string containing @drive's name. The returned
18761 * string should be freed when no longer needed.
18766 * g_drive_get_sort_key:
18767 * @drive: A #GDrive.
18769 * Gets the sort key for @drive, if any.
18771 * Returns: Sorting key for @drive or %NULL if no such key is available.
18777 * g_drive_get_start_stop_type:
18778 * @drive: a #GDrive.
18780 * Gets a hint about how a drive can be started/stopped.
18782 * Returns: A value from the #GDriveStartStopType enumeration.
18788 * g_drive_get_symbolic_icon:
18789 * @drive: a #GDrive.
18791 * Gets the icon for @drive.
18793 * Returns: (transfer full): symbolic #GIcon for the @drive.
18794 * Free the returned object with g_object_unref().
18800 * g_drive_get_volumes:
18801 * @drive: a #GDrive.
18803 * Get a list of mountable volumes for @drive.
18805 * The returned list should be freed with g_list_free(), after
18806 * its elements have been unreffed with g_object_unref().
18808 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
18813 * g_drive_has_media:
18814 * @drive: a #GDrive.
18816 * Checks if the @drive has media. Note that the OS may not be polling
18817 * the drive for media changes; see g_drive_is_media_check_automatic()
18818 * for more details.
18820 * Returns: %TRUE if @drive has media, %FALSE otherwise.
18825 * g_drive_has_volumes:
18826 * @drive: a #GDrive.
18828 * Check if @drive has any mountable volumes.
18830 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
18835 * g_drive_is_media_check_automatic:
18836 * @drive: a #GDrive.
18838 * Checks if @drive is capabable of automatically detecting media changes.
18840 * Returns: %TRUE if the @drive is capabable of automatically detecting
18841 * media changes, %FALSE otherwise.
18846 * g_drive_is_media_removable:
18847 * @drive: a #GDrive.
18849 * Checks if the @drive supports removable media.
18851 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
18856 * g_drive_poll_for_media:
18857 * @drive: a #GDrive.
18858 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18859 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18860 * @user_data: user data to pass to @callback
18862 * Asynchronously polls @drive to see if media has been inserted or removed.
18864 * When the operation is finished, @callback will be called.
18865 * You can then call g_drive_poll_for_media_finish() to obtain the
18866 * result of the operation.
18871 * g_drive_poll_for_media_finish:
18872 * @drive: a #GDrive.
18873 * @result: a #GAsyncResult.
18874 * @error: a #GError, or %NULL
18876 * Finishes an operation started with g_drive_poll_for_media() on a drive.
18878 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
18879 * %FALSE otherwise.
18885 * @drive: a #GDrive.
18886 * @flags: flags affecting the start operation.
18887 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
18888 * user interaction.
18889 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18890 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18891 * @user_data: user data to pass to @callback
18893 * Asynchronously starts a drive.
18895 * When the operation is finished, @callback will be called.
18896 * You can then call g_drive_start_finish() to obtain the
18897 * result of the operation.
18904 * g_drive_start_finish:
18905 * @drive: a #GDrive.
18906 * @result: a #GAsyncResult.
18907 * @error: a #GError, or %NULL
18909 * Finishes starting a drive.
18911 * Returns: %TRUE if the drive has been started successfully,
18912 * %FALSE otherwise.
18919 * @drive: a #GDrive.
18920 * @flags: flags affecting the unmount if required for stopping.
18921 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
18922 * user interaction.
18923 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
18924 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
18925 * @user_data: user data to pass to @callback
18927 * Asynchronously stops a drive.
18929 * When the operation is finished, @callback will be called.
18930 * You can then call g_drive_stop_finish() to obtain the
18931 * result of the operation.
18938 * g_drive_stop_finish:
18939 * @drive: a #GDrive.
18940 * @result: a #GAsyncResult.
18941 * @error: a #GError, or %NULL
18943 * Finishes stopping a drive.
18945 * Returns: %TRUE if the drive has been stopped successfully,
18946 * %FALSE otherwise.
18952 * g_emblem_get_icon:
18953 * @emblem: a #GEmblem from which the icon should be extracted.
18955 * Gives back the icon from @emblem.
18957 * Returns: (transfer none): a #GIcon. The returned object belongs to
18958 * the emblem and should not be modified or freed.
18964 * g_emblem_get_origin:
18965 * @emblem: a #GEmblem
18967 * Gets the origin of the emblem.
18969 * Returns: (transfer none): the origin of the emblem
18976 * @icon: a GIcon containing the icon.
18978 * Creates a new emblem for @icon.
18980 * Returns: a new #GEmblem.
18986 * g_emblem_new_with_origin:
18987 * @icon: a GIcon containing the icon.
18988 * @origin: a GEmblemOrigin enum defining the emblem's origin
18990 * Creates a new emblem for @icon.
18992 * Returns: a new #GEmblem.
18998 * g_emblemed_icon_add_emblem:
18999 * @emblemed: a #GEmblemedIcon
19000 * @emblem: a #GEmblem
19002 * Adds @emblem to the #GList of #GEmblem <!-- -->s.
19009 * g_emblemed_icon_clear_emblems:
19010 * @emblemed: a #GEmblemedIcon
19012 * Removes all the emblems from @icon.
19019 * g_emblemed_icon_get_emblems:
19020 * @emblemed: a #GEmblemedIcon
19022 * Gets the list of emblems for the @icon.
19024 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
19025 * #GEmblem <!-- -->s that is owned by @emblemed
19031 * g_emblemed_icon_get_icon:
19032 * @emblemed: a #GEmblemedIcon
19034 * Gets the main icon for @emblemed.
19036 * Returns: (transfer none): a #GIcon that is owned by @emblemed
19042 * g_emblemed_icon_new:
19044 * @emblem: (allow-none): a #GEmblem, or %NULL
19046 * Creates a new emblemed icon for @icon with the emblem @emblem.
19048 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
19054 * g_file_append_to:
19055 * @file: input #GFile
19056 * @flags: a set of #GFileCreateFlags
19057 * @cancellable: (allow-none): optional #GCancellable object,
19059 * @error: a #GError, or %NULL
19061 * Gets an output stream for appending data to the file.
19062 * If the file doesn't already exist it is created.
19064 * By default files created are generally readable by everyone,
19065 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19066 * will be made readable only to the current user, to the level that
19067 * is supported on the target filesystem.
19069 * If @cancellable is not %NULL, then the operation can be cancelled
19070 * by triggering the cancellable object from another thread. If the
19071 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19074 * Some file systems don't allow all file names, and may return an
19075 * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
19076 * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are
19077 * possible too, and depend on what kind of filesystem the file is on.
19079 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
19080 * Free the returned object with g_object_unref().
19085 * g_file_append_to_async:
19086 * @file: input #GFile
19087 * @flags: a set of #GFileCreateFlags
19088 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19090 * @cancellable: (allow-none): optional #GCancellable object,
19092 * @callback: (scope async): a #GAsyncReadyCallback to call
19093 * when the request is satisfied
19094 * @user_data: (closure): the data to pass to callback function
19096 * Asynchronously opens @file for appending.
19098 * For more details, see g_file_append_to() which is
19099 * the synchronous version of this call.
19101 * When the operation is finished, @callback will be called.
19102 * You can then call g_file_append_to_finish() to get the result
19103 * of the operation.
19108 * g_file_append_to_finish:
19109 * @file: input #GFile
19110 * @res: #GAsyncResult
19111 * @error: a #GError, or %NULL
19113 * Finishes an asynchronous file append operation started with
19114 * g_file_append_to_async().
19116 * Returns: (transfer full): a valid #GFileOutputStream
19117 * or %NULL on error.
19118 * Free the returned object with g_object_unref().
19123 * g_file_attribute_info_list_add:
19124 * @list: a #GFileAttributeInfoList.
19125 * @name: the name of the attribute to add.
19126 * @type: the #GFileAttributeType for the attribute.
19127 * @flags: #GFileAttributeInfoFlags for the attribute.
19129 * Adds a new attribute with @name to the @list, setting
19130 * its @type and @flags.
19135 * g_file_attribute_info_list_dup:
19136 * @list: a #GFileAttributeInfoList to duplicate.
19138 * Makes a duplicate of a file attribute info list.
19140 * Returns: a copy of the given @list.
19145 * g_file_attribute_info_list_lookup:
19146 * @list: a #GFileAttributeInfoList.
19147 * @name: the name of the attribute to lookup.
19149 * Gets the file attribute with the name @name from @list.
19151 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
19152 * attribute isn't found.
19157 * g_file_attribute_info_list_new:
19159 * Creates a new file attribute info list.
19161 * Returns: a #GFileAttributeInfoList.
19166 * g_file_attribute_info_list_ref:
19167 * @list: a #GFileAttributeInfoList to reference.
19169 * References a file attribute info list.
19171 * Returns: #GFileAttributeInfoList or %NULL on error.
19176 * g_file_attribute_info_list_unref:
19177 * @list: The #GFileAttributeInfoList to unreference.
19179 * Removes a reference from the given @list. If the reference count
19180 * falls to zero, the @list is deleted.
19185 * g_file_attribute_matcher_enumerate_namespace:
19186 * @matcher: a #GFileAttributeMatcher.
19187 * @ns: a string containing a file attribute namespace.
19189 * Checks if the matcher will match all of the keys in a given namespace.
19190 * This will always return %TRUE if a wildcard character is in use (e.g. if
19191 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
19192 * using "*" and namespace is anything.)
19194 * TODO: this is awkwardly worded.
19196 * Returns: %TRUE if the matcher matches all of the entries
19197 * in the given @ns, %FALSE otherwise.
19202 * g_file_attribute_matcher_enumerate_next:
19203 * @matcher: a #GFileAttributeMatcher.
19205 * Gets the next matched attribute from a #GFileAttributeMatcher.
19207 * Returns: a string containing the next attribute or %NULL if
19208 * no more attribute exist.
19213 * g_file_attribute_matcher_matches:
19214 * @matcher: a #GFileAttributeMatcher.
19215 * @attribute: a file attribute key.
19217 * Checks if an attribute will be matched by an attribute matcher. If
19218 * the matcher was created with the "*" matching string, this function
19219 * will always return %TRUE.
19221 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
19226 * g_file_attribute_matcher_matches_only:
19227 * @matcher: a #GFileAttributeMatcher.
19228 * @attribute: a file attribute key.
19230 * Checks if a attribute matcher only matches a given attribute. Always
19231 * returns %FALSE if "*" was used when creating the matcher.
19233 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
19238 * g_file_attribute_matcher_new:
19239 * @attributes: an attribute string to match.
19241 * Creates a new file attribute matcher, which matches attributes
19242 * against a given string. #GFileAttributeMatcher<!-- -->s are reference
19243 * counted structures, and are created with a reference count of 1. If
19244 * the number of references falls to 0, the #GFileAttributeMatcher is
19245 * automatically destroyed.
19247 * The @attribute string should be formatted with specific keys separated
19248 * from namespaces with a double colon. Several "namespace::key" strings may be
19249 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
19250 * The wildcard "*" may be used to match all keys and namespaces, or
19251 * "namespace::*" will match all keys in a given namespace.
19253 * Examples of strings to use:
19255 * <title>File Attribute Matcher strings and results</title>
19256 * <tgroup cols='2' align='left'><thead>
19257 * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead>
19259 * <row><entry>"*"</entry><entry>matches all attributes.</entry></row>
19260 * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row>
19261 * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and
19262 * all keys in the unix namespace.</entry></row>
19263 * </tbody></tgroup>
19266 * Returns: a #GFileAttributeMatcher.
19271 * g_file_attribute_matcher_ref:
19272 * @matcher: a #GFileAttributeMatcher.
19274 * References a file attribute matcher.
19276 * Returns: a #GFileAttributeMatcher.
19281 * g_file_attribute_matcher_subtract:
19282 * @matcher: Matcher to subtract from
19283 * @subtract: The matcher to subtract
19285 * Subtracts all attributes of @subtract from @matcher and returns
19286 * a matcher that supports those attributes.
19288 * Note that currently it is not possible to remove a single
19289 * attribute when the @matcher matches the whole namespace - or remove
19290 * a namespace or attribute when the matcher matches everything. This
19291 * is a limitation of the current implementation, but may be fixed
19294 * Returns: A file attribute matcher matching all attributes of
19295 * @matcher that are not matched by @subtract
19300 * g_file_attribute_matcher_to_string:
19301 * @matcher: (allow-none): a #GFileAttributeMatcher.
19303 * Prints what the matcher is matching against. The format will be
19304 * equal to the format passed to g_file_attribute_matcher_new().
19305 * The output however, might not be identical, as the matcher may
19306 * decide to use a different order or omit needless parts.
19308 * Returns: a string describing the attributes the matcher matches
19309 * against or %NULL if @matcher was %NULL.
19315 * g_file_attribute_matcher_unref:
19316 * @matcher: a #GFileAttributeMatcher.
19318 * Unreferences @matcher. If the reference count falls below 1,
19319 * the @matcher is automatically freed.
19325 * @source: input #GFile
19326 * @destination: destination #GFile
19327 * @flags: set of #GFileCopyFlags
19328 * @cancellable: (allow-none): optional #GCancellable object,
19330 * @progress_callback: (allow-none) (scope call): function to callback with
19331 * progress information, or %NULL if progress information is not needed
19332 * @progress_callback_data: (closure): user data to pass to @progress_callback
19333 * @error: #GError to set on error, or %NULL
19335 * Copies the file @source to the location specified by @destination.
19336 * Can not handle recursive copies of directories.
19338 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
19339 * existing @destination file is overwritten.
19341 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
19342 * will be copied as symlinks, otherwise the target of the
19343 * @source symlink will be copied.
19345 * If @cancellable is not %NULL, then the operation can be cancelled by
19346 * triggering the cancellable object from another thread. If the operation
19347 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19349 * If @progress_callback is not %NULL, then the operation can be monitored
19350 * by setting this to a #GFileProgressCallback function.
19351 * @progress_callback_data will be passed to this function. It is guaranteed
19352 * that this callback will be called after all data has been transferred with
19353 * the total number of bytes copied during the operation.
19355 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
19356 * is returned, independent on the status of the @destination.
19358 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
19359 * the error %G_IO_ERROR_EXISTS is returned.
19361 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
19362 * error is returned. If trying to overwrite a directory with a directory the
19363 * %G_IO_ERROR_WOULD_MERGE error is returned.
19365 * If the source is a directory and the target does not exist, or
19366 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
19367 * %G_IO_ERROR_WOULD_RECURSE error is returned.
19369 * If you are interested in copying the #GFile object itself (not the on-disk
19370 * file), see g_file_dup().
19372 * Returns: %TRUE on success, %FALSE otherwise.
19377 * g_file_copy_async: (skip)
19378 * @source: input #GFile
19379 * @destination: destination #GFile
19380 * @flags: set of #GFileCopyFlags
19381 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19383 * @cancellable: (allow-none): optional #GCancellable object,
19385 * @progress_callback: (allow-none): function to callback with progress
19386 * information, or %NULL if progress information is not needed
19387 * @progress_callback_data: (closure): user data to pass to @progress_callback
19388 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
19389 * @user_data: the data to pass to callback function
19391 * Copies the file @source to the location specified by @destination
19392 * asynchronously. For details of the behaviour, see g_file_copy().
19394 * If @progress_callback is not %NULL, then that function that will be called
19395 * just like in g_file_copy(), however the callback will run in the main loop,
19396 * not in the thread that is doing the I/O operation.
19398 * When the operation is finished, @callback will be called. You can then call
19399 * g_file_copy_finish() to get the result of the operation.
19404 * g_file_copy_attributes:
19405 * @source: a #GFile with attributes
19406 * @destination: a #GFile to copy attributes to
19407 * @flags: a set of #GFileCopyFlags
19408 * @cancellable: (allow-none): optional #GCancellable object,
19410 * @error: a #GError, %NULL to ignore
19412 * Copies the file attributes from @source to @destination.
19414 * Normally only a subset of the file attributes are copied,
19415 * those that are copies in a normal file copy operation
19416 * (which for instance does not include e.g. owner). However
19417 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
19418 * all the metadata that is possible to copy is copied. This
19419 * is useful when implementing move by copy + delete source.
19421 * Returns: %TRUE if the attributes were copied successfully,
19422 * %FALSE otherwise.
19427 * g_file_copy_finish:
19428 * @file: input #GFile
19429 * @res: a #GAsyncResult
19430 * @error: a #GError, or %NULL
19432 * Finishes copying the file started with g_file_copy_async().
19434 * Returns: a %TRUE on success, %FALSE on error.
19440 * @file: input #GFile
19441 * @flags: a set of #GFileCreateFlags
19442 * @cancellable: (allow-none): optional #GCancellable object,
19444 * @error: a #GError, or %NULL
19446 * Creates a new file and returns an output stream for writing to it.
19447 * The file must not already exist.
19449 * By default files created are generally readable by everyone,
19450 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19451 * will be made readable only to the current user, to the level
19452 * that is supported on the target filesystem.
19454 * If @cancellable is not %NULL, then the operation can be cancelled
19455 * by triggering the cancellable object from another thread. If the
19456 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19459 * If a file or directory with this name already exists the
19460 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
19461 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
19462 * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will
19463 * be returned. Other errors are possible too, and depend on what kind
19464 * of filesystem the file is on.
19466 * Returns: (transfer full): a #GFileOutputStream for the newly created
19467 * file, or %NULL on error.
19468 * Free the returned object with g_object_unref().
19473 * g_file_create_async:
19474 * @file: input #GFile
19475 * @flags: a set of #GFileCreateFlags
19476 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19478 * @cancellable: (allow-none): optional #GCancellable object,
19480 * @callback: (scope async): a #GAsyncReadyCallback to call
19481 * when the request is satisfied
19482 * @user_data: (closure): the data to pass to callback function
19484 * Asynchronously creates a new file and returns an output stream
19485 * for writing to it. The file must not already exist.
19487 * For more details, see g_file_create() which is
19488 * the synchronous version of this call.
19490 * When the operation is finished, @callback will be called.
19491 * You can then call g_file_create_finish() to get the result
19492 * of the operation.
19497 * g_file_create_finish:
19498 * @file: input #GFile
19499 * @res: a #GAsyncResult
19500 * @error: a #GError, or %NULL
19502 * Finishes an asynchronous file create operation started with
19503 * g_file_create_async().
19505 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
19506 * Free the returned object with g_object_unref().
19511 * g_file_create_readwrite:
19513 * @flags: a set of #GFileCreateFlags
19514 * @cancellable: (allow-none): optional #GCancellable object,
19516 * @error: return location for a #GError, or %NULL
19518 * Creates a new file and returns a stream for reading and
19519 * writing to it. The file must not already exist.
19521 * By default files created are generally readable by everyone,
19522 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
19523 * will be made readable only to the current user, to the level
19524 * that is supported on the target filesystem.
19526 * If @cancellable is not %NULL, then the operation can be cancelled
19527 * by triggering the cancellable object from another thread. If the
19528 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19531 * If a file or directory with this name already exists, the
19532 * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
19533 * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
19534 * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG
19535 * will be returned. Other errors are possible too, and depend on what
19536 * kind of filesystem the file is on.
19538 * Note that in many non-local file cases read and write streams are
19539 * not supported, so make sure you really need to do read and write
19540 * streaming, rather than just opening for reading or writing.
19542 * Returns: (transfer full): a #GFileIOStream for the newly created
19543 * file, or %NULL on error.
19544 * Free the returned object with g_object_unref().
19550 * g_file_create_readwrite_async:
19551 * @file: input #GFile
19552 * @flags: a set of #GFileCreateFlags
19553 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19555 * @cancellable: (allow-none): optional #GCancellable object,
19557 * @callback: (scope async): a #GAsyncReadyCallback to call
19558 * when the request is satisfied
19559 * @user_data: (closure): the data to pass to callback function
19561 * Asynchronously creates a new file and returns a stream
19562 * for reading and writing to it. The file must not already exist.
19564 * For more details, see g_file_create_readwrite() which is
19565 * the synchronous version of this call.
19567 * When the operation is finished, @callback will be called.
19568 * You can then call g_file_create_readwrite_finish() to get
19569 * the result of the operation.
19576 * g_file_create_readwrite_finish:
19577 * @file: input #GFile
19578 * @res: a #GAsyncResult
19579 * @error: a #GError, or %NULL
19581 * Finishes an asynchronous file create operation started with
19582 * g_file_create_readwrite_async().
19584 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
19585 * Free the returned object with g_object_unref().
19591 * g_file_delete: (virtual delete_file)
19592 * @file: input #GFile
19593 * @cancellable: (allow-none): optional #GCancellable object,
19595 * @error: a #GError, or %NULL
19597 * Deletes a file. If the @file is a directory, it will only be
19598 * deleted if it is empty. This has the same semantics as g_unlink().
19600 * If @cancellable is not %NULL, then the operation can be cancelled by
19601 * triggering the cancellable object from another thread. If the operation
19602 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19604 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
19609 * g_file_delete_async: (virtual delete_file_async)
19610 * @file: input #GFile
19611 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19613 * @cancellable: (allow-none): optional #GCancellable object,
19615 * @callback: a #GAsyncReadyCallback to call
19616 * when the request is satisfied
19617 * @user_data: the data to pass to callback function
19619 * Asynchronously delete a file. If the @file is a directory, it will
19620 * only be deleted if it is empty. This has the same semantics as
19628 * g_file_delete_finish: (virtual delete_file_finish)
19629 * @file: input #GFile
19630 * @result: a #GAsyncResult
19631 * @error: a #GError, or %NULL
19633 * Finishes deleting a file started with g_file_delete_async().
19635 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
19641 * g_file_descriptor_based_get_fd:
19642 * @fd_based: a #GFileDescriptorBased.
19644 * Gets the underlying file descriptor.
19646 * Returns: The file descriptor
19653 * @file: input #GFile
19655 * Duplicates a #GFile handle. This operation does not duplicate
19656 * the actual file or directory represented by the #GFile; see
19657 * g_file_copy() if attempting to copy a file.
19659 * This call does no blocking I/O.
19661 * Returns: (transfer full): a new #GFile that is a duplicate
19662 * of the given #GFile.
19667 * g_file_eject_mountable:
19668 * @file: input #GFile
19669 * @flags: flags affecting the operation
19670 * @cancellable: (allow-none): optional #GCancellable object,
19672 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
19673 * when the request is satisfied, or %NULL
19674 * @user_data: (closure): the data to pass to callback function
19676 * Starts an asynchronous eject on a mountable.
19677 * When this operation has completed, @callback will be called with
19678 * @user_user data, and the operation can be finalized with
19679 * g_file_eject_mountable_finish().
19681 * If @cancellable is not %NULL, then the operation can be cancelled by
19682 * triggering the cancellable object from another thread. If the operation
19683 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19685 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
19690 * g_file_eject_mountable_finish:
19691 * @file: input #GFile
19692 * @result: a #GAsyncResult
19693 * @error: a #GError, or %NULL
19695 * Finishes an asynchronous eject operation started by
19696 * g_file_eject_mountable().
19698 * Returns: %TRUE if the @file was ejected successfully.
19699 * %FALSE otherwise.
19700 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
19706 * g_file_eject_mountable_with_operation:
19707 * @file: input #GFile
19708 * @flags: flags affecting the operation
19709 * @mount_operation: (allow-none): a #GMountOperation,
19710 * or %NULL to avoid user interaction
19711 * @cancellable: (allow-none): optional #GCancellable object,
19713 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
19714 * when the request is satisfied, or %NULL
19715 * @user_data: (closure): the data to pass to callback function
19717 * Starts an asynchronous eject on a mountable.
19718 * When this operation has completed, @callback will be called with
19719 * @user_user data, and the operation can be finalized with
19720 * g_file_eject_mountable_with_operation_finish().
19722 * If @cancellable is not %NULL, then the operation can be cancelled by
19723 * triggering the cancellable object from another thread. If the operation
19724 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19731 * g_file_eject_mountable_with_operation_finish:
19732 * @file: input #GFile
19733 * @result: a #GAsyncResult
19734 * @error: a #GError, or %NULL
19736 * Finishes an asynchronous eject operation started by
19737 * g_file_eject_mountable_with_operation().
19739 * Returns: %TRUE if the @file was ejected successfully.
19740 * %FALSE otherwise.
19746 * g_file_enumerate_children:
19747 * @file: input #GFile
19748 * @attributes: an attribute query string
19749 * @flags: a set of #GFileQueryInfoFlags
19750 * @cancellable: (allow-none): optional #GCancellable object,
19752 * @error: #GError for error reporting
19754 * Gets the requested information about the files in a directory.
19755 * The result is a #GFileEnumerator object that will give out
19756 * #GFileInfo objects for all the files in the directory.
19758 * The @attributes value is a string that specifies the file
19759 * attributes that should be gathered. It is not an error if
19760 * it's not possible to read a particular requested attribute
19761 * from a file - it just won't be set. @attributes should
19762 * be a comma-separated list of attributes or attribute wildcards.
19763 * The wildcard "*" means all attributes, and a wildcard like
19764 * "standard::*" means all attributes in the standard namespace.
19765 * An example attribute query be "standard::*,owner::user".
19766 * The standard attributes are available as defines, like
19767 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
19769 * If @cancellable is not %NULL, then the operation can be cancelled
19770 * by triggering the cancellable object from another thread. If the
19771 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
19774 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
19775 * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY
19776 * error will be returned. Other errors are possible too.
19778 * Returns: (transfer full): A #GFileEnumerator if successful,
19779 * %NULL on error. Free the returned object with g_object_unref().
19784 * g_file_enumerate_children_async:
19785 * @file: input #GFile
19786 * @attributes: an attribute query string
19787 * @flags: a set of #GFileQueryInfoFlags
19788 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19790 * @cancellable: (allow-none): optional #GCancellable object,
19792 * @callback: (scope async): a #GAsyncReadyCallback to call when the
19793 * request is satisfied
19794 * @user_data: (closure): the data to pass to callback function
19796 * Asynchronously gets the requested information about the files
19797 * in a directory. The result is a #GFileEnumerator object that will
19798 * give out #GFileInfo objects for all the files in the directory.
19800 * For more details, see g_file_enumerate_children() which is
19801 * the synchronous version of this call.
19803 * When the operation is finished, @callback will be called. You can
19804 * then call g_file_enumerate_children_finish() to get the result of
19810 * g_file_enumerate_children_finish:
19811 * @file: input #GFile
19812 * @res: a #GAsyncResult
19813 * @error: a #GError
19815 * Finishes an async enumerate children operation.
19816 * See g_file_enumerate_children_async().
19818 * Returns: (transfer full): a #GFileEnumerator or %NULL
19819 * if an error occurred.
19820 * Free the returned object with g_object_unref().
19825 * g_file_enumerator_close:
19826 * @enumerator: a #GFileEnumerator.
19827 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19828 * @error: location to store the error occurring, or %NULL to ignore
19830 * Releases all resources used by this enumerator, making the
19831 * enumerator return %G_IO_ERROR_CLOSED on all calls.
19833 * This will be automatically called when the last reference
19834 * is dropped, but you might want to call this function to make
19835 * sure resources are released as early as possible.
19837 * Returns: #TRUE on success or #FALSE on error.
19842 * g_file_enumerator_close_async:
19843 * @enumerator: a #GFileEnumerator.
19844 * @io_priority: the <link linkend="io-priority">I/O priority</link>
19846 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19847 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
19848 * @user_data: (closure): the data to pass to callback function
19850 * Asynchronously closes the file enumerator.
19852 * If @cancellable is not %NULL, then the operation can be cancelled by
19853 * triggering the cancellable object from another thread. If the operation
19854 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
19855 * g_file_enumerator_close_finish().
19860 * g_file_enumerator_close_finish:
19861 * @enumerator: a #GFileEnumerator.
19862 * @result: a #GAsyncResult.
19863 * @error: a #GError location to store the error occurring, or %NULL to
19866 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
19868 * If the file enumerator was already closed when g_file_enumerator_close_async()
19869 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
19870 * return %FALSE. If the file enumerator had pending operation when the close
19871 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
19872 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
19873 * cancelled by triggering the cancellable object from another thread. If the operation
19874 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
19877 * Returns: %TRUE if the close operation has finished successfully.
19882 * g_file_enumerator_get_child:
19883 * @enumerator: a #GFileEnumerator
19884 * @info: a #GFileInfo gotten from g_file_enumerator_next_file()
19885 * or the async equivalents.
19887 * Return a new #GFile which refers to the file named by @info in the source
19888 * directory of @enumerator. This function is primarily intended to be used
19889 * inside loops with g_file_enumerator_next_file().
19891 * This is a convenience method that's equivalent to:
19893 * gchar *name = g_file_info_get_name (info);
19894 * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
19898 * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
19904 * g_file_enumerator_get_container:
19905 * @enumerator: a #GFileEnumerator
19907 * Get the #GFile container which is being enumerated.
19909 * Returns: (transfer none): the #GFile which is being enumerated.
19915 * g_file_enumerator_has_pending:
19916 * @enumerator: a #GFileEnumerator.
19918 * Checks if the file enumerator has pending operations.
19920 * Returns: %TRUE if the @enumerator has pending operations.
19925 * g_file_enumerator_is_closed:
19926 * @enumerator: a #GFileEnumerator.
19928 * Checks if the file enumerator has been closed.
19930 * Returns: %TRUE if the @enumerator is closed.
19935 * g_file_enumerator_next_file:
19936 * @enumerator: a #GFileEnumerator.
19937 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19938 * @error: location to store the error occurring, or %NULL to ignore
19940 * Returns information for the next file in the enumerated object.
19941 * Will block until the information is available. The #GFileInfo
19942 * returned from this function will contain attributes that match the
19943 * attribute string that was passed when the #GFileEnumerator was created.
19945 * See the documentation of #GFileEnumerator for information about the
19946 * order of returned files.
19948 * On error, returns %NULL and sets @error to the error. If the
19949 * enumerator is at the end, %NULL will be returned and @error will
19952 * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
19953 * Free the returned object with g_object_unref() when no longer needed.
19958 * g_file_enumerator_next_files_async:
19959 * @enumerator: a #GFileEnumerator.
19960 * @num_files: the number of file info objects to request
19961 * @io_priority: the <link linkend="io-priority">io priority</link>
19963 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19964 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
19965 * @user_data: (closure): the data to pass to callback function
19967 * Request information for a number of files from the enumerator asynchronously.
19968 * When all i/o for the operation is finished the @callback will be called with
19969 * the requested information.
19971 * See the documentation of #GFileEnumerator for information about the
19972 * order of returned files.
19974 * The callback can be called with less than @num_files files in case of error
19975 * or at the end of the enumerator. In case of a partial error the callback will
19976 * be called with any succeeding items and no error, and on the next request the
19977 * error will be reported. If a request is cancelled the callback will be called
19978 * with %G_IO_ERROR_CANCELLED.
19980 * During an async request no other sync and async calls are allowed, and will
19981 * result in %G_IO_ERROR_PENDING errors.
19983 * Any outstanding i/o request with higher priority (lower numerical value) will
19984 * be executed before an outstanding request with lower priority. Default
19985 * priority is %G_PRIORITY_DEFAULT.
19990 * g_file_enumerator_next_files_finish:
19991 * @enumerator: a #GFileEnumerator.
19992 * @result: a #GAsyncResult.
19993 * @error: a #GError location to store the error occurring, or %NULL to
19996 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
19998 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
19999 * g_list_free() and unref the infos with g_object_unref() when you're
20005 * g_file_enumerator_set_pending:
20006 * @enumerator: a #GFileEnumerator.
20007 * @pending: a boolean value.
20009 * Sets the file enumerator as having pending operations.
20015 * @file1: the first #GFile
20016 * @file2: the second #GFile
20018 * Checks equality of two given #GFiles.
20020 * Note that two #GFiles that differ can still refer to the same
20021 * file on the filesystem due to various forms of filename
20024 * This call does no blocking I/O.
20026 * Returns: %TRUE if @file1 and @file2 are equal.
20027 * %FALSE if either is not a #GFile.
20032 * g_file_find_enclosing_mount:
20033 * @file: input #GFile
20034 * @cancellable: (allow-none): optional #GCancellable object,
20036 * @error: a #GError
20038 * Gets a #GMount for the #GFile.
20040 * If the #GFileIface for @file does not have a mount (e.g.
20041 * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
20042 * and %NULL will be returned.
20044 * If @cancellable is not %NULL, then the operation can be cancelled by
20045 * triggering the cancellable object from another thread. If the operation
20046 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
20048 * Returns: (transfer full): a #GMount where the @file is located
20049 * or %NULL on error.
20050 * Free the returned object with g_object_unref().
20055 * g_file_find_enclosing_mount_async:
20057 * @io_priority: the <link linkend="io-priority">I/O priority</link>
20059 * @cancellable: (allow-none): optional #GCancellable object,
20061 * @callback: (scope async): a #GAsyncReadyCallback to call
20062 * when the request is satisfied
20063 * @user_data: (closure): the data to pass to callback function
20065 * Asynchronously gets the mount for the file.
20067 * For more details, see g_file_find_enclosing_mount() which is
20068 * the synchronous version of this call.
20070 * When the operation is finished, @callback will be called.
20071 * You can then call g_file_find_enclosing_mount_finish() to
20072 * get the result of the operation.
20077 * g_file_find_enclosing_mount_finish:
20079 * @res: a #GAsyncResult
20080 * @error: a #GError
20082 * Finishes an asynchronous find mount request.
20083 * See g_file_find_enclosing_mount_async().
20085 * Returns: (transfer full): #GMount for given @file or %NULL on error.
20086 * Free the returned object with g_object_unref().
20091 * g_file_get_basename:
20092 * @file: input #GFile
20094 * Gets the base name (the last component of the path) for a given #GFile.
20096 * If called for the top level of a system (such as the filesystem root
20097 * or a uri like sftp://host/) it will return a single directory separator
20098 * (and on Windows, possibly a drive letter).
20100 * The base name is a byte string (not UTF-8). It has no defined encoding
20101 * or rules other than it may not contain zero bytes. If you want to use
20102 * filenames in a user interface you should use the display name that you
20103 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
20104 * attribute with g_file_query_info().
20106 * This call does no blocking I/O.
20108 * Returns: string containing the #GFile's base name, or %NULL
20109 * if given #GFile is invalid. The returned string should be
20110 * freed with g_free() when no longer needed.
20115 * g_file_get_child:
20116 * @file: input #GFile
20117 * @name: string containing the child's basename
20119 * Gets a child of @file with basename equal to @name.
20121 * Note that the file with that specific name might not exist, but
20122 * you can still have a #GFile that points to it. You can use this
20123 * for instance to create that file.
20125 * This call does no blocking I/O.
20127 * Returns: (transfer full): a #GFile to a child specified by @name.
20128 * Free the returned object with g_object_unref().
20133 * g_file_get_child_for_display_name:
20134 * @file: input #GFile
20135 * @display_name: string to a possible child
20136 * @error: return location for an error
20138 * Gets the child of @file for a given @display_name (i.e. a UTF-8
20139 * version of the name). If this function fails, it returns %NULL
20140 * and @error will be set. This is very useful when constructing a
20141 * #GFile for a new file and the user entered the filename in the
20142 * user interface, for instance when you select a directory and
20143 * type a filename in the file selector.
20145 * This call does no blocking I/O.
20147 * Returns: (transfer full): a #GFile to the specified child, or
20148 * %NULL if the display name couldn't be converted.
20149 * Free the returned object with g_object_unref().
20154 * g_file_get_parent:
20155 * @file: input #GFile
20157 * Gets the parent directory for the @file.
20158 * If the @file represents the root directory of the
20159 * file system, then %NULL will be returned.
20161 * This call does no blocking I/O.
20163 * Returns: (transfer full): a #GFile structure to the
20164 * parent of the given #GFile or %NULL if there is
20165 * no parent. Free the returned object with g_object_unref().
20170 * g_file_get_parse_name:
20171 * @file: input #GFile
20173 * Gets the parse name of the @file.
20174 * A parse name is a UTF-8 string that describes the
20175 * file such that one can get the #GFile back using
20176 * g_file_parse_name().
20178 * This is generally used to show the #GFile as a nice
20179 * full-pathname kind of string in a user interface,
20180 * like in a location entry.
20182 * For local files with names that can safely be converted
20183 * to UTF-8 the pathname is used, otherwise the IRI is used
20184 * (a form of URI that allows UTF-8 characters unescaped).
20186 * This call does no blocking I/O.
20188 * Returns: a string containing the #GFile's parse name.
20189 * The returned string should be freed with g_free()
20190 * when no longer needed.
20196 * @file: input #GFile
20198 * Gets the local pathname for #GFile, if one exists.
20200 * This call does no blocking I/O.
20202 * Returns: string containing the #GFile's path, or %NULL if
20203 * no such path exists. The returned string should be
20204 * freed with g_free() when no longer needed.
20209 * g_file_get_relative_path:
20210 * @parent: input #GFile
20211 * @descendant: input #GFile
20213 * Gets the path for @descendant relative to @parent.
20215 * This call does no blocking I/O.
20217 * Returns: string with the relative path from @descendant
20218 * to @parent. The returned string should be freed with
20219 * g_free() when no longer needed.
20225 * @file: input #GFile
20227 * Gets the URI for the @file.
20229 * This call does no blocking I/O.
20231 * Returns: a string containing the #GFile's URI.
20232 * The returned string should be freed with g_free()
20233 * when no longer needed.
20238 * g_file_get_uri_scheme:
20239 * @file: input #GFile
20241 * Gets the URI scheme for a #GFile.
20242 * RFC 3986 decodes the scheme as:
20244 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
20245 * </programlisting>
20246 * Common schemes include "file", "http", "ftp", etc.
20248 * This call does no blocking I/O.
20250 * Returns: a string containing the URI scheme for the given
20251 * #GFile. The returned string should be freed with g_free()
20252 * when no longer needed.
20257 * g_file_has_parent:
20258 * @file: input #GFile
20259 * @parent: (allow-none): the parent to check for, or %NULL
20261 * Checks if @file has a parent, and optionally, if it is @parent.
20263 * If @parent is %NULL then this function returns %TRUE if @file has any
20264 * parent at all. If @parent is non-%NULL then %TRUE is only returned
20265 * if @file is a child of @parent.
20267 * Returns: %TRUE if @file is a child of @parent (or any parent in the
20268 * case that @parent is %NULL).
20274 * g_file_has_prefix: (virtual prefix_matches)
20275 * @file: input #GFile
20276 * @prefix: input #GFile
20278 * Checks whether @file has the prefix specified by @prefix.
20280 * In other words, if the names of initial elements of @file's
20281 * pathname match @prefix. Only full pathname elements are matched,
20282 * so a path like /foo is not considered a prefix of /foobar, only
20285 * This call does no I/O, as it works purely on names. As such it can
20286 * sometimes return %FALSE even if @file is inside a @prefix (from a
20287 * filesystem point of view), because the prefix of @file is an alias
20290 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
20291 * %FALSE otherwise.
20296 * g_file_has_uri_scheme:
20297 * @file: input #GFile
20298 * @uri_scheme: a string containing a URI scheme
20300 * Checks to see if a #GFile has a given URI scheme.
20302 * This call does no blocking I/O.
20304 * Returns: %TRUE if #GFile's backend supports the
20305 * given URI scheme, %FALSE if URI scheme is %NULL,
20306 * not supported, or #GFile is invalid.
20311 * g_file_hash: (virtual hash)
20312 * @file: (type GFile): #gconstpointer to a #GFile
20314 * Creates a hash value for a #GFile.
20316 * This call does no blocking I/O.
20318 * Returns: 0 if @file is not a valid #GFile, otherwise an
20319 * integer that can be used as hash value for the #GFile.
20320 * This function is intended for easily hashing a #GFile to
20321 * add to a #GHashTable or similar data structure.
20326 * g_file_icon_get_file:
20329 * Gets the #GFile associated with the given @icon.
20331 * Returns: (transfer none): a #GFile, or %NULL.
20339 * Creates a new icon for a file.
20341 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
20342 * @file, or %NULL on error.
20347 * g_file_info_clear_status:
20348 * @info: a #GFileInfo.
20350 * Clears the status information from @info.
20355 * g_file_info_copy_into:
20356 * @src_info: source to copy attributes from.
20357 * @dest_info: destination to copy attributes to.
20359 * Copies all of the <link linkend="gio-GFileAttribute">GFileAttribute</link>s
20360 * from @src_info to @dest_info.
20366 * @other: a #GFileInfo.
20368 * Duplicates a file info structure.
20370 * Returns: (transfer full): a duplicate #GFileInfo of @other.
20375 * g_file_info_get_attribute_as_string:
20376 * @info: a #GFileInfo.
20377 * @attribute: a file attribute key.
20379 * Gets the value of a attribute, formated as a string.
20380 * This escapes things as needed to make the string valid
20383 * Returns: a UTF-8 string associated with the given @attribute.
20384 * When you're done with the string it must be freed with g_free().
20389 * g_file_info_get_attribute_boolean:
20390 * @info: a #GFileInfo.
20391 * @attribute: a file attribute key.
20393 * Gets the value of a boolean attribute. If the attribute does not
20394 * contain a boolean value, %FALSE will be returned.
20396 * Returns: the boolean value contained within the attribute.
20401 * g_file_info_get_attribute_byte_string:
20402 * @info: a #GFileInfo.
20403 * @attribute: a file attribute key.
20405 * Gets the value of a byte string attribute. If the attribute does
20406 * not contain a byte string, %NULL will be returned.
20408 * Returns: the contents of the @attribute value as a byte string, or
20414 * g_file_info_get_attribute_data:
20415 * @info: a #GFileInfo
20416 * @attribute: a file attribute key
20417 * @type: (out) (allow-none): return location for the attribute type, or %NULL
20418 * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
20419 * @status: (out) (allow-none): return location for the attribute status, or %NULL
20421 * Gets the attribute type, value and status for an attribute key.
20423 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
20424 * %FALSE otherwise.
20429 * g_file_info_get_attribute_int32:
20430 * @info: a #GFileInfo.
20431 * @attribute: a file attribute key.
20433 * Gets a signed 32-bit integer contained within the attribute. If the
20434 * attribute does not contain a signed 32-bit integer, or is invalid,
20435 * 0 will be returned.
20437 * Returns: a signed 32-bit integer from the attribute.
20442 * g_file_info_get_attribute_int64:
20443 * @info: a #GFileInfo.
20444 * @attribute: a file attribute key.
20446 * Gets a signed 64-bit integer contained within the attribute. If the
20447 * attribute does not contain an signed 64-bit integer, or is invalid,
20448 * 0 will be returned.
20450 * Returns: a signed 64-bit integer from the attribute.
20455 * g_file_info_get_attribute_object:
20456 * @info: a #GFileInfo.
20457 * @attribute: a file attribute key.
20459 * Gets the value of a #GObject attribute. If the attribute does
20460 * not contain a #GObject, %NULL will be returned.
20462 * Returns: (transfer none): a #GObject associated with the given @attribute, or
20468 * g_file_info_get_attribute_status:
20469 * @info: a #GFileInfo
20470 * @attribute: a file attribute key
20472 * Gets the attribute status for an attribute key.
20474 * Returns: a #GFileAttributeStatus for the given @attribute, or
20475 * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
20480 * g_file_info_get_attribute_string:
20481 * @info: a #GFileInfo.
20482 * @attribute: a file attribute key.
20484 * Gets the value of a string attribute. If the attribute does
20485 * not contain a string, %NULL will be returned.
20487 * Returns: the contents of the @attribute value as a UTF-8 string, or
20493 * g_file_info_get_attribute_stringv:
20494 * @info: a #GFileInfo.
20495 * @attribute: a file attribute key.
20497 * Gets the value of a stringv attribute. If the attribute does
20498 * not contain a stringv, %NULL will be returned.
20500 * Returns: (transfer none): the contents of the @attribute value as a stringv, or
20501 * %NULL otherwise. Do not free. These returned strings are UTF-8.
20507 * g_file_info_get_attribute_type:
20508 * @info: a #GFileInfo.
20509 * @attribute: a file attribute key.
20511 * Gets the attribute type for an attribute key.
20513 * Returns: a #GFileAttributeType for the given @attribute, or
20514 * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
20519 * g_file_info_get_attribute_uint32:
20520 * @info: a #GFileInfo.
20521 * @attribute: a file attribute key.
20523 * Gets an unsigned 32-bit integer contained within the attribute. If the
20524 * attribute does not contain an unsigned 32-bit integer, or is invalid,
20525 * 0 will be returned.
20527 * Returns: an unsigned 32-bit integer from the attribute.
20532 * g_file_info_get_attribute_uint64:
20533 * @info: a #GFileInfo.
20534 * @attribute: a file attribute key.
20536 * Gets a unsigned 64-bit integer contained within the attribute. If the
20537 * attribute does not contain an unsigned 64-bit integer, or is invalid,
20538 * 0 will be returned.
20540 * Returns: a unsigned 64-bit integer from the attribute.
20545 * g_file_info_get_content_type:
20546 * @info: a #GFileInfo.
20548 * Gets the file's content type.
20550 * Returns: a string containing the file's content type.
20555 * g_file_info_get_deletion_date:
20556 * @info: a #GFileInfo.
20558 * Returns the #GDateTime representing the deletion date of the file, as
20559 * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
20560 * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
20562 * Returns: a #GDateTime, or %NULL.
20568 * g_file_info_get_display_name:
20569 * @info: a #GFileInfo.
20571 * Gets a display name for a file.
20573 * Returns: a string containing the display name.
20578 * g_file_info_get_edit_name:
20579 * @info: a #GFileInfo.
20581 * Gets the edit name for a file.
20583 * Returns: a string containing the edit name.
20588 * g_file_info_get_etag:
20589 * @info: a #GFileInfo.
20591 * Gets the <link linkend="gfile-etag">entity tag</link> for a given
20592 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
20594 * Returns: a string containing the value of the "etag:value" attribute.
20599 * g_file_info_get_file_type:
20600 * @info: a #GFileInfo.
20602 * Gets a file's type (whether it is a regular file, symlink, etc).
20603 * This is different from the file's content type, see g_file_info_get_content_type().
20605 * Returns: a #GFileType for the given file.
20610 * g_file_info_get_icon:
20611 * @info: a #GFileInfo.
20613 * Gets the icon for a file.
20615 * Returns: (transfer none): #GIcon for the given @info.
20620 * g_file_info_get_is_backup:
20621 * @info: a #GFileInfo.
20623 * Checks if a file is a backup file.
20625 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
20630 * g_file_info_get_is_hidden:
20631 * @info: a #GFileInfo.
20633 * Checks if a file is hidden.
20635 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
20640 * g_file_info_get_is_symlink:
20641 * @info: a #GFileInfo.
20643 * Checks if a file is a symlink.
20645 * Returns: %TRUE if the given @info is a symlink.
20650 * g_file_info_get_modification_time:
20651 * @info: a #GFileInfo.
20652 * @result: (out caller-allocates): a #GTimeVal.
20654 * Gets the modification time of the current @info and sets it
20660 * g_file_info_get_name:
20661 * @info: a #GFileInfo.
20663 * Gets the name for a file.
20665 * Returns: a string containing the file name.
20670 * g_file_info_get_size:
20671 * @info: a #GFileInfo.
20673 * Gets the file's size.
20675 * Returns: a #goffset containing the file's size.
20680 * g_file_info_get_sort_order:
20681 * @info: a #GFileInfo.
20683 * Gets the value of the sort_order attribute from the #GFileInfo.
20684 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
20686 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
20691 * g_file_info_get_symbolic_icon:
20692 * @info: a #GFileInfo.
20694 * Gets the symbolic icon for a file.
20696 * Returns: (transfer none): #GIcon for the given @info.
20702 * g_file_info_get_symlink_target:
20703 * @info: a #GFileInfo.
20705 * Gets the symlink target for a given #GFileInfo.
20707 * Returns: a string containing the symlink target.
20712 * g_file_info_has_attribute:
20713 * @info: a #GFileInfo.
20714 * @attribute: a file attribute key.
20716 * Checks if a file info structure has an attribute named @attribute.
20718 * Returns: %TRUE if @Ginfo has an attribute named @attribute,
20719 * %FALSE otherwise.
20724 * g_file_info_has_namespace:
20725 * @info: a #GFileInfo.
20726 * @name_space: a file attribute namespace.
20728 * Checks if a file info structure has an attribute in the
20729 * specified @name_space.
20731 * Returns: %TRUE if @Ginfo has an attribute in @name_space,
20732 * %FALSE otherwise.
20738 * g_file_info_list_attributes:
20739 * @info: a #GFileInfo.
20740 * @name_space: a file attribute key's namespace.
20742 * Lists the file info structure's attributes.
20744 * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
20745 * possible attribute types for the given @name_space, or
20753 * Creates a new file info structure.
20755 * Returns: a #GFileInfo.
20760 * g_file_info_remove_attribute:
20761 * @info: a #GFileInfo.
20762 * @attribute: a file attribute key.
20764 * Removes all cases of @attribute from @info if it exists.
20769 * g_file_info_set_attribute:
20770 * @info: a #GFileInfo.
20771 * @attribute: a file attribute key.
20772 * @type: a #GFileAttributeType
20773 * @value_p: pointer to the value
20775 * Sets the @attribute to contain the given value, if possible. To unset the
20776 * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
20781 * g_file_info_set_attribute_boolean:
20782 * @info: a #GFileInfo.
20783 * @attribute: a file attribute key.
20784 * @attr_value: a boolean value.
20786 * Sets the @attribute to contain the given @attr_value,
20792 * g_file_info_set_attribute_byte_string:
20793 * @info: a #GFileInfo.
20794 * @attribute: a file attribute key.
20795 * @attr_value: a byte string.
20797 * Sets the @attribute to contain the given @attr_value,
20803 * g_file_info_set_attribute_int32:
20804 * @info: a #GFileInfo.
20805 * @attribute: a file attribute key.
20806 * @attr_value: a signed 32-bit integer
20808 * Sets the @attribute to contain the given @attr_value,
20814 * g_file_info_set_attribute_int64:
20815 * @info: a #GFileInfo.
20816 * @attribute: attribute name to set.
20817 * @attr_value: int64 value to set attribute to.
20819 * Sets the @attribute to contain the given @attr_value,
20825 * g_file_info_set_attribute_mask:
20826 * @info: a #GFileInfo.
20827 * @mask: a #GFileAttributeMatcher.
20829 * Sets @mask on @info to match specific attribute types.
20834 * g_file_info_set_attribute_object:
20835 * @info: a #GFileInfo.
20836 * @attribute: a file attribute key.
20837 * @attr_value: a #GObject.
20839 * Sets the @attribute to contain the given @attr_value,
20845 * g_file_info_set_attribute_status:
20846 * @info: a #GFileInfo
20847 * @attribute: a file attribute key
20848 * @status: a #GFileAttributeStatus
20850 * Sets the attribute status for an attribute key. This is only
20851 * needed by external code that implement g_file_set_attributes_from_info()
20852 * or similar functions.
20854 * The attribute must exist in @info for this to work. Otherwise %FALSE
20855 * is returned and @info is unchanged.
20857 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
20863 * g_file_info_set_attribute_string:
20864 * @info: a #GFileInfo.
20865 * @attribute: a file attribute key.
20866 * @attr_value: a UTF-8 string.
20868 * Sets the @attribute to contain the given @attr_value,
20874 * g_file_info_set_attribute_stringv:
20875 * @info: a #GFileInfo.
20876 * @attribute: a file attribute key
20877 * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
20879 * Sets the @attribute to contain the given @attr_value,
20887 * g_file_info_set_attribute_uint32:
20888 * @info: a #GFileInfo.
20889 * @attribute: a file attribute key.
20890 * @attr_value: an unsigned 32-bit integer.
20892 * Sets the @attribute to contain the given @attr_value,
20898 * g_file_info_set_attribute_uint64:
20899 * @info: a #GFileInfo.
20900 * @attribute: a file attribute key.
20901 * @attr_value: an unsigned 64-bit integer.
20903 * Sets the @attribute to contain the given @attr_value,
20909 * g_file_info_set_content_type:
20910 * @info: a #GFileInfo.
20911 * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>.
20913 * Sets the content type attribute for a given #GFileInfo.
20914 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
20919 * g_file_info_set_display_name:
20920 * @info: a #GFileInfo.
20921 * @display_name: a string containing a display name.
20923 * Sets the display name for the current #GFileInfo.
20924 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
20929 * g_file_info_set_edit_name:
20930 * @info: a #GFileInfo.
20931 * @edit_name: a string containing an edit name.
20933 * Sets the edit name for the current file.
20934 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
20939 * g_file_info_set_file_type:
20940 * @info: a #GFileInfo.
20941 * @type: a #GFileType.
20943 * Sets the file type in a #GFileInfo to @type.
20944 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
20949 * g_file_info_set_icon:
20950 * @info: a #GFileInfo.
20953 * Sets the icon for a given #GFileInfo.
20954 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
20959 * g_file_info_set_is_hidden:
20960 * @info: a #GFileInfo.
20961 * @is_hidden: a #gboolean.
20963 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
20964 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
20969 * g_file_info_set_is_symlink:
20970 * @info: a #GFileInfo.
20971 * @is_symlink: a #gboolean.
20973 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
20974 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
20979 * g_file_info_set_modification_time:
20980 * @info: a #GFileInfo.
20981 * @mtime: a #GTimeVal.
20983 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
20984 * info to the given time value.
20989 * g_file_info_set_name:
20990 * @info: a #GFileInfo.
20991 * @name: a string containing a name.
20993 * Sets the name attribute for the current #GFileInfo.
20994 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
20999 * g_file_info_set_size:
21000 * @info: a #GFileInfo.
21001 * @size: a #goffset containing the file's size.
21003 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
21004 * to the given size.
21009 * g_file_info_set_sort_order:
21010 * @info: a #GFileInfo.
21011 * @sort_order: a sort order integer.
21013 * Sets the sort order attribute in the file info structure. See
21014 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
21019 * g_file_info_set_symbolic_icon:
21020 * @info: a #GFileInfo.
21023 * Sets the symbolic icon for a given #GFileInfo.
21024 * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
21031 * g_file_info_set_symlink_target:
21032 * @info: a #GFileInfo.
21033 * @symlink_target: a static string containing a path to a symlink target.
21035 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
21036 * to the given symlink target.
21041 * g_file_info_unset_attribute_mask:
21042 * @info: #GFileInfo.
21044 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
21050 * g_file_input_stream_query_info:
21051 * @stream: a #GFileInputStream.
21052 * @attributes: a file attribute query string.
21053 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21054 * @error: a #GError location to store the error occurring, or %NULL to
21057 * Queries a file input stream the given @attributes. This function blocks
21058 * while querying the stream. For the asynchronous (non-blocking) version
21059 * of this function, see g_file_input_stream_query_info_async(). While the
21060 * stream is blocked, the stream will set the pending flag internally, and
21061 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
21063 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
21068 * g_file_input_stream_query_info_async:
21069 * @stream: a #GFileInputStream.
21070 * @attributes: a file attribute query string.
21071 * @io_priority: the <link linkend="io-priority">I/O priority</link>
21073 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21074 * @callback: (scope async): callback to call when the request is satisfied
21075 * @user_data: (closure): the data to pass to callback function
21077 * Queries the stream information asynchronously.
21078 * When the operation is finished @callback will be called.
21079 * You can then call g_file_input_stream_query_info_finish()
21080 * to get the result of the operation.
21082 * For the synchronous version of this function,
21083 * see g_file_input_stream_query_info().
21085 * If @cancellable is not %NULL, then the operation can be cancelled by
21086 * triggering the cancellable object from another thread. If the operation
21087 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
21092 * g_file_input_stream_query_info_finish:
21093 * @stream: a #GFileInputStream.
21094 * @result: a #GAsyncResult.
21095 * @error: a #GError location to store the error occurring,
21096 * or %NULL to ignore.
21098 * Finishes an asynchronous info query operation.
21100 * Returns: (transfer full): #GFileInfo.
21105 * g_file_io_stream_get_etag:
21106 * @stream: a #GFileIOStream.
21108 * Gets the entity tag for the file when it has been written.
21109 * This must be called after the stream has been written
21110 * and closed, as the etag can change while writing.
21112 * Returns: the entity tag for the stream.
21118 * g_file_io_stream_query_info:
21119 * @stream: a #GFileIOStream.
21120 * @attributes: a file attribute query string.
21121 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21122 * @error: a #GError, %NULL to ignore.
21124 * Queries a file io stream for the given @attributes.
21125 * This function blocks while querying the stream. For the asynchronous
21126 * version of this function, see g_file_io_stream_query_info_async().
21127 * While the stream is blocked, the stream will set the pending flag
21128 * internally, and any other operations on the stream will fail with
21129 * %G_IO_ERROR_PENDING.
21131 * Can fail if the stream was already closed (with @error being set to
21132 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
21133 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
21134 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
21135 * all cases of failure, %NULL will be returned.
21137 * If @cancellable is not %NULL, then the operation can be cancelled by
21138 * triggering the cancellable object from another thread. If the operation
21139 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
21142 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
21148 * g_file_io_stream_query_info_async:
21149 * @stream: a #GFileIOStream.
21150 * @attributes: a file attribute query string.
21151 * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
21153 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
21154 * @callback: (scope async): callback to call when the request is satisfied
21155 * @user_data: (closure): the data to pass to callback function
21157 * Asynchronously queries the @stream for a #GFileInfo. When completed,
21158 * @callback will be called with a #GAsyncResult which can be used to
21159 * finish the operation with g_file_io_stream_query_info_finish().
21161 * For the synchronous version of this function, see
21162 * g_file_io_stream_query_info().
21169 * g_file_io_stream_query_info_finish:
21170 * @stream: a #GFileIOStream.
21171 * @result: a #GAsyncResult.
21172 * @error: a #GError, %NULL to ignore.
21174 * Finalizes the asynchronous query started
21175 * by g_file_io_stream_query_info_async().
21177 * Returns: (transfer full): A #GFileInfo for the finished query.
21183 * g_file_is_native:
21184 * @file: input #GFile
21186 * Checks to see if a file is native to the platform.
21188 * A native file s one expressed in the platform-native filename format,
21189 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
21190 * as it might be on a locally mounted remote filesystem.
21192 * On some systems non-native files may be available using the native
21193 * filesystem via a userspace filesystem (FUSE), in these cases this call
21194 * will return %FALSE, but g_file_get_path() will still return a native path.
21196 * This call does no blocking I/O.
21198 * Returns: %TRUE if @file is native
21203 * g_file_load_contents:
21204 * @file: input #GFile
21205 * @cancellable: optional #GCancellable object, %NULL to ignore
21206 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21207 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21208 * or %NULL if the length is not needed
21209 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21210 * or %NULL if the entity tag is not needed
21211 * @error: a #GError, or %NULL
21213 * Loads the content of the file into memory. The data is always
21214 * zero-terminated, but this is not included in the resultant @length.
21215 * The returned @content should be freed with g_free() when no longer
21218 * If @cancellable is not %NULL, then the operation can be cancelled by
21219 * triggering the cancellable object from another thread. If the operation
21220 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21222 * Returns: %TRUE if the @file's contents were successfully loaded.
21223 * %FALSE if there were errors.
21228 * g_file_load_contents_async:
21229 * @file: input #GFile
21230 * @cancellable: optional #GCancellable object, %NULL to ignore
21231 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
21232 * @user_data: the data to pass to callback function
21234 * Starts an asynchronous load of the @file's contents.
21236 * For more details, see g_file_load_contents() which is
21237 * the synchronous version of this call.
21239 * When the load operation has completed, @callback will be called
21240 * with @user data. To finish the operation, call
21241 * g_file_load_contents_finish() with the #GAsyncResult returned by
21244 * If @cancellable is not %NULL, then the operation can be cancelled by
21245 * triggering the cancellable object from another thread. If the operation
21246 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21251 * g_file_load_contents_finish:
21252 * @file: input #GFile
21253 * @res: a #GAsyncResult
21254 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21255 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21256 * or %NULL if the length is not needed
21257 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21258 * or %NULL if the entity tag is not needed
21259 * @error: a #GError, or %NULL
21261 * Finishes an asynchronous load of the @file's contents.
21262 * The contents are placed in @contents, and @length is set to the
21263 * size of the @contents string. The @content should be freed with
21264 * g_free() when no longer needed. If @etag_out is present, it will be
21265 * set to the new entity tag for the @file.
21267 * Returns: %TRUE if the load was successful. If %FALSE and @error is
21268 * present, it will be set appropriately.
21273 * g_file_load_partial_contents_async: (skip)
21274 * @file: input #GFile
21275 * @cancellable: optional #GCancellable object, %NULL to ignore
21276 * @read_more_callback: a #GFileReadMoreCallback to receive partial data
21277 * and to specify whether further data should be read
21278 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
21279 * @user_data: the data to pass to the callback functions
21281 * Reads the partial contents of a file. A #GFileReadMoreCallback should
21282 * be used to stop reading from the file when appropriate, else this
21283 * function will behave exactly as g_file_load_contents_async(). This
21284 * operation can be finished by g_file_load_partial_contents_finish().
21286 * Users of this function should be aware that @user_data is passed to
21287 * both the @read_more_callback and the @callback.
21289 * If @cancellable is not %NULL, then the operation can be cancelled by
21290 * triggering the cancellable object from another thread. If the operation
21291 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21296 * g_file_load_partial_contents_finish:
21297 * @file: input #GFile
21298 * @res: a #GAsyncResult
21299 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file
21300 * @length: (out) (allow-none): a location to place the length of the contents of the file,
21301 * or %NULL if the length is not needed
21302 * @etag_out: (out) (allow-none): a location to place the current entity tag for the file,
21303 * or %NULL if the entity tag is not needed
21304 * @error: a #GError, or %NULL
21306 * Finishes an asynchronous partial load operation that was started
21307 * with g_file_load_partial_contents_async(). The data is always
21308 * zero-terminated, but this is not included in the resultant @length.
21309 * The returned @content should be freed with g_free() when no longer
21312 * Returns: %TRUE if the load was successful. If %FALSE and @error is
21313 * present, it will be set appropriately.
21318 * g_file_make_directory:
21319 * @file: input #GFile
21320 * @cancellable: (allow-none): optional #GCancellable object,
21322 * @error: a #GError, or %NULL
21324 * Creates a directory. Note that this will only create a child directory
21325 * of the immediate parent directory of the path or URI given by the #GFile.
21326 * To recursively create directories, see g_file_make_directory_with_parents().
21327 * This function will fail if the parent directory does not exist, setting
21328 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
21329 * creating directories, this function will fail, setting @error to
21330 * %G_IO_ERROR_NOT_SUPPORTED.
21332 * For a local #GFile the newly created directory will have the default
21333 * (current) ownership and permissions of the current process.
21335 * If @cancellable is not %NULL, then the operation can be cancelled by
21336 * triggering the cancellable object from another thread. If the operation
21337 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21339 * Returns: %TRUE on successful creation, %FALSE otherwise.
21344 * g_file_make_directory_async: (virtual make_directory_async)
21345 * @file: input #GFile
21346 * @io_priority: the <link linkend="io-priority">I/O priority</link>
21348 * @cancellable: (allow-none): optional #GCancellable object,
21350 * @callback: a #GAsyncReadyCallback to call
21351 * when the request is satisfied
21352 * @user_data: the data to pass to callback function
21354 * Asynchronously creates a directory.
21361 * g_file_make_directory_finish: (virtual make_directory_finish)
21362 * @file: input #GFile
21363 * @result: a #GAsyncResult
21364 * @error: a #GError, or %NULL
21366 * Finishes an asynchronous directory creation, started with
21367 * g_file_make_directory_async().
21369 * Returns: %TRUE on successful directory creation, %FALSE otherwise.
21375 * g_file_make_directory_with_parents:
21376 * @file: input #GFile
21377 * @cancellable: (allow-none): optional #GCancellable object,
21379 * @error: a #GError, or %NULL
21381 * Creates a directory and any parent directories that may not
21382 * exist similar to 'mkdir -p'. If the file system does not support
21383 * creating directories, this function will fail, setting @error to
21384 * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
21385 * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
21386 * the similar g_mkdir_with_parents().
21388 * For a local #GFile the newly created directories will have the default
21389 * (current) ownership and permissions of the current process.
21391 * If @cancellable is not %NULL, then the operation can be cancelled by
21392 * triggering the cancellable object from another thread. If the operation
21393 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21395 * Returns: %TRUE if all directories have been successfully created, %FALSE
21402 * g_file_make_symbolic_link:
21403 * @file: a #GFile with the name of the symlink to create
21404 * @symlink_value: a string with the path for the target of the new symlink
21405 * @cancellable: (allow-none): optional #GCancellable object,
21407 * @error: a #GError
21409 * Creates a symbolic link named @file which contains the string
21412 * If @cancellable is not %NULL, then the operation can be cancelled by
21413 * triggering the cancellable object from another thread. If the operation
21414 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21416 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
21421 * g_file_measure_disk_usage:
21423 * @flags: #GFileMeasureFlags
21424 * @cancellable: (allow-none): optional #GCancellable
21425 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
21426 * @progress_data: user_data for @progress_callback
21427 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
21428 * @num_dirs: (allow-none) (out): the number of directories encountered
21429 * @num_files: (allow-none) (out): the number of non-directories encountered
21430 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
21432 * Recursively measures the disk usage of @file.
21434 * This is essentially an analog of the '<literal>du</literal>' command,
21435 * but it also reports the number of directories and non-directory files
21436 * encountered (including things like symbolic links).
21438 * By default, errors are only reported against the toplevel file
21439 * itself. Errors found while recursing are silently ignored, unless
21440 * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
21442 * The returned size, @disk_usage, is in bytes and should be formatted
21443 * with g_format_size() in order to get something reasonable for showing
21444 * in a user interface.
21446 * @progress_callback and @progress_data can be given to request
21447 * periodic progress updates while scanning. See the documentation for
21448 * #GFileMeasureProgressCallback for information about when and how the
21449 * callback will be invoked.
21451 * Returns: %TRUE if successful, with the out parameters set.
21452 * %FALSE otherwise, with @error set.
21458 * g_file_measure_disk_usage_async:
21460 * @flags: #GFileMeasureFlags
21461 * @io_priority: the <link linkend="io-priority">I/O priority</link>
21463 * @cancellable: (allow-none): optional #GCancellable
21464 * @progress_callback: (allow-none): a #GFileMeasureProgressCallback
21465 * @progress_data: user_data for @progress_callback
21466 * @callback: (allow-none): a #GAsyncReadyCallback to call when complete
21467 * @user_data: the data to pass to callback function
21469 * Recursively measures the disk usage of @file.
21471 * This is the asynchronous version of g_file_measure_disk_usage(). See
21472 * there for more information.
21479 * g_file_measure_disk_usage_finish:
21481 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
21482 * @disk_usage: (allow-none) (out): the number of bytes of disk space used
21483 * @num_dirs: (allow-none) (out): the number of directories encountered
21484 * @num_files: (allow-none) (out): the number of non-directories encountered
21485 * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer
21487 * Collects the results from an earlier call to
21488 * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
21489 * more information.
21491 * Returns: %TRUE if successful, with the out parameters set.
21492 * %FALSE otherwise, with @error set.
21499 * @file: input #GFile
21500 * @flags: a set of #GFileMonitorFlags
21501 * @cancellable: (allow-none): optional #GCancellable object,
21503 * @error: a #GError, or %NULL
21505 * Obtains a file or directory monitor for the given file,
21506 * depending on the type of the file.
21508 * If @cancellable is not %NULL, then the operation can be cancelled by
21509 * triggering the cancellable object from another thread. If the operation
21510 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21512 * Returns: (transfer full): a #GFileMonitor for the given @file,
21513 * or %NULL on error.
21514 * Free the returned object with g_object_unref().
21520 * g_file_monitor_cancel:
21521 * @monitor: a #GFileMonitor.
21523 * Cancels a file monitor.
21525 * Returns: %TRUE if monitor was cancelled.
21530 * g_file_monitor_directory: (virtual monitor_dir)
21531 * @file: input #GFile
21532 * @flags: a set of #GFileMonitorFlags
21533 * @cancellable: (allow-none): optional #GCancellable object,
21535 * @error: a #GError, or %NULL
21537 * Obtains a directory monitor for the given file.
21538 * This may fail if directory monitoring is not supported.
21540 * If @cancellable is not %NULL, then the operation can be cancelled by
21541 * triggering the cancellable object from another thread. If the operation
21542 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21544 * It does not make sense for @flags to contain
21545 * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to
21546 * directories. It is not possible to monitor all the files in a
21547 * directory for changes made via hard links; if you want to do this then
21548 * you must register individual watches with g_file_monitor().
21550 * Returns: (transfer full): a #GFileMonitor for the given @file,
21551 * or %NULL on error.
21552 * Free the returned object with g_object_unref().
21557 * g_file_monitor_emit_event:
21558 * @monitor: a #GFileMonitor.
21559 * @child: a #GFile.
21560 * @other_file: a #GFile.
21561 * @event_type: a set of #GFileMonitorEvent flags.
21563 * Emits the #GFileMonitor::changed signal if a change
21564 * has taken place. Should be called from file monitor
21565 * implementations only.
21567 * The signal will be emitted from an idle handler (in the <link
21568 * linkend="g-main-context-push-thread-default">thread-default main
21574 * g_file_monitor_file:
21575 * @file: input #GFile
21576 * @flags: a set of #GFileMonitorFlags
21577 * @cancellable: (allow-none): optional #GCancellable object,
21579 * @error: a #GError, or %NULL
21581 * Obtains a file monitor for the given file. If no file notification
21582 * mechanism exists, then regular polling of the file is used.
21584 * If @cancellable is not %NULL, then the operation can be cancelled by
21585 * triggering the cancellable object from another thread. If the operation
21586 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21588 * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor
21589 * will also attempt to report changes made to the file via another
21590 * filename (ie, a hard link). Without this flag, you can only rely on
21591 * changes made through the filename contained in @file to be
21592 * reported. Using this flag may result in an increase in resource
21593 * usage, and may not have any effect depending on the #GFileMonitor
21594 * backend and/or filesystem type.
21596 * Returns: (transfer full): a #GFileMonitor for the given @file,
21597 * or %NULL on error.
21598 * Free the returned object with g_object_unref().
21603 * g_file_monitor_is_cancelled:
21604 * @monitor: a #GFileMonitor
21606 * Returns whether the monitor is canceled.
21608 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
21613 * g_file_monitor_set_rate_limit:
21614 * @monitor: a #GFileMonitor.
21615 * @limit_msecs: a non-negative integer with the limit in milliseconds
21616 * to poll for changes
21618 * Sets the rate limit to which the @monitor will report
21619 * consecutive change events to the same file.
21624 * g_file_mount_enclosing_volume:
21625 * @location: input #GFile
21626 * @flags: flags affecting the operation
21627 * @mount_operation: (allow-none): a #GMountOperation
21628 * or %NULL to avoid user interaction
21629 * @cancellable: (allow-none): optional #GCancellable object,
21631 * @callback: (allow-none): a #GAsyncReadyCallback to call
21632 * when the request is satisfied, or %NULL
21633 * @user_data: the data to pass to callback function
21635 * Starts a @mount_operation, mounting the volume that contains
21636 * the file @location.
21638 * When this operation has completed, @callback will be called with
21639 * @user_user data, and the operation can be finalized with
21640 * g_file_mount_enclosing_volume_finish().
21642 * If @cancellable is not %NULL, then the operation can be cancelled by
21643 * triggering the cancellable object from another thread. If the operation
21644 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21649 * g_file_mount_enclosing_volume_finish:
21650 * @location: input #GFile
21651 * @result: a #GAsyncResult
21652 * @error: a #GError, or %NULL
21654 * Finishes a mount operation started by g_file_mount_enclosing_volume().
21656 * Returns: %TRUE if successful. If an error has occurred,
21657 * this function will return %FALSE and set @error
21658 * appropriately if present.
21663 * g_file_mount_mountable:
21664 * @file: input #GFile
21665 * @flags: flags affecting the operation
21666 * @mount_operation: (allow-none): a #GMountOperation,
21667 * or %NULL to avoid user interaction
21668 * @cancellable: (allow-none): optional #GCancellable object,
21670 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
21671 * when the request is satisfied, or %NULL
21672 * @user_data: (closure): the data to pass to callback function
21674 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
21675 * Using @mount_operation, you can request callbacks when, for instance,
21676 * passwords are needed during authentication.
21678 * If @cancellable is not %NULL, then the operation can be cancelled by
21679 * triggering the cancellable object from another thread. If the operation
21680 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21682 * When the operation is finished, @callback will be called.
21683 * You can then call g_file_mount_mountable_finish() to get
21684 * the result of the operation.
21689 * g_file_mount_mountable_finish:
21690 * @file: input #GFile
21691 * @result: a #GAsyncResult
21692 * @error: a #GError, or %NULL
21694 * Finishes a mount operation. See g_file_mount_mountable() for details.
21696 * Finish an asynchronous mount operation that was started
21697 * with g_file_mount_mountable().
21699 * Returns: (transfer full): a #GFile or %NULL on error.
21700 * Free the returned object with g_object_unref().
21706 * @source: #GFile pointing to the source location
21707 * @destination: #GFile pointing to the destination location
21708 * @flags: set of #GFileCopyFlags
21709 * @cancellable: (allow-none): optional #GCancellable object,
21711 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback
21712 * function for updates
21713 * @progress_callback_data: (closure): gpointer to user data for
21714 * the callback function
21715 * @error: #GError for returning error conditions, or %NULL
21717 * Tries to move the file or directory @source to the location specified
21718 * by @destination. If native move operations are supported then this is
21719 * used, otherwise a copy + delete fallback is used. The native
21720 * implementation may support moving directories (for instance on moves
21721 * inside the same filesystem), but the fallback code does not.
21723 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
21724 * existing @destination file is overwritten.
21726 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
21727 * will be copied as symlinks, otherwise the target of the
21728 * @source symlink will be copied.
21730 * If @cancellable is not %NULL, then the operation can be cancelled by
21731 * triggering the cancellable object from another thread. If the operation
21732 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
21734 * If @progress_callback is not %NULL, then the operation can be monitored
21735 * by setting this to a #GFileProgressCallback function.
21736 * @progress_callback_data will be passed to this function. It is
21737 * guaranteed that this callback will be called after all data has been
21738 * transferred with the total number of bytes copied during the operation.
21740 * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
21741 * error is returned, independent on the status of the @destination.
21743 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
21744 * then the error %G_IO_ERROR_EXISTS is returned.
21746 * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
21747 * error is returned. If trying to overwrite a directory with a directory the
21748 * %G_IO_ERROR_WOULD_MERGE error is returned.
21750 * If the source is a directory and the target does not exist, or
21751 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
21752 * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
21753 * move operation isn't available).
21755 * Returns: %TRUE on successful move, %FALSE otherwise.
21760 * g_file_new_for_commandline_arg:
21761 * @arg: a command line string
21763 * Creates a #GFile with the given argument from the command line.
21764 * The value of @arg can be either a URI, an absolute path or a
21765 * relative path resolved relative to the current working directory.
21766 * This operation never fails, but the returned object might not
21767 * support any I/O operation if @arg points to a malformed path.
21769 * Returns: (transfer full): a new #GFile.
21770 * Free the returned object with g_object_unref().
21775 * g_file_new_for_commandline_arg_and_cwd:
21776 * @arg: a command line string
21777 * @cwd: the current working directory of the commandline
21779 * Creates a #GFile with the given argument from the command line.
21781 * This function is similar to g_file_new_for_commandline_arg() except
21782 * that it allows for passing the current working directory as an
21783 * argument instead of using the current working directory of the
21786 * This is useful if the commandline argument was given in a context
21787 * other than the invocation of the current process.
21789 * See also g_application_command_line_create_file_for_arg().
21791 * Returns: (transfer full): a new #GFile
21797 * g_file_new_for_path:
21798 * @path: a string containing a relative or absolute path.
21799 * The string must be encoded in the glib filename encoding.
21801 * Constructs a #GFile for a given path. This operation never
21802 * fails, but the returned object might not support any I/O
21803 * operation if @path is malformed.
21805 * Returns: (transfer full): a new #GFile for the given @path.
21806 * Free the returned object with g_object_unref().
21811 * g_file_new_for_uri:
21812 * @uri: a UTF-8 string containing a URI
21814 * Constructs a #GFile for a given URI. This operation never
21815 * fails, but the returned object might not support any I/O
21816 * operation if @uri is malformed or if the uri type is
21819 * Returns: (transfer full): a new #GFile for the given @uri.
21820 * Free the returned object with g_object_unref().
21826 * @tmpl: (type filename) (allow-none): Template for the file
21827 * name, as in g_file_open_tmp(), or %NULL for a default template
21828 * @iostream: (out): on return, a #GFileIOStream for the created file
21829 * @error: a #GError, or %NULL
21831 * Opens a file in the preferred directory for temporary files (as
21832 * returned by g_get_tmp_dir()) and returns a #GFile and
21833 * #GFileIOStream pointing to it.
21835 * @tmpl should be a string in the GLib file name encoding
21836 * containing a sequence of six 'X' characters, and containing no
21837 * directory components. If it is %NULL, a default template is used.
21839 * Unlike the other #GFile constructors, this will return %NULL if
21840 * a temporary file could not be created.
21842 * Returns: (transfer full): a new #GFile.
21843 * Free the returned object with g_object_unref().
21849 * g_file_open_readwrite:
21850 * @file: #GFile to open
21851 * @cancellable: (allow-none): a #GCancellable
21852 * @error: a #GError, or %NULL
21854 * Opens an existing file for reading and writing. The result is
21855 * a #GFileIOStream that can be used to read and write the contents
21858 * If @cancellable is not %NULL, then the operation can be cancelled
21859 * by triggering the cancellable object from another thread. If the
21860 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
21863 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
21864 * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
21865 * error will be returned. Other errors are possible too, and depend on
21866 * what kind of filesystem the file is on. Note that in many non-local
21867 * file cases read and write streams are not supported, so make sure you
21868 * really need to do read and write streaming, rather than just opening
21869 * for reading or writing.
21871 * Returns: (transfer full): #GFileIOStream or %NULL on error.
21872 * Free the returned object with g_object_unref().
21878 * g_file_open_readwrite_async:
21879 * @file: input #GFile
21880 * @io_priority: the <link linkend="io-priority">I/O priority</link>
21882 * @cancellable: (allow-none): optional #GCancellable object,
21884 * @callback: (scope async): a #GAsyncReadyCallback to call
21885 * when the request is satisfied
21886 * @user_data: (closure): the data to pass to callback function
21888 * Asynchronously opens @file for reading and writing.
21890 * For more details, see g_file_open_readwrite() which is
21891 * the synchronous version of this call.
21893 * When the operation is finished, @callback will be called.
21894 * You can then call g_file_open_readwrite_finish() to get
21895 * the result of the operation.
21902 * g_file_open_readwrite_finish:
21903 * @file: input #GFile
21904 * @res: a #GAsyncResult
21905 * @error: a #GError, or %NULL
21907 * Finishes an asynchronous file read operation started with
21908 * g_file_open_readwrite_async().
21910 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
21911 * Free the returned object with g_object_unref().
21917 * g_file_output_stream_get_etag:
21918 * @stream: a #GFileOutputStream.
21920 * Gets the entity tag for the file when it has been written.
21921 * This must be called after the stream has been written
21922 * and closed, as the etag can change while writing.
21924 * Returns: the entity tag for the stream.
21929 * g_file_output_stream_query_info:
21930 * @stream: a #GFileOutputStream.
21931 * @attributes: a file attribute query string.
21932 * @cancellable: optional #GCancellable object, %NULL to ignore.
21933 * @error: a #GError, %NULL to ignore.
21935 * Queries a file output stream for the given @attributes.
21936 * This function blocks while querying the stream. For the asynchronous
21937 * version of this function, see g_file_output_stream_query_info_async().
21938 * While the stream is blocked, the stream will set the pending flag
21939 * internally, and any other operations on the stream will fail with
21940 * %G_IO_ERROR_PENDING.
21942 * Can fail if the stream was already closed (with @error being set to
21943 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
21944 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
21945 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
21946 * all cases of failure, %NULL will be returned.
21948 * If @cancellable is not %NULL, then the operation can be cancelled by
21949 * triggering the cancellable object from another thread. If the operation
21950 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
21953 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
21958 * g_file_output_stream_query_info_async:
21959 * @stream: a #GFileOutputStream.
21960 * @attributes: a file attribute query string.
21961 * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link>
21963 * @cancellable: optional #GCancellable object, %NULL to ignore.
21964 * @callback: callback to call when the request is satisfied
21965 * @user_data: the data to pass to callback function
21967 * Asynchronously queries the @stream for a #GFileInfo. When completed,
21968 * @callback will be called with a #GAsyncResult which can be used to
21969 * finish the operation with g_file_output_stream_query_info_finish().
21971 * For the synchronous version of this function, see
21972 * g_file_output_stream_query_info().
21977 * g_file_output_stream_query_info_finish:
21978 * @stream: a #GFileOutputStream.
21979 * @result: a #GAsyncResult.
21980 * @error: a #GError, %NULL to ignore.
21982 * Finalizes the asynchronous query started
21983 * by g_file_output_stream_query_info_async().
21985 * Returns: (transfer full): A #GFileInfo for the finished query.
21990 * g_file_parse_name:
21991 * @parse_name: a file name or path to be parsed
21993 * Constructs a #GFile with the given @parse_name (i.e. something
21994 * given by g_file_get_parse_name()). This operation never fails,
21995 * but the returned object might not support any I/O operation if
21996 * the @parse_name cannot be parsed.
21998 * Returns: (transfer full): a new #GFile.
22003 * g_file_poll_mountable:
22004 * @file: input #GFile
22005 * @cancellable: optional #GCancellable object, %NULL to ignore
22006 * @callback: (allow-none): a #GAsyncReadyCallback to call
22007 * when the request is satisfied, or %NULL
22008 * @user_data: the data to pass to callback function
22010 * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
22012 * If @cancellable is not %NULL, then the operation can be cancelled by
22013 * triggering the cancellable object from another thread. If the operation
22014 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22016 * When the operation is finished, @callback will be called.
22017 * You can then call g_file_mount_mountable_finish() to get
22018 * the result of the operation.
22025 * g_file_poll_mountable_finish:
22026 * @file: input #GFile
22027 * @result: a #GAsyncResult
22028 * @error: a #GError, or %NULL
22030 * Finishes a poll operation. See g_file_poll_mountable() for details.
22032 * Finish an asynchronous poll operation that was polled
22033 * with g_file_poll_mountable().
22035 * Returns: %TRUE if the operation finished successfully. %FALSE
22042 * g_file_query_default_handler:
22043 * @file: a #GFile to open
22044 * @cancellable: optional #GCancellable object, %NULL to ignore
22045 * @error: a #GError, or %NULL
22047 * Returns the #GAppInfo that is registered as the default
22048 * application to handle the file specified by @file.
22050 * If @cancellable is not %NULL, then the operation can be cancelled by
22051 * triggering the cancellable object from another thread. If the operation
22052 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22054 * Returns: (transfer full): a #GAppInfo if the handle was found,
22055 * %NULL if there were errors.
22056 * When you are done with it, release it with g_object_unref()
22061 * g_file_query_exists:
22062 * @file: input #GFile
22063 * @cancellable: (allow-none): optional #GCancellable object,
22066 * Utility function to check if a particular file exists. This is
22067 * implemented using g_file_query_info() and as such does blocking I/O.
22069 * Note that in many cases it is racy to first check for file existence
22070 * and then execute something based on the outcome of that, because the
22071 * file might have been created or removed in between the operations. The
22072 * general approach to handling that is to not check, but just do the
22073 * operation and handle the errors as they come.
22075 * As an example of race-free checking, take the case of reading a file,
22076 * and if it doesn't exist, creating it. There are two racy versions: read
22077 * it, and on error create it; and: check if it exists, if not create it.
22078 * These can both result in two processes creating the file (with perhaps
22079 * a partially written file as the result). The correct approach is to
22080 * always try to create the file with g_file_create() which will either
22081 * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
22083 * However, in many cases an existence check is useful in a user interface,
22084 * for instance to make a menu item sensitive/insensitive, so that you don't
22085 * have to fool users that something is possible and then just show an error
22086 * dialog. If you do this, you should make sure to also handle the errors
22087 * that can happen due to races when you execute the operation.
22089 * Returns: %TRUE if the file exists (and can be detected without error),
22090 * %FALSE otherwise (or if cancelled).
22095 * g_file_query_file_type:
22096 * @file: input #GFile
22097 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
22098 * @cancellable: (allow-none): optional #GCancellable object,
22101 * Utility function to inspect the #GFileType of a file. This is
22102 * implemented using g_file_query_info() and as such does blocking I/O.
22104 * The primary use case of this method is to check if a file is
22105 * a regular file, directory, or symlink.
22107 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
22108 * if the file does not exist
22114 * g_file_query_filesystem_info:
22115 * @file: input #GFile
22116 * @attributes: an attribute query string
22117 * @cancellable: (allow-none): optional #GCancellable object,
22119 * @error: a #GError
22121 * Similar to g_file_query_info(), but obtains information
22122 * about the filesystem the @file is on, rather than the file itself.
22123 * For instance the amount of space available and the type of
22126 * The @attributes value is a string that specifies the attributes
22127 * that should be gathered. It is not an error if it's not possible
22128 * to read a particular requested attribute from a file - it just
22129 * won't be set. @attributes should be a comma-separated list of
22130 * attributes or attribute wildcards. The wildcard "*" means all
22131 * attributes, and a wildcard like "filesystem::*" means all attributes
22132 * in the filesystem namespace. The standard namespace for filesystem
22133 * attributes is "filesystem". Common attributes of interest are
22134 * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
22135 * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
22136 * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
22138 * If @cancellable is not %NULL, then the operation can be cancelled
22139 * by triggering the cancellable object from another thread. If the
22140 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22143 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
22144 * be returned. Other errors are possible too, and depend on what
22145 * kind of filesystem the file is on.
22147 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
22148 * Free the returned object with g_object_unref().
22153 * g_file_query_filesystem_info_async:
22154 * @file: input #GFile
22155 * @attributes: an attribute query string
22156 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22158 * @cancellable: (allow-none): optional #GCancellable object,
22160 * @callback: (scope async): a #GAsyncReadyCallback to call
22161 * when the request is satisfied
22162 * @user_data: (closure): the data to pass to callback function
22164 * Asynchronously gets the requested information about the filesystem
22165 * that the specified @file is on. The result is a #GFileInfo object
22166 * that contains key-value attributes (such as type or size for the
22169 * For more details, see g_file_query_filesystem_info() which is the
22170 * synchronous version of this call.
22172 * When the operation is finished, @callback will be called. You can
22173 * then call g_file_query_info_finish() to get the result of the
22179 * g_file_query_filesystem_info_finish:
22180 * @file: input #GFile
22181 * @res: a #GAsyncResult
22182 * @error: a #GError
22184 * Finishes an asynchronous filesystem info query.
22185 * See g_file_query_filesystem_info_async().
22187 * Returns: (transfer full): #GFileInfo for given @file
22188 * or %NULL on error.
22189 * Free the returned object with g_object_unref().
22194 * g_file_query_info:
22195 * @file: input #GFile
22196 * @attributes: an attribute query string
22197 * @flags: a set of #GFileQueryInfoFlags
22198 * @cancellable: (allow-none): optional #GCancellable object,
22200 * @error: a #GError
22202 * Gets the requested information about specified @file.
22203 * The result is a #GFileInfo object that contains key-value
22204 * attributes (such as the type or size of the file).
22206 * The @attributes value is a string that specifies the file
22207 * attributes that should be gathered. It is not an error if
22208 * it's not possible to read a particular requested attribute
22209 * from a file - it just won't be set. @attributes should be a
22210 * comma-separated list of attributes or attribute wildcards.
22211 * The wildcard "*" means all attributes, and a wildcard like
22212 * "standard::*" means all attributes in the standard namespace.
22213 * An example attribute query be "standard::*,owner::user".
22214 * The standard attributes are available as defines, like
22215 * #G_FILE_ATTRIBUTE_STANDARD_NAME.
22217 * If @cancellable is not %NULL, then the operation can be cancelled
22218 * by triggering the cancellable object from another thread. If the
22219 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22222 * For symlinks, normally the information about the target of the
22223 * symlink is returned, rather than information about the symlink
22224 * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
22225 * in @flags the information about the symlink itself will be returned.
22226 * Also, for symlinks that point to non-existing files the information
22227 * about the symlink itself will be returned.
22229 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
22230 * returned. Other errors are possible too, and depend on what kind of
22231 * filesystem the file is on.
22233 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
22234 * on error. Free the returned object with g_object_unref().
22239 * g_file_query_info_async:
22240 * @file: input #GFile
22241 * @attributes: an attribute query string
22242 * @flags: a set of #GFileQueryInfoFlags
22243 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22245 * @cancellable: (allow-none): optional #GCancellable object,
22247 * @callback: (scope async): a #GAsyncReadyCallback to call when the
22248 * request is satisfied
22249 * @user_data: (closure): the data to pass to callback function
22251 * Asynchronously gets the requested information about specified @file.
22252 * The result is a #GFileInfo object that contains key-value attributes
22253 * (such as type or size for the file).
22255 * For more details, see g_file_query_info() which is the synchronous
22256 * version of this call.
22258 * When the operation is finished, @callback will be called. You can
22259 * then call g_file_query_info_finish() to get the result of the operation.
22264 * g_file_query_info_finish:
22265 * @file: input #GFile
22266 * @res: a #GAsyncResult
22267 * @error: a #GError
22269 * Finishes an asynchronous file info query.
22270 * See g_file_query_info_async().
22272 * Returns: (transfer full): #GFileInfo for given @file
22273 * or %NULL on error. Free the returned object with
22274 * g_object_unref().
22279 * g_file_query_settable_attributes:
22280 * @file: input #GFile
22281 * @cancellable: (allow-none): optional #GCancellable object,
22283 * @error: a #GError, or %NULL
22285 * Obtain the list of settable attributes for the file.
22287 * Returns the type and full attribute name of all the attributes
22288 * that can be set on this file. This doesn't mean setting it will
22289 * always succeed though, you might get an access failure, or some
22290 * specific file may not support a specific attribute.
22292 * If @cancellable is not %NULL, then the operation can be cancelled by
22293 * triggering the cancellable object from another thread. If the operation
22294 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22296 * Returns: a #GFileAttributeInfoList describing the settable attributes.
22297 * When you are done with it, release it with
22298 * g_file_attribute_info_list_unref()
22303 * g_file_query_writable_namespaces:
22304 * @file: input #GFile
22305 * @cancellable: (allow-none): optional #GCancellable object,
22307 * @error: a #GError, or %NULL
22309 * Obtain the list of attribute namespaces where new attributes
22310 * can be created by a user. An example of this is extended
22311 * attributes (in the "xattr" namespace).
22313 * If @cancellable is not %NULL, then the operation can be cancelled by
22314 * triggering the cancellable object from another thread. If the operation
22315 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22317 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
22318 * When you are done with it, release it with
22319 * g_file_attribute_info_list_unref()
22324 * g_file_read: (virtual read_fn)
22325 * @file: #GFile to read
22326 * @cancellable: (allow-none): a #GCancellable
22327 * @error: a #GError, or %NULL
22329 * Opens a file for reading. The result is a #GFileInputStream that
22330 * can be used to read the contents of the file.
22332 * If @cancellable is not %NULL, then the operation can be cancelled by
22333 * triggering the cancellable object from another thread. If the operation
22334 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22336 * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
22337 * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY
22338 * error will be returned. Other errors are possible too, and depend
22339 * on what kind of filesystem the file is on.
22341 * Returns: (transfer full): #GFileInputStream or %NULL on error.
22342 * Free the returned object with g_object_unref().
22347 * g_file_read_async:
22348 * @file: input #GFile
22349 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22351 * @cancellable: (allow-none): optional #GCancellable object,
22353 * @callback: (scope async): a #GAsyncReadyCallback to call
22354 * when the request is satisfied
22355 * @user_data: (closure): the data to pass to callback function
22357 * Asynchronously opens @file for reading.
22359 * For more details, see g_file_read() which is
22360 * the synchronous version of this call.
22362 * When the operation is finished, @callback will be called.
22363 * You can then call g_file_read_finish() to get the result
22364 * of the operation.
22369 * g_file_read_finish:
22370 * @file: input #GFile
22371 * @res: a #GAsyncResult
22372 * @error: a #GError, or %NULL
22374 * Finishes an asynchronous file read operation started with
22375 * g_file_read_async().
22377 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
22378 * Free the returned object with g_object_unref().
22384 * @file: input #GFile
22385 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link>
22386 * for the current #GFile, or #NULL to ignore
22387 * @make_backup: %TRUE if a backup should be created
22388 * @flags: a set of #GFileCreateFlags
22389 * @cancellable: (allow-none): optional #GCancellable object,
22391 * @error: a #GError, or %NULL
22393 * Returns an output stream for overwriting the file, possibly
22394 * creating a backup copy of the file first. If the file doesn't exist,
22395 * it will be created.
22397 * This will try to replace the file in the safest way possible so
22398 * that any errors during the writing will not affect an already
22399 * existing copy of the file. For instance, for local files it
22400 * may write to a temporary file and then atomically rename over
22401 * the destination when the stream is closed.
22403 * By default files created are generally readable by everyone,
22404 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
22405 * will be made readable only to the current user, to the level that
22406 * is supported on the target filesystem.
22408 * If @cancellable is not %NULL, then the operation can be cancelled
22409 * by triggering the cancellable object from another thread. If the
22410 * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
22413 * If you pass in a non-%NULL @etag value, then this value is
22414 * compared to the current entity tag of the file, and if they differ
22415 * an %G_IO_ERROR_WRONG_ETAG error is returned. This generally means
22416 * that the file has been changed since you last read it. You can get
22417 * the new etag from g_file_output_stream_get_etag() after you've
22418 * finished writing and closed the #GFileOutputStream. When you load
22419 * a new file you can use g_file_input_stream_query_info() to get
22420 * the etag of the file.
22422 * If @make_backup is %TRUE, this function will attempt to make a
22423 * backup of the current file before overwriting it. If this fails
22424 * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
22425 * want to replace anyway, try again with @make_backup set to %FALSE.
22427 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
22428 * be returned, and if the file is some other form of non-regular file
22429 * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
22430 * file systems don't allow all file names, and may return an
22431 * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
22432 * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are
22433 * possible too, and depend on what kind of filesystem the file is on.
22435 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
22436 * Free the returned object with g_object_unref().
22441 * g_file_replace_async:
22442 * @file: input #GFile
22443 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link>
22444 * for the current #GFile, or NULL to ignore
22445 * @make_backup: %TRUE if a backup should be created
22446 * @flags: a set of #GFileCreateFlags
22447 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22449 * @cancellable: (allow-none): optional #GCancellable object,
22451 * @callback: (scope async): a #GAsyncReadyCallback to call
22452 * when the request is satisfied
22453 * @user_data: (closure): the data to pass to callback function
22455 * Asynchronously overwrites the file, replacing the contents,
22456 * possibly creating a backup copy of the file first.
22458 * For more details, see g_file_replace() which is
22459 * the synchronous version of this call.
22461 * When the operation is finished, @callback will be called.
22462 * You can then call g_file_replace_finish() to get the result
22463 * of the operation.
22468 * g_file_replace_contents:
22469 * @file: input #GFile
22470 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file
22471 * @length: the length of @contents in bytes
22472 * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link>
22473 * for the document, or %NULL
22474 * @make_backup: %TRUE if a backup should be created
22475 * @flags: a set of #GFileCreateFlags
22476 * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link>
22477 * for the document. This should be freed with g_free() when no longer
22479 * @cancellable: optional #GCancellable object, %NULL to ignore
22480 * @error: a #GError, or %NULL
22482 * Replaces the contents of @file with @contents of @length bytes.
22484 * If @etag is specified (not %NULL), any existing file must have that etag,
22485 * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
22487 * If @make_backup is %TRUE, this function will attempt to make a backup
22490 * If @cancellable is not %NULL, then the operation can be cancelled by
22491 * triggering the cancellable object from another thread. If the operation
22492 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22494 * The returned @new_etag can be used to verify that the file hasn't
22495 * changed the next time it is saved over.
22497 * Returns: %TRUE if successful. If an error has occurred, this function
22498 * will return %FALSE and set @error appropriately if present.
22503 * g_file_replace_contents_async:
22504 * @file: input #GFile
22505 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with
22506 * @length: the length of @contents in bytes
22507 * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL
22508 * @make_backup: %TRUE if a backup should be created
22509 * @flags: a set of #GFileCreateFlags
22510 * @cancellable: optional #GCancellable object, %NULL to ignore
22511 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
22512 * @user_data: the data to pass to callback function
22514 * Starts an asynchronous replacement of @file with the given
22515 * @contents of @length bytes. @etag will replace the document's
22516 * current entity tag.
22518 * When this operation has completed, @callback will be called with
22519 * @user_user data, and the operation can be finalized with
22520 * g_file_replace_contents_finish().
22522 * If @cancellable is not %NULL, then the operation can be cancelled by
22523 * triggering the cancellable object from another thread. If the operation
22524 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22526 * If @make_backup is %TRUE, this function will attempt to
22527 * make a backup of @file.
22532 * g_file_replace_contents_finish:
22533 * @file: input #GFile
22534 * @res: a #GAsyncResult
22535 * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link>
22536 * for the document. This should be freed with g_free() when it is no
22537 * longer needed, or %NULL
22538 * @error: a #GError, or %NULL
22540 * Finishes an asynchronous replace of the given @file. See
22541 * g_file_replace_contents_async(). Sets @new_etag to the new entity
22542 * tag for the document, if present.
22544 * Returns: %TRUE on success, %FALSE on failure.
22549 * g_file_replace_finish:
22550 * @file: input #GFile
22551 * @res: a #GAsyncResult
22552 * @error: a #GError, or %NULL
22554 * Finishes an asynchronous file replace operation started with
22555 * g_file_replace_async().
22557 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
22558 * Free the returned object with g_object_unref().
22563 * g_file_replace_readwrite:
22565 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link>
22566 * for the current #GFile, or #NULL to ignore
22567 * @make_backup: %TRUE if a backup should be created
22568 * @flags: a set of #GFileCreateFlags
22569 * @cancellable: (allow-none): optional #GCancellable object,
22571 * @error: return location for a #GError, or %NULL
22573 * Returns an output stream for overwriting the file in readwrite mode,
22574 * possibly creating a backup copy of the file first. If the file doesn't
22575 * exist, it will be created.
22577 * For details about the behaviour, see g_file_replace() which does the
22578 * same thing but returns an output stream only.
22580 * Note that in many non-local file cases read and write streams are not
22581 * supported, so make sure you really need to do read and write streaming,
22582 * rather than just opening for reading or writing.
22584 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
22585 * Free the returned object with g_object_unref().
22591 * g_file_replace_readwrite_async:
22592 * @file: input #GFile
22593 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link>
22594 * for the current #GFile, or NULL to ignore
22595 * @make_backup: %TRUE if a backup should be created
22596 * @flags: a set of #GFileCreateFlags
22597 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22599 * @cancellable: (allow-none): optional #GCancellable object,
22601 * @callback: (scope async): a #GAsyncReadyCallback to call
22602 * when the request is satisfied
22603 * @user_data: (closure): the data to pass to callback function
22605 * Asynchronously overwrites the file in read-write mode,
22606 * replacing the contents, possibly creating a backup copy
22607 * of the file first.
22609 * For more details, see g_file_replace_readwrite() which is
22610 * the synchronous version of this call.
22612 * When the operation is finished, @callback will be called.
22613 * You can then call g_file_replace_readwrite_finish() to get
22614 * the result of the operation.
22621 * g_file_replace_readwrite_finish:
22622 * @file: input #GFile
22623 * @res: a #GAsyncResult
22624 * @error: a #GError, or %NULL
22626 * Finishes an asynchronous file replace operation started with
22627 * g_file_replace_readwrite_async().
22629 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
22630 * Free the returned object with g_object_unref().
22636 * g_file_resolve_relative_path:
22637 * @file: input #GFile
22638 * @relative_path: a given relative path string
22640 * Resolves a relative path for @file to an absolute path.
22642 * This call does no blocking I/O.
22644 * Returns: (transfer full): #GFile to the resolved path.
22645 * %NULL if @relative_path is %NULL or if @file is invalid.
22646 * Free the returned object with g_object_unref().
22651 * g_file_set_attribute:
22652 * @file: input #GFile
22653 * @attribute: a string containing the attribute's name
22654 * @type: The type of the attribute
22655 * @value_p: (allow-none): a pointer to the value (or the pointer
22656 * itself if the type is a pointer type)
22657 * @flags: a set of #GFileQueryInfoFlags
22658 * @cancellable: (allow-none): optional #GCancellable object,
22660 * @error: a #GError, or %NULL
22662 * Sets an attribute in the file with attribute name @attribute to @value.
22664 * Some attributes can be unset by setting @attribute to
22665 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
22667 * If @cancellable is not %NULL, then the operation can be cancelled by
22668 * triggering the cancellable object from another thread. If the operation
22669 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22671 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
22676 * g_file_set_attribute_byte_string:
22677 * @file: input #GFile
22678 * @attribute: a string containing the attribute's name
22679 * @value: a string containing the attribute's new value
22680 * @flags: a #GFileQueryInfoFlags
22681 * @cancellable: (allow-none): optional #GCancellable object,
22683 * @error: a #GError, or %NULL
22685 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
22686 * If @attribute is of a different type, this operation will fail,
22687 * returning %FALSE.
22689 * If @cancellable is not %NULL, then the operation can be cancelled by
22690 * triggering the cancellable object from another thread. If the operation
22691 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22693 * Returns: %TRUE if the @attribute was successfully set to @value
22694 * in the @file, %FALSE otherwise.
22699 * g_file_set_attribute_int32:
22700 * @file: input #GFile
22701 * @attribute: a string containing the attribute's name
22702 * @value: a #gint32 containing the attribute's new value
22703 * @flags: a #GFileQueryInfoFlags
22704 * @cancellable: (allow-none): optional #GCancellable object,
22706 * @error: a #GError, or %NULL
22708 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
22709 * If @attribute is of a different type, this operation will fail.
22711 * If @cancellable is not %NULL, then the operation can be cancelled by
22712 * triggering the cancellable object from another thread. If the operation
22713 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22715 * Returns: %TRUE if the @attribute was successfully set to @value
22716 * in the @file, %FALSE otherwise.
22721 * g_file_set_attribute_int64:
22722 * @file: input #GFile
22723 * @attribute: a string containing the attribute's name
22724 * @value: a #guint64 containing the attribute's new value
22725 * @flags: a #GFileQueryInfoFlags
22726 * @cancellable: (allow-none): optional #GCancellable object,
22728 * @error: a #GError, or %NULL
22730 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
22731 * If @attribute is of a different type, this operation will fail.
22733 * If @cancellable is not %NULL, then the operation can be cancelled by
22734 * triggering the cancellable object from another thread. If the operation
22735 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22737 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
22742 * g_file_set_attribute_string:
22743 * @file: input #GFile
22744 * @attribute: a string containing the attribute's name
22745 * @value: a string containing the attribute's value
22746 * @flags: #GFileQueryInfoFlags
22747 * @cancellable: (allow-none): optional #GCancellable object,
22749 * @error: a #GError, or %NULL
22751 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
22752 * If @attribute is of a different type, this operation will fail.
22754 * If @cancellable is not %NULL, then the operation can be cancelled by
22755 * triggering the cancellable object from another thread. If the operation
22756 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22758 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
22763 * g_file_set_attribute_uint32:
22764 * @file: input #GFile
22765 * @attribute: a string containing the attribute's name
22766 * @value: a #guint32 containing the attribute's new value
22767 * @flags: a #GFileQueryInfoFlags
22768 * @cancellable: (allow-none): optional #GCancellable object,
22770 * @error: a #GError, or %NULL
22772 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
22773 * If @attribute is of a different type, this operation will fail.
22775 * If @cancellable is not %NULL, then the operation can be cancelled by
22776 * triggering the cancellable object from another thread. If the operation
22777 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22779 * Returns: %TRUE if the @attribute was successfully set to @value
22780 * in the @file, %FALSE otherwise.
22785 * g_file_set_attribute_uint64:
22786 * @file: input #GFile
22787 * @attribute: a string containing the attribute's name
22788 * @value: a #guint64 containing the attribute's new value
22789 * @flags: a #GFileQueryInfoFlags
22790 * @cancellable: (allow-none): optional #GCancellable object,
22792 * @error: a #GError, or %NULL
22794 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
22795 * If @attribute is of a different type, this operation will fail.
22797 * If @cancellable is not %NULL, then the operation can be cancelled by
22798 * triggering the cancellable object from another thread. If the operation
22799 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22801 * Returns: %TRUE if the @attribute was successfully set to @value
22802 * in the @file, %FALSE otherwise.
22807 * g_file_set_attributes_async:
22808 * @file: input #GFile
22809 * @info: a #GFileInfo
22810 * @flags: a #GFileQueryInfoFlags
22811 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22813 * @cancellable: (allow-none): optional #GCancellable object,
22815 * @callback: (scope async): a #GAsyncReadyCallback
22816 * @user_data: (closure): a #gpointer
22818 * Asynchronously sets the attributes of @file with @info.
22820 * For more details, see g_file_set_attributes_from_info(),
22821 * which is the synchronous version of this call.
22823 * When the operation is finished, @callback will be called.
22824 * You can then call g_file_set_attributes_finish() to get
22825 * the result of the operation.
22830 * g_file_set_attributes_finish:
22831 * @file: input #GFile
22832 * @result: a #GAsyncResult
22833 * @info: (out) (transfer full): a #GFileInfo
22834 * @error: a #GError, or %NULL
22836 * Finishes setting an attribute started in g_file_set_attributes_async().
22838 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
22843 * g_file_set_attributes_from_info:
22844 * @file: input #GFile
22845 * @info: a #GFileInfo
22846 * @flags: #GFileQueryInfoFlags
22847 * @cancellable: (allow-none): optional #GCancellable object,
22849 * @error: a #GError, or %NULL
22851 * Tries to set all attributes in the #GFileInfo on the target
22852 * values, not stopping on the first error.
22854 * If there is any error during this operation then @error will
22855 * be set to the first error. Error on particular fields are flagged
22856 * by setting the "status" field in the attribute value to
22857 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
22858 * also detect further errors.
22860 * If @cancellable is not %NULL, then the operation can be cancelled by
22861 * triggering the cancellable object from another thread. If the operation
22862 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22864 * Returns: %FALSE if there was any error, %TRUE otherwise.
22869 * g_file_set_display_name:
22870 * @file: input #GFile
22871 * @display_name: a string
22872 * @cancellable: (allow-none): optional #GCancellable object,
22874 * @error: a #GError, or %NULL
22876 * Renames @file to the specified display name.
22878 * The display name is converted from UTF-8 to the correct encoding
22879 * for the target filesystem if possible and the @file is renamed to this.
22881 * If you want to implement a rename operation in the user interface the
22882 * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
22883 * initial value in the rename widget, and then the result after editing
22884 * should be passed to g_file_set_display_name().
22886 * On success the resulting converted filename is returned.
22888 * If @cancellable is not %NULL, then the operation can be cancelled by
22889 * triggering the cancellable object from another thread. If the operation
22890 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22892 * Returns: (transfer full): a #GFile specifying what @file was renamed to,
22893 * or %NULL if there was an error.
22894 * Free the returned object with g_object_unref().
22899 * g_file_set_display_name_async:
22900 * @file: input #GFile
22901 * @display_name: a string
22902 * @io_priority: the <link linkend="io-priority">I/O priority</link>
22904 * @cancellable: (allow-none): optional #GCancellable object,
22906 * @callback: (scope async): a #GAsyncReadyCallback to call
22907 * when the request is satisfied
22908 * @user_data: (closure): the data to pass to callback function
22910 * Asynchronously sets the display name for a given #GFile.
22912 * For more details, see g_file_set_display_name() which is
22913 * the synchronous version of this call.
22915 * When the operation is finished, @callback will be called.
22916 * You can then call g_file_set_display_name_finish() to get
22917 * the result of the operation.
22922 * g_file_set_display_name_finish:
22923 * @file: input #GFile
22924 * @res: a #GAsyncResult
22925 * @error: a #GError, or %NULL
22927 * Finishes setting a display name started with
22928 * g_file_set_display_name_async().
22930 * Returns: (transfer full): a #GFile or %NULL on error.
22931 * Free the returned object with g_object_unref().
22936 * g_file_start_mountable:
22937 * @file: input #GFile
22938 * @flags: flags affecting the operation
22939 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction
22940 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
22941 * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL
22942 * @user_data: the data to pass to callback function
22944 * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
22945 * Using @start_operation, you can request callbacks when, for instance,
22946 * passwords are needed during authentication.
22948 * If @cancellable is not %NULL, then the operation can be cancelled by
22949 * triggering the cancellable object from another thread. If the operation
22950 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22952 * When the operation is finished, @callback will be called.
22953 * You can then call g_file_mount_mountable_finish() to get
22954 * the result of the operation.
22961 * g_file_start_mountable_finish:
22962 * @file: input #GFile
22963 * @result: a #GAsyncResult
22964 * @error: a #GError, or %NULL
22966 * Finishes a start operation. See g_file_start_mountable() for details.
22968 * Finish an asynchronous start operation that was started
22969 * with g_file_start_mountable().
22971 * Returns: %TRUE if the operation finished successfully. %FALSE
22978 * g_file_stop_mountable:
22979 * @file: input #GFile
22980 * @flags: flags affecting the operation
22981 * @mount_operation: (allow-none): a #GMountOperation,
22982 * or %NULL to avoid user interaction.
22983 * @cancellable: (allow-none): optional #GCancellable object,
22985 * @callback: (allow-none): a #GAsyncReadyCallback to call
22986 * when the request is satisfied, or %NULL
22987 * @user_data: the data to pass to callback function
22989 * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
22991 * If @cancellable is not %NULL, then the operation can be cancelled by
22992 * triggering the cancellable object from another thread. If the operation
22993 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
22995 * When the operation is finished, @callback will be called.
22996 * You can then call g_file_stop_mountable_finish() to get
22997 * the result of the operation.
23004 * g_file_stop_mountable_finish:
23005 * @file: input #GFile
23006 * @result: a #GAsyncResult
23007 * @error: a #GError, or %NULL
23009 * Finishes an stop operation, see g_file_stop_mountable() for details.
23011 * Finish an asynchronous stop operation that was started
23012 * with g_file_stop_mountable().
23014 * Returns: %TRUE if the operation finished successfully.
23015 * %FALSE otherwise.
23021 * g_file_supports_thread_contexts:
23024 * Checks if @file supports <link
23025 * linkend="g-main-context-push-thread-default-context">thread-default
23026 * contexts</link>. If this returns %FALSE, you cannot perform
23027 * asynchronous operations on @file in a thread that has a
23028 * thread-default context.
23030 * Returns: Whether or not @file supports thread-default contexts.
23036 * g_file_trash: (virtual trash)
23037 * @file: #GFile to send to trash
23038 * @cancellable: (allow-none): optional #GCancellable object,
23040 * @error: a #GError, or %NULL
23042 * Sends @file to the "Trashcan", if possible. This is similar to
23043 * deleting it, but the user can recover it before emptying the trashcan.
23044 * Not all file systems support trashing, so this call can return the
23045 * %G_IO_ERROR_NOT_SUPPORTED error.
23047 * If @cancellable is not %NULL, then the operation can be cancelled by
23048 * triggering the cancellable object from another thread. If the operation
23049 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23051 * Returns: %TRUE on successful trash, %FALSE otherwise.
23056 * g_file_trash_async: (virtual trash_async)
23057 * @file: input #GFile
23058 * @io_priority: the <link linkend="io-priority">I/O priority</link>
23060 * @cancellable: (allow-none): optional #GCancellable object,
23062 * @callback: a #GAsyncReadyCallback to call
23063 * when the request is satisfied
23064 * @user_data: the data to pass to callback function
23066 * Asynchronously sends @file to the Trash location, if possible.
23073 * g_file_trash_finish: (virtual trash_finish)
23074 * @file: input #GFile
23075 * @result: a #GAsyncResult
23076 * @error: a #GError, or %NULL
23078 * Finishes an asynchronous file trashing operation, started with
23079 * g_file_trash_async().
23081 * Returns: %TRUE on successful trash, %FALSE otherwise.
23087 * g_file_unmount_mountable:
23088 * @file: input #GFile
23089 * @flags: flags affecting the operation
23090 * @cancellable: (allow-none): optional #GCancellable object,
23092 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
23093 * when the request is satisfied, or %NULL
23094 * @user_data: (closure): the data to pass to callback function
23096 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
23098 * If @cancellable is not %NULL, then the operation can be cancelled by
23099 * triggering the cancellable object from another thread. If the operation
23100 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23102 * When the operation is finished, @callback will be called.
23103 * You can then call g_file_unmount_mountable_finish() to get
23104 * the result of the operation.
23106 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
23111 * g_file_unmount_mountable_finish:
23112 * @file: input #GFile
23113 * @result: a #GAsyncResult
23114 * @error: a #GError, or %NULL
23116 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
23118 * Finish an asynchronous unmount operation that was started
23119 * with g_file_unmount_mountable().
23121 * Returns: %TRUE if the operation finished successfully.
23122 * %FALSE otherwise.
23123 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish()
23129 * g_file_unmount_mountable_with_operation:
23130 * @file: input #GFile
23131 * @flags: flags affecting the operation
23132 * @mount_operation: (allow-none): a #GMountOperation,
23133 * or %NULL to avoid user interaction
23134 * @cancellable: (allow-none): optional #GCancellable object,
23136 * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
23137 * when the request is satisfied, or %NULL
23138 * @user_data: (closure): the data to pass to callback function
23140 * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
23142 * If @cancellable is not %NULL, then the operation can be cancelled by
23143 * triggering the cancellable object from another thread. If the operation
23144 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23146 * When the operation is finished, @callback will be called.
23147 * You can then call g_file_unmount_mountable_finish() to get
23148 * the result of the operation.
23155 * g_file_unmount_mountable_with_operation_finish:
23156 * @file: input #GFile
23157 * @result: a #GAsyncResult
23158 * @error: a #GError, or %NULL
23160 * Finishes an unmount operation,
23161 * see g_file_unmount_mountable_with_operation() for details.
23163 * Finish an asynchronous unmount operation that was started
23164 * with g_file_unmount_mountable_with_operation().
23166 * Returns: %TRUE if the operation finished successfully.
23167 * %FALSE otherwise.
23173 * g_filename_completer_get_completion_suffix:
23174 * @completer: the filename completer.
23175 * @initial_text: text to be completed.
23177 * Obtains a completion for @initial_text from @completer.
23179 * Returns: a completed string, or %NULL if no completion exists.
23180 * This string is not owned by GIO, so remember to g_free() it
23186 * g_filename_completer_get_completions:
23187 * @completer: the filename completer.
23188 * @initial_text: text to be completed.
23190 * Gets an array of completion strings for a given initial text.
23192 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
23193 * This array must be freed by g_strfreev() when finished.
23198 * g_filename_completer_new:
23200 * Creates a new filename completer.
23202 * Returns: a #GFilenameCompleter.
23207 * g_filename_completer_set_dirs_only:
23208 * @completer: the filename completer.
23209 * @dirs_only: a #gboolean.
23211 * If @dirs_only is %TRUE, @completer will only
23212 * complete directory names, and not file names.
23217 * g_filter_input_stream_get_base_stream:
23218 * @stream: a #GFilterInputStream.
23220 * Gets the base stream for the filter stream.
23222 * Returns: (transfer none): a #GInputStream.
23227 * g_filter_input_stream_get_close_base_stream:
23228 * @stream: a #GFilterInputStream.
23230 * Returns whether the base stream will be closed when @stream is
23233 * Returns: %TRUE if the base stream will be closed.
23238 * g_filter_input_stream_set_close_base_stream:
23239 * @stream: a #GFilterInputStream.
23240 * @close_base: %TRUE to close the base stream.
23242 * Sets whether the base stream will be closed when @stream is closed.
23247 * g_filter_output_stream_get_base_stream:
23248 * @stream: a #GFilterOutputStream.
23250 * Gets the base stream for the filter stream.
23252 * Returns: (transfer none): a #GOutputStream.
23257 * g_filter_output_stream_get_close_base_stream:
23258 * @stream: a #GFilterOutputStream.
23260 * Returns whether the base stream will be closed when @stream is
23263 * Returns: %TRUE if the base stream will be closed.
23268 * g_filter_output_stream_set_close_base_stream:
23269 * @stream: a #GFilterOutputStream.
23270 * @close_base: %TRUE to close the base stream.
23272 * Sets whether the base stream will be closed when @stream is closed.
23277 * g_icon_deserialize:
23278 * @value: a #GVariant created with g_icon_serialize()
23280 * Deserializes a #GIcon previously serialized using g_icon_serialize().
23282 * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails.
23289 * @icon1: (allow-none): pointer to the first #GIcon.
23290 * @icon2: (allow-none): pointer to the second #GIcon.
23292 * Checks if two icons are equal.
23294 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
23299 * g_icon_hash: (virtual hash)
23300 * @icon: #gconstpointer to an icon object.
23302 * Gets a hash for an icon.
23304 * Returns: a #guint containing a hash for the @icon, suitable for
23305 * use in a #GHashTable or similar data structure.
23310 * g_icon_new_for_string:
23311 * @str: A string obtained via g_icon_to_string().
23312 * @error: Return location for error.
23314 * Generate a #GIcon instance from @str. This function can fail if
23315 * @str is not valid - see g_icon_to_string() for discussion.
23317 * If your application or library provides one or more #GIcon
23318 * implementations you need to ensure that each #GType is registered
23319 * with the type system prior to calling g_icon_new_for_string().
23321 * Returns: (transfer full): An object implementing the #GIcon
23322 * interface or %NULL if @error is set.
23328 * g_icon_serialize:
23331 * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
23332 * back by calling g_icon_deserialize() on the returned value.
23333 * As serialization will avoid using raw icon data when possible, it only
23334 * makes sense to transfer the #GVariant between processes on the same machine,
23335 * (as opposed to over the network), and within the same file system namespace.
23337 * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
23343 * g_icon_to_string: (virtual to_tokens)
23346 * Generates a textual representation of @icon that can be used for
23347 * serialization such as when passing @icon to a different process or
23348 * saving it to persistent storage. Use g_icon_new_for_string() to
23349 * get @icon back from the returned string.
23351 * The encoding of the returned string is proprietary to #GIcon except
23352 * in the following two cases
23356 * If @icon is a #GFileIcon, the returned string is a native path
23357 * (such as <literal>/path/to/my icon.png</literal>) without escaping
23358 * if the #GFile for @icon is a native file. If the file is not
23359 * native, the returned string is the result of g_file_get_uri()
23360 * (such as <literal>sftp://path/to/my%20icon.png</literal>).
23361 * </para></listitem>
23363 * If @icon is a #GThemedIcon with exactly one name, the encoding is
23364 * simply the name (such as <literal>network-server</literal>).
23365 * </para></listitem>
23368 * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
23369 * be serialized. Use g_free() to free.
23375 * g_inet_address_equal:
23376 * @address: A #GInetAddress.
23377 * @other_address: Another #GInetAddress.
23379 * Checks if two #GInetAddress instances are equal, e.g. the same address.
23381 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
23387 * g_inet_address_get_family:
23388 * @address: a #GInetAddress
23390 * Gets @address's family
23392 * Returns: @address's family
23398 * g_inet_address_get_is_any:
23399 * @address: a #GInetAddress
23401 * Tests whether @address is the "any" address for its family.
23403 * Returns: %TRUE if @address is the "any" address for its family.
23409 * g_inet_address_get_is_link_local:
23410 * @address: a #GInetAddress
23412 * Tests whether @address is a link-local address (that is, if it
23413 * identifies a host on a local network that is not connected to the
23416 * Returns: %TRUE if @address is a link-local address.
23422 * g_inet_address_get_is_loopback:
23423 * @address: a #GInetAddress
23425 * Tests whether @address is the loopback address for its family.
23427 * Returns: %TRUE if @address is the loopback address for its family.
23433 * g_inet_address_get_is_mc_global:
23434 * @address: a #GInetAddress
23436 * Tests whether @address is a global multicast address.
23438 * Returns: %TRUE if @address is a global multicast address.
23444 * g_inet_address_get_is_mc_link_local:
23445 * @address: a #GInetAddress
23447 * Tests whether @address is a link-local multicast address.
23449 * Returns: %TRUE if @address is a link-local multicast address.
23455 * g_inet_address_get_is_mc_node_local:
23456 * @address: a #GInetAddress
23458 * Tests whether @address is a node-local multicast address.
23460 * Returns: %TRUE if @address is a node-local multicast address.
23466 * g_inet_address_get_is_mc_org_local:
23467 * @address: a #GInetAddress
23469 * Tests whether @address is an organization-local multicast address.
23471 * Returns: %TRUE if @address is an organization-local multicast address.
23477 * g_inet_address_get_is_mc_site_local:
23478 * @address: a #GInetAddress
23480 * Tests whether @address is a site-local multicast address.
23482 * Returns: %TRUE if @address is a site-local multicast address.
23488 * g_inet_address_get_is_multicast:
23489 * @address: a #GInetAddress
23491 * Tests whether @address is a multicast address.
23493 * Returns: %TRUE if @address is a multicast address.
23499 * g_inet_address_get_is_site_local:
23500 * @address: a #GInetAddress
23502 * Tests whether @address is a site-local address such as 10.0.0.1
23503 * (that is, the address identifies a host on a local network that can
23504 * not be reached directly from the Internet, but which may have
23505 * outgoing Internet connectivity via a NAT or firewall).
23507 * Returns: %TRUE if @address is a site-local address.
23513 * g_inet_address_get_native_size:
23514 * @address: a #GInetAddress
23516 * Gets the size of the native raw binary address for @address. This
23517 * is the size of the data that you get from g_inet_address_to_bytes().
23519 * Returns: the number of bytes used for the native version of @address.
23525 * g_inet_address_mask_equal:
23526 * @mask: a #GInetAddressMask
23527 * @mask2: another #GInetAddressMask
23529 * Tests if @mask and @mask2 are the same mask.
23531 * Returns: whether @mask and @mask2 are the same mask
23537 * g_inet_address_mask_get_address:
23538 * @mask: a #GInetAddressMask
23540 * Gets @mask's base address
23542 * Returns: (transfer none): @mask's base address
23548 * g_inet_address_mask_get_family:
23549 * @mask: a #GInetAddressMask
23551 * Gets the #GSocketFamily of @mask's address
23553 * Returns: the #GSocketFamily of @mask's address
23559 * g_inet_address_mask_get_length:
23560 * @mask: a #GInetAddressMask
23562 * Gets @mask's length
23564 * Returns: @mask's length
23570 * g_inet_address_mask_matches:
23571 * @mask: a #GInetAddressMask
23572 * @address: a #GInetAddress
23574 * Tests if @address falls within the range described by @mask.
23576 * Returns: whether @address falls within the range described by
23583 * g_inet_address_mask_new:
23584 * @addr: a #GInetAddress
23585 * @length: number of bits of @addr to use
23586 * @error: return location for #GError, or %NULL
23588 * Creates a new #GInetAddressMask representing all addresses whose
23589 * first @length bits match @addr.
23591 * Returns: a new #GInetAddressMask, or %NULL on error
23597 * g_inet_address_mask_new_from_string:
23598 * @mask_string: an IP address or address/length string
23599 * @error: return location for #GError, or %NULL
23601 * Parses @mask_string as an IP address and (optional) length, and
23602 * creates a new #GInetAddressMask. The length, if present, is
23603 * delimited by a "/". If it is not present, then the length is
23604 * assumed to be the full length of the address.
23606 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
23613 * g_inet_address_mask_to_string:
23614 * @mask: a #GInetAddressMask
23616 * Converts @mask back to its corresponding string form.
23618 * Returns: a string corresponding to @mask.
23624 * g_inet_address_new_any:
23625 * @family: the address family
23627 * Creates a #GInetAddress for the "any" address (unassigned/"don't
23628 * care") for @family.
23630 * Returns: a new #GInetAddress corresponding to the "any" address
23637 * g_inet_address_new_from_bytes:
23638 * @bytes: (array) (element-type guint8): raw address data
23639 * @family: the address family of @bytes
23641 * Creates a new #GInetAddress from the given @family and @bytes.
23642 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
23643 * %G_SOCKET_FAMILY_IPV6.
23645 * Returns: a new #GInetAddress corresponding to @family and @bytes.
23651 * g_inet_address_new_from_string:
23652 * @string: a string representation of an IP address
23654 * Parses @string as an IP address and creates a new #GInetAddress.
23656 * Returns: a new #GInetAddress corresponding to @string, or %NULL if
23657 * @string could not be parsed.
23663 * g_inet_address_new_loopback:
23664 * @family: the address family
23666 * Creates a #GInetAddress for the loopback address for @family.
23668 * Returns: a new #GInetAddress corresponding to the loopback address
23675 * g_inet_address_to_bytes: (skip)
23676 * @address: a #GInetAddress
23678 * Gets the raw binary address data from @address.
23680 * Returns: a pointer to an internal array of the bytes in @address,
23681 * which should not be modified, stored, or freed. The size of this
23682 * array can be gotten with g_inet_address_get_native_size().
23688 * g_inet_address_to_string:
23689 * @address: a #GInetAddress
23691 * Converts @address to string form.
23693 * Returns: a representation of @address as a string, which should be
23700 * g_inet_socket_address_get_address:
23701 * @address: a #GInetSocketAddress
23703 * Gets @address's #GInetAddress.
23705 * Returns: (transfer none): the #GInetAddress for @address, which must be
23706 * g_object_ref()'d if it will be stored
23712 * g_inet_socket_address_get_flowinfo:
23713 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
23715 * Gets the <literal>sin6_flowinfo</literal> field from @address,
23716 * which must be an IPv6 address.
23718 * Returns: the flowinfo field
23724 * g_inet_socket_address_get_port:
23725 * @address: a #GInetSocketAddress
23727 * Gets @address's port.
23729 * Returns: the port for @address
23735 * g_inet_socket_address_get_scope_id:
23736 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
23738 * Gets the <literal>sin6_scope_id</literal> field from @address,
23739 * which must be an IPv6 address.
23741 * Returns: the scope id field
23747 * g_inet_socket_address_new:
23748 * @address: a #GInetAddress
23749 * @port: a port number
23751 * Creates a new #GInetSocketAddress for @address and @port.
23753 * Returns: a new #GInetSocketAddress
23760 * @initable: a #GInitable.
23761 * @cancellable: optional #GCancellable object, %NULL to ignore.
23762 * @error: a #GError location to store the error occurring, or %NULL to
23765 * Initializes the object implementing the interface.
23767 * The object must be initialized before any real use after initial
23768 * construction, either with this function or g_async_initable_init_async().
23770 * Implementations may also support cancellation. If @cancellable is not %NULL,
23771 * then initialization can be cancelled by triggering the cancellable object
23772 * from another thread. If the operation was cancelled, the error
23773 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
23774 * the object doesn't support cancellable initialization the error
23775 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
23777 * If the object is not initialized, or initialization returns with an
23778 * error, then all operations on the object except g_object_ref() and
23779 * g_object_unref() are considered to be invalid, and have undefined
23780 * behaviour. See the <xref linkend="ginitable"/> section introduction
23781 * for more details.
23783 * Implementations of this method must be idempotent, i.e. multiple calls
23784 * to this function with the same argument should return the same results.
23785 * Only the first call initializes the object, further calls return the result
23786 * of the first call. This is so that it's safe to implement the singleton
23787 * pattern in the GObject constructor function.
23789 * Returns: %TRUE if successful. If an error has occurred, this function will
23790 * return %FALSE and set @error appropriately if present.
23797 * @object_type: a #GType supporting #GInitable.
23798 * @cancellable: optional #GCancellable object, %NULL to ignore.
23799 * @error: a #GError location to store the error occurring, or %NULL to
23801 * @first_property_name: (allow-none): the name of the first property, or %NULL if no
23803 * @...: the value if the first property, followed by and other property
23804 * value pairs, and ended by %NULL.
23806 * Helper function for constructing #GInitable object. This is
23807 * similar to g_object_new() but also initializes the object
23808 * and returns %NULL, setting an error on failure.
23810 * Returns: (type GObject.Object) (transfer full): a newly allocated
23811 * #GObject, or %NULL on error
23817 * g_initable_new_valist:
23818 * @object_type: a #GType supporting #GInitable.
23819 * @first_property_name: the name of the first property, followed by
23820 * the value, and other property value pairs, and ended by %NULL.
23821 * @var_args: The var args list generated from @first_property_name.
23822 * @cancellable: optional #GCancellable object, %NULL to ignore.
23823 * @error: a #GError location to store the error occurring, or %NULL to
23826 * Helper function for constructing #GInitable object. This is
23827 * similar to g_object_new_valist() but also initializes the object
23828 * and returns %NULL, setting an error on failure.
23830 * Returns: (type GObject.Object) (transfer full): a newly allocated
23831 * #GObject, or %NULL on error
23838 * @object_type: a #GType supporting #GInitable.
23839 * @n_parameters: the number of parameters in @parameters
23840 * @parameters: (array length=n_parameters): the parameters to use to construct the object
23841 * @cancellable: optional #GCancellable object, %NULL to ignore.
23842 * @error: a #GError location to store the error occurring, or %NULL to
23845 * Helper function for constructing #GInitable object. This is
23846 * similar to g_object_newv() but also initializes the object
23847 * and returns %NULL, setting an error on failure.
23849 * Returns: (type GObject.Object) (transfer full): a newly allocated
23850 * #GObject, or %NULL on error
23856 * g_input_stream_async_read_is_via_threads:
23857 * @stream: input stream
23859 * Checks if an input stream's read_async function uses threads.
23861 * Returns: %TRUE if @stream's read_async function uses threads.
23866 * g_input_stream_clear_pending:
23867 * @stream: input stream
23869 * Clears the pending flag on @stream.
23874 * g_input_stream_close:
23875 * @stream: A #GInputStream.
23876 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
23877 * @error: location to store the error occurring, or %NULL to ignore
23879 * Closes the stream, releasing resources related to it.
23881 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
23882 * Closing a stream multiple times will not return an error.
23884 * Streams will be automatically closed when the last reference
23885 * is dropped, but you might want to call this function to make sure
23886 * resources are released as early as possible.
23888 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
23889 * open after the stream is closed. See the documentation for the individual
23890 * stream for details.
23892 * On failure the first error that happened will be reported, but the close
23893 * operation will finish as much as possible. A stream that failed to
23894 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
23895 * is important to check and report the error to the user.
23897 * If @cancellable is not %NULL, then the operation can be cancelled by
23898 * triggering the cancellable object from another thread. If the operation
23899 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
23900 * Cancelling a close will still leave the stream closed, but some streams
23901 * can use a faster close that doesn't block to e.g. check errors.
23903 * Returns: %TRUE on success, %FALSE on failure
23908 * g_input_stream_close_async:
23909 * @stream: A #GInputStream.
23910 * @io_priority: the <link linkend="io-priority">I/O priority</link>
23912 * @cancellable: (allow-none): optional cancellable object
23913 * @callback: (scope async): callback to call when the request is satisfied
23914 * @user_data: (closure): the data to pass to callback function
23916 * Requests an asynchronous closes of the stream, releasing resources related to it.
23917 * When the operation is finished @callback will be called.
23918 * You can then call g_input_stream_close_finish() to get the result of the
23921 * For behaviour details see g_input_stream_close().
23923 * The asyncronous methods have a default fallback that uses threads to implement
23924 * asynchronicity, so they are optional for inheriting classes. However, if you
23925 * override one you must override all.
23930 * g_input_stream_close_finish:
23931 * @stream: a #GInputStream.
23932 * @result: a #GAsyncResult.
23933 * @error: a #GError location to store the error occurring, or %NULL to
23936 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
23938 * Returns: %TRUE if the stream was closed successfully.
23943 * g_input_stream_has_pending:
23944 * @stream: input stream.
23946 * Checks if an input stream has pending actions.
23948 * Returns: %TRUE if @stream has pending actions.
23953 * g_input_stream_is_closed:
23954 * @stream: input stream.
23956 * Checks if an input stream is closed.
23958 * Returns: %TRUE if the stream is closed.
23963 * g_input_stream_read:
23964 * @stream: a #GInputStream.
23965 * @buffer: (array length=count) (element-type guint8): a buffer to
23966 * read data into (which should be at least count bytes long).
23967 * @count: the number of bytes that will be read from the stream
23968 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
23969 * @error: location to store the error occurring, or %NULL to ignore
23971 * Tries to read @count bytes from the stream into the buffer starting at
23972 * @buffer. Will block during this read.
23974 * If count is zero returns zero and does nothing. A value of @count
23975 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
23977 * On success, the number of bytes read into the buffer is returned.
23978 * It is not an error if this is not the same as the requested size, as it
23979 * can happen e.g. near the end of a file. Zero is returned on end of file
23980 * (or if @count is zero), but never otherwise.
23982 * If @cancellable is not %NULL, then the operation can be cancelled by
23983 * triggering the cancellable object from another thread. If the operation
23984 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
23985 * operation was partially finished when the operation was cancelled the
23986 * partial result will be returned, without an error.
23988 * On error -1 is returned and @error is set accordingly.
23990 * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
23995 * g_input_stream_read_all:
23996 * @stream: a #GInputStream.
23997 * @buffer: (array length=count) (element-type guint8): a buffer to
23998 * read data into (which should be at least count bytes long).
23999 * @count: the number of bytes that will be read from the stream
24000 * @bytes_read: (out): location to store the number of bytes that was read from the stream
24001 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24002 * @error: location to store the error occurring, or %NULL to ignore
24004 * Tries to read @count bytes from the stream into the buffer starting at
24005 * @buffer. Will block during this read.
24007 * This function is similar to g_input_stream_read(), except it tries to
24008 * read as many bytes as requested, only stopping on an error or end of stream.
24010 * On a successful read of @count bytes, or if we reached the end of the
24011 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
24012 * read into @buffer.
24014 * If there is an error during the operation %FALSE is returned and @error
24015 * is set to indicate the error status, @bytes_read is updated to contain
24016 * the number of bytes read into @buffer before the error occurred.
24018 * Returns: %TRUE on success, %FALSE if there was an error
24023 * g_input_stream_read_async:
24024 * @stream: A #GInputStream.
24025 * @buffer: (array length=count) (element-type guint8): a buffer to
24026 * read data into (which should be at least count bytes long).
24027 * @count: the number of bytes that will be read from the stream
24028 * @io_priority: the <link linkend="io-priority">I/O priority</link>
24030 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24031 * @callback: (scope async): callback to call when the request is satisfied
24032 * @user_data: (closure): the data to pass to callback function
24034 * Request an asynchronous read of @count bytes from the stream into the buffer
24035 * starting at @buffer. When the operation is finished @callback will be called.
24036 * You can then call g_input_stream_read_finish() to get the result of the
24039 * During an async request no other sync and async calls are allowed on @stream, and will
24040 * result in %G_IO_ERROR_PENDING errors.
24042 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24044 * On success, the number of bytes read into the buffer will be passed to the
24045 * callback. It is not an error if this is not the same as the requested size, as it
24046 * can happen e.g. near the end of a file, but generally we try to read
24047 * as many bytes as requested. Zero is returned on end of file
24048 * (or if @count is zero), but never otherwise.
24050 * Any outstanding i/o request with higher priority (lower numerical value) will
24051 * be executed before an outstanding request with lower priority. Default
24052 * priority is %G_PRIORITY_DEFAULT.
24054 * The asyncronous methods have a default fallback that uses threads to implement
24055 * asynchronicity, so they are optional for inheriting classes. However, if you
24056 * override one you must override all.
24061 * g_input_stream_read_bytes:
24062 * @stream: a #GInputStream.
24063 * @count: maximum number of bytes that will be read from the stream. Common
24064 * values include 4096 and 8192.
24065 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24066 * @error: location to store the error occurring, or %NULL to ignore
24068 * Like g_input_stream_read(), this tries to read @count bytes from
24069 * the stream in a blocking fashion. However, rather than reading into
24070 * a user-supplied buffer, this will create a new #GBytes containing
24071 * the data that was read. This may be easier to use from language
24074 * If count is zero, returns a zero-length #GBytes and does nothing. A
24075 * value of @count larger than %G_MAXSSIZE will cause a
24076 * %G_IO_ERROR_INVALID_ARGUMENT error.
24078 * On success, a new #GBytes is returned. It is not an error if the
24079 * size of this object is not the same as the requested size, as it
24080 * can happen e.g. near the end of a file. A zero-length #GBytes is
24081 * returned on end of file (or if @count is zero), but never
24084 * If @cancellable is not %NULL, then the operation can be cancelled by
24085 * triggering the cancellable object from another thread. If the operation
24086 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24087 * operation was partially finished when the operation was cancelled the
24088 * partial result will be returned, without an error.
24090 * On error %NULL is returned and @error is set accordingly.
24092 * Returns: a new #GBytes, or %NULL on error
24097 * g_input_stream_read_bytes_async:
24098 * @stream: A #GInputStream.
24099 * @count: the number of bytes that will be read from the stream
24100 * @io_priority: the <link linkend="io-priority">I/O priority</link>
24102 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24103 * @callback: (scope async): callback to call when the request is satisfied
24104 * @user_data: (closure): the data to pass to callback function
24106 * Request an asynchronous read of @count bytes from the stream into a
24107 * new #GBytes. When the operation is finished @callback will be
24108 * called. You can then call g_input_stream_read_bytes_finish() to get the
24109 * result of the operation.
24111 * During an async request no other sync and async calls are allowed
24112 * on @stream, and will result in %G_IO_ERROR_PENDING errors.
24114 * A value of @count larger than %G_MAXSSIZE will cause a
24115 * %G_IO_ERROR_INVALID_ARGUMENT error.
24117 * On success, the new #GBytes will be passed to the callback. It is
24118 * not an error if this is smaller than the requested size, as it can
24119 * happen e.g. near the end of a file, but generally we try to read as
24120 * many bytes as requested. Zero is returned on end of file (or if
24121 * @count is zero), but never otherwise.
24123 * Any outstanding I/O request with higher priority (lower numerical
24124 * value) will be executed before an outstanding request with lower
24125 * priority. Default priority is %G_PRIORITY_DEFAULT.
24130 * g_input_stream_read_bytes_finish:
24131 * @stream: a #GInputStream.
24132 * @result: a #GAsyncResult.
24133 * @error: a #GError location to store the error occurring, or %NULL to
24136 * Finishes an asynchronous stream read-into-#GBytes operation.
24138 * Returns: the newly-allocated #GBytes, or %NULL on error
24143 * g_input_stream_read_finish:
24144 * @stream: a #GInputStream.
24145 * @result: a #GAsyncResult.
24146 * @error: a #GError location to store the error occurring, or %NULL to
24149 * Finishes an asynchronous stream read operation.
24151 * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
24156 * g_input_stream_set_pending:
24157 * @stream: input stream
24158 * @error: a #GError location to store the error occurring, or %NULL to
24161 * Sets @stream to have actions pending. If the pending flag is
24162 * already set or @stream is closed, it will return %FALSE and set
24165 * Returns: %TRUE if pending was previously unset and is now set.
24170 * g_input_stream_skip:
24171 * @stream: a #GInputStream.
24172 * @count: the number of bytes that will be skipped from the stream
24173 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24174 * @error: location to store the error occurring, or %NULL to ignore
24176 * Tries to skip @count bytes from the stream. Will block during the operation.
24178 * This is identical to g_input_stream_read(), from a behaviour standpoint,
24179 * but the bytes that are skipped are not returned to the user. Some
24180 * streams have an implementation that is more efficient than reading the data.
24182 * This function is optional for inherited classes, as the default implementation
24183 * emulates it using read.
24185 * If @cancellable is not %NULL, then the operation can be cancelled by
24186 * triggering the cancellable object from another thread. If the operation
24187 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
24188 * operation was partially finished when the operation was cancelled the
24189 * partial result will be returned, without an error.
24191 * Returns: Number of bytes skipped, or -1 on error
24196 * g_input_stream_skip_async:
24197 * @stream: A #GInputStream.
24198 * @count: the number of bytes that will be skipped from the stream
24199 * @io_priority: the <link linkend="io-priority">I/O priority</link>
24201 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24202 * @callback: (scope async): callback to call when the request is satisfied
24203 * @user_data: (closure): the data to pass to callback function
24205 * Request an asynchronous skip of @count bytes from the stream.
24206 * When the operation is finished @callback will be called.
24207 * You can then call g_input_stream_skip_finish() to get the result
24208 * of the operation.
24210 * During an async request no other sync and async calls are allowed,
24211 * and will result in %G_IO_ERROR_PENDING errors.
24213 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
24215 * On success, the number of bytes skipped will be passed to the callback.
24216 * It is not an error if this is not the same as the requested size, as it
24217 * can happen e.g. near the end of a file, but generally we try to skip
24218 * as many bytes as requested. Zero is returned on end of file
24219 * (or if @count is zero), but never otherwise.
24221 * Any outstanding i/o request with higher priority (lower numerical value)
24222 * will be executed before an outstanding request with lower priority.
24223 * Default priority is %G_PRIORITY_DEFAULT.
24225 * The asynchronous methods have a default fallback that uses threads to
24226 * implement asynchronicity, so they are optional for inheriting classes.
24227 * However, if you override one, you must override all.
24232 * g_input_stream_skip_finish:
24233 * @stream: a #GInputStream.
24234 * @result: a #GAsyncResult.
24235 * @error: a #GError location to store the error occurring, or %NULL to
24238 * Finishes a stream skip operation.
24240 * Returns: the size of the bytes skipped, or %-1 on error.
24245 * g_io_error_from_errno:
24246 * @err_no: Error number as defined in errno.h.
24248 * Converts errno.h error codes into GIO error codes.
24250 * Returns: #GIOErrorEnum value for the given errno.h error number.
24255 * g_io_error_from_win32_error:
24256 * @error_code: Windows error number.
24258 * Converts some common error codes into GIO error codes. The
24259 * fallback value G_IO_ERROR_FAILED is returned for error codes not
24262 * Returns: #GIOErrorEnum value for the given error number.
24268 * g_io_error_quark:
24270 * Gets the GIO Error Quark.
24272 * Returns: a #GQuark.
24277 * g_io_extension_get_name:
24278 * @extension: a #GIOExtension
24280 * Gets the name under which @extension was registered.
24282 * Note that the same type may be registered as extension
24283 * for multiple extension points, under different names.
24285 * Returns: the name of @extension.
24290 * g_io_extension_get_priority:
24291 * @extension: a #GIOExtension
24293 * Gets the priority with which @extension was registered.
24295 * Returns: the priority of @extension
24300 * g_io_extension_get_type:
24301 * @extension: a #GIOExtension
24303 * Gets the type associated with @extension.
24305 * Returns: the type of @extension
24310 * g_io_extension_point_get_extension_by_name:
24311 * @extension_point: a #GIOExtensionPoint
24312 * @name: the name of the extension to get
24314 * Finds a #GIOExtension for an extension point by name.
24316 * Returns: (transfer none): the #GIOExtension for @extension_point that has the
24317 * given name, or %NULL if there is no extension with that name
24322 * g_io_extension_point_get_extensions:
24323 * @extension_point: a #GIOExtensionPoint
24325 * Gets a list of all extensions that implement this extension point.
24326 * The list is sorted by priority, beginning with the highest priority.
24328 * Returns: (element-type GIOExtension) (transfer none): a #GList of
24329 * #GIOExtension<!-- -->s. The list is owned by GIO and should not be
24335 * g_io_extension_point_get_required_type:
24336 * @extension_point: a #GIOExtensionPoint
24338 * Gets the required type for @extension_point.
24340 * Returns: the #GType that all implementations must have,
24341 * or #G_TYPE_INVALID if the extension point has no required type
24346 * g_io_extension_point_implement:
24347 * @extension_point_name: the name of the extension point
24348 * @type: the #GType to register as extension
24349 * @extension_name: the name for the extension
24350 * @priority: the priority for the extension
24352 * Registers @type as extension for the extension point with name
24353 * @extension_point_name.
24355 * If @type has already been registered as an extension for this
24356 * extension point, the existing #GIOExtension object is returned.
24358 * Returns: (transfer none): a #GIOExtension object for #GType
24363 * g_io_extension_point_lookup:
24364 * @name: the name of the extension point
24366 * Looks up an existing extension point.
24368 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
24369 * is no registered extension point with the given name.
24374 * g_io_extension_point_register:
24375 * @name: The name of the extension point
24377 * Registers an extension point.
24379 * Returns: (transfer none): the new #GIOExtensionPoint. This object is
24380 * owned by GIO and should not be freed.
24385 * g_io_extension_point_set_required_type:
24386 * @extension_point: a #GIOExtensionPoint
24387 * @type: the #GType to require
24389 * Sets the required type for @extension_point to @type.
24390 * All implementations must henceforth have this type.
24395 * g_io_extension_ref_class:
24396 * @extension: a #GIOExtension
24398 * Gets a reference to the class for the type that is
24399 * associated with @extension.
24401 * Returns: (transfer full): the #GTypeClass for the type of @extension
24407 * @filename: filename of the shared library module.
24409 * Creates a new GIOModule that will load the specific
24410 * shared library when in use.
24412 * Returns: a #GIOModule from given @filename,
24413 * or %NULL on error.
24418 * g_io_module_scope_block:
24419 * @scope: a module loading scope
24420 * @basename: the basename to block
24422 * Block modules with the given @basename from being loaded when
24423 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
24424 * or g_io_modules_load_all_in_directory_with_scope().
24431 * g_io_module_scope_free:
24432 * @scope: a module loading scope
24434 * Free a module scope.
24441 * g_io_module_scope_new:
24442 * @flags: flags for the new scope
24444 * Create a new scope for loading of IO modules. A scope can be used for
24445 * blocking duplicate modules, or blocking a module you don't want to load.
24447 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
24448 * which have the same base name as a module that has already been seen
24451 * Returns: (transfer full): the new module scope
24457 * g_io_modules_load_all_in_directory:
24458 * @dirname: pathname for a directory containing modules to load.
24460 * Loads all the modules in the specified directory.
24462 * If don't require all modules to be initialized (and thus registering
24463 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
24464 * which allows delayed/lazy loading of modules.
24466 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
24467 * from the directory,
24468 * All the modules are loaded into memory, if you want to
24469 * unload them (enabling on-demand loading) you must call
24470 * g_type_module_unuse() on all the modules. Free the list
24471 * with g_list_free().
24476 * g_io_modules_load_all_in_directory_with_scope:
24477 * @dirname: pathname for a directory containing modules to load.
24478 * @scope: a scope to use when scanning the modules.
24480 * Loads all the modules in the specified directory.
24482 * If don't require all modules to be initialized (and thus registering
24483 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
24484 * which allows delayed/lazy loading of modules.
24486 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
24487 * from the directory,
24488 * All the modules are loaded into memory, if you want to
24489 * unload them (enabling on-demand loading) you must call
24490 * g_type_module_unuse() on all the modules. Free the list
24491 * with g_list_free().
24497 * g_io_modules_scan_all_in_directory:
24498 * @dirname: pathname for a directory containing modules to scan.
24500 * Scans all the modules in the specified directory, ensuring that
24501 * any extension point implemented by a module is registered.
24503 * This may not actually load and initialize all the types in each
24504 * module, some modules may be lazily loaded and initialized when
24505 * an extension point it implementes is used with e.g.
24506 * g_io_extension_point_get_extensions() or
24507 * g_io_extension_point_get_extension_by_name().
24509 * If you need to guarantee that all types are loaded in all the modules,
24510 * use g_io_modules_load_all_in_directory().
24517 * g_io_modules_scan_all_in_directory_with_scope:
24518 * @dirname: pathname for a directory containing modules to scan.
24519 * @scope: a scope to use when scanning the modules
24521 * Scans all the modules in the specified directory, ensuring that
24522 * any extension point implemented by a module is registered.
24524 * This may not actually load and initialize all the types in each
24525 * module, some modules may be lazily loaded and initialized when
24526 * an extension point it implementes is used with e.g.
24527 * g_io_extension_point_get_extensions() or
24528 * g_io_extension_point_get_extension_by_name().
24530 * If you need to guarantee that all types are loaded in all the modules,
24531 * use g_io_modules_load_all_in_directory().
24538 * g_io_scheduler_cancel_all_jobs:
24540 * Cancels all cancellable I/O jobs.
24542 * A job is cancellable if a #GCancellable was passed into
24543 * g_io_scheduler_push_job().
24545 * Deprecated: You should never call this function, since you don't
24546 * know how other libraries in your program might be making use of
24552 * g_io_scheduler_job_send_to_mainloop:
24553 * @job: a #GIOSchedulerJob
24554 * @func: a #GSourceFunc callback that will be called in the original thread
24555 * @user_data: data to pass to @func
24556 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24558 * Used from an I/O job to send a callback to be run in the thread
24559 * that the job was started from, waiting for the result (and thus
24560 * blocking the I/O job).
24562 * Returns: The return value of @func
24563 * Deprecated: Use g_main_context_invoke().
24568 * g_io_scheduler_job_send_to_mainloop_async:
24569 * @job: a #GIOSchedulerJob
24570 * @func: a #GSourceFunc callback that will be called in the original thread
24571 * @user_data: data to pass to @func
24572 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24574 * Used from an I/O job to send a callback to be run asynchronously in
24575 * the thread that the job was started from. The callback will be run
24576 * when the main loop is available, but at that time the I/O job might
24577 * have finished. The return value from the callback is ignored.
24579 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
24580 * on to this function you have to ensure that it is not freed before
24581 * @func is called, either by passing %NULL as @notify to
24582 * g_io_scheduler_push_job() or by using refcounting for @user_data.
24584 * Deprecated: Use g_main_context_invoke().
24589 * g_io_scheduler_push_job:
24590 * @job_func: a #GIOSchedulerJobFunc.
24591 * @user_data: data to pass to @job_func
24592 * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
24593 * @io_priority: the <link linkend="io-priority">I/O priority</link>
24595 * @cancellable: optional #GCancellable object, %NULL to ignore.
24597 * Schedules the I/O job to run in another thread.
24599 * @notify will be called on @user_data after @job_func has returned,
24600 * regardless whether the job was cancelled or has run to completion.
24602 * If @cancellable is not %NULL, it can be used to cancel the I/O job
24603 * by calling g_cancellable_cancel() or by calling
24604 * g_io_scheduler_cancel_all_jobs().
24606 * Deprecated: use #GThreadPool or g_task_run_in_thread()
24611 * g_io_stream_clear_pending:
24612 * @stream: a #GIOStream
24614 * Clears the pending flag on @stream.
24621 * g_io_stream_close:
24622 * @stream: a #GIOStream
24623 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
24624 * @error: location to store the error occurring, or %NULL to ignore
24626 * Closes the stream, releasing resources related to it. This will also
24627 * closes the individual input and output streams, if they are not already
24630 * Once the stream is closed, all other operations will return
24631 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
24634 * Closing a stream will automatically flush any outstanding buffers
24637 * Streams will be automatically closed when the last reference
24638 * is dropped, but you might want to call this function to make sure
24639 * resources are released as early as possible.
24641 * Some streams might keep the backing store of the stream (e.g. a file
24642 * descriptor) open after the stream is closed. See the documentation for
24643 * the individual stream for details.
24645 * On failure the first error that happened will be reported, but the
24646 * close operation will finish as much as possible. A stream that failed
24647 * to close will still return %G_IO_ERROR_CLOSED for all operations.
24648 * Still, it is important to check and report the error to the user,
24649 * otherwise there might be a loss of data as all data might not be written.
24651 * If @cancellable is not NULL, then the operation can be cancelled by
24652 * triggering the cancellable object from another thread. If the operation
24653 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24654 * Cancelling a close will still leave the stream closed, but some streams
24655 * can use a faster close that doesn't block to e.g. check errors.
24657 * The default implementation of this method just calls close on the
24658 * individual input/output streams.
24660 * Returns: %TRUE on success, %FALSE on failure
24666 * g_io_stream_close_async:
24667 * @stream: a #GIOStream
24668 * @io_priority: the io priority of the request
24669 * @cancellable: (allow-none): optional cancellable object
24670 * @callback: (scope async): callback to call when the request is satisfied
24671 * @user_data: (closure): the data to pass to callback function
24673 * Requests an asynchronous close of the stream, releasing resources
24674 * related to it. When the operation is finished @callback will be
24675 * called. You can then call g_io_stream_close_finish() to get
24676 * the result of the operation.
24678 * For behaviour details see g_io_stream_close().
24680 * The asynchronous methods have a default fallback that uses threads
24681 * to implement asynchronicity, so they are optional for inheriting
24682 * classes. However, if you override one you must override all.
24689 * g_io_stream_close_finish:
24690 * @stream: a #GIOStream
24691 * @result: a #GAsyncResult
24692 * @error: a #GError location to store the error occurring, or %NULL to
24697 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
24703 * g_io_stream_get_input_stream:
24704 * @stream: a #GIOStream
24706 * Gets the input stream for this object. This is used
24709 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
24716 * g_io_stream_get_output_stream:
24717 * @stream: a #GIOStream
24719 * Gets the output stream for this object. This is used for
24722 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
24729 * g_io_stream_has_pending:
24730 * @stream: a #GIOStream
24732 * Checks if a stream has pending actions.
24734 * Returns: %TRUE if @stream has pending actions.
24740 * g_io_stream_is_closed:
24741 * @stream: a #GIOStream
24743 * Checks if a stream is closed.
24745 * Returns: %TRUE if the stream is closed.
24751 * g_io_stream_set_pending:
24752 * @stream: a #GIOStream
24753 * @error: a #GError location to store the error occurring, or %NULL to
24756 * Sets @stream to have actions pending. If the pending flag is
24757 * already set or @stream is closed, it will return %FALSE and set
24760 * Returns: %TRUE if pending was previously unset and is now set.
24766 * g_io_stream_splice_async:
24767 * @stream1: a #GIOStream.
24768 * @stream2: a #GIOStream.
24769 * @flags: a set of #GIOStreamSpliceFlags.
24770 * @io_priority: the io priority of the request.
24771 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24772 * @callback: (scope async): a #GAsyncReadyCallback.
24773 * @user_data: (closure): user data passed to @callback.
24775 * Asyncronously splice the output stream of @stream1 to the input stream of
24776 * @stream2, and splice the output stream of @stream2 to the input stream of
24779 * When the operation is finished @callback will be called.
24780 * You can then call g_io_stream_splice_finish() to get the
24781 * result of the operation.
24788 * g_io_stream_splice_finish:
24789 * @result: a #GAsyncResult.
24790 * @error: a #GError location to store the error occurring, or %NULL to
24793 * Finishes an asynchronous io stream splice operation.
24795 * Returns: %TRUE on success, %FALSE otherwise.
24801 * g_keyfile_settings_backend_new:
24802 * @filename: the filename of the keyfile
24803 * @root_path: the path under which all settings keys appear
24804 * @root_group: (allow-none): the group name corresponding to
24805 * @root_path, or %NULL
24807 * Creates a keyfile-backed #GSettingsBackend.
24809 * The filename of the keyfile to use is given by @filename.
24811 * All settings read to or written from the backend must fall under the
24812 * path given in @root_path (which must start and end with a slash and
24813 * not contain two consecutive slashes). @root_path may be "/".
24815 * If @root_group is non-%NULL then it specifies the name of the keyfile
24816 * group used for keys that are written directly below @root_path. For
24817 * example, if @root_path is "/apps/example/" and @root_group is
24818 * "toplevel", then settings the key "/apps/example/enabled" to a value
24819 * of %TRUE will cause the following to appear in the keyfile:
24826 * If @root_group is %NULL then it is not permitted to store keys
24827 * directly below the @root_path.
24829 * For keys not stored directly below @root_path (ie: in a sub-path),
24830 * the name of the subpath (with the final slash stripped) is used as
24831 * the name of the keyfile group. To continue the example, if
24832 * "/apps/example/profiles/default/font-size" were set to
24833 * 12 then the following would appear in the keyfile:
24836 * [profiles/default]
24840 * The backend will refuse writes (and return writability as being
24841 * %FALSE) for keys outside of @root_path and, in the event that
24842 * @root_group is %NULL, also for keys directly under @root_path.
24843 * Writes will also be refused if the backend detects that it has the
24844 * inability to rewrite the keyfile (ie: the containing directory is not
24847 * There is no checking done for your key namespace clashing with the
24848 * syntax of the key file format. For example, if you have '[' or ']'
24849 * characters in your path names or '=' in your key names you may be in
24852 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
24857 * g_loadable_icon_load:
24858 * @icon: a #GLoadableIcon.
24859 * @size: an integer.
24860 * @type: (out) (allow-none): a location to store the type of the
24861 * loaded icon, %NULL to ignore.
24862 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24863 * @error: a #GError location to store the error occurring, or %NULL to
24866 * Loads a loadable icon. For the asynchronous version of this function,
24867 * see g_loadable_icon_load_async().
24869 * Returns: (transfer full): a #GInputStream to read the icon from.
24874 * g_loadable_icon_load_async:
24875 * @icon: a #GLoadableIcon.
24876 * @size: an integer.
24877 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24878 * @callback: (scope async): a #GAsyncReadyCallback to call when the
24879 * request is satisfied
24880 * @user_data: (closure): the data to pass to callback function
24882 * Loads an icon asynchronously. To finish this function, see
24883 * g_loadable_icon_load_finish(). For the synchronous, blocking
24884 * version of this function, see g_loadable_icon_load().
24889 * g_loadable_icon_load_finish:
24890 * @icon: a #GLoadableIcon.
24891 * @res: a #GAsyncResult.
24892 * @type: (out) (allow-none): a location to store the type of the
24893 * loaded icon, %NULL to ignore.
24894 * @error: a #GError location to store the error occurring, or %NULL to
24897 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
24899 * Returns: (transfer full): a #GInputStream to read the icon from.
24906 * Returns a new #GVfs handle for a local vfs.
24908 * Returns: a new #GVfs handle.
24913 * g_memory_input_stream_add_bytes:
24914 * @stream: a #GMemoryInputStream
24915 * @bytes: input data
24917 * Appends @bytes to data that can be read from the input stream.
24924 * g_memory_input_stream_add_data:
24925 * @stream: a #GMemoryInputStream
24926 * @data: (array length=len) (element-type guint8) (transfer full): input data
24927 * @len: length of the data, may be -1 if @data is a nul-terminated string
24928 * @destroy: (allow-none): function that is called to free @data, or %NULL
24930 * Appends @data to data that can be read from the input stream
24935 * g_memory_input_stream_new:
24937 * Creates a new empty #GMemoryInputStream.
24939 * Returns: a new #GInputStream
24944 * g_memory_input_stream_new_from_bytes:
24945 * @bytes: a #GBytes
24947 * Creates a new #GMemoryInputStream with data from the given @bytes.
24949 * Returns: new #GInputStream read from @bytes
24955 * g_memory_input_stream_new_from_data:
24956 * @data: (array length=len) (element-type guint8) (transfer full): input data
24957 * @len: length of the data, may be -1 if @data is a nul-terminated string
24958 * @destroy: (allow-none): function that is called to free @data, or %NULL
24960 * Creates a new #GMemoryInputStream with data in memory of a given size.
24962 * Returns: new #GInputStream read from @data of @len bytes.
24967 * g_memory_output_stream_get_data:
24968 * @ostream: a #GMemoryOutputStream
24970 * Gets any loaded data from the @ostream.
24972 * Note that the returned pointer may become invalid on the next
24973 * write or truncate operation on the stream.
24975 * Returns: (transfer none): pointer to the stream's data
24980 * g_memory_output_stream_get_data_size:
24981 * @ostream: a #GMemoryOutputStream
24983 * Returns the number of bytes from the start up to including the last
24984 * byte written in the stream that has not been truncated away.
24986 * Returns: the number of bytes written to the stream
24992 * g_memory_output_stream_get_size:
24993 * @ostream: a #GMemoryOutputStream
24995 * Gets the size of the currently allocated data area (available from
24996 * g_memory_output_stream_get_data()).
24998 * You probably don't want to use this function on resizable streams.
24999 * See g_memory_output_stream_get_data_size() instead. For resizable
25000 * streams the size returned by this function is an implementation
25001 * detail and may be change at any time in response to operations on the
25004 * If the stream is fixed-sized (ie: no realloc was passed to
25005 * g_memory_output_stream_new()) then this is the maximum size of the
25006 * stream and further writes will return %G_IO_ERROR_NO_SPACE.
25008 * In any case, if you want the number of bytes currently written to the
25009 * stream, use g_memory_output_stream_get_data_size().
25011 * Returns: the number of bytes allocated for the data buffer
25016 * g_memory_output_stream_new: (skip)
25017 * @data: (allow-none): pointer to a chunk of memory to use, or %NULL
25018 * @size: the size of @data
25019 * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc())
25020 * to be called when @data needs to be grown, or %NULL
25021 * @destroy_function: (allow-none): a function to be called on @data when the stream is
25022 * finalized, or %NULL
25024 * Creates a new #GMemoryOutputStream.
25026 * In most cases this is not the function you want. See
25027 * g_memory_output_stream_new_resizable() instead.
25029 * If @data is non-%NULL, the stream will use that for its internal storage.
25031 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
25032 * storage when necessary and the stream will be considered resizable.
25033 * In that case, the stream will start out being (conceptually) empty.
25034 * @size is used only as a hint for how big @data is. Specifically,
25035 * seeking to the end of a newly-created stream will seek to zero, not
25036 * @size. Seeking past the end of the stream and then writing will
25037 * introduce a zero-filled gap.
25039 * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to
25040 * the end will seek to @size exactly. Writing past the end will give
25041 * an 'out of space' error. Attempting to seek past the end will fail.
25042 * Unlike the resizable case, seeking to an offset within the stream and
25043 * writing will preserve the bytes passed in as @data before that point
25044 * and will return them as part of g_memory_output_stream_steal_data().
25045 * If you intend to seek you should probably therefore ensure that @data
25046 * is properly initialised.
25048 * It is probably only meaningful to provide @data and @size in the case
25049 * that you want a fixed-sized stream. Put another way: if @realloc_fn
25050 * is non-%NULL then it makes most sense to give @data as %NULL and
25051 * @size as 0 (allowing #GMemoryOutputStream to do the initial
25052 * allocation for itself).
25055 * /* a stream that can grow */
25056 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
25058 * /* another stream that can grow */
25059 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
25061 * /* a fixed-size stream */
25062 * data = malloc (200);
25063 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
25066 * Returns: A newly created #GMemoryOutputStream object.
25071 * g_memory_output_stream_new_resizable:
25073 * Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
25074 * for memory allocation.
25081 * g_memory_output_stream_steal_as_bytes:
25082 * @ostream: a #GMemoryOutputStream
25084 * Returns data from the @ostream as a #GBytes. @ostream must be
25085 * closed before calling this function.
25087 * Returns: (transfer full): the stream's data
25093 * g_memory_output_stream_steal_data:
25094 * @ostream: a #GMemoryOutputStream
25096 * Gets any loaded data from the @ostream. Ownership of the data
25097 * is transferred to the caller; when no longer needed it must be
25098 * freed using the free function set in @ostream's
25099 * #GMemoryOutputStream:destroy-function property.
25101 * @ostream must be closed before calling this function.
25103 * Returns: (transfer full): the stream's data
25109 * g_memory_settings_backend_new:
25111 * Creates a memory-backed #GSettingsBackend.
25113 * This backend allows changes to settings, but does not write them
25114 * to any backing storage, so the next time you run your application,
25115 * the memory backend will start out with the default values again.
25117 * Returns: (transfer full): a newly created #GSettingsBackend
25125 * @label: (allow-none): the section label, or %NULL
25126 * @detailed_action: (allow-none): the detailed action string, or %NULL
25128 * Convenience function for appending a normal menu item to the end of
25129 * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
25130 * flexible alternative.
25137 * g_menu_append_item:
25139 * @item: a #GMenuItem to append
25141 * Appends @item to the end of @menu.
25143 * See g_menu_insert_item() for more information.
25150 * g_menu_append_section:
25152 * @label: (allow-none): the section label, or %NULL
25153 * @section: a #GMenuModel with the items of the section
25155 * Convenience function for appending a section menu item to the end of
25156 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
25157 * more flexible alternative.
25164 * g_menu_append_submenu:
25166 * @label: (allow-none): the section label, or %NULL
25167 * @submenu: a #GMenuModel with the items of the submenu
25169 * Convenience function for appending a submenu menu item to the end of
25170 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
25171 * more flexible alternative.
25178 * g_menu_attribute_iter_get_name:
25179 * @iter: a #GMenuAttributeIter
25181 * Gets the name of the attribute at the current iterator position, as
25184 * The iterator is not advanced.
25186 * Returns: the name of the attribute
25192 * g_menu_attribute_iter_get_next:
25193 * @iter: a #GMenuAttributeIter
25194 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
25195 * @value: (out) (allow-none) (transfer full): the attribute value
25197 * This function combines g_menu_attribute_iter_next() with
25198 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
25200 * First the iterator is advanced to the next (possibly first) attribute.
25201 * If that fails, then %FALSE is returned and there are no other
25204 * If successful, @name and @value are set to the name and value of the
25205 * attribute that has just been advanced to. At this point,
25206 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
25207 * return the same values again.
25209 * The value returned in @name remains valid for as long as the iterator
25210 * remains at the current position. The value returned in @value must
25211 * be unreffed using g_variant_unref() when it is no longer in use.
25213 * Returns: %TRUE on success, or %FALSE if there is no additional
25220 * g_menu_attribute_iter_get_value:
25221 * @iter: a #GMenuAttributeIter
25223 * Gets the value of the attribute at the current iterator position.
25225 * The iterator is not advanced.
25227 * Returns: (transfer full): the value of the current attribute
25233 * g_menu_attribute_iter_next:
25234 * @iter: a #GMenuAttributeIter
25236 * Attempts to advance the iterator to the next (possibly first)
25239 * %TRUE is returned on success, or %FALSE if there are no more
25242 * You must call this function when you first acquire the iterator
25243 * to advance it to the first attribute (and determine if the first
25244 * attribute exists at all).
25246 * Returns: %TRUE on success, or %FALSE when there are no more attributes
25255 * Marks @menu as frozen.
25257 * After the menu is frozen, it is an error to attempt to make any
25258 * changes to it. In effect this means that the #GMenu API must no
25261 * This function causes g_menu_model_is_mutable() to begin returning
25262 * %FALSE, which has some positive performance implications.
25271 * @position: the position at which to insert the item
25272 * @label: (allow-none): the section label, or %NULL
25273 * @detailed_action: (allow-none): the detailed action string, or %NULL
25275 * Convenience function for inserting a normal menu item into @menu.
25276 * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
25284 * g_menu_insert_item:
25286 * @position: the position at which to insert the item
25287 * @item: the #GMenuItem to insert
25289 * Inserts @item into @menu.
25291 * The "insertion" is actually done by copying all of the attribute and
25292 * link values of @item and using them to form a new item within @menu.
25293 * As such, @item itself is not really inserted, but rather, a menu item
25294 * that is exactly the same as the one presently described by @item.
25296 * This means that @item is essentially useless after the insertion
25297 * occurs. Any changes you make to it are ignored unless it is inserted
25298 * again (at which point its updated values will be copied).
25300 * You should probably just free @item once you're done.
25302 * There are many convenience functions to take care of common cases.
25303 * See g_menu_insert(), g_menu_insert_section() and
25304 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
25305 * each of these functions.
25312 * g_menu_insert_section:
25314 * @position: the position at which to insert the item
25315 * @label: (allow-none): the section label, or %NULL
25316 * @section: a #GMenuModel with the items of the section
25318 * Convenience function for inserting a section menu item into @menu.
25319 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
25320 * flexible alternative.
25327 * g_menu_insert_submenu:
25329 * @position: the position at which to insert the item
25330 * @label: (allow-none): the section label, or %NULL
25331 * @submenu: a #GMenuModel with the items of the submenu
25333 * Convenience function for inserting a submenu menu item into @menu.
25334 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
25335 * flexible alternative.
25342 * g_menu_item_get_attribute:
25343 * @menu_item: a #GMenuItem
25344 * @attribute: the attribute name to query
25345 * @format_string: a #GVariant format string
25346 * @...: positional parameters, as per @format_string
25348 * Queries the named @attribute on @menu_item.
25350 * If the attribute exists and matches the #GVariantType corresponding
25351 * to @format_string then @format_string is used to deconstruct the
25352 * value into the positional parameters and %TRUE is returned.
25354 * If the attribute does not exist, or it does exist but has the wrong
25355 * type, then the positional parameters are ignored and %FALSE is
25358 * Returns: %TRUE if the named attribute was found with the expected
25365 * g_menu_item_get_attribute_value:
25366 * @menu_item: a #GMenuItem
25367 * @attribute: the attribute name to query
25368 * @expected_type: (allow-none): the expected type of the attribute
25370 * Queries the named @attribute on @menu_item.
25372 * If @expected_type is specified and the attribute does not have this
25373 * type, %NULL is returned. %NULL is also returned if the attribute
25374 * simply does not exist.
25376 * Returns: (transfer full): the attribute value, or %NULL
25382 * g_menu_item_get_link:
25383 * @menu_item: a #GMenuItem
25384 * @link: the link name to query
25386 * Queries the named @link on @menu_item.
25388 * Returns: (transfer full): the link, or %NULL
25395 * @label: (allow-none): the section label, or %NULL
25396 * @detailed_action: (allow-none): the detailed action string, or %NULL
25398 * Creates a new #GMenuItem.
25400 * If @label is non-%NULL it is used to set the "label" attribute of the
25403 * If @detailed_action is non-%NULL it is used to set the "action" and
25404 * possibly the "target" attribute of the new item. See
25405 * g_menu_item_set_detailed_action() for more information.
25407 * Returns: a new #GMenuItem
25413 * g_menu_item_new_from_model:
25414 * @model: a #GMenuModel
25415 * @item_index: the index of an item in @model
25417 * Creates a #GMenuItem as an exact copy of an existing menu item in a
25420 * @item_index must be valid (ie: be sure to call
25421 * g_menu_model_get_n_items() first).
25423 * Returns: a new #GMenuItem.
25429 * g_menu_item_new_section:
25430 * @label: (allow-none): the section label, or %NULL
25431 * @section: a #GMenuModel with the items of the section
25433 * Creates a new #GMenuItem representing a section.
25435 * This is a convenience API around g_menu_item_new() and
25436 * g_menu_item_set_section().
25438 * The effect of having one menu appear as a section of another is
25439 * exactly as it sounds: the items from @section become a direct part of
25440 * the menu that @menu_item is added to.
25442 * Visual separation is typically displayed between two non-empty
25443 * sections. If @label is non-%NULL then it will be encorporated into
25444 * this visual indication. This allows for labeled subsections of a
25447 * As a simple example, consider a typical "Edit" menu from a simple
25448 * program. It probably contains an "Undo" and "Redo" item, followed by
25449 * a separator, followed by "Cut", "Copy" and "Paste".
25451 * This would be accomplished by creating three #GMenu instances. The
25452 * first would be populated with the "Undo" and "Redo" items, and the
25453 * second with the "Cut", "Copy" and "Paste" items. The first and
25454 * second menus would then be added as submenus of the third. In XML
25455 * format, this would look something like the following:
25457 * <informalexample><programlisting><![CDATA[
25458 * <menu id='edit-menu'>
25460 * <item label='Undo'/>
25461 * <item label='Redo'/>
25464 * <item label='Cut'/>
25465 * <item label='Copy'/>
25466 * <item label='Paste'/>
25469 * ]]></programlisting></informalexample>
25471 * The following example is exactly equivalent. It is more illustrative
25472 * of the exact relationship between the menus and items (keeping in
25473 * mind that the 'link' element defines a new menu that is linked to the
25474 * containing one). The style of the second example is more verbose and
25475 * difficult to read (and therefore not recommended except for the
25476 * purpose of understanding what is really going on).
25478 * <informalexample><programlisting><![CDATA[
25479 * <menu id='edit-menu'>
25481 * <link name='section'>
25482 * <item label='Undo'/>
25483 * <item label='Redo'/>
25487 * <link name='section'>
25488 * <item label='Cut'/>
25489 * <item label='Copy'/>
25490 * <item label='Paste'/>
25494 * ]]></programlisting></informalexample>
25496 * Returns: a new #GMenuItem
25502 * g_menu_item_new_submenu:
25503 * @label: (allow-none): the section label, or %NULL
25504 * @submenu: a #GMenuModel with the items of the submenu
25506 * Creates a new #GMenuItem representing a submenu.
25508 * This is a convenience API around g_menu_item_new() and
25509 * g_menu_item_set_submenu().
25511 * Returns: a new #GMenuItem
25517 * g_menu_item_set_action_and_target:
25518 * @menu_item: a #GMenuItem
25519 * @action: (allow-none): the name of the action for this item
25520 * @format_string: (allow-none): a GVariant format string
25521 * @...: positional parameters, as per @format_string
25523 * Sets or unsets the "action" and "target" attributes of @menu_item.
25525 * If @action is %NULL then both the "action" and "target" attributes
25526 * are unset (and @format_string is ignored along with the positional
25529 * If @action is non-%NULL then the "action" attribute is set.
25530 * @format_string is then inspected. If it is non-%NULL then the proper
25531 * position parameters are collected to create a #GVariant instance to
25532 * use as the target value. If it is %NULL then the positional
25533 * parameters are ignored and the "target" attribute is unset.
25535 * See also g_menu_item_set_action_and_target_value() for an equivalent
25536 * call that directly accepts a #GVariant. See
25537 * g_menu_item_set_detailed_action() for a more convenient version that
25538 * works with string-typed targets.
25540 * See also g_menu_item_set_action_and_target_value() for a
25541 * description of the semantics of the action and target attributes.
25548 * g_menu_item_set_action_and_target_value:
25549 * @menu_item: a #GMenuItem
25550 * @action: (allow-none): the name of the action for this item
25551 * @target_value: (allow-none): a #GVariant to use as the action target
25553 * Sets or unsets the "action" and "target" attributes of @menu_item.
25555 * If @action is %NULL then both the "action" and "target" attributes
25556 * are unset (and @target_value is ignored).
25558 * If @action is non-%NULL then the "action" attribute is set. The
25559 * "target" attribute is then set to the value of @target_value if it is
25560 * non-%NULL or unset otherwise.
25562 * Normal menu items (ie: not submenu, section or other custom item
25563 * types) are expected to have the "action" attribute set to identify
25564 * the action that they are associated with. The state type of the
25565 * action help to determine the disposition of the menu item. See
25566 * #GAction and #GActionGroup for an overview of actions.
25568 * In general, clicking on the menu item will result in activation of
25569 * the named action with the "target" attribute given as the parameter
25570 * to the action invocation. If the "target" attribute is not set then
25571 * the action is invoked with no parameter.
25573 * If the action has no state then the menu item is usually drawn as a
25574 * plain menu item (ie: with no additional decoration).
25576 * If the action has a boolean state then the menu item is usually drawn
25577 * as a toggle menu item (ie: with a checkmark or equivalent
25578 * indication). The item should be marked as 'toggled' or 'checked'
25579 * when the boolean state is %TRUE.
25581 * If the action has a string state then the menu item is usually drawn
25582 * as a radio menu item (ie: with a radio bullet or equivalent
25583 * indication). The item should be marked as 'selected' when the string
25584 * state is equal to the value of the @target property.
25586 * See g_menu_item_set_action_and_target() or
25587 * g_menu_item_set_detailed_action() for two equivalent calls that are
25588 * probably more convenient for most uses.
25595 * g_menu_item_set_attribute:
25596 * @menu_item: a #GMenuItem
25597 * @attribute: the attribute to set
25598 * @format_string: (allow-none): a #GVariant format string, or %NULL
25599 * @...: positional parameters, as per @format_string
25601 * Sets or unsets an attribute on @menu_item.
25603 * The attribute to set or unset is specified by @attribute. This
25604 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
25605 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
25607 * Attribute names are restricted to lowercase characters, numbers
25608 * and '-'. Furthermore, the names must begin with a lowercase character,
25609 * must not end with a '-', and must not contain consecutive dashes.
25611 * If @format_string is non-%NULL then the proper position parameters
25612 * are collected to create a #GVariant instance to use as the attribute
25613 * value. If it is %NULL then the positional parameterrs are ignored
25614 * and the named attribute is unset.
25616 * See also g_menu_item_set_attribute_value() for an equivalent call
25617 * that directly accepts a #GVariant.
25624 * g_menu_item_set_attribute_value:
25625 * @menu_item: a #GMenuItem
25626 * @attribute: the attribute to set
25627 * @value: (allow-none): a #GVariant to use as the value, or %NULL
25629 * Sets or unsets an attribute on @menu_item.
25631 * The attribute to set or unset is specified by @attribute. This
25632 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
25633 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
25635 * Attribute names are restricted to lowercase characters, numbers
25636 * and '-'. Furthermore, the names must begin with a lowercase character,
25637 * must not end with a '-', and must not contain consecutive dashes.
25639 * must consist only of lowercase
25640 * ASCII characters, digits and '-'.
25642 * If @value is non-%NULL then it is used as the new value for the
25643 * attribute. If @value is %NULL then the attribute is unset. If
25644 * the @value #GVariant is floating, it is consumed.
25646 * See also g_menu_item_set_attribute() for a more convenient way to do
25654 * g_menu_item_set_detailed_action:
25655 * @menu_item: a #GMenuItem
25656 * @detailed_action: the "detailed" action string
25658 * Sets the "action" and possibly the "target" attribute of @menu_item.
25660 * The format of @detailed_action is the same format parsed by
25661 * g_action_parse_detailed_name().
25663 * See g_menu_item_set_action_and_target() or
25664 * g_menu_item_set_action_and_target_value() for more flexible (but
25665 * slightly less convenient) alternatives.
25667 * See also g_menu_item_set_action_and_target_value() for a description of
25668 * the semantics of the action and target attributes.
25675 * g_menu_item_set_icon:
25676 * @menu_item: a #GMenuItem
25677 * @icon: a #GIcon, or %NULL
25679 * Sets (or unsets) the icon on @menu_item.
25681 * This call is the same as calling g_icon_serialize() and using the
25682 * result as the value to g_menu_item_set_attribute_value() for
25683 * %G_MENU_ATTRIBUTE_ICON.
25685 * This API is only intended for use with "noun" menu items; things like
25686 * bookmarks or applications in an "Open With" menu. Don't use it on
25687 * menu items corresponding to verbs (eg: stock icons for 'Save' or
25690 * If @icon is %NULL then the icon is unset.
25697 * g_menu_item_set_label:
25698 * @menu_item: a #GMenuItem
25699 * @label: (allow-none): the label to set, or %NULL to unset
25701 * Sets or unsets the "label" attribute of @menu_item.
25703 * If @label is non-%NULL it is used as the label for the menu item. If
25704 * it is %NULL then the label attribute is unset.
25711 * g_menu_item_set_link:
25712 * @menu_item: a #GMenuItem
25713 * @link: type of link to establish or unset
25714 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
25716 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
25718 * Links are used to establish a relationship between a particular menu
25719 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
25720 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
25721 * is used to create a section. Other types of link can be used, but there
25722 * is no guarantee that clients will be able to make sense of them.
25723 * Link types are restricted to lowercase characters, numbers
25724 * and '-'. Furthermore, the names must begin with a lowercase character,
25725 * must not end with a '-', and must not contain consecutive dashes.
25732 * g_menu_item_set_section:
25733 * @menu_item: a #GMenuItem
25734 * @section: (allow-none): a #GMenuModel, or %NULL
25736 * Sets or unsets the "section" link of @menu_item to @section.
25738 * The effect of having one menu appear as a section of another is
25739 * exactly as it sounds: the items from @section become a direct part of
25740 * the menu that @menu_item is added to. See g_menu_item_new_section()
25741 * for more information about what it means for a menu item to be a
25749 * g_menu_item_set_submenu:
25750 * @menu_item: a #GMenuItem
25751 * @submenu: (allow-none): a #GMenuModel, or %NULL
25753 * Sets or unsets the "submenu" link of @menu_item to @submenu.
25755 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
25758 * The effect of having one menu appear as a submenu of another is
25759 * exactly as it sounds.
25766 * g_menu_link_iter_get_name:
25767 * @iter: a #GMenuLinkIter
25769 * Gets the name of the link at the current iterator position.
25771 * The iterator is not advanced.
25773 * Returns: the type of the link
25779 * g_menu_link_iter_get_next:
25780 * @iter: a #GMenuLinkIter
25781 * @out_link: (out) (allow-none) (transfer none): the name of the link
25782 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
25784 * This function combines g_menu_link_iter_next() with
25785 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
25787 * First the iterator is advanced to the next (possibly first) link.
25788 * If that fails, then %FALSE is returned and there are no other effects.
25790 * If successful, @out_link and @value are set to the name and #GMenuModel
25791 * of the link that has just been advanced to. At this point,
25792 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
25793 * same values again.
25795 * The value returned in @out_link remains valid for as long as the iterator
25796 * remains at the current position. The value returned in @value must
25797 * be unreffed using g_object_unref() when it is no longer in use.
25799 * Returns: %TRUE on success, or %FALSE if there is no additional link
25805 * g_menu_link_iter_get_value:
25806 * @iter: a #GMenuLinkIter
25808 * Gets the linked #GMenuModel at the current iterator position.
25810 * The iterator is not advanced.
25812 * Returns: (transfer full): the #GMenuModel that is linked to
25818 * g_menu_link_iter_next:
25819 * @iter: a #GMenuLinkIter
25821 * Attempts to advance the iterator to the next (possibly first)
25824 * %TRUE is returned on success, or %FALSE if there are no more links.
25826 * You must call this function when you first acquire the iterator to
25827 * advance it to the first link (and determine if the first link exists
25830 * Returns: %TRUE on success, or %FALSE when there are no more links
25836 * g_menu_model_get_item_attribute:
25837 * @model: a #GMenuModel
25838 * @item_index: the index of the item
25839 * @attribute: the attribute to query
25840 * @format_string: a #GVariant format string
25841 * @...: positional parameters, as per @format_string
25843 * Queries item at position @item_index in @model for the attribute
25844 * specified by @attribute.
25846 * If the attribute exists and matches the #GVariantType corresponding
25847 * to @format_string then @format_string is used to deconstruct the
25848 * value into the positional parameters and %TRUE is returned.
25850 * If the attribute does not exist, or it does exist but has the wrong
25851 * type, then the positional parameters are ignored and %FALSE is
25854 * This function is a mix of g_menu_model_get_item_attribute_value() and
25855 * g_variant_get(), followed by a g_variant_unref(). As such,
25856 * @format_string must make a complete copy of the data (since the
25857 * #GVariant may go away after the call to g_variant_unref()). In
25858 * particular, no '&' characters are allowed in @format_string.
25860 * Returns: %TRUE if the named attribute was found with the expected
25867 * g_menu_model_get_item_attribute_value:
25868 * @model: a #GMenuModel
25869 * @item_index: the index of the item
25870 * @attribute: the attribute to query
25871 * @expected_type: (allow-none): the expected type of the attribute, or
25874 * Queries the item at position @item_index in @model for the attribute
25875 * specified by @attribute.
25877 * If @expected_type is non-%NULL then it specifies the expected type of
25878 * the attribute. If it is %NULL then any type will be accepted.
25880 * If the attribute exists and matches @expected_type (or if the
25881 * expected type is unspecified) then the value is returned.
25883 * If the attribute does not exist, or does not match the expected type
25884 * then %NULL is returned.
25886 * Returns: (transfer full): the value of the attribute
25892 * g_menu_model_get_item_link:
25893 * @model: a #GMenuModel
25894 * @item_index: the index of the item
25895 * @link: the link to query
25897 * Queries the item at position @item_index in @model for the link
25898 * specified by @link.
25900 * If the link exists, the linked #GMenuModel is returned. If the link
25901 * does not exist, %NULL is returned.
25903 * Returns: (transfer full): the linked #GMenuModel, or %NULL
25909 * g_menu_model_get_n_items:
25910 * @model: a #GMenuModel
25912 * Query the number of items in @model.
25914 * Returns: the number of items
25920 * g_menu_model_is_mutable:
25921 * @model: a #GMenuModel
25923 * Queries if @model is mutable.
25925 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
25926 * signal. Consumers of the model may make optimisations accordingly.
25928 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
25935 * g_menu_model_items_changed:
25936 * @model: a #GMenuModel
25937 * @position: the position of the change
25938 * @removed: the number of items removed
25939 * @added: the number of items added
25941 * Requests emission of the #GMenuModel::items-changed signal on @model.
25943 * This function should never be called except by #GMenuModel
25944 * subclasses. Any other calls to this function will very likely lead
25945 * to a violation of the interface of the model.
25947 * The implementation should update its internal representation of the
25948 * menu before emitting the signal. The implementation should further
25949 * expect to receive queries about the new state of the menu (and
25950 * particularly added menu items) while signal handlers are running.
25952 * The implementation must dispatch this call directly from a mainloop
25953 * entry and not in response to calls -- particularly those from the
25954 * #GMenuModel API. Said another way: the menu must not change while
25955 * user code is running without returning to the mainloop.
25962 * g_menu_model_iterate_item_attributes:
25963 * @model: a #GMenuModel
25964 * @item_index: the index of the item
25966 * Creates a #GMenuAttributeIter to iterate over the attributes of
25967 * the item at position @item_index in @model.
25969 * You must free the iterator with g_object_unref() when you are done.
25971 * Returns: (transfer full): a new #GMenuAttributeIter
25977 * g_menu_model_iterate_item_links:
25978 * @model: a #GMenuModel
25979 * @item_index: the index of the item
25981 * Creates a #GMenuLinkIter to iterate over the links of the item at
25982 * position @item_index in @model.
25984 * You must free the iterator with g_object_unref() when you are done.
25986 * Returns: (transfer full): a new #GMenuLinkIter
25994 * Creates a new #GMenu.
25996 * The new menu has no items.
25998 * Returns: a new #GMenu
26006 * @label: (allow-none): the section label, or %NULL
26007 * @detailed_action: (allow-none): the detailed action string, or %NULL
26009 * Convenience function for prepending a normal menu item to the start
26010 * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
26011 * flexible alternative.
26018 * g_menu_prepend_item:
26020 * @item: a #GMenuItem to prepend
26022 * Prepends @item to the start of @menu.
26024 * See g_menu_insert_item() for more information.
26031 * g_menu_prepend_section:
26033 * @label: (allow-none): the section label, or %NULL
26034 * @section: a #GMenuModel with the items of the section
26036 * Convenience function for prepending a section menu item to the start
26037 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
26038 * a more flexible alternative.
26045 * g_menu_prepend_submenu:
26047 * @label: (allow-none): the section label, or %NULL
26048 * @submenu: a #GMenuModel with the items of the submenu
26050 * Convenience function for prepending a submenu menu item to the start
26051 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
26052 * a more flexible alternative.
26061 * @position: the position of the item to remove
26063 * Removes an item from the menu.
26065 * @position gives the index of the item to remove.
26067 * It is an error if position is not in range the range from 0 to one
26068 * less than the number of items in the menu.
26070 * It is not possible to remove items by identity since items are added
26071 * to the menu simply by copying their links and attributes (ie:
26072 * identity of the item itself is not preserved).
26079 * g_menu_remove_all:
26082 * Removes all items in the menu.
26089 * g_mount_can_eject:
26090 * @mount: a #GMount.
26092 * Checks if @mount can be eject.
26094 * Returns: %TRUE if the @mount can be ejected.
26099 * g_mount_can_unmount:
26100 * @mount: a #GMount.
26102 * Checks if @mount can be mounted.
26104 * Returns: %TRUE if the @mount can be unmounted.
26110 * @mount: a #GMount.
26111 * @flags: flags affecting the unmount if required for eject
26112 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26113 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26114 * @user_data: user data passed to @callback.
26116 * Ejects a mount. This is an asynchronous operation, and is
26117 * finished by calling g_mount_eject_finish() with the @mount
26118 * and #GAsyncResult data returned in the @callback.
26120 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
26125 * g_mount_eject_finish:
26126 * @mount: a #GMount.
26127 * @result: a #GAsyncResult.
26128 * @error: a #GError location to store the error occurring, or %NULL to
26131 * Finishes ejecting a mount. If any errors occurred during the operation,
26132 * @error will be set to contain the errors and %FALSE will be returned.
26134 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
26135 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
26140 * g_mount_eject_with_operation:
26141 * @mount: a #GMount.
26142 * @flags: flags affecting the unmount if required for eject
26143 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26144 * user interaction.
26145 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26146 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26147 * @user_data: user data passed to @callback.
26149 * Ejects a mount. This is an asynchronous operation, and is
26150 * finished by calling g_mount_eject_with_operation_finish() with the @mount
26151 * and #GAsyncResult data returned in the @callback.
26158 * g_mount_eject_with_operation_finish:
26159 * @mount: a #GMount.
26160 * @result: a #GAsyncResult.
26161 * @error: a #GError location to store the error occurring, or %NULL to
26164 * Finishes ejecting a mount. If any errors occurred during the operation,
26165 * @error will be set to contain the errors and %FALSE will be returned.
26167 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
26173 * g_mount_get_default_location:
26174 * @mount: a #GMount.
26176 * Gets the default location of @mount. The default location of the given
26177 * @mount is a path that reflects the main entry point for the user (e.g.
26178 * the home directory, or the root of the volume).
26180 * Returns: (transfer full): a #GFile.
26181 * The returned object should be unreffed with
26182 * g_object_unref() when no longer needed.
26187 * g_mount_get_drive:
26188 * @mount: a #GMount.
26190 * Gets the drive for the @mount.
26192 * This is a convenience method for getting the #GVolume and then
26193 * using that object to get the #GDrive.
26195 * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
26196 * The returned object should be unreffed with
26197 * g_object_unref() when no longer needed.
26202 * g_mount_get_icon:
26203 * @mount: a #GMount.
26205 * Gets the icon for @mount.
26207 * Returns: (transfer full): a #GIcon.
26208 * The returned object should be unreffed with
26209 * g_object_unref() when no longer needed.
26214 * g_mount_get_name:
26215 * @mount: a #GMount.
26217 * Gets the name of @mount.
26219 * Returns: the name for the given @mount.
26220 * The returned string should be freed with g_free()
26221 * when no longer needed.
26226 * g_mount_get_root:
26227 * @mount: a #GMount.
26229 * Gets the root directory on @mount.
26231 * Returns: (transfer full): a #GFile.
26232 * The returned object should be unreffed with
26233 * g_object_unref() when no longer needed.
26238 * g_mount_get_sort_key:
26239 * @mount: A #GMount.
26241 * Gets the sort key for @mount, if any.
26243 * Returns: Sorting key for @mount or %NULL if no such key is available.
26249 * g_mount_get_symbolic_icon:
26250 * @mount: a #GMount.
26252 * Gets the symbolic icon for @mount.
26254 * Returns: (transfer full): a #GIcon.
26255 * The returned object should be unreffed with
26256 * g_object_unref() when no longer needed.
26262 * g_mount_get_uuid:
26263 * @mount: a #GMount.
26265 * Gets the UUID for the @mount. The reference is typically based on
26266 * the file system UUID for the mount in question and should be
26267 * considered an opaque string. Returns %NULL if there is no UUID
26270 * Returns: the UUID for @mount or %NULL if no UUID can be computed.
26271 * The returned string should be freed with g_free()
26272 * when no longer needed.
26277 * g_mount_get_volume:
26278 * @mount: a #GMount.
26280 * Gets the volume for the @mount.
26282 * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
26283 * The returned object should be unreffed with
26284 * g_object_unref() when no longer needed.
26289 * g_mount_guess_content_type:
26290 * @mount: a #GMount
26291 * @force_rescan: Whether to force a rescan of the content.
26292 * Otherwise a cached result will be used if available
26293 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26294 * @callback: a #GAsyncReadyCallback
26295 * @user_data: user data passed to @callback
26297 * Tries to guess the type of content stored on @mount. Returns one or
26298 * more textual identifiers of well-known content types (typically
26299 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
26300 * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
26301 * specification for more on x-content types.
26303 * This is an asynchronous operation (see
26304 * g_mount_guess_content_type_sync() for the synchronous version), and
26305 * is finished by calling g_mount_guess_content_type_finish() with the
26306 * @mount and #GAsyncResult data returned in the @callback.
26313 * g_mount_guess_content_type_finish:
26314 * @mount: a #GMount
26315 * @result: a #GAsyncResult
26316 * @error: a #GError location to store the error occurring, or %NULL to
26319 * Finishes guessing content types of @mount. If any errors occurred
26320 * during the operation, @error will be set to contain the errors and
26321 * %FALSE will be returned. In particular, you may get an
26322 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
26325 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
26326 * Caller should free this array with g_strfreev() when done with it.
26332 * g_mount_guess_content_type_sync:
26333 * @mount: a #GMount
26334 * @force_rescan: Whether to force a rescan of the content.
26335 * Otherwise a cached result will be used if available
26336 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
26337 * @error: a #GError location to store the error occurring, or %NULL to
26340 * Tries to guess the type of content stored on @mount. Returns one or
26341 * more textual identifiers of well-known content types (typically
26342 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
26343 * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
26344 * specification for more on x-content types.
26346 * This is an synchronous operation and as such may block doing IO;
26347 * see g_mount_guess_content_type() for the asynchronous version.
26349 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
26350 * Caller should free this array with g_strfreev() when done with it.
26356 * g_mount_is_shadowed:
26357 * @mount: A #GMount.
26359 * Determines if @mount is shadowed. Applications or libraries should
26360 * avoid displaying @mount in the user interface if it is shadowed.
26362 * A mount is said to be shadowed if there exists one or more user
26363 * visible objects (currently #GMount objects) with a root that is
26364 * inside the root of @mount.
26366 * One application of shadow mounts is when exposing a single file
26367 * system that is used to address several logical volumes. In this
26368 * situation, a #GVolumeMonitor implementation would create two
26369 * #GVolume objects (for example, one for the camera functionality of
26370 * the device and one for a SD card reader on the device) with
26371 * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal>
26372 * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the
26373 * underlying mount (with root
26374 * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said
26375 * #GVolumeMonitor implementation would create two #GMount objects
26376 * (each with their root matching the corresponding volume activation
26377 * root) that would shadow the original mount.
26379 * The proxy monitor in GVfs 2.26 and later, automatically creates and
26380 * manage shadow mounts (and shadows the underlying mount) if the
26381 * activation root on a #GVolume is set.
26383 * Returns: %TRUE if @mount is shadowed.
26389 * g_mount_operation_get_anonymous:
26390 * @op: a #GMountOperation.
26392 * Check to see whether the mount operation is being used
26393 * for an anonymous user.
26395 * Returns: %TRUE if mount operation is anonymous.
26400 * g_mount_operation_get_choice:
26401 * @op: a #GMountOperation.
26403 * Gets a choice from the mount operation.
26405 * Returns: an integer containing an index of the user's choice from
26406 * the choice's list, or %0.
26411 * g_mount_operation_get_domain:
26412 * @op: a #GMountOperation.
26414 * Gets the domain of the mount operation.
26416 * Returns: a string set to the domain.
26421 * g_mount_operation_get_password:
26422 * @op: a #GMountOperation.
26424 * Gets a password from the mount operation.
26426 * Returns: a string containing the password within @op.
26431 * g_mount_operation_get_password_save:
26432 * @op: a #GMountOperation.
26434 * Gets the state of saving passwords for the mount operation.
26436 * Returns: a #GPasswordSave flag.
26441 * g_mount_operation_get_username:
26442 * @op: a #GMountOperation.
26444 * Get the user name from the mount operation.
26446 * Returns: a string containing the user name.
26451 * g_mount_operation_new:
26453 * Creates a new mount operation.
26455 * Returns: a #GMountOperation.
26460 * g_mount_operation_reply:
26461 * @op: a #GMountOperation
26462 * @result: a #GMountOperationResult
26464 * Emits the #GMountOperation::reply signal.
26469 * g_mount_operation_set_anonymous:
26470 * @op: a #GMountOperation.
26471 * @anonymous: boolean value.
26473 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
26478 * g_mount_operation_set_choice:
26479 * @op: a #GMountOperation.
26480 * @choice: an integer.
26482 * Sets a default choice for the mount operation.
26487 * g_mount_operation_set_domain:
26488 * @op: a #GMountOperation.
26489 * @domain: the domain to set.
26491 * Sets the mount operation's domain.
26496 * g_mount_operation_set_password:
26497 * @op: a #GMountOperation.
26498 * @password: password to set.
26500 * Sets the mount operation's password to @password.
26505 * g_mount_operation_set_password_save:
26506 * @op: a #GMountOperation.
26507 * @save: a set of #GPasswordSave flags.
26509 * Sets the state of saving passwords for the mount operation.
26514 * g_mount_operation_set_username:
26515 * @op: a #GMountOperation.
26516 * @username: input username.
26518 * Sets the user name within @op to @username.
26524 * @mount: a #GMount.
26525 * @flags: flags affecting the operation
26526 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26527 * user interaction.
26528 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26529 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26530 * @user_data: user data passed to @callback.
26532 * Remounts a mount. This is an asynchronous operation, and is
26533 * finished by calling g_mount_remount_finish() with the @mount
26534 * and #GAsyncResults data returned in the @callback.
26536 * Remounting is useful when some setting affecting the operation
26537 * of the volume has been changed, as these may need a remount to
26538 * take affect. While this is semantically equivalent with unmounting
26539 * and then remounting not all backends might need to actually be
26545 * g_mount_remount_finish:
26546 * @mount: a #GMount.
26547 * @result: a #GAsyncResult.
26548 * @error: a #GError location to store the error occurring, or %NULL to
26551 * Finishes remounting a mount. If any errors occurred during the operation,
26552 * @error will be set to contain the errors and %FALSE will be returned.
26554 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
26560 * @mount: A #GMount.
26562 * Increments the shadow count on @mount. Usually used by
26563 * #GVolumeMonitor implementations when creating a shadow mount for
26564 * @mount, see g_mount_is_shadowed() for more information. The caller
26565 * will need to emit the #GMount::changed signal on @mount manually.
26573 * @mount: a #GMount.
26574 * @flags: flags affecting the operation
26575 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26576 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26577 * @user_data: user data passed to @callback.
26579 * Unmounts a mount. This is an asynchronous operation, and is
26580 * finished by calling g_mount_unmount_finish() with the @mount
26581 * and #GAsyncResult data returned in the @callback.
26583 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
26588 * g_mount_unmount_finish:
26589 * @mount: a #GMount.
26590 * @result: a #GAsyncResult.
26591 * @error: a #GError location to store the error occurring, or %NULL to
26594 * Finishes unmounting a mount. If any errors occurred during the operation,
26595 * @error will be set to contain the errors and %FALSE will be returned.
26597 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
26598 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
26603 * g_mount_unmount_with_operation:
26604 * @mount: a #GMount.
26605 * @flags: flags affecting the operation
26606 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
26607 * user interaction.
26608 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26609 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
26610 * @user_data: user data passed to @callback.
26612 * Unmounts a mount. This is an asynchronous operation, and is
26613 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
26614 * and #GAsyncResult data returned in the @callback.
26621 * g_mount_unmount_with_operation_finish:
26622 * @mount: a #GMount.
26623 * @result: a #GAsyncResult.
26624 * @error: a #GError location to store the error occurring, or %NULL to
26627 * Finishes unmounting a mount. If any errors occurred during the operation,
26628 * @error will be set to contain the errors and %FALSE will be returned.
26630 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
26636 * g_mount_unshadow:
26637 * @mount: A #GMount.
26639 * Decrements the shadow count on @mount. Usually used by
26640 * #GVolumeMonitor implementations when destroying a shadow mount for
26641 * @mount, see g_mount_is_shadowed() for more information. The caller
26642 * will need to emit the #GMount::changed signal on @mount manually.
26649 * g_network_address_get_hostname:
26650 * @addr: a #GNetworkAddress
26652 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
26653 * depending on what @addr was created with.
26655 * Returns: @addr's hostname
26661 * g_network_address_get_port:
26662 * @addr: a #GNetworkAddress
26664 * Gets @addr's port number
26666 * Returns: @addr's port (which may be 0)
26672 * g_network_address_get_scheme:
26673 * @addr: a #GNetworkAddress
26675 * Gets @addr's scheme
26677 * Returns: @addr's scheme (%NULL if not built from URI)
26683 * g_network_address_new:
26684 * @hostname: the hostname
26687 * Creates a new #GSocketConnectable for connecting to the given
26688 * @hostname and @port.
26690 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
26696 * g_network_address_parse:
26697 * @host_and_port: the hostname and optionally a port
26698 * @default_port: the default port if not in @host_and_port
26699 * @error: a pointer to a #GError, or %NULL
26701 * Creates a new #GSocketConnectable for connecting to the given
26702 * @hostname and @port. May fail and return %NULL in case
26703 * parsing @host_and_port fails.
26705 * @host_and_port may be in any of a number of recognised formats; an IPv6
26706 * address, an IPv4 address, or a domain name (in which case a DNS
26707 * lookup is performed). Quoting with [] is supported for all address
26708 * types. A port override may be specified in the usual way with a
26711 * If no port is specified in @host_and_port then @default_port will be
26712 * used as the port number to connect to.
26714 * In general, @host_and_port is expected to be provided by the user
26715 * (allowing them to give the hostname, and a port overide if necessary)
26716 * and @default_port is expected to be provided by the application.
26718 * (The port component of @host_and_port can also be specified as a
26719 * service name rather than as a numeric port, but this functionality
26720 * is deprecated, because it depends on the contents of /etc/services,
26721 * which is generally quite sparse on platforms other than Linux.)
26723 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
26729 * g_network_address_parse_uri:
26730 * @uri: the hostname and optionally a port
26731 * @default_port: The default port if none is found in the URI
26732 * @error: a pointer to a #GError, or %NULL
26734 * Creates a new #GSocketConnectable for connecting to the given
26735 * @uri. May fail and return %NULL in case parsing @uri fails.
26737 * Using this rather than g_network_address_new() or
26738 * g_network_address_parse() allows #GSocketClient to determine
26739 * when to use application-specific proxy protocols.
26741 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
26747 * g_network_monitor_base_add_network:
26748 * @monitor: the #GNetworkMonitorBase
26749 * @network: a #GInetAddressMask
26751 * Adds @network to @monitor's list of available networks.
26758 * g_network_monitor_base_remove_network:
26759 * @monitor: the #GNetworkMonitorBase
26760 * @network: a #GInetAddressMask
26762 * Removes @network from @monitor's list of available networks.
26769 * g_network_monitor_base_set_networks:
26770 * @monitor: the #GNetworkMonitorBase
26771 * @networks: (array length=length): an array of #GInetAddressMask
26772 * @length: length of @networks
26774 * Drops @monitor's current list of available networks and replaces
26775 * it with @networks.
26780 * g_network_monitor_can_reach:
26781 * @monitor: a #GNetworkMonitor
26782 * @connectable: a #GSocketConnectable
26783 * @cancellable: (allow-none): a #GCancellable, or %NULL
26784 * @error: return location for a #GError, or %NULL
26786 * Attempts to determine whether or not the host pointed to by
26787 * @connectable can be reached, without actually trying to connect to
26790 * This may return %TRUE even when #GNetworkMonitor:network-available
26791 * is %FALSE, if, for example, @monitor can determine that
26792 * @connectable refers to a host on a local network.
26794 * If @monitor believes that an attempt to connect to @connectable
26795 * will succeed, it will return %TRUE. Otherwise, it will return
26796 * %FALSE and set @error to an appropriate error (such as
26797 * %G_IO_ERROR_HOST_UNREACHABLE).
26799 * Note that although this does not attempt to connect to
26800 * @connectable, it may still block for a brief period of time (eg,
26801 * trying to do multicast DNS on the local network), so if you do not
26802 * want to block, you should use g_network_monitor_can_reach_async().
26804 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
26810 * g_network_monitor_can_reach_async:
26811 * @monitor: a #GNetworkMonitor
26812 * @connectable: a #GSocketConnectable
26813 * @cancellable: (allow-none): a #GCancellable, or %NULL
26814 * @callback: (scope async): a #GAsyncReadyCallback to call when the
26815 * request is satisfied
26816 * @user_data: (closure): the data to pass to callback function
26818 * Asynchronously attempts to determine whether or not the host
26819 * pointed to by @connectable can be reached, without actually
26820 * trying to connect to it.
26822 * For more details, see g_network_monitor_can_reach().
26824 * When the operation is finished, @callback will be called.
26825 * You can then call g_network_monitor_can_reach_finish()
26826 * to get the result of the operation.
26831 * g_network_monitor_can_reach_finish:
26832 * @monitor: a #GNetworkMonitor
26833 * @result: a #GAsyncResult
26834 * @error: return location for errors, or %NULL
26836 * Finishes an async network connectivity test.
26837 * See g_network_monitor_can_reach_async().
26839 * Returns: %TRUE if network is reachable, %FALSE if not.
26844 * g_network_monitor_get_default:
26846 * Gets the default #GNetworkMonitor for the system.
26848 * Returns: (transfer none): a #GNetworkMonitor
26854 * g_network_monitor_get_network_available:
26855 * @monitor: the #GNetworkMonitor
26857 * Checks if the network is available. "Available" here means that the
26858 * system has a default route available for at least one of IPv4 or
26859 * IPv6. It does not necessarily imply that the public Internet is
26860 * reachable. See #GNetworkMonitor:network-available for more details.
26862 * Returns: whether the network is available
26868 * g_network_service_get_domain:
26869 * @srv: a #GNetworkService
26871 * Gets the domain that @srv serves. This might be either UTF-8 or
26872 * ASCII-encoded, depending on what @srv was created with.
26874 * Returns: @srv's domain name
26880 * g_network_service_get_protocol:
26881 * @srv: a #GNetworkService
26883 * Gets @srv's protocol name (eg, "tcp").
26885 * Returns: @srv's protocol name
26891 * g_network_service_get_scheme:
26892 * @srv: a #GNetworkService
26894 * Get's the URI scheme used to resolve proxies. By default, the service name
26895 * is used as scheme.
26897 * Returns: @srv's scheme name
26903 * g_network_service_get_service:
26904 * @srv: a #GNetworkService
26906 * Gets @srv's service name (eg, "ldap").
26908 * Returns: @srv's service name
26914 * g_network_service_new:
26915 * @service: the service type to look up (eg, "ldap")
26916 * @protocol: the networking protocol to use for @service (eg, "tcp")
26917 * @domain: the DNS domain to look up the service in
26919 * Creates a new #GNetworkService representing the given @service,
26920 * @protocol, and @domain. This will initially be unresolved; use the
26921 * #GSocketConnectable interface to resolve it.
26923 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
26929 * g_network_service_set_scheme:
26930 * @srv: a #GNetworkService
26931 * @scheme: a URI scheme
26933 * Set's the URI scheme used to resolve proxies. By default, the service name
26934 * is used as scheme.
26941 * g_networking_init:
26943 * Initializes the platform networking libraries (eg, on Windows, this
26944 * calls WSAStartup()). GLib will call this itself if it is needed, so
26945 * you only need to call it if you directly call system networking
26946 * functions (without calling any GLib networking functions first).
26953 * g_notification_add_button:
26954 * @notification: a #GNotification
26955 * @label: label of the button
26956 * @detailed_action: a detailed action name
26958 * Adds a button to @notification that activates the action in
26959 * @detailed_action when clicked. That action must be an
26960 * application-wide action (starting with "app."). If @detailed_action
26961 * contains a target, the action will be activated with that target as
26964 * See g_action_parse_detailed_name() for a description of the format
26965 * for @detailed_action.
26972 * g_notification_add_button_with_target: (skip)
26973 * @notification: a #GNotification
26974 * @label: label of the button
26975 * @action: an action name
26976 * @target_format: (allow-none): a GVariant format string, or %NULL
26977 * @...: positional parameters, as determined by @format_string
26979 * Adds a button to @notification that activates @action when clicked.
26980 * @action must be an application-wide action (it must start with "app.").
26982 * If @target_format is given, it is used to collect remaining
26983 * positional parameters into a GVariant instance, similar to
26984 * g_variant_new(). @action will be activated with that GVariant as its
26992 * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
26993 * @notification: a #GNotification
26994 * @label: label of the button
26995 * @action: an action name
26996 * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
26998 * Adds a button to @notification that activates @action when clicked.
26999 * @action must be an application-wide action (it must start with "app.").
27001 * If @target is non-%NULL, @action will be activated with @target as
27009 * g_notification_new:
27010 * @title: the title of the notification
27012 * Creates a new #GNotification with @title as its title.
27014 * After populating @notification with more details, it can be sent to
27015 * the desktop shell with g_application_send_notification(). Changing
27016 * any properties after this call will not have any effect until
27017 * resending @notification.
27019 * Returns: a new #GNotification instance
27025 * g_notification_set_body:
27026 * @notification: a #GNotification
27027 * @body: (allow-none): the new body for @notification, or %NULL
27029 * Sets the body of @notification to @body.
27036 * g_notification_set_default_action:
27037 * @notification: a #GNotification
27038 * @detailed_action: a detailed action name
27040 * Sets the default action of @notification to @detailed_action. This
27041 * action is activated when the notification is clicked on.
27043 * The action in @detailed_action must be an application-wide action (it
27044 * must start with "app."). If @detailed_action contains a target, the
27045 * given action will be activated with that target as its parameter.
27046 * See g_action_parse_detailed_name() for a description of the format
27047 * for @detailed_action.
27049 * When no default action is set, the application that the notification
27050 * was sent on is activated.
27057 * g_notification_set_default_action_and_target: (skip)
27058 * @notification: a #GNotification
27059 * @action: an action name
27060 * @target_format: (allow-none): a GVariant format string, or %NULL
27061 * @...: positional parameters, as determined by @format_string
27063 * Sets the default action of @notification to @action. This action is
27064 * activated when the notification is clicked on. It must be an
27065 * application-wide action (it must start with "app.").
27067 * If @target_format is given, it is used to collect remaining
27068 * positional parameters into a GVariant instance, similar to
27069 * g_variant_new(). @action will be activated with that GVariant as its
27072 * When no default action is set, the application that the notification
27073 * was sent on is activated.
27080 * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
27081 * @notification: a #GNotification
27082 * @action: an action name
27083 * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
27085 * Sets the default action of @notification to @action. This action is
27086 * activated when the notification is clicked on. It must be an
27087 * application-wide action (start with "app.").
27089 * If @target_format is given, it is used to collect remaining
27090 * positional parameters into a GVariant instance, similar to
27093 * If @target is non-%NULL, @action will be activated with @target as
27096 * When no default action is set, the application that the notification
27097 * was sent on is activated.
27104 * g_notification_set_icon:
27105 * @notification: a #GNotification
27106 * @icon: the icon to be shown in @notification, as a #GIcon
27108 * Sets the icon of @notification to @icon.
27115 * g_notification_set_title:
27116 * @notification: a #GNotification
27117 * @title: the new title for @notification
27119 * Sets the title of @notification to @title.
27126 * g_notification_set_urgent:
27127 * @notification: a #GNotification
27128 * @urgent: %TRUE if @notification is urgent
27130 * Sets or unsets whether @notification is marked as urgent.
27137 * g_null_settings_backend_new:
27139 * Creates a readonly #GSettingsBackend.
27141 * This backend does not allow changes to settings, so all settings
27142 * will always have their default values.
27144 * Returns: (transfer full): a newly created #GSettingsBackend
27150 * g_output_stream_async_write_is_via_threads:
27151 * @stream: a #GOutputStream.
27153 * Checks if an ouput stream's write_async function uses threads.
27155 * Returns: %TRUE if @stream's write_async function uses threads.
27160 * g_output_stream_clear_pending:
27161 * @stream: output stream
27163 * Clears the pending flag on @stream.
27168 * g_output_stream_close:
27169 * @stream: A #GOutputStream.
27170 * @cancellable: (allow-none): optional cancellable object
27171 * @error: location to store the error occurring, or %NULL to ignore
27173 * Closes the stream, releasing resources related to it.
27175 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
27176 * Closing a stream multiple times will not return an error.
27178 * Closing a stream will automatically flush any outstanding buffers in the
27181 * Streams will be automatically closed when the last reference
27182 * is dropped, but you might want to call this function to make sure
27183 * resources are released as early as possible.
27185 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
27186 * open after the stream is closed. See the documentation for the individual
27187 * stream for details.
27189 * On failure the first error that happened will be reported, but the close
27190 * operation will finish as much as possible. A stream that failed to
27191 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
27192 * is important to check and report the error to the user, otherwise
27193 * there might be a loss of data as all data might not be written.
27195 * If @cancellable is not %NULL, then the operation can be cancelled by
27196 * triggering the cancellable object from another thread. If the operation
27197 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27198 * Cancelling a close will still leave the stream closed, but there some streams
27199 * can use a faster close that doesn't block to e.g. check errors. On
27200 * cancellation (as with any error) there is no guarantee that all written
27201 * data will reach the target.
27203 * Returns: %TRUE on success, %FALSE on failure
27208 * g_output_stream_close_async:
27209 * @stream: A #GOutputStream.
27210 * @io_priority: the io priority of the request.
27211 * @cancellable: (allow-none): optional cancellable object
27212 * @callback: (scope async): callback to call when the request is satisfied
27213 * @user_data: (closure): the data to pass to callback function
27215 * Requests an asynchronous close of the stream, releasing resources
27216 * related to it. When the operation is finished @callback will be
27217 * called. You can then call g_output_stream_close_finish() to get
27218 * the result of the operation.
27220 * For behaviour details see g_output_stream_close().
27222 * The asyncronous methods have a default fallback that uses threads
27223 * to implement asynchronicity, so they are optional for inheriting
27224 * classes. However, if you override one you must override all.
27229 * g_output_stream_close_finish:
27230 * @stream: a #GOutputStream.
27231 * @result: a #GAsyncResult.
27232 * @error: a #GError location to store the error occurring, or %NULL to
27235 * Closes an output stream.
27237 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
27242 * g_output_stream_flush:
27243 * @stream: a #GOutputStream.
27244 * @cancellable: (allow-none): optional cancellable object
27245 * @error: location to store the error occurring, or %NULL to ignore
27247 * Forces a write of all user-space buffered data for the given
27248 * @stream. Will block during the operation. Closing the stream will
27249 * implicitly cause a flush.
27251 * This function is optional for inherited classes.
27253 * If @cancellable is not %NULL, then the operation can be cancelled by
27254 * triggering the cancellable object from another thread. If the operation
27255 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27257 * Returns: %TRUE on success, %FALSE on error
27262 * g_output_stream_flush_async:
27263 * @stream: a #GOutputStream.
27264 * @io_priority: the io priority of the request.
27265 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27266 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27267 * @user_data: (closure): the data to pass to callback function
27269 * Forces an asynchronous write of all user-space buffered data for
27270 * the given @stream.
27271 * For behaviour details see g_output_stream_flush().
27273 * When the operation is finished @callback will be
27274 * called. You can then call g_output_stream_flush_finish() to get the
27275 * result of the operation.
27280 * g_output_stream_flush_finish:
27281 * @stream: a #GOutputStream.
27282 * @result: a GAsyncResult.
27283 * @error: a #GError location to store the error occurring, or %NULL to
27286 * Finishes flushing an output stream.
27288 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
27293 * g_output_stream_has_pending:
27294 * @stream: a #GOutputStream.
27296 * Checks if an ouput stream has pending actions.
27298 * Returns: %TRUE if @stream has pending actions.
27303 * g_output_stream_is_closed:
27304 * @stream: a #GOutputStream.
27306 * Checks if an output stream has already been closed.
27308 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
27313 * g_output_stream_is_closing:
27314 * @stream: a #GOutputStream.
27316 * Checks if an output stream is being closed. This can be
27317 * used inside e.g. a flush implementation to see if the
27318 * flush (or other i/o operation) is called from within
27319 * the closing operation.
27321 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
27327 * g_output_stream_set_pending:
27328 * @stream: a #GOutputStream.
27329 * @error: a #GError location to store the error occurring, or %NULL to
27332 * Sets @stream to have actions pending. If the pending flag is
27333 * already set or @stream is closed, it will return %FALSE and set
27336 * Returns: %TRUE if pending was previously unset and is now set.
27341 * g_output_stream_splice:
27342 * @stream: a #GOutputStream.
27343 * @source: a #GInputStream.
27344 * @flags: a set of #GOutputStreamSpliceFlags.
27345 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27346 * @error: a #GError location to store the error occurring, or %NULL to
27349 * Splices an input stream into an output stream.
27351 * Returns: a #gssize containing the size of the data spliced, or
27352 * -1 if an error occurred. Note that if the number of bytes
27353 * spliced is greater than %G_MAXSSIZE, then that will be
27354 * returned, and there is no way to determine the actual number
27355 * of bytes spliced.
27360 * g_output_stream_splice_async:
27361 * @stream: a #GOutputStream.
27362 * @source: a #GInputStream.
27363 * @flags: a set of #GOutputStreamSpliceFlags.
27364 * @io_priority: the io priority of the request.
27365 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27366 * @callback: (scope async): a #GAsyncReadyCallback.
27367 * @user_data: (closure): user data passed to @callback.
27369 * Splices a stream asynchronously.
27370 * When the operation is finished @callback will be called.
27371 * You can then call g_output_stream_splice_finish() to get the
27372 * result of the operation.
27374 * For the synchronous, blocking version of this function, see
27375 * g_output_stream_splice().
27380 * g_output_stream_splice_finish:
27381 * @stream: a #GOutputStream.
27382 * @result: a #GAsyncResult.
27383 * @error: a #GError location to store the error occurring, or %NULL to
27386 * Finishes an asynchronous stream splice operation.
27388 * Returns: a #gssize of the number of bytes spliced. Note that if the
27389 * number of bytes spliced is greater than %G_MAXSSIZE, then that
27390 * will be returned, and there is no way to determine the actual
27391 * number of bytes spliced.
27396 * g_output_stream_write: (virtual write_fn)
27397 * @stream: a #GOutputStream.
27398 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27399 * @count: the number of bytes to write
27400 * @cancellable: (allow-none): optional cancellable object
27401 * @error: location to store the error occurring, or %NULL to ignore
27403 * Tries to write @count bytes from @buffer into the stream. Will block
27404 * during the operation.
27406 * If count is 0, returns 0 and does nothing. A value of @count
27407 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
27409 * On success, the number of bytes written to the stream is returned.
27410 * It is not an error if this is not the same as the requested size, as it
27411 * can happen e.g. on a partial I/O error, or if there is not enough
27412 * storage in the stream. All writes block until at least one byte
27413 * is written or an error occurs; 0 is never returned (unless
27416 * If @cancellable is not %NULL, then the operation can be cancelled by
27417 * triggering the cancellable object from another thread. If the operation
27418 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
27419 * operation was partially finished when the operation was cancelled the
27420 * partial result will be returned, without an error.
27422 * On error -1 is returned and @error is set accordingly.
27424 * Returns: Number of bytes written, or -1 on error
27429 * g_output_stream_write_all:
27430 * @stream: a #GOutputStream.
27431 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27432 * @count: the number of bytes to write
27433 * @bytes_written: (out): location to store the number of bytes that was
27434 * written to the stream
27435 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27436 * @error: location to store the error occurring, or %NULL to ignore
27438 * Tries to write @count bytes from @buffer into the stream. Will block
27439 * during the operation.
27441 * This function is similar to g_output_stream_write(), except it tries to
27442 * write as many bytes as requested, only stopping on an error.
27444 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
27445 * is set to @count.
27447 * If there is an error during the operation %FALSE is returned and @error
27448 * is set to indicate the error status, @bytes_written is updated to contain
27449 * the number of bytes written into the stream before the error occurred.
27451 * Returns: %TRUE on success, %FALSE if there was an error
27456 * g_output_stream_write_async:
27457 * @stream: A #GOutputStream.
27458 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
27459 * @count: the number of bytes to write
27460 * @io_priority: the io priority of the request.
27461 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27462 * @callback: (scope async): callback to call when the request is satisfied
27463 * @user_data: (closure): the data to pass to callback function
27465 * Request an asynchronous write of @count bytes from @buffer into
27466 * the stream. When the operation is finished @callback will be called.
27467 * You can then call g_output_stream_write_finish() to get the result of the
27470 * During an async request no other sync and async calls are allowed,
27471 * and will result in %G_IO_ERROR_PENDING errors.
27473 * A value of @count larger than %G_MAXSSIZE will cause a
27474 * %G_IO_ERROR_INVALID_ARGUMENT error.
27476 * On success, the number of bytes written will be passed to the
27477 * @callback. It is not an error if this is not the same as the
27478 * requested size, as it can happen e.g. on a partial I/O error,
27479 * but generally we try to write as many bytes as requested.
27481 * You are guaranteed that this method will never fail with
27482 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
27483 * method will just wait until this changes.
27485 * Any outstanding I/O request with higher priority (lower numerical
27486 * value) will be executed before an outstanding request with lower
27487 * priority. Default priority is %G_PRIORITY_DEFAULT.
27489 * The asyncronous methods have a default fallback that uses threads
27490 * to implement asynchronicity, so they are optional for inheriting
27491 * classes. However, if you override one you must override all.
27493 * For the synchronous, blocking version of this function, see
27494 * g_output_stream_write().
27499 * g_output_stream_write_bytes:
27500 * @stream: a #GOutputStream.
27501 * @bytes: the #GBytes to write
27502 * @cancellable: (allow-none): optional cancellable object
27503 * @error: location to store the error occurring, or %NULL to ignore
27505 * A wrapper function for g_output_stream_write() which takes a
27506 * #GBytes as input. This can be more convenient for use by language
27507 * bindings or in other cases where the refcounted nature of #GBytes
27508 * is helpful over a bare pointer interface.
27510 * However, note that this function <emphasis>may</emphasis> still
27511 * perform partial writes, just like g_output_stream_write(). If that
27512 * occurs, to continue writing, you will need to create a new #GBytes
27513 * containing just the remaining bytes, using
27514 * g_bytes_new_from_bytes(). Passing the same #GBytes instance
27515 * multiple times potentially can result in duplicated data in the
27518 * Returns: Number of bytes written, or -1 on error
27523 * g_output_stream_write_bytes_async:
27524 * @stream: A #GOutputStream.
27525 * @bytes: The bytes to write
27526 * @io_priority: the io priority of the request.
27527 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27528 * @callback: (scope async): callback to call when the request is satisfied
27529 * @user_data: (closure): the data to pass to callback function
27531 * This function is similar to g_output_stream_write_async(), but
27532 * takes a #GBytes as input. Due to the refcounted nature of #GBytes,
27533 * this allows the stream to avoid taking a copy of the data.
27535 * However, note that this function <emphasis>may</emphasis> still
27536 * perform partial writes, just like g_output_stream_write_async().
27537 * If that occurs, to continue writing, you will need to create a new
27538 * #GBytes containing just the remaining bytes, using
27539 * g_bytes_new_from_bytes(). Passing the same #GBytes instance
27540 * multiple times potentially can result in duplicated data in the
27543 * For the synchronous, blocking version of this function, see
27544 * g_output_stream_write_bytes().
27549 * g_output_stream_write_bytes_finish:
27550 * @stream: a #GOutputStream.
27551 * @result: a #GAsyncResult.
27552 * @error: a #GError location to store the error occurring, or %NULL to
27555 * Finishes a stream write-from-#GBytes operation.
27557 * Returns: a #gssize containing the number of bytes written to the stream.
27562 * g_output_stream_write_finish:
27563 * @stream: a #GOutputStream.
27564 * @result: a #GAsyncResult.
27565 * @error: a #GError location to store the error occurring, or %NULL to
27568 * Finishes a stream write operation.
27570 * Returns: a #gssize containing the number of bytes written to the stream.
27575 * g_permission_acquire:
27576 * @permission: a #GPermission instance
27577 * @cancellable: (allow-none): a #GCancellable, or %NULL
27578 * @error: a pointer to a %NULL #GError, or %NULL
27580 * Attempts to acquire the permission represented by @permission.
27582 * The precise method by which this happens depends on the permission
27583 * and the underlying authentication mechanism. A simple example is
27584 * that a dialog may appear asking the user to enter their password.
27586 * You should check with g_permission_get_can_acquire() before calling
27589 * If the permission is acquired then %TRUE is returned. Otherwise,
27590 * %FALSE is returned and @error is set appropriately.
27592 * This call is blocking, likely for a very long time (in the case that
27593 * user interaction is required). See g_permission_acquire_async() for
27594 * the non-blocking version.
27596 * Returns: %TRUE if the permission was successfully acquired
27602 * g_permission_acquire_async:
27603 * @permission: a #GPermission instance
27604 * @cancellable: (allow-none): a #GCancellable, or %NULL
27605 * @callback: the #GAsyncReadyCallback to call when done
27606 * @user_data: the user data to pass to @callback
27608 * Attempts to acquire the permission represented by @permission.
27610 * This is the first half of the asynchronous version of
27611 * g_permission_acquire().
27618 * g_permission_acquire_finish:
27619 * @permission: a #GPermission instance
27620 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
27621 * @error: a pointer to a %NULL #GError, or %NULL
27623 * Collects the result of attempting to acquire the permission
27624 * represented by @permission.
27626 * This is the second half of the asynchronous version of
27627 * g_permission_acquire().
27629 * Returns: %TRUE if the permission was successfully acquired
27635 * g_permission_get_allowed:
27636 * @permission: a #GPermission instance
27638 * Gets the value of the 'allowed' property. This property is %TRUE if
27639 * the caller currently has permission to perform the action that
27640 * @permission represents the permission to perform.
27642 * Returns: the value of the 'allowed' property
27648 * g_permission_get_can_acquire:
27649 * @permission: a #GPermission instance
27651 * Gets the value of the 'can-acquire' property. This property is %TRUE
27652 * if it is generally possible to acquire the permission by calling
27653 * g_permission_acquire().
27655 * Returns: the value of the 'can-acquire' property
27661 * g_permission_get_can_release:
27662 * @permission: a #GPermission instance
27664 * Gets the value of the 'can-release' property. This property is %TRUE
27665 * if it is generally possible to release the permission by calling
27666 * g_permission_release().
27668 * Returns: the value of the 'can-release' property
27674 * g_permission_impl_update:
27675 * @permission: a #GPermission instance
27676 * @allowed: the new value for the 'allowed' property
27677 * @can_acquire: the new value for the 'can-acquire' property
27678 * @can_release: the new value for the 'can-release' property
27680 * This function is called by the #GPermission implementation to update
27681 * the properties of the permission. You should never call this
27682 * function except from a #GPermission implementation.
27684 * GObject notify signals are generated, as appropriate.
27691 * g_permission_release:
27692 * @permission: a #GPermission instance
27693 * @cancellable: (allow-none): a #GCancellable, or %NULL
27694 * @error: a pointer to a %NULL #GError, or %NULL
27696 * Attempts to release the permission represented by @permission.
27698 * The precise method by which this happens depends on the permission
27699 * and the underlying authentication mechanism. In most cases the
27700 * permission will be dropped immediately without further action.
27702 * You should check with g_permission_get_can_release() before calling
27705 * If the permission is released then %TRUE is returned. Otherwise,
27706 * %FALSE is returned and @error is set appropriately.
27708 * This call is blocking, likely for a very long time (in the case that
27709 * user interaction is required). See g_permission_release_async() for
27710 * the non-blocking version.
27712 * Returns: %TRUE if the permission was successfully released
27718 * g_permission_release_async:
27719 * @permission: a #GPermission instance
27720 * @cancellable: (allow-none): a #GCancellable, or %NULL
27721 * @callback: the #GAsyncReadyCallback to call when done
27722 * @user_data: the user data to pass to @callback
27724 * Attempts to release the permission represented by @permission.
27726 * This is the first half of the asynchronous version of
27727 * g_permission_release().
27734 * g_permission_release_finish:
27735 * @permission: a #GPermission instance
27736 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
27737 * @error: a pointer to a %NULL #GError, or %NULL
27739 * Collects the result of attempting to release the permission
27740 * represented by @permission.
27742 * This is the second half of the asynchronous version of
27743 * g_permission_release().
27745 * Returns: %TRUE if the permission was successfully released
27751 * g_poll_file_monitor_new:
27754 * Polls @file for changes.
27756 * Returns: a new #GFileMonitor for the given #GFile.
27761 * g_pollable_input_stream_can_poll:
27762 * @stream: a #GPollableInputStream.
27764 * Checks if @stream is actually pollable. Some classes may implement
27765 * #GPollableInputStream but have only certain instances of that class
27766 * be pollable. If this method returns %FALSE, then the behavior of
27767 * other #GPollableInputStream methods is undefined.
27769 * For any given stream, the value returned by this method is constant;
27770 * a stream cannot switch from pollable to non-pollable or vice versa.
27772 * Returns: %TRUE if @stream is pollable, %FALSE if not.
27778 * g_pollable_input_stream_create_source:
27779 * @stream: a #GPollableInputStream.
27780 * @cancellable: (allow-none): a #GCancellable, or %NULL
27782 * Creates a #GSource that triggers when @stream can be read, or
27783 * @cancellable is triggered or an error occurs. The callback on the
27784 * source is of the #GPollableSourceFunc type.
27786 * As with g_pollable_input_stream_is_readable(), it is possible that
27787 * the stream may not actually be readable even after the source
27788 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
27789 * rather than g_input_stream_read() from the callback.
27791 * Returns: (transfer full): a new #GSource
27797 * g_pollable_input_stream_is_readable:
27798 * @stream: a #GPollableInputStream.
27800 * Checks if @stream can be read.
27802 * Note that some stream types may not be able to implement this 100%
27803 * reliably, and it is possible that a call to g_input_stream_read()
27804 * after this returns %TRUE would still block. To guarantee
27805 * non-blocking behavior, you should always use
27806 * g_pollable_input_stream_read_nonblocking(), which will return a
27807 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
27809 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
27810 * has occurred on @stream, this will result in
27811 * g_pollable_input_stream_is_readable() returning %TRUE, and the
27812 * next attempt to read will return the error.
27818 * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
27819 * @stream: a #GPollableInputStream
27820 * @buffer: a buffer to read data into (which should be at least @count
27822 * @count: the number of bytes you want to read
27823 * @cancellable: (allow-none): a #GCancellable, or %NULL
27824 * @error: #GError for error reporting, or %NULL to ignore.
27826 * Attempts to read up to @count bytes from @stream into @buffer, as
27827 * with g_input_stream_read(). If @stream is not currently readable,
27828 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
27829 * use g_pollable_input_stream_create_source() to create a #GSource
27830 * that will be triggered when @stream is readable.
27832 * Note that since this method never blocks, you cannot actually
27833 * use @cancellable to cancel it. However, it will return an error
27834 * if @cancellable has already been cancelled when you call, which
27835 * may happen if you call this method after a source triggers due
27836 * to having been cancelled.
27838 * Returns: the number of bytes read, or -1 on error (including
27839 * %G_IO_ERROR_WOULD_BLOCK).
27844 * g_pollable_output_stream_can_poll:
27845 * @stream: a #GPollableOutputStream.
27847 * Checks if @stream is actually pollable. Some classes may implement
27848 * #GPollableOutputStream but have only certain instances of that
27849 * class be pollable. If this method returns %FALSE, then the behavior
27850 * of other #GPollableOutputStream methods is undefined.
27852 * For any given stream, the value returned by this method is constant;
27853 * a stream cannot switch from pollable to non-pollable or vice versa.
27855 * Returns: %TRUE if @stream is pollable, %FALSE if not.
27861 * g_pollable_output_stream_create_source:
27862 * @stream: a #GPollableOutputStream.
27863 * @cancellable: (allow-none): a #GCancellable, or %NULL
27865 * Creates a #GSource that triggers when @stream can be written, or
27866 * @cancellable is triggered or an error occurs. The callback on the
27867 * source is of the #GPollableSourceFunc type.
27869 * As with g_pollable_output_stream_is_writable(), it is possible that
27870 * the stream may not actually be writable even after the source
27871 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
27872 * rather than g_output_stream_write() from the callback.
27874 * Returns: (transfer full): a new #GSource
27880 * g_pollable_output_stream_is_writable:
27881 * @stream: a #GPollableOutputStream.
27883 * Checks if @stream can be written.
27885 * Note that some stream types may not be able to implement this 100%
27886 * reliably, and it is possible that a call to g_output_stream_write()
27887 * after this returns %TRUE would still block. To guarantee
27888 * non-blocking behavior, you should always use
27889 * g_pollable_output_stream_write_nonblocking(), which will return a
27890 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
27892 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
27893 * has occurred on @stream, this will result in
27894 * g_pollable_output_stream_is_writable() returning %TRUE, and the
27895 * next attempt to write will return the error.
27901 * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking)
27902 * @stream: a #GPollableOutputStream
27903 * @buffer: (array length=count) (element-type guint8): a buffer to write
27905 * @count: the number of bytes you want to write
27906 * @cancellable: (allow-none): a #GCancellable, or %NULL
27907 * @error: #GError for error reporting, or %NULL to ignore.
27909 * Attempts to write up to @count bytes from @buffer to @stream, as
27910 * with g_output_stream_write(). If @stream is not currently writable,
27911 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
27912 * use g_pollable_output_stream_create_source() to create a #GSource
27913 * that will be triggered when @stream is writable.
27915 * Note that since this method never blocks, you cannot actually
27916 * use @cancellable to cancel it. However, it will return an error
27917 * if @cancellable has already been cancelled when you call, which
27918 * may happen if you call this method after a source triggers due
27919 * to having been cancelled.
27921 * Returns: the number of bytes written, or -1 on error (including
27922 * %G_IO_ERROR_WOULD_BLOCK).
27927 * g_pollable_source_new:
27928 * @pollable_stream: the stream associated with the new source
27930 * Utility method for #GPollableInputStream and #GPollableOutputStream
27931 * implementations. Creates a new #GSource that expects a callback of
27932 * type #GPollableSourceFunc. The new source does not actually do
27933 * anything on its own; use g_source_add_child_source() to add other
27934 * sources to it to cause it to trigger.
27936 * Returns: (transfer full): the new #GSource.
27942 * g_pollable_source_new_full:
27943 * @pollable_stream: (type GObject): the stream associated with the
27945 * @child_source: (allow-none): optional child source to attach
27946 * @cancellable: (allow-none): optional #GCancellable to attach
27948 * Utility method for #GPollableInputStream and #GPollableOutputStream
27949 * implementations. Creates a new #GSource, as with
27950 * g_pollable_source_new(), but also attaching @child_source (with a
27951 * dummy callback), and @cancellable, if they are non-%NULL.
27953 * Returns: (transfer full): the new #GSource.
27959 * g_pollable_stream_read:
27960 * @stream: a #GInputStream
27961 * @buffer: a buffer to read data into
27962 * @count: the number of bytes to read
27963 * @blocking: whether to do blocking I/O
27964 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27965 * @error: location to store the error occurring, or %NULL to ignore
27967 * Tries to read from @stream, as with g_input_stream_read() (if
27968 * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
27969 * (if @blocking is %FALSE). This can be used to more easily share
27970 * code between blocking and non-blocking implementations of a method.
27972 * If @blocking is %FALSE, then @stream must be a
27973 * #GPollableInputStream for which g_pollable_input_stream_can_poll()
27974 * returns %TRUE, or else the behavior is undefined. If @blocking is
27975 * %TRUE, then @stream does not need to be a #GPollableInputStream.
27977 * Returns: the number of bytes read, or -1 on error.
27983 * g_pollable_stream_write:
27984 * @stream: a #GOutputStream.
27985 * @buffer: (array length=count) (element-type guint8): the buffer
27986 * containing the data to write.
27987 * @count: the number of bytes to write
27988 * @blocking: whether to do blocking I/O
27989 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27990 * @error: location to store the error occurring, or %NULL to ignore
27992 * Tries to write to @stream, as with g_output_stream_write() (if
27993 * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
27994 * (if @blocking is %FALSE). This can be used to more easily share
27995 * code between blocking and non-blocking implementations of a method.
27997 * If @blocking is %FALSE, then @stream must be a
27998 * #GPollableOutputStream for which
27999 * g_pollable_output_stream_can_poll() returns %TRUE or else the
28000 * behavior is undefined. If @blocking is %TRUE, then @stream does not
28001 * need to be a #GPollableOutputStream.
28003 * Returns: the number of bytes written, or -1 on error.
28009 * g_pollable_stream_write_all:
28010 * @stream: a #GOutputStream.
28011 * @buffer: (array length=count) (element-type guint8): the buffer
28012 * containing the data to write.
28013 * @count: the number of bytes to write
28014 * @blocking: whether to do blocking I/O
28015 * @bytes_written: (out): location to store the number of bytes that was
28016 * written to the stream
28017 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28018 * @error: location to store the error occurring, or %NULL to ignore
28020 * Tries to write @count bytes to @stream, as with
28021 * g_output_stream_write_all(), but using g_pollable_stream_write()
28022 * rather than g_output_stream_write().
28024 * On a successful write of @count bytes, %TRUE is returned, and
28025 * @bytes_written is set to @count.
28027 * If there is an error during the operation (including
28028 * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is
28029 * returned and @error is set to indicate the error status,
28030 * @bytes_written is updated to contain the number of bytes written
28031 * into the stream before the error occurred.
28033 * As with g_pollable_stream_write(), if @blocking is %FALSE, then
28034 * @stream must be a #GPollableOutputStream for which
28035 * g_pollable_output_stream_can_poll() returns %TRUE or else the
28036 * behavior is undefined. If @blocking is %TRUE, then @stream does not
28037 * need to be a #GPollableOutputStream.
28039 * Returns: %TRUE on success, %FALSE if there was an error
28045 * g_property_action_new:
28046 * @name: the name of the action to create
28047 * @object: the object that has the property to wrap
28048 * @property_name: the name of the property
28050 * Creates a #GAction corresponding to the value of property
28051 * @property_name on @object.
28053 * The property must be existent and readable and writable (and not
28056 * This function takes a reference on @object and doesn't release it
28057 * until the action is destroyed.
28059 * Returns: a new #GPropertyAction
28065 * g_proxy_address_get_destination_hostname:
28066 * @proxy: a #GProxyAddress
28068 * Gets @proxy's destination hostname; that is, the name of the host
28069 * that will be connected to via the proxy, not the name of the proxy
28072 * Returns: the @proxy's destination hostname
28078 * g_proxy_address_get_destination_port:
28079 * @proxy: a #GProxyAddress
28081 * Gets @proxy's destination port; that is, the port on the
28082 * destination host that will be connected to via the proxy, not the
28083 * port number of the proxy itself.
28085 * Returns: the @proxy's destination port
28091 * g_proxy_address_get_destination_protocol:
28092 * @proxy: a #GProxyAddress
28094 * Gets the protocol that is being spoken to the destination
28095 * server; eg, "http" or "ftp".
28097 * Returns: the @proxy's destination protocol
28103 * g_proxy_address_get_password:
28104 * @proxy: a #GProxyAddress
28106 * Gets @proxy's password.
28108 * Returns: the @proxy's password
28114 * g_proxy_address_get_protocol:
28115 * @proxy: a #GProxyAddress
28117 * Gets @proxy's protocol. eg, "socks" or "http"
28119 * Returns: the @proxy's protocol
28125 * g_proxy_address_get_uri:
28126 * @proxy: a #GProxyAddress
28128 * Gets the proxy URI that @proxy was constructed from.
28130 * Returns: the @proxy's URI, or %NULL if unknown
28136 * g_proxy_address_get_username:
28137 * @proxy: a #GProxyAddress
28139 * Gets @proxy's username.
28141 * Returns: the @proxy's username
28147 * g_proxy_address_new:
28148 * @inetaddr: The proxy server #GInetAddress.
28149 * @port: The proxy server port.
28150 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
28151 * @dest_hostname: The destination hostname the proxy should tunnel to.
28152 * @dest_port: The destination port to tunnel to.
28153 * @username: (allow-none): The username to authenticate to the proxy server
28155 * @password: (allow-none): The password to authenticate to the proxy server
28158 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
28159 * tunnel through @dest_hostname and @dest_port.
28161 * (Note that this method doesn't set the #GProxyAddress:uri or
28162 * #GProxyAddress:destination-protocol fields; use g_object_new()
28163 * directly if you want to set those.)
28165 * Returns: a new #GProxyAddress
28172 * @proxy: a #GProxy
28173 * @connection: a #GIOStream
28174 * @proxy_address: a #GProxyAddress
28175 * @cancellable: (allow-none): a #GCancellable
28176 * @error: return #GError
28178 * Given @connection to communicate with a proxy (eg, a
28179 * #GSocketConnection that is connected to the proxy server), this
28180 * does the necessary handshake to connect to @proxy_address, and if
28181 * required, wraps the #GIOStream to handle proxy payload.
28183 * Returns: (transfer full): a #GIOStream that will replace @connection. This might
28184 * be the same as @connection, in which case a reference
28191 * g_proxy_connect_async:
28192 * @proxy: a #GProxy
28193 * @connection: a #GIOStream
28194 * @proxy_address: a #GProxyAddress
28195 * @cancellable: (allow-none): a #GCancellable
28196 * @callback: (scope async): a #GAsyncReadyCallback
28197 * @user_data: (closure): callback data
28199 * Asynchronous version of g_proxy_connect().
28206 * g_proxy_connect_finish:
28207 * @proxy: a #GProxy
28208 * @result: a #GAsyncResult
28209 * @error: return #GError
28211 * See g_proxy_connect().
28213 * Returns: (transfer full): a #GIOStream.
28219 * g_proxy_get_default_for_protocol:
28220 * @protocol: the proxy protocol name (e.g. http, socks, etc)
28222 * Lookup "gio-proxy" extension point for a proxy implementation that supports
28223 * specified protocol.
28225 * Returns: (transfer full): return a #GProxy or NULL if protocol
28226 * is not supported.
28232 * g_proxy_resolver_get_default:
28234 * Gets the default #GProxyResolver for the system.
28236 * Returns: (transfer none): the default #GProxyResolver.
28242 * g_proxy_resolver_is_supported:
28243 * @resolver: a #GProxyResolver
28245 * Checks if @resolver can be used on this system. (This is used
28246 * internally; g_proxy_resolver_get_default() will only return a proxy
28247 * resolver that returns %TRUE for this method.)
28249 * Returns: %TRUE if @resolver is supported.
28255 * g_proxy_resolver_lookup:
28256 * @resolver: a #GProxyResolver
28257 * @uri: a URI representing the destination to connect to
28258 * @cancellable: (allow-none): a #GCancellable, or %NULL
28259 * @error: return location for a #GError, or %NULL
28261 * Looks into the system proxy configuration to determine what proxy,
28262 * if any, to use to connect to @uri. The returned proxy URIs are of the
28263 * form <literal><protocol>://[user[:password]@]host:port</literal>
28264 * or <literal>direct://</literal>, where <protocol> could be
28265 * http, rtsp, socks or other proxying protocol.
28267 * If you don't know what network protocol is being used on the
28268 * socket, you should use <literal>none</literal> as the URI protocol.
28269 * In this case, the resolver might still return a generic proxy type
28270 * (such as SOCKS), but would not return protocol-specific proxy types
28273 * <literal>direct://</literal> is used when no proxy is needed.
28274 * Direct connection should not be attempted unless it is part of the
28275 * returned array of proxies.
28277 * Returns: (transfer full) (array zero-terminated=1): A
28278 * NULL-terminated array of proxy URIs. Must be freed
28279 * with g_strfreev().
28285 * g_proxy_resolver_lookup_async:
28286 * @resolver: a #GProxyResolver
28287 * @uri: a URI representing the destination to connect to
28288 * @cancellable: (allow-none): a #GCancellable, or %NULL
28289 * @callback: (scope async): callback to call after resolution completes
28290 * @user_data: (closure): data for @callback
28292 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
28300 * g_proxy_resolver_lookup_finish:
28301 * @resolver: a #GProxyResolver
28302 * @result: the result passed to your #GAsyncReadyCallback
28303 * @error: return location for a #GError, or %NULL
28305 * Call this function to obtain the array of proxy URIs when
28306 * g_proxy_resolver_lookup_async() is complete. See
28307 * g_proxy_resolver_lookup() for more details.
28309 * Returns: (transfer full) (array zero-terminated=1): A
28310 * NULL-terminated array of proxy URIs. Must be freed
28311 * with g_strfreev().
28317 * g_proxy_supports_hostname:
28318 * @proxy: a #GProxy
28320 * Some proxy protocols expect to be passed a hostname, which they
28321 * will resolve to an IP address themselves. Others, like SOCKS4, do
28322 * not allow this. This function will return %FALSE if @proxy is
28323 * implementing such a protocol. When %FALSE is returned, the caller
28324 * should resolve the destination hostname first, and then pass a
28325 * #GProxyAddress containing the stringified IP address to
28326 * g_proxy_connect() or g_proxy_connect_async().
28328 * Returns: %TRUE if hostname resolution is supported.
28334 * g_remote_action_group_activate_action_full:
28335 * @remote: a #GDBusActionGroup
28336 * @action_name: the name of the action to activate
28337 * @parameter: (allow-none): the optional parameter to the activation
28338 * @platform_data: the platform data to send
28340 * Activates the remote action.
28342 * This is the same as g_action_group_activate_action() except that it
28343 * allows for provision of "platform data" to be sent along with the
28344 * activation request. This typically contains details such as the user
28345 * interaction timestamp or startup notification information.
28347 * @platform_data must be non-%NULL and must have the type
28348 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
28355 * g_remote_action_group_change_action_state_full:
28356 * @remote: a #GRemoteActionGroup
28357 * @action_name: the name of the action to change the state of
28358 * @value: the new requested value for the state
28359 * @platform_data: the platform data to send
28361 * Changes the state of a remote action.
28363 * This is the same as g_action_group_change_action_state() except that
28364 * it allows for provision of "platform data" to be sent along with the
28365 * state change request. This typically contains details such as the
28366 * user interaction timestamp or startup notification information.
28368 * @platform_data must be non-%NULL and must have the type
28369 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
28376 * g_resolver_error_quark:
28378 * Gets the #GResolver Error Quark.
28380 * Returns: a #GQuark.
28386 * g_resolver_free_addresses: (skip)
28387 * @addresses: a #GList of #GInetAddress
28389 * Frees @addresses (which should be the return value from
28390 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
28391 * (This is a convenience method; you can also simply free the results
28399 * g_resolver_free_targets: (skip)
28400 * @targets: a #GList of #GSrvTarget
28402 * Frees @targets (which should be the return value from
28403 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
28404 * (This is a convenience method; you can also simply free the
28405 * results by hand.)
28412 * g_resolver_get_default:
28414 * Gets the default #GResolver. You should unref it when you are done
28415 * with it. #GResolver may use its reference count as a hint about how
28416 * many threads it should allocate for concurrent DNS resolutions.
28418 * Returns: (transfer full): the default #GResolver.
28424 * g_resolver_lookup_by_address:
28425 * @resolver: a #GResolver
28426 * @address: the address to reverse-resolve
28427 * @cancellable: (allow-none): a #GCancellable, or %NULL
28428 * @error: return location for a #GError, or %NULL
28430 * Synchronously reverse-resolves @address to determine its
28431 * associated hostname.
28433 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28434 * a value from #GResolverError.
28436 * If @cancellable is non-%NULL, it can be used to cancel the
28437 * operation, in which case @error (if non-%NULL) will be set to
28438 * %G_IO_ERROR_CANCELLED.
28440 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
28441 * form), or %NULL on error.
28447 * g_resolver_lookup_by_address_async:
28448 * @resolver: a #GResolver
28449 * @address: the address to reverse-resolve
28450 * @cancellable: (allow-none): a #GCancellable, or %NULL
28451 * @callback: (scope async): callback to call after resolution completes
28452 * @user_data: (closure): data for @callback
28454 * Begins asynchronously reverse-resolving @address to determine its
28455 * associated hostname, and eventually calls @callback, which must
28456 * call g_resolver_lookup_by_address_finish() to get the final result.
28463 * g_resolver_lookup_by_address_finish:
28464 * @resolver: a #GResolver
28465 * @result: the result passed to your #GAsyncReadyCallback
28466 * @error: return location for a #GError, or %NULL
28468 * Retrieves the result of a previous call to
28469 * g_resolver_lookup_by_address_async().
28471 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28472 * a value from #GResolverError. If the operation was cancelled,
28473 * @error will be set to %G_IO_ERROR_CANCELLED.
28475 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
28476 * form), or %NULL on error.
28482 * g_resolver_lookup_by_name:
28483 * @resolver: a #GResolver
28484 * @hostname: the hostname to look up
28485 * @cancellable: (allow-none): a #GCancellable, or %NULL
28486 * @error: return location for a #GError, or %NULL
28488 * Synchronously resolves @hostname to determine its associated IP
28489 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
28490 * the textual form of an IP address (in which case this just becomes
28491 * a wrapper around g_inet_address_new_from_string()).
28493 * On success, g_resolver_lookup_by_name() will return a #GList of
28494 * #GInetAddress, sorted in order of preference and guaranteed to not
28495 * contain duplicates. That is, if using the result to connect to
28496 * @hostname, you should attempt to connect to the first address
28497 * first, then the second if the first fails, etc. If you are using
28498 * the result to listen on a socket, it is appropriate to add each
28499 * result using e.g. g_socket_listener_add_address().
28501 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
28502 * value from #GResolverError.
28504 * If @cancellable is non-%NULL, it can be used to cancel the
28505 * operation, in which case @error (if non-%NULL) will be set to
28506 * %G_IO_ERROR_CANCELLED.
28508 * If you are planning to connect to a socket on the resolved IP
28509 * address, it may be easier to create a #GNetworkAddress and use its
28510 * #GSocketConnectable interface.
28512 * Returns: (element-type GInetAddress) (transfer full): a #GList
28513 * of #GInetAddress, or %NULL on error. You
28514 * must unref each of the addresses and free the list when you are
28515 * done with it. (You can use g_resolver_free_addresses() to do this.)
28521 * g_resolver_lookup_by_name_async:
28522 * @resolver: a #GResolver
28523 * @hostname: the hostname to look up the address of
28524 * @cancellable: (allow-none): a #GCancellable, or %NULL
28525 * @callback: (scope async): callback to call after resolution completes
28526 * @user_data: (closure): data for @callback
28528 * Begins asynchronously resolving @hostname to determine its
28529 * associated IP address(es), and eventually calls @callback, which
28530 * must call g_resolver_lookup_by_name_finish() to get the result.
28531 * See g_resolver_lookup_by_name() for more details.
28538 * g_resolver_lookup_by_name_finish:
28539 * @resolver: a #GResolver
28540 * @result: the result passed to your #GAsyncReadyCallback
28541 * @error: return location for a #GError, or %NULL
28543 * Retrieves the result of a call to
28544 * g_resolver_lookup_by_name_async().
28546 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28547 * a value from #GResolverError. If the operation was cancelled,
28548 * @error will be set to %G_IO_ERROR_CANCELLED.
28550 * Returns: (element-type GInetAddress) (transfer full): a #GList
28551 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
28552 * for more details.
28558 * g_resolver_lookup_records:
28559 * @resolver: a #GResolver
28560 * @rrname: the DNS name to lookup the record for
28561 * @record_type: the type of DNS record to lookup
28562 * @cancellable: (allow-none): a #GCancellable, or %NULL
28563 * @error: return location for a #GError, or %NULL
28565 * Synchronously performs a DNS record lookup for the given @rrname and returns
28566 * a list of records as #GVariant tuples. See #GResolverRecordType for
28567 * information on what the records contain for each @record_type.
28569 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28570 * a value from #GResolverError.
28572 * If @cancellable is non-%NULL, it can be used to cancel the
28573 * operation, in which case @error (if non-%NULL) will be set to
28574 * %G_IO_ERROR_CANCELLED.
28576 * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant,
28577 * or %NULL on error. You must free each of the records and the list when you are
28578 * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
28584 * g_resolver_lookup_records_async:
28585 * @resolver: a #GResolver
28586 * @rrname: the DNS name to lookup the record for
28587 * @record_type: the type of DNS record to lookup
28588 * @cancellable: (allow-none): a #GCancellable, or %NULL
28589 * @callback: (scope async): callback to call after resolution completes
28590 * @user_data: (closure): data for @callback
28592 * Begins asynchronously performing a DNS lookup for the given
28593 * @rrname, and eventually calls @callback, which must call
28594 * g_resolver_lookup_records_finish() to get the final result. See
28595 * g_resolver_lookup_records() for more details.
28602 * g_resolver_lookup_records_finish:
28603 * @resolver: a #GResolver
28604 * @result: the result passed to your #GAsyncReadyCallback
28605 * @error: return location for a #GError, or %NULL
28607 * Retrieves the result of a previous call to
28608 * g_resolver_lookup_records_async(). Returns a list of records as #GVariant
28609 * tuples. See #GResolverRecordType for information on what the records contain.
28611 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28612 * a value from #GResolverError. If the operation was cancelled,
28613 * @error will be set to %G_IO_ERROR_CANCELLED.
28615 * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant,
28616 * or %NULL on error. You must free each of the records and the list when you are
28617 * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
28623 * g_resolver_lookup_service:
28624 * @resolver: a #GResolver
28625 * @service: the service type to look up (eg, "ldap")
28626 * @protocol: the networking protocol to use for @service (eg, "tcp")
28627 * @domain: the DNS domain to look up the service in
28628 * @cancellable: (allow-none): a #GCancellable, or %NULL
28629 * @error: return location for a #GError, or %NULL
28631 * Synchronously performs a DNS SRV lookup for the given @service and
28632 * @protocol in the given @domain and returns an array of #GSrvTarget.
28633 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
28634 * @service and @protocol arguments <emphasis>do not</emphasis>
28635 * include the leading underscore that appears in the actual DNS
28638 * On success, g_resolver_lookup_service() will return a #GList of
28639 * #GSrvTarget, sorted in order of preference. (That is, you should
28640 * attempt to connect to the first target first, then the second if
28641 * the first fails, etc.)
28643 * If the DNS resolution fails, @error (if non-%NULL) will be set to
28644 * a value from #GResolverError.
28646 * If @cancellable is non-%NULL, it can be used to cancel the
28647 * operation, in which case @error (if non-%NULL) will be set to
28648 * %G_IO_ERROR_CANCELLED.
28650 * If you are planning to connect to the service, it is usually easier
28651 * to create a #GNetworkService and use its #GSocketConnectable
28654 * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
28655 * or %NULL on error. You must free each of the targets and the list when you are
28656 * done with it. (You can use g_resolver_free_targets() to do this.)
28662 * g_resolver_lookup_service_async:
28663 * @resolver: a #GResolver
28664 * @service: the service type to look up (eg, "ldap")
28665 * @protocol: the networking protocol to use for @service (eg, "tcp")
28666 * @domain: the DNS domain to look up the service in
28667 * @cancellable: (allow-none): a #GCancellable, or %NULL
28668 * @callback: (scope async): callback to call after resolution completes
28669 * @user_data: (closure): data for @callback
28671 * Begins asynchronously performing a DNS SRV lookup for the given
28672 * @service and @protocol in the given @domain, and eventually calls
28673 * @callback, which must call g_resolver_lookup_service_finish() to
28674 * get the final result. See g_resolver_lookup_service() for more
28682 * g_resolver_lookup_service_finish:
28683 * @resolver: a #GResolver
28684 * @result: the result passed to your #GAsyncReadyCallback
28685 * @error: return location for a #GError, or %NULL
28687 * Retrieves the result of a previous call to
28688 * g_resolver_lookup_service_async().
28690 * If the DNS resolution failed, @error (if non-%NULL) will be set to
28691 * a value from #GResolverError. If the operation was cancelled,
28692 * @error will be set to %G_IO_ERROR_CANCELLED.
28694 * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
28695 * or %NULL on error. See g_resolver_lookup_service() for more details.
28701 * g_resolver_set_default:
28702 * @resolver: the new default #GResolver
28704 * Sets @resolver to be the application's default resolver (reffing
28705 * @resolver, and unreffing the previous default resolver, if any).
28706 * Future calls to g_resolver_get_default() will return this resolver.
28708 * This can be used if an application wants to perform any sort of DNS
28709 * caching or "pinning"; it can implement its own #GResolver that
28710 * calls the original default resolver for DNS operations, and
28711 * implements its own cache policies on top of that, and then set
28712 * itself as the default resolver for all later code to use.
28719 * g_resource_enumerate_children:
28720 * @resource: A #GResource
28721 * @path: A pathname inside the resource
28722 * @lookup_flags: A #GResourceLookupFlags
28723 * @error: return location for a #GError, or %NULL
28725 * Returns all the names of children at the specified @path in the resource.
28726 * The return result is a %NULL terminated list of strings which should
28727 * be released with g_strfreev().
28729 * @lookup_flags controls the behaviour of the lookup.
28731 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
28737 * g_resource_error_quark:
28739 * Gets the #GResource Error Quark.
28741 * Returns: a #GQuark
28747 * g_resource_get_info:
28748 * @resource: A #GResource
28749 * @path: A pathname inside the resource
28750 * @lookup_flags: A #GResourceLookupFlags
28751 * @size: (out) (allow-none): a location to place the length of the contents of the file,
28752 * or %NULL if the length is not needed
28753 * @flags: (out) (allow-none): a location to place the flags about the file,
28754 * or %NULL if the length is not needed
28755 * @error: return location for a #GError, or %NULL
28757 * Looks for a file at the specified @path in the resource and
28758 * if found returns information about it.
28760 * @lookup_flags controls the behaviour of the lookup.
28762 * Returns: %TRUE if the file was found. %FALSE if there were errors
28769 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
28770 * @error: return location for a #GError, or %NULL
28772 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
28773 * you to query it for data.
28775 * If you want to use this resource in the global resource namespace you need
28776 * to register it with g_resources_register().
28778 * Returns: (transfer full): a new #GResource, or %NULL on error
28784 * g_resource_lookup_data:
28785 * @resource: A #GResource
28786 * @path: A pathname inside the resource
28787 * @lookup_flags: A #GResourceLookupFlags
28788 * @error: return location for a #GError, or %NULL
28790 * Looks for a file at the specified @path in the resource and
28791 * returns a #GBytes that lets you directly access the data in
28794 * The data is always followed by a zero byte, so you
28795 * can safely use the data as a C string. However, that byte
28796 * is not included in the size of the GBytes.
28798 * For uncompressed resource files this is a pointer directly into
28799 * the resource bundle, which is typically in some readonly data section
28800 * in the program binary. For compressed files we allocate memory on
28801 * the heap and automatically uncompress the data.
28803 * @lookup_flags controls the behaviour of the lookup.
28805 * Returns: (transfer full): #GBytes or %NULL on error.
28806 * Free the returned object with g_bytes_unref()
28812 * g_resource_new_from_data:
28814 * @error: return location for a #GError, or %NULL
28816 * Creates a GResource from a reference to the binary resource bundle.
28817 * This will keep a reference to @data while the resource lives, so
28818 * the data should not be modified or freed.
28820 * If you want to use this resource in the global resource namespace you need
28821 * to register it with g_resources_register().
28823 * Returns: (transfer full): a new #GResource, or %NULL on error
28829 * g_resource_open_stream:
28830 * @resource: A #GResource
28831 * @path: A pathname inside the resource
28832 * @lookup_flags: A #GResourceLookupFlags
28833 * @error: return location for a #GError, or %NULL
28835 * Looks for a file at the specified @path in the resource and
28836 * returns a #GInputStream that lets you read the data.
28838 * @lookup_flags controls the behaviour of the lookup.
28840 * Returns: (transfer full): #GInputStream or %NULL on error.
28841 * Free the returned object with g_object_unref()
28848 * @resource: A #GResource
28850 * Atomically increments the reference count of @array by one. This
28851 * function is MT-safe and may be called from any thread.
28853 * Returns: The passed in #GResource
28859 * g_resource_unref:
28860 * @resource: A #GResource
28862 * Atomically decrements the reference count of @resource by one. If the
28863 * reference count drops to 0, all memory allocated by the array is
28864 * released. This function is MT-safe and may be called from any
28872 * g_resources_enumerate_children:
28873 * @path: A pathname inside the resource
28874 * @lookup_flags: A #GResourceLookupFlags
28875 * @error: return location for a #GError, or %NULL
28877 * Returns all the names of children at the specified @path in the set of
28878 * globally registered resources.
28879 * The return result is a %NULL terminated list of strings which should
28880 * be released with g_strfreev().
28882 * @lookup_flags controls the behaviour of the lookup.
28884 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
28890 * g_resources_get_info:
28891 * @path: A pathname inside the resource
28892 * @lookup_flags: A #GResourceLookupFlags
28893 * @size: (out) (allow-none): a location to place the length of the contents of the file,
28894 * or %NULL if the length is not needed
28895 * @flags: (out) (allow-none): a location to place the flags about the file,
28896 * or %NULL if the length is not needed
28897 * @error: return location for a #GError, or %NULL
28899 * Looks for a file at the specified @path in the set of
28900 * globally registered resources and if found returns information about it.
28902 * @lookup_flags controls the behaviour of the lookup.
28904 * Returns: %TRUE if the file was found. %FALSE if there were errors
28910 * g_resources_lookup_data:
28911 * @path: A pathname inside the resource
28912 * @lookup_flags: A #GResourceLookupFlags
28913 * @error: return location for a #GError, or %NULL
28915 * Looks for a file at the specified @path in the set of
28916 * globally registered resources and returns a #GBytes that
28917 * lets you directly access the data in memory.
28919 * The data is always followed by a zero byte, so you
28920 * can safely use the data as a C string. However, that byte
28921 * is not included in the size of the GBytes.
28923 * For uncompressed resource files this is a pointer directly into
28924 * the resource bundle, which is typically in some readonly data section
28925 * in the program binary. For compressed files we allocate memory on
28926 * the heap and automatically uncompress the data.
28928 * @lookup_flags controls the behaviour of the lookup.
28930 * Returns: (transfer full): #GBytes or %NULL on error.
28931 * Free the returned object with g_bytes_unref()
28937 * g_resources_open_stream:
28938 * @path: A pathname inside the resource
28939 * @lookup_flags: A #GResourceLookupFlags
28940 * @error: return location for a #GError, or %NULL
28942 * Looks for a file at the specified @path in the set of
28943 * globally registered resources and returns a #GInputStream
28944 * that lets you read the data.
28946 * @lookup_flags controls the behaviour of the lookup.
28948 * Returns: (transfer full): #GInputStream or %NULL on error.
28949 * Free the returned object with g_object_unref()
28955 * g_resources_register:
28956 * @resource: A #GResource
28958 * Registers the resource with the process-global set of resources.
28959 * Once a resource is registered the files in it can be accessed
28960 * with the global resource lookup functions like g_resources_lookup_data().
28967 * g_resources_unregister:
28968 * @resource: A #GResource
28970 * Unregisters the resource from the process-global set of resources.
28977 * g_seekable_can_seek:
28978 * @seekable: a #GSeekable.
28980 * Tests if the stream supports the #GSeekableIface.
28982 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
28987 * g_seekable_can_truncate:
28988 * @seekable: a #GSeekable.
28990 * Tests if the stream can be truncated.
28992 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
28998 * @seekable: a #GSeekable.
28999 * @offset: a #goffset.
29000 * @type: a #GSeekType.
29001 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29002 * @error: a #GError location to store the error occurring, or %NULL to
29005 * Seeks in the stream by the given @offset, modified by @type.
29007 * Attempting to seek past the end of the stream will have different
29008 * results depending on if the stream is fixed-sized or resizable. If
29009 * the stream is resizable then seeking past the end and then writing
29010 * will result in zeros filling the empty space. Seeking past the end
29011 * of a resizable stream and reading will result in EOF. Seeking past
29012 * the end of a fixed-sized stream will fail.
29014 * Any operation that would result in a negative offset will fail.
29016 * If @cancellable is not %NULL, then the operation can be cancelled by
29017 * triggering the cancellable object from another thread. If the operation
29018 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
29020 * Returns: %TRUE if successful. If an error
29021 * has occurred, this function will return %FALSE and set @error
29022 * appropriately if present.
29028 * @seekable: a #GSeekable.
29030 * Tells the current position within the stream.
29032 * Returns: the offset from the beginning of the buffer.
29037 * g_seekable_truncate: (virtual truncate_fn)
29038 * @seekable: a #GSeekable.
29039 * @offset: a #goffset.
29040 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29041 * @error: a #GError location to store the error occurring, or %NULL to
29044 * Truncates a stream with a given #offset.
29046 * If @cancellable is not %NULL, then the operation can be cancelled by
29047 * triggering the cancellable object from another thread. If the operation
29048 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
29049 * operation was partially finished when the operation was cancelled the
29050 * partial result will be returned, without an error.
29052 * Returns: %TRUE if successful. If an error
29053 * has occurred, this function will return %FALSE and set @error
29054 * appropriately if present.
29059 * g_settings_apply:
29060 * @settings: a #GSettings instance
29062 * Applies any changes that have been made to the settings. This
29063 * function does nothing unless @settings is in 'delay-apply' mode;
29064 * see g_settings_delay(). In the normal case settings are always
29065 * applied immediately.
29070 * g_settings_backend_changed:
29071 * @backend: a #GSettingsBackend implementation
29072 * @key: the name of the key
29073 * @origin_tag: the origin tag
29075 * Signals that a single key has possibly changed. Backend
29076 * implementations should call this if a key has possibly changed its
29079 * @key must be a valid key (ie starting with a slash, not containing
29080 * '//', and not ending with a slash).
29082 * The implementation must call this function during any call to
29083 * g_settings_backend_write(), before the call returns (except in the
29084 * case that no keys are actually changed and it cares to detect this
29085 * fact). It may not rely on the existence of a mainloop for
29086 * dispatching the signal later.
29088 * The implementation may call this function at any other time it likes
29089 * in response to other events (such as changes occurring outside of the
29090 * program). These calls may originate from a mainloop or may originate
29091 * in response to any other action (including from calls to
29092 * g_settings_backend_write()).
29094 * In the case that this call is in response to a call to
29095 * g_settings_backend_write() then @origin_tag must be set to the same
29096 * value that was passed to that call.
29103 * g_settings_backend_changed_tree:
29104 * @backend: a #GSettingsBackend implementation
29105 * @tree: a #GTree containing the changes
29106 * @origin_tag: the origin tag
29108 * This call is a convenience wrapper. It gets the list of changes from
29109 * @tree, computes the longest common prefix and calls
29110 * g_settings_backend_changed().
29117 * g_settings_backend_flatten_tree:
29118 * @tree: a #GTree containing the changes
29119 * @path: (out): the location to save the path
29120 * @keys: (out) (transfer container) (array zero-terminated=1): the
29121 * location to save the relative keys
29122 * @values: (out) (allow-none) (transfer container) (array zero-terminated=1):
29123 * the location to save the values, or %NULL
29125 * Calculate the longest common prefix of all keys in a tree and write
29126 * out an array of the key names relative to that prefix and,
29127 * optionally, the value to store at each of those keys.
29129 * You must free the value returned in @path, @keys and @values using
29130 * g_free(). You should not attempt to free or unref the contents of
29131 * @keys or @values.
29138 * g_settings_backend_get_default:
29140 * Returns the default #GSettingsBackend. It is possible to override
29141 * the default by setting the <envar>GSETTINGS_BACKEND</envar>
29142 * environment variable to the name of a settings backend.
29144 * The user gets a reference to the backend.
29146 * Returns: (transfer full): the default #GSettingsBackend
29152 * g_settings_backend_keys_changed:
29153 * @backend: a #GSettingsBackend implementation
29154 * @path: the path containing the changes
29155 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
29156 * @origin_tag: the origin tag
29158 * Signals that a list of keys have possibly changed. Backend
29159 * implementations should call this if keys have possibly changed their
29162 * @path must be a valid path (ie starting and ending with a slash and
29163 * not containing '//'). Each string in @items must form a valid key
29164 * name when @path is prefixed to it (ie: each item must not start or
29165 * end with '/' and must not contain '//').
29167 * The meaning of this signal is that any of the key names resulting
29168 * from the contatenation of @path with each item in @items may have
29171 * The same rules for when notifications must occur apply as per
29172 * g_settings_backend_changed(). These two calls can be used
29173 * interchangeably if exactly one item has changed (although in that
29174 * case g_settings_backend_changed() is definitely preferred).
29176 * For efficiency reasons, the implementation should strive for @path to
29177 * be as long as possible (ie: the longest common prefix of all of the
29178 * keys that were changed) but this is not strictly required.
29185 * g_settings_backend_path_changed:
29186 * @backend: a #GSettingsBackend implementation
29187 * @path: the path containing the changes
29188 * @origin_tag: the origin tag
29190 * Signals that all keys below a given path may have possibly changed.
29191 * Backend implementations should call this if an entire path of keys
29192 * have possibly changed their values.
29194 * @path must be a valid path (ie starting and ending with a slash and
29195 * not containing '//').
29197 * The meaning of this signal is that any of the key which has a name
29198 * starting with @path may have changed.
29200 * The same rules for when notifications must occur apply as per
29201 * g_settings_backend_changed(). This call might be an appropriate
29202 * reasponse to a 'reset' call but implementations are also free to
29203 * explicitly list the keys that were affected by that call if they can
29206 * For efficiency reasons, the implementation should strive for @path to
29207 * be as long as possible (ie: the longest common prefix of all of the
29208 * keys that were changed) but this is not strictly required. As an
29209 * example, if this function is called with the path of "/" then every
29210 * single key in the application will be notified of a possible change.
29217 * g_settings_backend_path_writable_changed:
29218 * @backend: a #GSettingsBackend implementation
29219 * @path: the name of the path
29221 * Signals that the writability of all keys below a given path may have
29224 * Since GSettings performs no locking operations for itself, this call
29225 * will always be made in response to external events.
29232 * g_settings_backend_writable_changed:
29233 * @backend: a #GSettingsBackend implementation
29234 * @key: the name of the key
29236 * Signals that the writability of a single key has possibly changed.
29238 * Since GSettings performs no locking operations for itself, this call
29239 * will always be made in response to external events.
29247 * @settings: a #GSettings object
29248 * @key: the key to bind
29249 * @object: (type GObject.Object): a #GObject
29250 * @property: the name of the property to bind
29251 * @flags: flags for the binding
29253 * Create a binding between the @key in the @settings object
29254 * and the property @property of @object.
29256 * The binding uses the default GIO mapping functions to map
29257 * between the settings and property values. These functions
29258 * handle booleans, numeric types and string types in a
29259 * straightforward way. Use g_settings_bind_with_mapping() if
29260 * you need a custom mapping, or map between types that are not
29261 * supported by the default mapping functions.
29263 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
29264 * function also establishes a binding between the writability of
29265 * @key and the "sensitive" property of @object (if @object has
29266 * a boolean property by that name). See g_settings_bind_writable()
29267 * for more details about writable bindings.
29269 * Note that the lifecycle of the binding is tied to the object,
29270 * and that you can have only one binding per object property.
29271 * If you bind the same property twice on the same object, the second
29272 * binding overrides the first one.
29279 * g_settings_bind_with_mapping: (skip)
29280 * @settings: a #GSettings object
29281 * @key: the key to bind
29282 * @object: (type GObject.Object): a #GObject
29283 * @property: the name of the property to bind
29284 * @flags: flags for the binding
29285 * @get_mapping: a function that gets called to convert values
29286 * from @settings to @object, or %NULL to use the default GIO mapping
29287 * @set_mapping: a function that gets called to convert values
29288 * from @object to @settings, or %NULL to use the default GIO mapping
29289 * @user_data: data that gets passed to @get_mapping and @set_mapping
29290 * @destroy: #GDestroyNotify function for @user_data
29292 * Create a binding between the @key in the @settings object
29293 * and the property @property of @object.
29295 * The binding uses the provided mapping functions to map between
29296 * settings and property values.
29298 * Note that the lifecycle of the binding is tied to the object,
29299 * and that you can have only one binding per object property.
29300 * If you bind the same property twice on the same object, the second
29301 * binding overrides the first one.
29308 * g_settings_bind_writable:
29309 * @settings: a #GSettings object
29310 * @key: the key to bind
29311 * @object: (type GObject.Object): a #GObject
29312 * @property: the name of a boolean property to bind
29313 * @inverted: whether to 'invert' the value
29315 * Create a binding between the writability of @key in the
29316 * @settings object and the property @property of @object.
29317 * The property must be boolean; "sensitive" or "visible"
29318 * properties of widgets are the most likely candidates.
29320 * Writable bindings are always uni-directional; changes of the
29321 * writability of the setting will be propagated to the object
29322 * property, not the other way.
29324 * When the @inverted argument is %TRUE, the binding inverts the
29325 * value as it passes from the setting to the object, i.e. @property
29326 * will be set to %TRUE if the key is <emphasis>not</emphasis>
29329 * Note that the lifecycle of the binding is tied to the object,
29330 * and that you can have only one binding per object property.
29331 * If you bind the same property twice on the same object, the second
29332 * binding overrides the first one.
29339 * g_settings_create_action:
29340 * @settings: a #GSettings
29341 * @key: the name of a key in @settings
29343 * Creates a #GAction corresponding to a given #GSettings key.
29345 * The action has the same name as the key.
29347 * The value of the key becomes the state of the action and the action
29348 * is enabled when the key is writable. Changing the state of the
29349 * action results in the key being written to. Changes to the value or
29350 * writability of the key cause appropriate change notifications to be
29351 * emitted for the action.
29353 * For boolean-valued keys, action activations take no parameter and
29354 * result in the toggling of the value. For all other types,
29355 * activations take the new value for the key (which must have the
29358 * Returns: (transfer full): a new #GAction
29364 * g_settings_delay:
29365 * @settings: a #GSettings object
29367 * Changes the #GSettings object into 'delay-apply' mode. In this
29368 * mode, changes to @settings are not immediately propagated to the
29369 * backend, but kept locally until g_settings_apply() is called.
29377 * @settings: a #GSettings object
29378 * @key: the key to get the value for
29379 * @format: a #GVariant format string
29380 * @...: arguments as per @format
29382 * Gets the value that is stored at @key in @settings.
29384 * A convenience function that combines g_settings_get_value() with
29387 * It is a programmer error to give a @key that isn't contained in the
29388 * schema for @settings or for the #GVariantType of @format to mismatch
29389 * the type given in the schema.
29396 * g_settings_get_boolean:
29397 * @settings: a #GSettings object
29398 * @key: the key to get the value for
29400 * Gets the value that is stored at @key in @settings.
29402 * A convenience variant of g_settings_get() for booleans.
29404 * It is a programmer error to give a @key that isn't specified as
29405 * having a boolean type in the schema for @settings.
29407 * Returns: a boolean
29413 * g_settings_get_child:
29414 * @settings: a #GSettings object
29415 * @name: the name of the 'child' schema
29417 * Creates a 'child' settings object which has a base path of
29418 * <replaceable>base-path</replaceable>/@name, where
29419 * <replaceable>base-path</replaceable> is the base path of @settings.
29421 * The schema for the child settings object must have been declared
29422 * in the schema of @settings using a <tag class="starttag">child</tag> element.
29424 * Returns: (transfer full): a 'child' settings object
29430 * g_settings_get_default_value:
29431 * @settings: a #GSettings object
29432 * @key: the key to check for being set
29434 * Gets the "default value" of a key.
29436 * This is the value that would be read if g_settings_reset() were to be
29437 * called on the key.
29439 * Note that this may be a different value than returned by
29440 * g_settings_schema_key_get_default_value() if the system administrator
29441 * has provided a default value.
29443 * Comparing the return values of g_settings_get_default_value() and
29444 * g_settings_get_value() is not sufficient for determining if a value
29445 * has been set because the user may have explicitly set the value to
29446 * something that happens to be equal to the default. The difference
29447 * here is that if the default changes in the future, the user's key
29448 * will still be set.
29450 * This function may be useful for adding an indication to a UI of what
29451 * the default value was before the user set it.
29453 * It is a programmer error to give a @key that isn't contained in the
29454 * schema for @settings.
29456 * Returns: (allow none) (transfer full): the default value
29462 * g_settings_get_double:
29463 * @settings: a #GSettings object
29464 * @key: the key to get the value for
29466 * Gets the value that is stored at @key in @settings.
29468 * A convenience variant of g_settings_get() for doubles.
29470 * It is a programmer error to give a @key that isn't specified as
29471 * having a 'double' type in the schema for @settings.
29473 * Returns: a double
29479 * g_settings_get_enum:
29480 * @settings: a #GSettings object
29481 * @key: the key to get the value for
29483 * Gets the value that is stored in @settings for @key and converts it
29484 * to the enum value that it represents.
29486 * In order to use this function the type of the value must be a string
29487 * and it must be marked in the schema file as an enumerated type.
29489 * It is a programmer error to give a @key that isn't contained in the
29490 * schema for @settings or is not marked as an enumerated type.
29492 * If the value stored in the configuration database is not a valid
29493 * value for the enumerated type then this function will return the
29496 * Returns: the enum value
29502 * g_settings_get_flags:
29503 * @settings: a #GSettings object
29504 * @key: the key to get the value for
29506 * Gets the value that is stored in @settings for @key and converts it
29507 * to the flags value that it represents.
29509 * In order to use this function the type of the value must be an array
29510 * of strings and it must be marked in the schema file as an flags type.
29512 * It is a programmer error to give a @key that isn't contained in the
29513 * schema for @settings or is not marked as a flags type.
29515 * If the value stored in the configuration database is not a valid
29516 * value for the flags type then this function will return the default
29519 * Returns: the flags value
29525 * g_settings_get_has_unapplied:
29526 * @settings: a #GSettings object
29528 * Returns whether the #GSettings object has any unapplied
29529 * changes. This can only be the case if it is in 'delayed-apply' mode.
29531 * Returns: %TRUE if @settings has unapplied changes
29537 * g_settings_get_int:
29538 * @settings: a #GSettings object
29539 * @key: the key to get the value for
29541 * Gets the value that is stored at @key in @settings.
29543 * A convenience variant of g_settings_get() for 32-bit integers.
29545 * It is a programmer error to give a @key that isn't specified as
29546 * having a int32 type in the schema for @settings.
29548 * Returns: an integer
29554 * g_settings_get_mapped:
29555 * @settings: a #GSettings object
29556 * @key: the key to get the value for
29557 * @mapping: (scope call): the function to map the value in the
29558 * settings database to the value used by the application
29559 * @user_data: user data for @mapping
29561 * Gets the value that is stored at @key in @settings, subject to
29562 * application-level validation/mapping.
29564 * You should use this function when the application needs to perform
29565 * some processing on the value of the key (for example, parsing). The
29566 * @mapping function performs that processing. If the function
29567 * indicates that the processing was unsuccessful (due to a parse error,
29568 * for example) then the mapping is tried again with another value.
29570 * This allows a robust 'fall back to defaults' behaviour to be
29571 * implemented somewhat automatically.
29573 * The first value that is tried is the user's setting for the key. If
29574 * the mapping function fails to map this value, other values may be
29575 * tried in an unspecified order (system or site defaults, translated
29576 * schema default values, untranslated schema default values, etc).
29578 * If the mapping function fails for all possible values, one additional
29579 * attempt is made: the mapping function is called with a %NULL value.
29580 * If the mapping function still indicates failure at this point then
29581 * the application will be aborted.
29583 * The result parameter for the @mapping function is pointed to a
29584 * #gpointer which is initially set to %NULL. The same pointer is given
29585 * to each invocation of @mapping. The final value of that #gpointer is
29586 * what is returned by this function. %NULL is valid; it is returned
29587 * just as any other value would be.
29589 * Returns: (transfer full): the result, which may be %NULL
29594 * g_settings_get_range:
29595 * @settings: a #GSettings
29596 * @key: the key to query the range of
29598 * Queries the range of a key.
29601 * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead.
29606 * g_settings_get_string:
29607 * @settings: a #GSettings object
29608 * @key: the key to get the value for
29610 * Gets the value that is stored at @key in @settings.
29612 * A convenience variant of g_settings_get() for strings.
29614 * It is a programmer error to give a @key that isn't specified as
29615 * having a string type in the schema for @settings.
29617 * Returns: a newly-allocated string
29623 * g_settings_get_strv:
29624 * @settings: a #GSettings object
29625 * @key: the key to get the value for
29627 * A convenience variant of g_settings_get() for string arrays.
29629 * It is a programmer error to give a @key that isn't specified as
29630 * having an array of strings type in the schema for @settings.
29632 * Returns: (array zero-terminated=1) (transfer full): a
29633 * newly-allocated, %NULL-terminated array of strings, the value that
29634 * is stored at @key in @settings.
29640 * g_settings_get_uint:
29641 * @settings: a #GSettings object
29642 * @key: the key to get the value for
29644 * Gets the value that is stored at @key in @settings.
29646 * A convenience variant of g_settings_get() for 32-bit unsigned
29649 * It is a programmer error to give a @key that isn't specified as
29650 * having a uint32 type in the schema for @settings.
29652 * Returns: an unsigned integer
29658 * g_settings_get_user_value:
29659 * @settings: a #GSettings object
29660 * @key: the key to check for being set
29662 * Checks the "user value" of a key, if there is one.
29664 * The user value of a key is the last value that was set by the user.
29666 * After calling g_settings_reset() this function should always return
29667 * %NULL (assuming something is not wrong with the system
29670 * It is possible that g_settings_get_value() will return a different
29671 * value than this function. This can happen in the case that the user
29672 * set a value for a key that was subsequently locked down by the system
29673 * administrator -- this function will return the user's old value.
29675 * This function may be useful for adding a "reset" option to a UI or
29676 * for providing indication that a particular value has been changed.
29678 * It is a programmer error to give a @key that isn't contained in the
29679 * schema for @settings.
29681 * Returns: (allow none) (transfer full): the user's value, if set
29687 * g_settings_get_value:
29688 * @settings: a #GSettings object
29689 * @key: the key to get the value for
29691 * Gets the value that is stored in @settings for @key.
29693 * It is a programmer error to give a @key that isn't contained in the
29694 * schema for @settings.
29696 * Returns: a new #GVariant
29702 * g_settings_is_writable:
29703 * @settings: a #GSettings object
29704 * @name: the name of a key
29706 * Finds out if a key can be written or not
29708 * Returns: %TRUE if the key @name is writable
29714 * g_settings_list_children:
29715 * @settings: a #GSettings object
29717 * Gets the list of children on @settings.
29719 * The list is exactly the list of strings for which it is not an error
29720 * to call g_settings_get_child().
29722 * For GSettings objects that are lists, this value can change at any
29723 * time and you should connect to the "children-changed" signal to watch
29724 * for those changes. Note that there is a race condition here: you may
29725 * request a child after listing it only for it to have been destroyed
29726 * in the meantime. For this reason, g_settings_get_child() may return
29727 * %NULL even for a child that was listed by this function.
29729 * For GSettings objects that are not lists, you should probably not be
29730 * calling this function from "normal" code (since you should already
29731 * know what children are in your schema). This function may still be
29732 * useful there for introspection reasons, however.
29734 * You should free the return value with g_strfreev() when you are done
29737 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
29742 * g_settings_list_keys:
29743 * @settings: a #GSettings object
29745 * Introspects the list of keys on @settings.
29747 * You should probably not be calling this function from "normal" code
29748 * (since you should already know what keys are in your schema). This
29749 * function is intended for introspection reasons.
29751 * You should free the return value with g_strfreev() when you are done
29754 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
29759 * g_settings_list_relocatable_schemas:
29761 * Returns: (element-type utf8) (transfer none): a list of relocatable
29762 * #GSettings schemas that are available. The list must not be
29763 * modified or freed.
29765 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
29770 * g_settings_list_schemas:
29772 * Returns: (element-type utf8) (transfer none): a list of #GSettings
29773 * schemas that are available. The list must not be modified or
29776 * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
29782 * @schema_id: the id of the schema
29784 * Creates a new #GSettings object with the schema specified by
29787 * Signals on the newly created #GSettings object will be dispatched
29788 * via the thread-default #GMainContext in effect at the time of the
29789 * call to g_settings_new(). The new #GSettings will hold a reference
29790 * on the context. See g_main_context_push_thread_default().
29792 * Returns: a new #GSettings object
29798 * g_settings_new_full:
29799 * @schema: a #GSettingsSchema
29800 * @backend: (allow-none): a #GSettingsBackend
29801 * @path: (allow-none): the path to use
29803 * Creates a new #GSettings object with a given schema, backend and
29806 * It should be extremely rare that you ever want to use this function.
29807 * It is made available for advanced use-cases (such as plugin systems
29808 * that want to provide access to schemas loaded from custom locations,
29811 * At the most basic level, a #GSettings object is a pure composition of
29812 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
29813 * backend, and a #GMainContext to which signals are dispatched.
29815 * This constructor therefore gives you full control over constructing
29816 * #GSettings instances. The first 4 parameters are given directly as
29817 * @schema, @backend and @path, and the main context is taken from the
29818 * thread-default (as per g_settings_new()).
29820 * If @backend is %NULL then the default backend is used.
29822 * If @path is %NULL then the path from the schema is used. It is an
29823 * error f @path is %NULL and the schema has no path of its own or if
29824 * @path is non-%NULL and not equal to the path that the schema does
29827 * Returns: a new #GSettings object
29833 * g_settings_new_with_backend:
29834 * @schema_id: the id of the schema
29835 * @backend: the #GSettingsBackend to use
29837 * Creates a new #GSettings object with the schema specified by
29838 * @schema_id and a given #GSettingsBackend.
29840 * Creating a #GSettings object with a different backend allows accessing
29841 * settings from a database other than the usual one. For example, it may make
29842 * sense to pass a backend corresponding to the "defaults" settings database on
29843 * the system to get a settings object that modifies the system default
29844 * settings instead of the settings for this user.
29846 * Returns: a new #GSettings object
29852 * g_settings_new_with_backend_and_path:
29853 * @schema_id: the id of the schema
29854 * @backend: the #GSettingsBackend to use
29855 * @path: the path to use
29857 * Creates a new #GSettings object with the schema specified by
29858 * @schema_id and a given #GSettingsBackend and path.
29860 * This is a mix of g_settings_new_with_backend() and
29861 * g_settings_new_with_path().
29863 * Returns: a new #GSettings object
29869 * g_settings_new_with_path:
29870 * @schema_id: the id of the schema
29871 * @path: the path to use
29873 * Creates a new #GSettings object with the relocatable schema specified
29874 * by @schema_id and a given path.
29876 * You only need to do this if you want to directly create a settings
29877 * object with a schema that doesn't have a specified path of its own.
29878 * That's quite rare.
29880 * It is a programmer error to call this function for a schema that
29881 * has an explicitly specified path.
29883 * It is a programmer error if @path is not a valid path. A valid path
29884 * begins and ends with '/' and does not contain two consecutive '/'
29887 * Returns: a new #GSettings object
29893 * g_settings_range_check:
29894 * @settings: a #GSettings
29895 * @key: the key to check
29896 * @value: the value to check
29898 * Checks if the given @value is of the correct type and within the
29899 * permitted range for @key.
29901 * Returns: %TRUE if @value is valid for @key
29903 * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead.
29908 * g_settings_reset:
29909 * @settings: a #GSettings object
29910 * @key: the name of a key
29912 * Resets @key to its default value.
29914 * This call resets the key, as much as possible, to its default value.
29915 * That might the value specified in the schema or the one set by the
29921 * g_settings_revert:
29922 * @settings: a #GSettings instance
29924 * Reverts all non-applied changes to the settings. This function
29925 * does nothing unless @settings is in 'delay-apply' mode; see
29926 * g_settings_delay(). In the normal case settings are always applied
29929 * Change notifications will be emitted for affected keys.
29934 * g_settings_schema_get_id:
29935 * @schema: a #GSettingsSchema
29937 * Get the ID of @schema.
29939 * Returns: (transfer none): the ID
29944 * g_settings_schema_get_key:
29945 * @schema: a #GSettingsSchema
29946 * @name: the name of a key
29948 * Gets the key named @name from @schema.
29950 * It is a programmer error to request a key that does not exist. See
29951 * g_settings_schema_list_keys().
29953 * Returns: (transfer full): the #GSettingsSchemaKey for @name
29959 * g_settings_schema_get_path:
29960 * @schema: a #GSettingsSchema
29962 * Gets the path associated with @schema, or %NULL.
29964 * Schemas may be single-instance or relocatable. Single-instance
29965 * schemas correspond to exactly one set of keys in the backend
29966 * database: those located at the path returned by this function.
29968 * Relocatable schemas can be referenced by other schemas and can
29969 * threfore describe multiple sets of keys at different locations. For
29970 * relocatable schemas, this function will return %NULL.
29972 * Returns: (transfer none): the path of the schema, or %NULL
29978 * g_settings_schema_has_key:
29979 * @schema: a #GSettingsSchema
29980 * @name: the name of a key
29982 * Checks if @schema has a key named @name.
29984 * Returns: %TRUE if such a key exists
29990 * g_settings_schema_key_get_default_value:
29991 * @key: a #GSettingsSchemaKey
29993 * Gets the default value for @key.
29995 * Note that this is the default value according to the schema. System
29996 * administrator defaults and lockdown are not visible via this API.
29998 * Returns: (transfer full): the default value for the key
30004 * g_settings_schema_key_get_description:
30005 * @key: a #GSettingsSchemaKey
30007 * Gets the description for @key.
30009 * If no description has been provided in the schema for @key, returns
30012 * The description can be one sentence to several paragraphs in length.
30013 * Paragraphs are delimited with a double newline. Descriptions can be
30014 * translated and the value returned from this function is is the
30017 * This function is slow. The summary and description information for
30018 * the schemas is not stored in the compiled schema database so this
30019 * function has to parse all of the source XML files in the schema
30022 * Returns: the description for @key, or %NULL
30028 * g_settings_schema_key_get_range:
30029 * @key: a #GSettingsSchemaKey
30031 * Queries the range of a key.
30033 * This function will return a #GVariant that fully describes the range
30034 * of values that are valid for @key.
30036 * The type of #GVariant returned is <literal>(sv)</literal>. The
30037 * string describes the type of range restriction in effect. The type
30038 * and meaning of the value contained in the variant depends on the
30041 * If the string is <literal>'type'</literal> then the variant contains
30042 * an empty array. The element type of that empty array is the expected
30043 * type of value and all values of that type are valid.
30045 * If the string is <literal>'enum'</literal> then the variant contains
30046 * an array enumerating the possible values. Each item in the array is
30047 * a possible valid value and no other values are valid.
30049 * If the string is <literal>'flags'</literal> then the variant contains
30050 * an array. Each item in the array is a value that may appear zero or
30051 * one times in an array to be used as the value for this key. For
30052 * example, if the variant contained the array <literal>['x',
30053 * 'y']</literal> then the valid values for the key would be
30054 * <literal>[]</literal>, <literal>['x']</literal>,
30055 * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
30056 * <literal>['y', 'x']</literal>.
30058 * Finally, if the string is <literal>'range'</literal> then the variant
30059 * contains a pair of like-typed values -- the minimum and maximum
30060 * permissible values for this key.
30062 * This information should not be used by normal programs. It is
30063 * considered to be a hint for introspection purposes. Normal programs
30064 * should already know what is permitted by their own schema. The
30065 * format may change in any way in the future -- but particularly, new
30066 * forms may be added to the possibilities described above.
30068 * You should free the returned value with g_variant_unref() when it is
30069 * no longer needed.
30071 * Returns: (transfer full): a #GVariant describing the range
30077 * g_settings_schema_key_get_summary:
30078 * @key: a #GSettingsSchemaKey
30080 * Gets the summary for @key.
30082 * If no summary has been provided in the schema for @key, returns
30085 * The summary is a short description of the purpose of the key; usually
30086 * one short sentence. Summaries can be translated and the value
30087 * returned from this function is is the current locale.
30089 * This function is slow. The summary and description information for
30090 * the schemas is not stored in the compiled schema database so this
30091 * function has to parse all of the source XML files in the schema
30094 * Returns: the summary for @key, or %NULL
30100 * g_settings_schema_key_get_value_type:
30101 * @key: a #GSettingsSchemaKey
30103 * Gets the #GVariantType of @key.
30105 * Returns: (transfer none): the type of @key
30111 * g_settings_schema_key_range_check:
30112 * @key: a #GSettingsSchemaKey
30113 * @value: the value to check
30115 * Checks if the given @value is of the correct type and within the
30116 * permitted range for @key.
30118 * It is a programmer error if @value is not of the correct type -- you
30119 * must check for this first.
30121 * Returns: %TRUE if @value is valid for @key
30127 * g_settings_schema_key_ref:
30128 * @key: a #GSettingsSchemaKey
30130 * Increase the reference count of @key, returning a new reference.
30132 * Returns: a new reference to @key
30138 * g_settings_schema_key_unref:
30139 * @key: a #GSettingsSchemaKey
30141 * Decrease the reference count of @key, possibly freeing it.
30148 * g_settings_schema_ref:
30149 * @schema: a #GSettingsSchema
30151 * Increase the reference count of @schema, returning a new reference.
30153 * Returns: a new reference to @schema
30159 * g_settings_schema_source_get_default:
30161 * Gets the default system schema source.
30163 * This function is not required for normal uses of #GSettings but it
30164 * may be useful to authors of plugin management systems or to those who
30165 * want to introspect the content of schemas.
30167 * If no schemas are installed, %NULL will be returned.
30169 * The returned source may actually consist of multiple schema sources
30170 * from different directories, depending on which directories were given
30171 * in <envar>XDG_DATA_DIRS</envar> and
30172 * <envar>GSETTINGS_SCHEMA_DIR</envar>. For this reason, all lookups
30173 * performed against the default source should probably be done
30176 * Returns: (transfer none): the default schema source
30182 * g_settings_schema_source_list_schemas:
30183 * @source: a #GSettingsSchemaSource
30184 * @recursive: if we should recurse
30185 * @non_relocatable: (out) (transfer full): the list of non-relocatable
30187 * @relocatable: (out) (transfer full): the list of relocatable schemas
30189 * Lists the schemas in a given source.
30191 * If @recursive is %TRUE then include parent sources. If %FALSE then
30192 * only include the schemas from one source (ie: one directory). You
30193 * probably want %TRUE.
30195 * Non-relocatable schemas are those for which you can call
30196 * g_settings_new(). Relocatable schemas are those for which you must
30197 * use g_settings_new_with_path().
30199 * Do not call this function from normal programs. This is designed for
30200 * use by database editors, commandline tools, etc.
30207 * g_settings_schema_source_lookup:
30208 * @source: a #GSettingsSchemaSource
30209 * @schema_id: a schema ID
30210 * @recursive: %TRUE if the lookup should be recursive
30212 * Looks up a schema with the identifier @schema_id in @source.
30214 * This function is not required for normal uses of #GSettings but it
30215 * may be useful to authors of plugin management systems or to those who
30216 * want to introspect the content of schemas.
30218 * If the schema isn't found directly in @source and @recursive is %TRUE
30219 * then the parent sources will also be checked.
30221 * If the schema isn't found, %NULL is returned.
30223 * Returns: (transfer full): a new #GSettingsSchema
30229 * g_settings_schema_source_new_from_directory:
30230 * @directory: the filename of a directory
30231 * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
30232 * @trusted: %TRUE, if the directory is trusted
30233 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
30235 * Attempts to create a new schema source corresponding to the contents
30236 * of the given directory.
30238 * This function is not required for normal uses of #GSettings but it
30239 * may be useful to authors of plugin management systems.
30241 * The directory should contain a file called
30242 * <filename>gschemas.compiled</filename> as produced by
30243 * <command>glib-compile-schemas</command>.
30245 * If @trusted is %TRUE then <filename>gschemas.compiled</filename> is
30246 * trusted not to be corrupted. This assumption has a performance
30247 * advantage, but can result in crashes or inconsistent behaviour in the
30248 * case of a corrupted file. Generally, you should set @trusted to
30249 * %TRUE for files installed by the system and to %FALSE for files in
30250 * the home directory.
30252 * If @parent is non-%NULL then there are two effects.
30254 * First, if g_settings_schema_source_lookup() is called with the
30255 * @recursive flag set to %TRUE and the schema can not be found in the
30256 * source, the lookup will recurse to the parent.
30258 * Second, any references to other schemas specified within this
30259 * source (ie: <literal>child</literal> or <literal>extends</literal>)
30260 * references may be resolved from the @parent.
30262 * For this second reason, except in very unusual situations, the
30263 * @parent should probably be given as the default schema source, as
30264 * returned by g_settings_schema_source_get_default().
30271 * g_settings_schema_source_ref:
30272 * @source: a #GSettingsSchemaSource
30274 * Increase the reference count of @source, returning a new reference.
30276 * Returns: a new reference to @source
30282 * g_settings_schema_source_unref:
30283 * @source: a #GSettingsSchemaSource
30285 * Decrease the reference count of @source, possibly freeing it.
30292 * g_settings_schema_unref:
30293 * @schema: a #GSettingsSchema
30295 * Decrease the reference count of @schema, possibly freeing it.
30303 * @settings: a #GSettings object
30304 * @key: the name of the key to set
30305 * @format: a #GVariant format string
30306 * @...: arguments as per @format
30308 * Sets @key in @settings to @value.
30310 * A convenience function that combines g_settings_set_value() with
30313 * It is a programmer error to give a @key that isn't contained in the
30314 * schema for @settings or for the #GVariantType of @format to mismatch
30315 * the type given in the schema.
30317 * Returns: %TRUE if setting the key succeeded,
30318 * %FALSE if the key was not writable
30324 * g_settings_set_boolean:
30325 * @settings: a #GSettings object
30326 * @key: the name of the key to set
30327 * @value: the value to set it to
30329 * Sets @key in @settings to @value.
30331 * A convenience variant of g_settings_set() for booleans.
30333 * It is a programmer error to give a @key that isn't specified as
30334 * having a boolean type in the schema for @settings.
30336 * Returns: %TRUE if setting the key succeeded,
30337 * %FALSE if the key was not writable
30343 * g_settings_set_double:
30344 * @settings: a #GSettings object
30345 * @key: the name of the key to set
30346 * @value: the value to set it to
30348 * Sets @key in @settings to @value.
30350 * A convenience variant of g_settings_set() for doubles.
30352 * It is a programmer error to give a @key that isn't specified as
30353 * having a 'double' type in the schema for @settings.
30355 * Returns: %TRUE if setting the key succeeded,
30356 * %FALSE if the key was not writable
30362 * g_settings_set_enum:
30363 * @settings: a #GSettings object
30364 * @key: a key, within @settings
30365 * @value: an enumerated value
30367 * Looks up the enumerated type nick for @value and writes it to @key,
30368 * within @settings.
30370 * It is a programmer error to give a @key that isn't contained in the
30371 * schema for @settings or is not marked as an enumerated type, or for
30372 * @value not to be a valid value for the named type.
30374 * After performing the write, accessing @key directly with
30375 * g_settings_get_string() will return the 'nick' associated with
30378 * Returns: %TRUE, if the set succeeds
30383 * g_settings_set_flags:
30384 * @settings: a #GSettings object
30385 * @key: a key, within @settings
30386 * @value: a flags value
30388 * Looks up the flags type nicks for the bits specified by @value, puts
30389 * them in an array of strings and writes the array to @key, within
30392 * It is a programmer error to give a @key that isn't contained in the
30393 * schema for @settings or is not marked as a flags type, or for @value
30394 * to contain any bits that are not value for the named type.
30396 * After performing the write, accessing @key directly with
30397 * g_settings_get_strv() will return an array of 'nicks'; one for each
30400 * Returns: %TRUE, if the set succeeds
30405 * g_settings_set_int:
30406 * @settings: a #GSettings object
30407 * @key: the name of the key to set
30408 * @value: the value to set it to
30410 * Sets @key in @settings to @value.
30412 * A convenience variant of g_settings_set() for 32-bit integers.
30414 * It is a programmer error to give a @key that isn't specified as
30415 * having a int32 type in the schema for @settings.
30417 * Returns: %TRUE if setting the key succeeded,
30418 * %FALSE if the key was not writable
30424 * g_settings_set_string:
30425 * @settings: a #GSettings object
30426 * @key: the name of the key to set
30427 * @value: the value to set it to
30429 * Sets @key in @settings to @value.
30431 * A convenience variant of g_settings_set() for strings.
30433 * It is a programmer error to give a @key that isn't specified as
30434 * having a string type in the schema for @settings.
30436 * Returns: %TRUE if setting the key succeeded,
30437 * %FALSE if the key was not writable
30443 * g_settings_set_strv:
30444 * @settings: a #GSettings object
30445 * @key: the name of the key to set
30446 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
30448 * Sets @key in @settings to @value.
30450 * A convenience variant of g_settings_set() for string arrays. If
30451 * @value is %NULL, then @key is set to be the empty array.
30453 * It is a programmer error to give a @key that isn't specified as
30454 * having an array of strings type in the schema for @settings.
30456 * Returns: %TRUE if setting the key succeeded,
30457 * %FALSE if the key was not writable
30463 * g_settings_set_uint:
30464 * @settings: a #GSettings object
30465 * @key: the name of the key to set
30466 * @value: the value to set it to
30468 * Sets @key in @settings to @value.
30470 * A convenience variant of g_settings_set() for 32-bit unsigned
30473 * It is a programmer error to give a @key that isn't specified as
30474 * having a uint32 type in the schema for @settings.
30476 * Returns: %TRUE if setting the key succeeded,
30477 * %FALSE if the key was not writable
30483 * g_settings_set_value:
30484 * @settings: a #GSettings object
30485 * @key: the name of the key to set
30486 * @value: a #GVariant of the correct type
30488 * Sets @key in @settings to @value.
30490 * It is a programmer error to give a @key that isn't contained in the
30491 * schema for @settings or for @value to have the incorrect type, per
30494 * If @value is floating then this function consumes the reference.
30496 * Returns: %TRUE if setting the key succeeded,
30497 * %FALSE if the key was not writable
30505 * Ensures that all pending operations for the given are complete for
30506 * the default backend.
30508 * Writes made to a #GSettings are handled asynchronously. For this
30509 * reason, it is very unlikely that the changes have it to disk by the
30510 * time g_settings_set() returns.
30512 * This call will block until all of the writes have made it to the
30513 * backend. Since the mainloop is not running, no change notifications
30514 * will be dispatched during this call (but some may be queued by the
30515 * time the call is done).
30520 * g_settings_unbind:
30521 * @object: the object
30522 * @property: the property whose binding is removed
30524 * Removes an existing binding for @property on @object.
30526 * Note that bindings are automatically removed when the
30527 * object is finalized, so it is rarely necessary to call this
30535 * g_simple_action_group_add_entries:
30536 * @simple: a #GSimpleActionGroup
30537 * @entries: (array length=n_entries): a pointer to the first item in
30538 * an array of #GActionEntry structs
30539 * @n_entries: the length of @entries, or -1
30540 * @user_data: the user data for signal connections
30542 * A convenience function for creating multiple #GSimpleAction instances
30543 * and adding them to the action group.
30546 * Deprecated: 2.38: Use g_action_map_add_action_entries()
30551 * g_simple_action_group_insert:
30552 * @simple: a #GSimpleActionGroup
30553 * @action: a #GAction
30555 * Adds an action to the action group.
30557 * If the action group already contains an action with the same name as
30558 * @action then the old action is dropped from the group.
30560 * The action group takes its own reference on @action.
30563 * Deprecated: 2.38: Use g_action_map_add_action()
30568 * g_simple_action_group_lookup:
30569 * @simple: a #GSimpleActionGroup
30570 * @action_name: the name of an action
30572 * Looks up the action with the name @action_name in the group.
30574 * If no such action exists, returns %NULL.
30576 * Returns: (transfer none): a #GAction, or %NULL
30578 * Deprecated: 2.38: Use g_action_map_lookup_action()
30583 * g_simple_action_group_new:
30585 * Creates a new, empty, #GSimpleActionGroup.
30587 * Returns: a new #GSimpleActionGroup
30593 * g_simple_action_group_remove:
30594 * @simple: a #GSimpleActionGroup
30595 * @action_name: the name of the action
30597 * Removes the named action from the action group.
30599 * If no action of this name is in the group then nothing happens.
30602 * Deprecated: 2.38: Use g_action_map_remove_action()
30607 * g_simple_action_new:
30608 * @name: the name of the action
30609 * @parameter_type: (allow-none): the type of parameter to the activate function
30611 * Creates a new action.
30613 * The created action is stateless. See g_simple_action_new_stateful().
30615 * Returns: a new #GSimpleAction
30621 * g_simple_action_new_stateful:
30622 * @name: the name of the action
30623 * @parameter_type: (allow-none): the type of the parameter to the activate function
30624 * @state: the initial state of the action
30626 * Creates a new stateful action.
30628 * @state is the initial state of the action. All future state values
30629 * must have the same #GVariantType as the initial state.
30631 * If the @state GVariant is floating, it is consumed.
30633 * Returns: a new #GSimpleAction
30639 * g_simple_action_set_enabled:
30640 * @simple: a #GSimpleAction
30641 * @enabled: whether the action is enabled
30643 * Sets the action as enabled or not.
30645 * An action must be enabled in order to be activated or in order to
30646 * have its state changed from outside callers.
30648 * This should only be called by the implementor of the action. Users
30649 * of the action should not attempt to modify its enabled flag.
30656 * g_simple_action_set_state:
30657 * @simple: a #GSimpleAction
30658 * @value: the new #GVariant for the state
30660 * Sets the state of the action.
30662 * This directly updates the 'state' property to the given value.
30664 * This should only be called by the implementor of the action. Users
30665 * of the action should not attempt to directly modify the 'state'
30666 * property. Instead, they should call g_action_change_state() to
30667 * request the change.
30669 * If the @value GVariant is floating, it is consumed.
30676 * g_simple_async_report_error_in_idle: (skip)
30677 * @object: (allow-none): a #GObject, or %NULL.
30678 * @callback: a #GAsyncReadyCallback.
30679 * @user_data: user data passed to @callback.
30680 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
30681 * @code: a specific error code.
30682 * @format: a formatted error reporting string.
30683 * @...: a list of variables to fill in @format.
30685 * Reports an error in an asynchronous function in an idle function by
30686 * directly setting the contents of the #GAsyncResult with the given error
30692 * g_simple_async_report_gerror_in_idle:
30693 * @object: (allow-none): a #GObject, or %NULL
30694 * @callback: (scope async): a #GAsyncReadyCallback.
30695 * @user_data: (closure): user data passed to @callback.
30696 * @error: the #GError to report
30698 * Reports an error in an idle function. Similar to
30699 * g_simple_async_report_error_in_idle(), but takes a #GError rather
30700 * than building a new one.
30705 * g_simple_async_report_take_gerror_in_idle: (skip)
30706 * @object: (allow-none): a #GObject, or %NULL
30707 * @callback: a #GAsyncReadyCallback.
30708 * @user_data: user data passed to @callback.
30709 * @error: the #GError to report
30711 * Reports an error in an idle function. Similar to
30712 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
30713 * ownership of @error, so the caller does not have to free it any more.
30720 * g_simple_async_result_complete:
30721 * @simple: a #GSimpleAsyncResult.
30723 * Completes an asynchronous I/O job immediately. Must be called in
30724 * the thread where the asynchronous result was to be delivered, as it
30725 * invokes the callback directly. If you are in a different thread use
30726 * g_simple_async_result_complete_in_idle().
30728 * Calling this function takes a reference to @simple for as long as
30729 * is needed to complete the call.
30734 * g_simple_async_result_complete_in_idle:
30735 * @simple: a #GSimpleAsyncResult.
30737 * Completes an asynchronous function in an idle handler in the <link
30738 * linkend="g-main-context-push-thread-default">thread-default main
30739 * loop</link> of the thread that @simple was initially created in
30740 * (and re-pushes that context around the invocation of the callback).
30742 * Calling this function takes a reference to @simple for as long as
30743 * is needed to complete the call.
30748 * g_simple_async_result_get_op_res_gboolean:
30749 * @simple: a #GSimpleAsyncResult.
30751 * Gets the operation result boolean from within the asynchronous result.
30753 * Returns: %TRUE if the operation's result was %TRUE, %FALSE
30754 * if the operation's result was %FALSE.
30759 * g_simple_async_result_get_op_res_gpointer: (skip)
30760 * @simple: a #GSimpleAsyncResult.
30762 * Gets a pointer result as returned by the asynchronous function.
30764 * Returns: a pointer from the result.
30769 * g_simple_async_result_get_op_res_gssize:
30770 * @simple: a #GSimpleAsyncResult.
30772 * Gets a gssize from the asynchronous result.
30774 * Returns: a gssize returned from the asynchronous function.
30779 * g_simple_async_result_get_source_tag: (skip)
30780 * @simple: a #GSimpleAsyncResult.
30782 * Gets the source tag for the #GSimpleAsyncResult.
30784 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
30789 * g_simple_async_result_is_valid:
30790 * @result: the #GAsyncResult passed to the _finish function.
30791 * @source: the #GObject passed to the _finish function.
30792 * @source_tag: the asynchronous function.
30794 * Ensures that the data passed to the _finish function of an async
30795 * operation is consistent. Three checks are performed.
30797 * First, @result is checked to ensure that it is really a
30798 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
30799 * matches the source object of @result. Third, @source_tag is
30800 * checked to ensure that it is either %NULL (as it is when the result was
30801 * created by g_simple_async_report_error_in_idle() or
30802 * g_simple_async_report_gerror_in_idle()) or equal to the
30803 * @source_tag argument given to g_simple_async_result_new() (which, by
30804 * convention, is a pointer to the _async function corresponding to the
30805 * _finish function from which this function is called).
30807 * Returns: #TRUE if all checks passed or #FALSE if any failed.
30813 * g_simple_async_result_new:
30814 * @source_object: (allow-none): a #GObject, or %NULL.
30815 * @callback: (scope async): a #GAsyncReadyCallback.
30816 * @user_data: (closure): user data passed to @callback.
30817 * @source_tag: the asynchronous function.
30819 * Creates a #GSimpleAsyncResult.
30821 * The common convention is to create the #GSimpleAsyncResult in the
30822 * function that starts the asynchronous operation and use that same
30823 * function as the @source_tag.
30825 * If your operation supports cancellation with #GCancellable (which it
30826 * probably should) then you should provide the user's cancellable to
30827 * g_simple_async_result_set_check_cancellable() immediately after
30828 * this function returns.
30830 * Returns: a #GSimpleAsyncResult.
30835 * g_simple_async_result_new_error:
30836 * @source_object: (allow-none): a #GObject, or %NULL.
30837 * @callback: (scope async): a #GAsyncReadyCallback.
30838 * @user_data: (closure): user data passed to @callback.
30839 * @domain: a #GQuark.
30840 * @code: an error code.
30841 * @format: a string with format characters.
30842 * @...: a list of values to insert into @format.
30844 * Creates a new #GSimpleAsyncResult with a set error.
30846 * Returns: a #GSimpleAsyncResult.
30851 * g_simple_async_result_new_from_error:
30852 * @source_object: (allow-none): a #GObject, or %NULL.
30853 * @callback: (scope async): a #GAsyncReadyCallback.
30854 * @user_data: (closure): user data passed to @callback.
30855 * @error: a #GError
30857 * Creates a #GSimpleAsyncResult from an error condition.
30859 * Returns: a #GSimpleAsyncResult.
30864 * g_simple_async_result_new_take_error: (skip)
30865 * @source_object: (allow-none): a #GObject, or %NULL
30866 * @callback: (scope async): a #GAsyncReadyCallback
30867 * @user_data: (closure): user data passed to @callback
30868 * @error: a #GError
30870 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
30871 * caller's ownership of @error, so the caller does not need to free it anymore.
30873 * Returns: a #GSimpleAsyncResult
30879 * g_simple_async_result_propagate_error:
30880 * @simple: a #GSimpleAsyncResult.
30881 * @dest: (out): a location to propagate the error to.
30883 * Propagates an error from within the simple asynchronous result to
30884 * a given destination.
30886 * If the #GCancellable given to a prior call to
30887 * g_simple_async_result_set_check_cancellable() is cancelled then this
30888 * function will return %TRUE with @dest set appropriately.
30890 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
30895 * g_simple_async_result_run_in_thread: (skip)
30896 * @simple: a #GSimpleAsyncResult.
30897 * @func: a #GSimpleAsyncThreadFunc.
30898 * @io_priority: the io priority of the request.
30899 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30901 * Runs the asynchronous job in a separate thread and then calls
30902 * g_simple_async_result_complete_in_idle() on @simple to return
30903 * the result to the appropriate main loop.
30905 * Calling this function takes a reference to @simple for as long as
30906 * is needed to run the job and report its completion.
30911 * g_simple_async_result_set_check_cancellable:
30912 * @simple: a #GSimpleAsyncResult
30913 * @check_cancellable: (allow-none): a #GCancellable to check, or %NULL to unset
30915 * Sets a #GCancellable to check before dispatching results.
30917 * This function has one very specific purpose: the provided cancellable
30918 * is checked at the time of g_simple_async_result_propagate_error() If
30919 * it is cancelled, these functions will return an "Operation was
30920 * cancelled" error (%G_IO_ERROR_CANCELLED).
30922 * Implementors of cancellable asynchronous functions should use this in
30923 * order to provide a guarantee to their callers that cancelling an
30924 * async operation will reliably result in an error being returned for
30925 * that operation (even if a positive result for the operation has
30926 * already been sent as an idle to the main context to be dispatched).
30928 * The checking described above is done regardless of any call to the
30929 * unrelated g_simple_async_result_set_handle_cancellation() function.
30936 * g_simple_async_result_set_error: (skip)
30937 * @simple: a #GSimpleAsyncResult.
30938 * @domain: a #GQuark (usually #G_IO_ERROR).
30939 * @code: an error code.
30940 * @format: a formatted error reporting string.
30941 * @...: a list of variables to fill in @format.
30943 * Sets an error within the asynchronous result without a #GError.
30948 * g_simple_async_result_set_error_va: (skip)
30949 * @simple: a #GSimpleAsyncResult.
30950 * @domain: a #GQuark (usually #G_IO_ERROR).
30951 * @code: an error code.
30952 * @format: a formatted error reporting string.
30953 * @args: va_list of arguments.
30955 * Sets an error within the asynchronous result without a #GError.
30956 * Unless writing a binding, see g_simple_async_result_set_error().
30961 * g_simple_async_result_set_from_error:
30962 * @simple: a #GSimpleAsyncResult.
30965 * Sets the result from a #GError.
30970 * g_simple_async_result_set_handle_cancellation:
30971 * @simple: a #GSimpleAsyncResult.
30972 * @handle_cancellation: a #gboolean.
30974 * Sets whether to handle cancellation within the asynchronous operation.
30976 * This function has nothing to do with
30977 * g_simple_async_result_set_check_cancellable(). It only refers to the
30978 * #GCancellable passed to g_simple_async_result_run_in_thread().
30983 * g_simple_async_result_set_op_res_gboolean:
30984 * @simple: a #GSimpleAsyncResult.
30985 * @op_res: a #gboolean.
30987 * Sets the operation result to a boolean within the asynchronous result.
30992 * g_simple_async_result_set_op_res_gpointer: (skip)
30993 * @simple: a #GSimpleAsyncResult.
30994 * @op_res: a pointer result from an asynchronous function.
30995 * @destroy_op_res: a #GDestroyNotify function.
30997 * Sets the operation result within the asynchronous result to a pointer.
31002 * g_simple_async_result_set_op_res_gssize:
31003 * @simple: a #GSimpleAsyncResult.
31004 * @op_res: a #gssize.
31006 * Sets the operation result within the asynchronous result to
31007 * the given @op_res.
31012 * g_simple_async_result_take_error: (skip)
31013 * @simple: a #GSimpleAsyncResult
31014 * @error: a #GError
31016 * Sets the result from @error, and takes over the caller's ownership
31017 * of @error, so the caller does not need to free it any more.
31024 * g_simple_permission_new:
31025 * @allowed: %TRUE if the action is allowed
31027 * Creates a new #GPermission instance that represents an action that is
31028 * either always or never allowed.
31030 * Returns: the #GSimplePermission, as a #GPermission
31036 * g_simple_proxy_resolver_new:
31037 * @default_proxy: (allow-none): the default proxy to use, eg
31038 * "socks://192.168.1.1"
31039 * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses
31040 * to not use a proxy for.
31042 * Creates a new #GSimpleProxyResolver. See
31043 * #GSimpleProxyResolver:default-proxy and
31044 * #GSimpleProxyResolver:ignore-hosts for more details on how the
31045 * arguments are interpreted.
31047 * Returns: a new #GSimpleProxyResolver
31053 * g_simple_proxy_resolver_set_default_proxy:
31054 * @resolver: a #GSimpleProxyResolver
31055 * @default_proxy: the default proxy to use
31057 * Sets the default proxy on @resolver, to be used for any URIs that
31058 * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
31059 * via g_simple_proxy_resolver_set_uri_proxy().
31061 * If @default_proxy starts with "<literal>socks://</literal>",
31062 * #GSimpleProxyResolver will treat it as referring to all three of
31063 * the <literal>socks5</literal>, <literal>socks4a</literal>, and
31064 * <literal>socks4</literal> proxy types.
31071 * g_simple_proxy_resolver_set_ignore_hosts:
31072 * @resolver: a #GSimpleProxyResolver
31073 * @ignore_hosts: %NULL-terminated list of hosts/IP addresses
31074 * to not use a proxy for
31076 * Sets the list of ignored hosts.
31078 * See #GSimpleProxyResolver:ignore-hosts for more details on how the
31079 * @ignore_hosts argument is interpreted.
31086 * g_simple_proxy_resolver_set_uri_proxy:
31087 * @resolver: a #GSimpleProxyResolver
31088 * @uri_scheme: the URI scheme to add a proxy for
31089 * @proxy: the proxy to use for @uri_scheme
31091 * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme
31092 * matches @uri_scheme (and which don't match
31093 * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
31095 * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
31096 * "<literal>socks://</literal>", #GSimpleProxyResolver will treat it
31097 * as referring to all three of the <literal>socks5</literal>,
31098 * <literal>socks4a</literal>, and <literal>socks4</literal> proxy
31107 * @socket: a #GSocket.
31108 * @cancellable: (allow-none): a %GCancellable or %NULL
31109 * @error: #GError for error reporting, or %NULL to ignore.
31111 * Accept incoming connections on a connection-based socket. This removes
31112 * the first outstanding connection request from the listening socket and
31113 * creates a #GSocket object for it.
31115 * The @socket must be bound to a local address with g_socket_bind() and
31116 * must be listening for incoming connections (g_socket_listen()).
31118 * If there are no outstanding connections then the operation will block
31119 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
31120 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
31122 * Returns: (transfer full): a new #GSocket, or %NULL on error.
31123 * Free the returned object with g_object_unref().
31129 * g_socket_address_enumerator_next:
31130 * @enumerator: a #GSocketAddressEnumerator
31131 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31132 * @error: a #GError.
31134 * Retrieves the next #GSocketAddress from @enumerator. Note that this
31135 * may block for some amount of time. (Eg, a #GNetworkAddress may need
31136 * to do a DNS lookup before it can return an address.) Use
31137 * g_socket_address_enumerator_next_async() if you need to avoid
31140 * If @enumerator is expected to yield addresses, but for some reason
31141 * is unable to (eg, because of a DNS error), then the first call to
31142 * g_socket_address_enumerator_next() will return an appropriate error
31143 * in *@error. However, if the first call to
31144 * g_socket_address_enumerator_next() succeeds, then any further
31145 * internal errors (other than @cancellable being triggered) will be
31148 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
31149 * error (in which case *@error will be set) or if there are no
31155 * g_socket_address_enumerator_next_async:
31156 * @enumerator: a #GSocketAddressEnumerator
31157 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31158 * @callback: (scope async): a #GAsyncReadyCallback to call when the request
31160 * @user_data: (closure): the data to pass to callback function
31162 * Asynchronously retrieves the next #GSocketAddress from @enumerator
31163 * and then calls @callback, which must call
31164 * g_socket_address_enumerator_next_finish() to get the result.
31169 * g_socket_address_enumerator_next_finish:
31170 * @enumerator: a #GSocketAddressEnumerator
31171 * @result: a #GAsyncResult
31172 * @error: a #GError
31174 * Retrieves the result of a completed call to
31175 * g_socket_address_enumerator_next_async(). See
31176 * g_socket_address_enumerator_next() for more information about
31179 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
31180 * error (in which case *@error will be set) or if there are no
31186 * g_socket_address_get_family:
31187 * @address: a #GSocketAddress
31189 * Gets the socket family type of @address.
31191 * Returns: the socket family type of @address.
31197 * g_socket_address_get_native_size:
31198 * @address: a #GSocketAddress
31200 * Gets the size of @address's native <type>struct sockaddr</type>.
31201 * You can use this to allocate memory to pass to
31202 * g_socket_address_to_native().
31204 * Returns: the size of the native <type>struct sockaddr</type> that
31205 * @address represents
31211 * g_socket_address_new_from_native:
31212 * @native: a pointer to a <type>struct sockaddr</type>
31213 * @len: the size of the memory location pointed to by @native
31215 * Creates a #GSocketAddress subclass corresponding to the native
31216 * <type>struct sockaddr</type> @native.
31218 * Returns: a new #GSocketAddress if @native could successfully be converted,
31225 * g_socket_address_to_native:
31226 * @address: a #GSocketAddress
31227 * @dest: a pointer to a memory location that will contain the native
31228 * <type>struct sockaddr</type>.
31229 * @destlen: the size of @dest. Must be at least as large as
31230 * g_socket_address_get_native_size().
31231 * @error: #GError for error reporting, or %NULL to ignore.
31233 * Converts a #GSocketAddress to a native <type>struct
31234 * sockaddr</type>, which can be passed to low-level functions like
31235 * connect() or bind().
31237 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
31238 * returned. If the address type is not known on the system
31239 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
31241 * Returns: %TRUE if @dest was filled in, %FALSE on error
31248 * @socket: a #GSocket.
31249 * @address: a #GSocketAddress specifying the local address.
31250 * @allow_reuse: whether to allow reusing this address
31251 * @error: #GError for error reporting, or %NULL to ignore.
31253 * When a socket is created it is attached to an address family, but it
31254 * doesn't have an address in this family. g_socket_bind() assigns the
31255 * address (sometimes called name) of the socket.
31257 * It is generally required to bind to a local address before you can
31258 * receive connections. (See g_socket_listen() and g_socket_accept() ).
31259 * In certain situations, you may also want to bind a socket that will be
31260 * used to initiate connections, though this is not normally required.
31262 * If @socket is a TCP socket, then @allow_reuse controls the setting
31263 * of the <literal>SO_REUSEADDR</literal> socket option; normally it
31264 * should be %TRUE for server sockets (sockets that you will
31265 * eventually call g_socket_accept() on), and %FALSE for client
31266 * sockets. (Failing to set this flag on a server socket may cause
31267 * g_socket_bind() to return %G_IO_ERROR_ADDRESS_IN_USE if the server
31268 * program is stopped and then immediately restarted.)
31270 * If @socket is a UDP socket, then @allow_reuse determines whether or
31271 * not other UDP sockets can be bound to the same address at the same
31272 * time. In particular, you can have several UDP sockets bound to the
31273 * same address, and they will all receive all of the multicast and
31274 * broadcast packets sent to that address. (The behavior of unicast
31275 * UDP packets to an address with multiple listeners is not defined.)
31277 * Returns: %TRUE on success, %FALSE on error.
31283 * g_socket_check_connect_result:
31284 * @socket: a #GSocket
31285 * @error: #GError for error reporting, or %NULL to ignore.
31287 * Checks and resets the pending connect error for the socket.
31288 * This is used to check for errors when g_socket_connect() is
31289 * used in non-blocking mode.
31291 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
31297 * g_socket_client_add_application_proxy:
31298 * @client: a #GSocketClient
31299 * @protocol: The proxy protocol
31301 * Enable proxy protocols to be handled by the application. When the
31302 * indicated proxy protocol is returned by the #GProxyResolver,
31303 * #GSocketClient will consider this protocol as supported but will
31304 * not try to find a #GProxy instance to handle handshaking. The
31305 * application must check for this case by calling
31306 * g_socket_connection_get_remote_address() on the returned
31307 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
31308 * appropriate type, to determine whether or not it needs to handle
31309 * the proxy handshaking itself.
31311 * This should be used for proxy protocols that are dialects of
31312 * another protocol such as HTTP proxy. It also allows cohabitation of
31313 * proxy protocols that are reused between protocols. A good example
31314 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
31315 * be use as generic socket proxy through the HTTP CONNECT method.
31317 * When the proxy is detected as being an application proxy, TLS handshake
31318 * will be skipped. This is required to let the application do the proxy
31319 * specific handshake.
31324 * g_socket_client_connect:
31325 * @client: a #GSocketClient.
31326 * @connectable: a #GSocketConnectable specifying the remote address.
31327 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31328 * @error: #GError for error reporting, or %NULL to ignore.
31330 * Tries to resolve the @connectable and make a network connection to it.
31332 * Upon a successful connection, a new #GSocketConnection is constructed
31333 * and returned. The caller owns this new object and must drop their
31334 * reference to it when finished with it.
31336 * The type of the #GSocketConnection object returned depends on the type of
31337 * the underlying socket that is used. For instance, for a TCP/IP connection
31338 * it will be a #GTcpConnection.
31340 * The socket created will be the same family as the address that the
31341 * @connectable resolves to, unless family is set with g_socket_client_set_family()
31342 * or indirectly via g_socket_client_set_local_address(). The socket type
31343 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
31344 * g_socket_client_set_socket_type().
31346 * If a local address is specified with g_socket_client_set_local_address() the
31347 * socket will be bound to this address before connecting.
31349 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31355 * g_socket_client_connect_async:
31356 * @client: a #GSocketClient
31357 * @connectable: a #GSocketConnectable specifying the remote address.
31358 * @cancellable: (allow-none): a #GCancellable, or %NULL
31359 * @callback: (scope async): a #GAsyncReadyCallback
31360 * @user_data: (closure): user data for the callback
31362 * This is the asynchronous version of g_socket_client_connect().
31364 * When the operation is finished @callback will be
31365 * called. You can then call g_socket_client_connect_finish() to get
31366 * the result of the operation.
31373 * g_socket_client_connect_finish:
31374 * @client: a #GSocketClient.
31375 * @result: a #GAsyncResult.
31376 * @error: a #GError location to store the error occurring, or %NULL to
31379 * Finishes an async connect operation. See g_socket_client_connect_async()
31381 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31387 * g_socket_client_connect_to_host:
31388 * @client: a #GSocketClient
31389 * @host_and_port: the name and optionally port of the host to connect to
31390 * @default_port: the default port to connect to
31391 * @cancellable: (allow-none): a #GCancellable, or %NULL
31392 * @error: a pointer to a #GError, or %NULL
31394 * This is a helper function for g_socket_client_connect().
31396 * Attempts to create a TCP connection to the named host.
31398 * @host_and_port may be in any of a number of recognized formats; an IPv6
31399 * address, an IPv4 address, or a domain name (in which case a DNS
31400 * lookup is performed). Quoting with [] is supported for all address
31401 * types. A port override may be specified in the usual way with a
31402 * colon. Ports may be given as decimal numbers or symbolic names (in
31403 * which case an /etc/services lookup is performed).
31405 * If no port override is given in @host_and_port then @default_port will be
31406 * used as the port number to connect to.
31408 * In general, @host_and_port is expected to be provided by the user (allowing
31409 * them to give the hostname, and a port override if necessary) and
31410 * @default_port is expected to be provided by the application.
31412 * In the case that an IP address is given, a single connection
31413 * attempt is made. In the case that a name is given, multiple
31414 * connection attempts may be made, in turn and according to the
31415 * number of address records in DNS, until a connection succeeds.
31417 * Upon a successful connection, a new #GSocketConnection is constructed
31418 * and returned. The caller owns this new object and must drop their
31419 * reference to it when finished with it.
31421 * In the event of any failure (DNS error, service not found, no hosts
31422 * connectable) %NULL is returned and @error (if non-%NULL) is set
31425 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31431 * g_socket_client_connect_to_host_async:
31432 * @client: a #GSocketClient
31433 * @host_and_port: the name and optionally the port of the host to connect to
31434 * @default_port: the default port to connect to
31435 * @cancellable: (allow-none): a #GCancellable, or %NULL
31436 * @callback: (scope async): a #GAsyncReadyCallback
31437 * @user_data: (closure): user data for the callback
31439 * This is the asynchronous version of g_socket_client_connect_to_host().
31441 * When the operation is finished @callback will be
31442 * called. You can then call g_socket_client_connect_to_host_finish() to get
31443 * the result of the operation.
31450 * g_socket_client_connect_to_host_finish:
31451 * @client: a #GSocketClient.
31452 * @result: a #GAsyncResult.
31453 * @error: a #GError location to store the error occurring, or %NULL to
31456 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
31458 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31464 * g_socket_client_connect_to_service:
31465 * @client: a #GSocketConnection
31466 * @domain: a domain name
31467 * @service: the name of the service to connect to
31468 * @cancellable: (allow-none): a #GCancellable, or %NULL
31469 * @error: a pointer to a #GError, or %NULL
31471 * Attempts to create a TCP connection to a service.
31473 * This call looks up the SRV record for @service at @domain for the
31474 * "tcp" protocol. It then attempts to connect, in turn, to each of
31475 * the hosts providing the service until either a connection succeeds
31476 * or there are no hosts remaining.
31478 * Upon a successful connection, a new #GSocketConnection is constructed
31479 * and returned. The caller owns this new object and must drop their
31480 * reference to it when finished with it.
31482 * In the event of any failure (DNS error, service not found, no hosts
31483 * connectable) %NULL is returned and @error (if non-%NULL) is set
31486 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
31491 * g_socket_client_connect_to_service_async:
31492 * @client: a #GSocketClient
31493 * @domain: a domain name
31494 * @service: the name of the service to connect to
31495 * @cancellable: (allow-none): a #GCancellable, or %NULL
31496 * @callback: (scope async): a #GAsyncReadyCallback
31497 * @user_data: (closure): user data for the callback
31499 * This is the asynchronous version of
31500 * g_socket_client_connect_to_service().
31507 * g_socket_client_connect_to_service_finish:
31508 * @client: a #GSocketClient.
31509 * @result: a #GAsyncResult.
31510 * @error: a #GError location to store the error occurring, or %NULL to
31513 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
31515 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31521 * g_socket_client_connect_to_uri:
31522 * @client: a #GSocketClient
31523 * @uri: A network URI
31524 * @default_port: the default port to connect to
31525 * @cancellable: (allow-none): a #GCancellable, or %NULL
31526 * @error: a pointer to a #GError, or %NULL
31528 * This is a helper function for g_socket_client_connect().
31530 * Attempts to create a TCP connection with a network URI.
31532 * @uri may be any valid URI containing an "authority" (hostname/port)
31533 * component. If a port is not specified in the URI, @default_port
31534 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
31535 * (#GSocketClient does not know to automatically assume TLS for
31536 * certain URI schemes.)
31538 * Using this rather than g_socket_client_connect() or
31539 * g_socket_client_connect_to_host() allows #GSocketClient to
31540 * determine when to use application-specific proxy protocols.
31542 * Upon a successful connection, a new #GSocketConnection is constructed
31543 * and returned. The caller owns this new object and must drop their
31544 * reference to it when finished with it.
31546 * In the event of any failure (DNS error, service not found, no hosts
31547 * connectable) %NULL is returned and @error (if non-%NULL) is set
31550 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31556 * g_socket_client_connect_to_uri_async:
31557 * @client: a #GSocketClient
31558 * @uri: a network uri
31559 * @default_port: the default port to connect to
31560 * @cancellable: (allow-none): a #GCancellable, or %NULL
31561 * @callback: (scope async): a #GAsyncReadyCallback
31562 * @user_data: (closure): user data for the callback
31564 * This is the asynchronous version of g_socket_client_connect_to_uri().
31566 * When the operation is finished @callback will be
31567 * called. You can then call g_socket_client_connect_to_uri_finish() to get
31568 * the result of the operation.
31575 * g_socket_client_connect_to_uri_finish:
31576 * @client: a #GSocketClient.
31577 * @result: a #GAsyncResult.
31578 * @error: a #GError location to store the error occurring, or %NULL to
31581 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
31583 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
31589 * g_socket_client_get_enable_proxy:
31590 * @client: a #GSocketClient.
31592 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
31594 * Returns: whether proxying is enabled
31600 * g_socket_client_get_family:
31601 * @client: a #GSocketClient.
31603 * Gets the socket family of the socket client.
31605 * See g_socket_client_set_family() for details.
31607 * Returns: a #GSocketFamily
31613 * g_socket_client_get_local_address:
31614 * @client: a #GSocketClient.
31616 * Gets the local address of the socket client.
31618 * See g_socket_client_set_local_address() for details.
31620 * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
31626 * g_socket_client_get_protocol:
31627 * @client: a #GSocketClient
31629 * Gets the protocol name type of the socket client.
31631 * See g_socket_client_set_protocol() for details.
31633 * Returns: a #GSocketProtocol
31639 * g_socket_client_get_proxy_resolver:
31640 * @client: a #GSocketClient.
31642 * Gets the #GProxyResolver being used by @client. Normally, this will
31643 * be the resolver returned by g_proxy_resolver_get_default(), but you
31644 * can override it with g_socket_client_set_proxy_resolver().
31646 * Returns: (transfer none): The #GProxyResolver being used by
31653 * g_socket_client_get_socket_type:
31654 * @client: a #GSocketClient.
31656 * Gets the socket type of the socket client.
31658 * See g_socket_client_set_socket_type() for details.
31660 * Returns: a #GSocketFamily
31666 * g_socket_client_get_timeout:
31667 * @client: a #GSocketClient
31669 * Gets the I/O timeout time for sockets created by @client.
31671 * See g_socket_client_set_timeout() for details.
31673 * Returns: the timeout in seconds
31679 * g_socket_client_get_tls:
31680 * @client: a #GSocketClient.
31682 * Gets whether @client creates TLS connections. See
31683 * g_socket_client_set_tls() for details.
31685 * Returns: whether @client uses TLS
31691 * g_socket_client_get_tls_validation_flags:
31692 * @client: a #GSocketClient.
31694 * Gets the TLS validation flags used creating TLS connections via
31697 * Returns: the TLS validation flags
31703 * g_socket_client_new:
31705 * Creates a new #GSocketClient with the default options.
31707 * Returns: a #GSocketClient.
31708 * Free the returned object with g_object_unref().
31714 * g_socket_client_set_enable_proxy:
31715 * @client: a #GSocketClient.
31716 * @enable: whether to enable proxies
31718 * Sets whether or not @client attempts to make connections via a
31719 * proxy server. When enabled (the default), #GSocketClient will use a
31720 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
31721 * needed, and automatically do the necessary proxy negotiation.
31723 * See also g_socket_client_set_proxy_resolver().
31730 * g_socket_client_set_family:
31731 * @client: a #GSocketClient.
31732 * @family: a #GSocketFamily
31734 * Sets the socket family of the socket client.
31735 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
31736 * then the sockets created by this object will be of the specified
31739 * This might be useful for instance if you want to force the local
31740 * connection to be an ipv4 socket, even though the address might
31741 * be an ipv6 mapped to ipv4 address.
31748 * g_socket_client_set_local_address:
31749 * @client: a #GSocketClient.
31750 * @address: (allow-none): a #GSocketAddress, or %NULL
31752 * Sets the local address of the socket client.
31753 * The sockets created by this object will bound to the
31754 * specified address (if not %NULL) before connecting.
31756 * This is useful if you want to ensure that the local
31757 * side of the connection is on a specific port, or on
31758 * a specific interface.
31765 * g_socket_client_set_protocol:
31766 * @client: a #GSocketClient.
31767 * @protocol: a #GSocketProtocol
31769 * Sets the protocol of the socket client.
31770 * The sockets created by this object will use of the specified
31773 * If @protocol is %0 that means to use the default
31774 * protocol for the socket family and type.
31781 * g_socket_client_set_proxy_resolver:
31782 * @client: a #GSocketClient.
31783 * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the
31786 * Overrides the #GProxyResolver used by @client. You can call this if
31787 * you want to use specific proxies, rather than using the system
31788 * default proxy settings.
31790 * Note that whether or not the proxy resolver is actually used
31791 * depends on the setting of #GSocketClient:enable-proxy, which is not
31792 * changed by this function (but which is %TRUE by default)
31799 * g_socket_client_set_socket_type:
31800 * @client: a #GSocketClient.
31801 * @type: a #GSocketType
31803 * Sets the socket type of the socket client.
31804 * The sockets created by this object will be of the specified
31807 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
31808 * as GSocketClient is used for connection oriented services.
31815 * g_socket_client_set_timeout:
31816 * @client: a #GSocketClient.
31817 * @timeout: the timeout
31819 * Sets the I/O timeout for sockets created by @client. @timeout is a
31820 * time in seconds, or 0 for no timeout (the default).
31822 * The timeout value affects the initial connection attempt as well,
31823 * so setting this may cause calls to g_socket_client_connect(), etc,
31824 * to fail with %G_IO_ERROR_TIMED_OUT.
31831 * g_socket_client_set_tls:
31832 * @client: a #GSocketClient.
31833 * @tls: whether to use TLS
31835 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
31836 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
31837 * and perform a TLS handshake when connecting.
31839 * Note that since #GSocketClient must return a #GSocketConnection,
31840 * but #GTlsClientConnection is not a #GSocketConnection, this
31841 * actually wraps the resulting #GTlsClientConnection in a
31842 * #GTcpWrapperConnection when returning it. You can use
31843 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
31844 * to extract the #GTlsClientConnection.
31846 * If you need to modify the behavior of the TLS handshake (eg, by
31847 * setting a client-side certificate to use, or connecting to the
31848 * #GTlsConnection::accept-certificate signal), you can connect to
31849 * @client's #GSocketClient::event signal and wait for it to be
31850 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
31851 * a chance to see the #GTlsClientConnection before the handshake
31859 * g_socket_client_set_tls_validation_flags:
31860 * @client: a #GSocketClient.
31861 * @flags: the validation flags
31863 * Sets the TLS validation flags used when creating TLS connections
31864 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
31872 * @socket: a #GSocket
31873 * @error: #GError for error reporting, or %NULL to ignore.
31875 * Closes the socket, shutting down any active connection.
31877 * Closing a socket does not wait for all outstanding I/O operations
31878 * to finish, so the caller should not rely on them to be guaranteed
31879 * to complete even if the close returns with no error.
31881 * Once the socket is closed, all other operations will return
31882 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
31885 * Sockets will be automatically closed when the last reference
31886 * is dropped, but you might want to call this function to make sure
31887 * resources are released as early as possible.
31889 * Beware that due to the way that TCP works, it is possible for
31890 * recently-sent data to be lost if either you close a socket while the
31891 * %G_IO_IN condition is set, or else if the remote connection tries to
31892 * send something to you after you close the socket but before it has
31893 * finished reading all of the data you sent. There is no easy generic
31894 * way to avoid this problem; the easiest fix is to design the network
31895 * protocol such that the client will never send data "out of turn".
31896 * Another solution is for the server to half-close the connection by
31897 * calling g_socket_shutdown() with only the @shutdown_write flag set,
31898 * and then wait for the client to notice this and close its side of the
31899 * connection, after which the server can safely call g_socket_close().
31900 * (This is what #GTcpConnection does if you call
31901 * g_tcp_connection_set_graceful_disconnect(). But of course, this
31902 * only works if the client will close its connection after the server
31905 * Returns: %TRUE on success, %FALSE on error
31911 * g_socket_condition_check:
31912 * @socket: a #GSocket
31913 * @condition: a #GIOCondition mask to check
31915 * Checks on the readiness of @socket to perform operations.
31916 * The operations specified in @condition are checked for and masked
31917 * against the currently-satisfied conditions on @socket. The result
31920 * Note that on Windows, it is possible for an operation to return
31921 * %G_IO_ERROR_WOULD_BLOCK even immediately after
31922 * g_socket_condition_check() has claimed that the socket is ready for
31923 * writing. Rather than calling g_socket_condition_check() and then
31924 * writing to the socket if it succeeds, it is generally better to
31925 * simply try writing to the socket right away, and try again later if
31926 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
31928 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
31929 * these conditions will always be set in the output if they are true.
31931 * This call never blocks.
31933 * Returns: the @GIOCondition mask of the current state
31939 * g_socket_condition_timed_wait:
31940 * @socket: a #GSocket
31941 * @condition: a #GIOCondition mask to wait for
31942 * @timeout: the maximum time (in microseconds) to wait, or -1
31943 * @cancellable: (allow-none): a #GCancellable, or %NULL
31944 * @error: a #GError pointer, or %NULL
31946 * Waits for up to @timeout microseconds for @condition to become true
31947 * on @socket. If the condition is met, %TRUE is returned.
31949 * If @cancellable is cancelled before the condition is met, or if
31950 * @timeout (or the socket's #GSocket:timeout) is reached before the
31951 * condition is met, then %FALSE is returned and @error, if non-%NULL,
31952 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
31953 * %G_IO_ERROR_TIMED_OUT).
31955 * If you don't want a timeout, use g_socket_condition_wait().
31956 * (Alternatively, you can pass -1 for @timeout.)
31958 * Note that although @timeout is in microseconds for consistency with
31959 * other GLib APIs, this function actually only has millisecond
31960 * resolution, and the behavior is undefined if @timeout is not an
31961 * exact number of milliseconds.
31963 * Returns: %TRUE if the condition was met, %FALSE otherwise
31969 * g_socket_condition_wait:
31970 * @socket: a #GSocket
31971 * @condition: a #GIOCondition mask to wait for
31972 * @cancellable: (allow-none): a #GCancellable, or %NULL
31973 * @error: a #GError pointer, or %NULL
31975 * Waits for @condition to become true on @socket. When the condition
31976 * is met, %TRUE is returned.
31978 * If @cancellable is cancelled before the condition is met, or if the
31979 * socket has a timeout set and it is reached before the condition is
31980 * met, then %FALSE is returned and @error, if non-%NULL, is set to
31981 * the appropriate value (%G_IO_ERROR_CANCELLED or
31982 * %G_IO_ERROR_TIMED_OUT).
31984 * See also g_socket_condition_timed_wait().
31986 * Returns: %TRUE if the condition was met, %FALSE otherwise
31992 * g_socket_connect:
31993 * @socket: a #GSocket.
31994 * @address: a #GSocketAddress specifying the remote address.
31995 * @cancellable: (allow-none): a %GCancellable or %NULL
31996 * @error: #GError for error reporting, or %NULL to ignore.
31998 * Connect the socket to the specified remote address.
32000 * For connection oriented socket this generally means we attempt to make
32001 * a connection to the @address. For a connection-less socket it sets
32002 * the default address for g_socket_send() and discards all incoming datagrams
32003 * from other sources.
32005 * Generally connection oriented sockets can only connect once, but
32006 * connection-less sockets can connect multiple times to change the
32009 * If the connect call needs to do network I/O it will block, unless
32010 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
32011 * and the user can be notified of the connection finishing by waiting
32012 * for the G_IO_OUT condition. The result of the connection must then be
32013 * checked with g_socket_check_connect_result().
32015 * Returns: %TRUE if connected, %FALSE on error.
32021 * g_socket_connectable_enumerate:
32022 * @connectable: a #GSocketConnectable
32024 * Creates a #GSocketAddressEnumerator for @connectable.
32026 * Returns: (transfer full): a new #GSocketAddressEnumerator.
32032 * g_socket_connectable_proxy_enumerate:
32033 * @connectable: a #GSocketConnectable
32035 * Creates a #GSocketAddressEnumerator for @connectable that will
32036 * return #GProxyAddress<!-- -->es for addresses that you must connect
32039 * If @connectable does not implement
32040 * g_socket_connectable_proxy_enumerate(), this will fall back to
32041 * calling g_socket_connectable_enumerate().
32043 * Returns: (transfer full): a new #GSocketAddressEnumerator.
32049 * g_socket_connection_connect:
32050 * @connection: a #GSocketConnection
32051 * @address: a #GSocketAddress specifying the remote address.
32052 * @cancellable: (allow-none): a %GCancellable or %NULL
32053 * @error: #GError for error reporting, or %NULL to ignore.
32055 * Connect @connection to the specified remote address.
32057 * Returns: %TRUE if the connection succeeded, %FALSE on error
32063 * g_socket_connection_connect_async:
32064 * @connection: a #GSocketConnection
32065 * @address: a #GSocketAddress specifying the remote address.
32066 * @cancellable: (allow-none): a %GCancellable or %NULL
32067 * @callback: (scope async): a #GAsyncReadyCallback
32068 * @user_data: (closure): user data for the callback
32070 * Asynchronously connect @connection to the specified remote address.
32072 * This clears the #GSocket:blocking flag on @connection's underlying
32073 * socket if it is currently set.
32075 * Use g_socket_connection_connect_finish() to retrieve the result.
32082 * g_socket_connection_connect_finish:
32083 * @connection: a #GSocketConnection
32084 * @result: the #GAsyncResult
32085 * @error: #GError for error reporting, or %NULL to ignore.
32087 * Gets the result of a g_socket_connection_connect_async() call.
32089 * Returns: %TRUE if the connection succeeded, %FALSE on error
32095 * g_socket_connection_factory_create_connection:
32096 * @socket: a #GSocket
32098 * Creates a #GSocketConnection subclass of the right type for
32101 * Returns: (transfer full): a #GSocketConnection
32107 * g_socket_connection_factory_lookup_type:
32108 * @family: a #GSocketFamily
32109 * @type: a #GSocketType
32110 * @protocol_id: a protocol id
32112 * Looks up the #GType to be used when creating socket connections on
32113 * sockets with the specified @family, @type and @protocol_id.
32115 * If no type is registered, the #GSocketConnection base type is returned.
32117 * Returns: a #GType
32123 * g_socket_connection_factory_register_type:
32124 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
32125 * @family: a #GSocketFamily
32126 * @type: a #GSocketType
32127 * @protocol: a protocol id
32129 * Looks up the #GType to be used when creating socket connections on
32130 * sockets with the specified @family, @type and @protocol.
32132 * If no type is registered, the #GSocketConnection base type is returned.
32139 * g_socket_connection_get_local_address:
32140 * @connection: a #GSocketConnection
32141 * @error: #GError for error reporting, or %NULL to ignore.
32143 * Try to get the local address of a socket connection.
32145 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32146 * Free the returned object with g_object_unref().
32152 * g_socket_connection_get_remote_address:
32153 * @connection: a #GSocketConnection
32154 * @error: #GError for error reporting, or %NULL to ignore.
32156 * Try to get the remote address of a socket connection.
32158 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32159 * Free the returned object with g_object_unref().
32165 * g_socket_connection_get_socket:
32166 * @connection: a #GSocketConnection
32168 * Gets the underlying #GSocket object of the connection.
32169 * This can be useful if you want to do something unusual on it
32170 * not supported by the #GSocketConnection APIs.
32172 * Returns: (transfer none): a #GSocketAddress or %NULL on error.
32178 * g_socket_connection_is_connected:
32179 * @connection: a #GSocketConnection
32181 * Checks if @connection is connected. This is equivalent to calling
32182 * g_socket_is_connected() on @connection's underlying #GSocket.
32184 * Returns: whether @connection is connected
32190 * g_socket_control_message_deserialize:
32191 * @level: a socket level
32192 * @type: a socket control message type for the given @level
32193 * @size: the size of the data in bytes
32194 * @data: (array length=size) (element-type guint8): pointer to the message data
32196 * Tries to deserialize a socket control message of a given
32197 * @level and @type. This will ask all known (to GType) subclasses
32198 * of #GSocketControlMessage if they can understand this kind
32199 * of message and if so deserialize it into a #GSocketControlMessage.
32201 * If there is no implementation for this kind of control message, %NULL
32202 * will be returned.
32204 * Returns: (transfer full): the deserialized message or %NULL
32210 * g_socket_control_message_get_level:
32211 * @message: a #GSocketControlMessage
32213 * Returns the "level" (i.e. the originating protocol) of the control message.
32214 * This is often SOL_SOCKET.
32216 * Returns: an integer describing the level
32222 * g_socket_control_message_get_msg_type:
32223 * @message: a #GSocketControlMessage
32225 * Returns the protocol specific type of the control message.
32226 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
32228 * Returns: an integer describing the type of control message
32234 * g_socket_control_message_get_size:
32235 * @message: a #GSocketControlMessage
32237 * Returns the space required for the control message, not including
32238 * headers or alignment.
32240 * Returns: The number of bytes required.
32246 * g_socket_control_message_serialize:
32247 * @message: a #GSocketControlMessage
32248 * @data: A buffer to write data to
32250 * Converts the data in the message to bytes placed in the
32253 * @data is guaranteed to have enough space to fit the size
32254 * returned by g_socket_control_message_get_size() on this
32262 * g_socket_create_source: (skip)
32263 * @socket: a #GSocket
32264 * @condition: a #GIOCondition mask to monitor
32265 * @cancellable: (allow-none): a %GCancellable or %NULL
32267 * Creates a %GSource that can be attached to a %GMainContext to monitor
32268 * for the availibility of the specified @condition on the socket.
32270 * The callback on the source is of the #GSocketSourceFunc type.
32272 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
32273 * these conditions will always be reported output if they are true.
32275 * @cancellable if not %NULL can be used to cancel the source, which will
32276 * cause the source to trigger, reporting the current condition (which
32277 * is likely 0 unless cancellation happened at the same time as a
32278 * condition change). You can check for this in the callback using
32279 * g_cancellable_is_cancelled().
32281 * If @socket has a timeout set, and it is reached before @condition
32282 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
32283 * %G_IO_OUT depending on @condition. However, @socket will have been
32284 * marked as having had a timeout, and so the next #GSocket I/O method
32285 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
32287 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
32293 * g_socket_get_available_bytes:
32294 * @socket: a #GSocket
32296 * Get the amount of data pending in the OS input buffer.
32298 * If @socket is a UDP or SCTP socket, this will return the size of
32299 * just the next packet, even if additional packets are buffered after
32302 * Note that on Windows, this function is rather inefficient in the
32303 * UDP case, and so if you know any plausible upper bound on the size
32304 * of the incoming packet, it is better to just do a
32305 * g_socket_receive() with a buffer of that size, rather than calling
32306 * g_socket_get_available_bytes() first and then doing a receive of
32307 * exactly the right size.
32309 * Returns: the number of bytes that can be read from the socket
32310 * without blocking or truncating, or -1 on error.
32316 * g_socket_get_blocking:
32317 * @socket: a #GSocket.
32319 * Gets the blocking mode of the socket. For details on blocking I/O,
32320 * see g_socket_set_blocking().
32322 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
32328 * g_socket_get_broadcast:
32329 * @socket: a #GSocket.
32331 * Gets the broadcast setting on @socket; if %TRUE,
32332 * it is possible to send packets to broadcast
32335 * Returns: the broadcast setting on @socket
32341 * g_socket_get_credentials:
32342 * @socket: a #GSocket.
32343 * @error: #GError for error reporting, or %NULL to ignore.
32345 * Returns the credentials of the foreign process connected to this
32346 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
32349 * If this operation isn't supported on the OS, the method fails with
32350 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
32351 * by reading the %SO_PEERCRED option on the underlying socket.
32353 * Other ways to obtain credentials from a foreign peer includes the
32354 * #GUnixCredentialsMessage type and
32355 * g_unix_connection_send_credentials() /
32356 * g_unix_connection_receive_credentials() functions.
32358 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
32359 * that must be freed with g_object_unref().
32365 * g_socket_get_family:
32366 * @socket: a #GSocket.
32368 * Gets the socket family of the socket.
32370 * Returns: a #GSocketFamily
32377 * @socket: a #GSocket.
32379 * Returns the underlying OS socket object. On unix this
32380 * is a socket file descriptor, and on Windows this is
32381 * a Winsock2 SOCKET handle. This may be useful for
32382 * doing platform specific or otherwise unusual operations
32385 * Returns: the file descriptor of the socket.
32391 * g_socket_get_keepalive:
32392 * @socket: a #GSocket.
32394 * Gets the keepalive mode of the socket. For details on this,
32395 * see g_socket_set_keepalive().
32397 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
32403 * g_socket_get_listen_backlog:
32404 * @socket: a #GSocket.
32406 * Gets the listen backlog setting of the socket. For details on this,
32407 * see g_socket_set_listen_backlog().
32409 * Returns: the maximum number of pending connections.
32415 * g_socket_get_local_address:
32416 * @socket: a #GSocket.
32417 * @error: #GError for error reporting, or %NULL to ignore.
32419 * Try to get the local address of a bound socket. This is only
32420 * useful if the socket has been bound to a local address,
32421 * either explicitly or implicitly when connecting.
32423 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32424 * Free the returned object with g_object_unref().
32430 * g_socket_get_multicast_loopback:
32431 * @socket: a #GSocket.
32433 * Gets the multicast loopback setting on @socket; if %TRUE (the
32434 * default), outgoing multicast packets will be looped back to
32435 * multicast listeners on the same host.
32437 * Returns: the multicast loopback setting on @socket
32443 * g_socket_get_multicast_ttl:
32444 * @socket: a #GSocket.
32446 * Gets the multicast time-to-live setting on @socket; see
32447 * g_socket_set_multicast_ttl() for more details.
32449 * Returns: the multicast time-to-live setting on @socket
32455 * g_socket_get_option:
32456 * @socket: a #GSocket
32457 * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>)
32458 * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
32459 * @value: (out): return location for the option value
32460 * @error: #GError for error reporting, or %NULL to ignore.
32462 * Gets the value of an integer-valued option on @socket, as with
32463 * <literal>getsockopt ()</literal>. (If you need to fetch a
32464 * non-integer-valued option, you will need to call
32465 * <literal>getsockopt ()</literal> directly.)
32467 * The <link linkend="gio-gnetworking.h"><literal><gio/gnetworking.h></literal></link>
32468 * header pulls in system headers that will define most of the
32469 * standard/portable socket options. For unusual socket protocols or
32470 * platform-dependent options, you may need to include additional
32473 * Note that even for socket options that are a single byte in size,
32474 * @value is still a pointer to a #gint variable, not a #guchar;
32475 * g_socket_get_option() will handle the conversion internally.
32477 * Returns: success or failure. On failure, @error will be set, and
32478 * the system error value (<literal>errno</literal> or
32479 * <literal>WSAGetLastError ()</literal>) will still be set to the
32480 * result of the <literal>getsockopt ()</literal> call.
32486 * g_socket_get_protocol:
32487 * @socket: a #GSocket.
32489 * Gets the socket protocol id the socket was created with.
32490 * In case the protocol is unknown, -1 is returned.
32492 * Returns: a protocol id, or -1 if unknown
32498 * g_socket_get_remote_address:
32499 * @socket: a #GSocket.
32500 * @error: #GError for error reporting, or %NULL to ignore.
32502 * Try to get the remove address of a connected socket. This is only
32503 * useful for connection oriented sockets that have been connected.
32505 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
32506 * Free the returned object with g_object_unref().
32512 * g_socket_get_socket_type:
32513 * @socket: a #GSocket.
32515 * Gets the socket type of the socket.
32517 * Returns: a #GSocketType
32523 * g_socket_get_timeout:
32524 * @socket: a #GSocket.
32526 * Gets the timeout setting of the socket. For details on this, see
32527 * g_socket_set_timeout().
32529 * Returns: the timeout in seconds
32535 * g_socket_get_ttl:
32536 * @socket: a #GSocket.
32538 * Gets the unicast time-to-live setting on @socket; see
32539 * g_socket_set_ttl() for more details.
32541 * Returns: the time-to-live setting on @socket
32547 * g_socket_is_closed:
32548 * @socket: a #GSocket
32550 * Checks whether a socket is closed.
32552 * Returns: %TRUE if socket is closed, %FALSE otherwise
32558 * g_socket_is_connected:
32559 * @socket: a #GSocket.
32561 * Check whether the socket is connected. This is only useful for
32562 * connection-oriented sockets.
32564 * Returns: %TRUE if socket is connected, %FALSE otherwise.
32570 * g_socket_join_multicast_group:
32571 * @socket: a #GSocket.
32572 * @group: a #GInetAddress specifying the group address to join.
32573 * @iface: (allow-none): Name of the interface to use, or %NULL
32574 * @source_specific: %TRUE if source-specific multicast should be used
32575 * @error: #GError for error reporting, or %NULL to ignore.
32577 * Registers @socket to receive multicast messages sent to @group.
32578 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
32579 * been bound to an appropriate interface and port with
32582 * If @iface is %NULL, the system will automatically pick an interface
32583 * to bind to based on @group.
32585 * If @source_specific is %TRUE, source-specific multicast as defined
32586 * in RFC 4604 is used. Note that on older platforms this may fail
32587 * with a %G_IO_ERROR_NOT_SUPPORTED error.
32589 * Returns: %TRUE on success, %FALSE on error.
32595 * g_socket_leave_multicast_group:
32596 * @socket: a #GSocket.
32597 * @group: a #GInetAddress specifying the group address to leave.
32598 * @iface: (allow-none): Interface used
32599 * @source_specific: %TRUE if source-specific multicast was used
32600 * @error: #GError for error reporting, or %NULL to ignore.
32602 * Removes @socket from the multicast group defined by @group, @iface,
32603 * and @source_specific (which must all have the same values they had
32604 * when you joined the group).
32606 * @socket remains bound to its address and port, and can still receive
32607 * unicast messages after calling this.
32609 * Returns: %TRUE on success, %FALSE on error.
32616 * @socket: a #GSocket.
32617 * @error: #GError for error reporting, or %NULL to ignore.
32619 * Marks the socket as a server socket, i.e. a socket that is used
32620 * to accept incoming requests using g_socket_accept().
32622 * Before calling this the socket must be bound to a local address using
32625 * To set the maximum amount of outstanding clients, use
32626 * g_socket_set_listen_backlog().
32628 * Returns: %TRUE on success, %FALSE on error.
32634 * g_socket_listener_accept:
32635 * @listener: a #GSocketListener
32636 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
32637 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32638 * @error: #GError for error reporting, or %NULL to ignore.
32640 * Blocks waiting for a client to connect to any of the sockets added
32641 * to the listener. Returns a #GSocketConnection for the socket that was
32644 * If @source_object is not %NULL it will be filled out with the source
32645 * object specified when the corresponding socket or address was added
32648 * If @cancellable is not %NULL, then the operation can be cancelled by
32649 * triggering the cancellable object from another thread. If the operation
32650 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32652 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32658 * g_socket_listener_accept_async:
32659 * @listener: a #GSocketListener
32660 * @cancellable: (allow-none): a #GCancellable, or %NULL
32661 * @callback: (scope async): a #GAsyncReadyCallback
32662 * @user_data: (closure): user data for the callback
32664 * This is the asynchronous version of g_socket_listener_accept().
32666 * When the operation is finished @callback will be
32667 * called. You can then call g_socket_listener_accept_socket()
32668 * to get the result of the operation.
32675 * g_socket_listener_accept_finish:
32676 * @listener: a #GSocketListener
32677 * @result: a #GAsyncResult.
32678 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
32679 * @error: a #GError location to store the error occurring, or %NULL to
32682 * Finishes an async accept operation. See g_socket_listener_accept_async()
32684 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
32690 * g_socket_listener_accept_socket:
32691 * @listener: a #GSocketListener
32692 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
32693 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32694 * @error: #GError for error reporting, or %NULL to ignore.
32696 * Blocks waiting for a client to connect to any of the sockets added
32697 * to the listener. Returns the #GSocket that was accepted.
32699 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
32700 * which is often the case, then you should use g_socket_listener_accept()
32703 * If @source_object is not %NULL it will be filled out with the source
32704 * object specified when the corresponding socket or address was added
32707 * If @cancellable is not %NULL, then the operation can be cancelled by
32708 * triggering the cancellable object from another thread. If the operation
32709 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32711 * Returns: (transfer full): a #GSocket on success, %NULL on error.
32717 * g_socket_listener_accept_socket_async:
32718 * @listener: a #GSocketListener
32719 * @cancellable: (allow-none): a #GCancellable, or %NULL
32720 * @callback: (scope async): a #GAsyncReadyCallback
32721 * @user_data: (closure): user data for the callback
32723 * This is the asynchronous version of g_socket_listener_accept_socket().
32725 * When the operation is finished @callback will be
32726 * called. You can then call g_socket_listener_accept_socket_finish()
32727 * to get the result of the operation.
32734 * g_socket_listener_accept_socket_finish:
32735 * @listener: a #GSocketListener
32736 * @result: a #GAsyncResult.
32737 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
32738 * @error: a #GError location to store the error occurring, or %NULL to
32741 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
32743 * Returns: (transfer full): a #GSocket on success, %NULL on error.
32749 * g_socket_listener_add_address:
32750 * @listener: a #GSocketListener
32751 * @address: a #GSocketAddress
32752 * @type: a #GSocketType
32753 * @protocol: a #GSocketProtocol
32754 * @source_object: (allow-none): Optional #GObject identifying this source
32755 * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
32756 * @error: #GError for error reporting, or %NULL to ignore.
32758 * Creates a socket of type @type and protocol @protocol, binds
32759 * it to @address and adds it to the set of sockets we're accepting
32762 * Note that adding an IPv6 address, depending on the platform,
32763 * may or may not result in a listener that also accepts IPv4
32764 * connections. For more deterministic behavior, see
32765 * g_socket_listener_add_inet_port().
32767 * @source_object will be passed out in the various calls
32768 * to accept to identify this particular source, which is
32769 * useful if you're listening on multiple addresses and do
32770 * different things depending on what address is connected to.
32772 * If successful and @effective_address is non-%NULL then it will
32773 * be set to the address that the binding actually occurred at. This
32774 * is helpful for determining the port number that was used for when
32775 * requesting a binding to port 0 (ie: "any port"). This address, if
32776 * requested, belongs to the caller and must be freed.
32778 * Returns: %TRUE on success, %FALSE on error.
32784 * g_socket_listener_add_any_inet_port:
32785 * @listener: a #GSocketListener
32786 * @source_object: (allow-none): Optional #GObject identifying this source
32787 * @error: a #GError location to store the error occurring, or %NULL to
32790 * Listens for TCP connections on any available port number for both
32791 * IPv6 and IPv4 (if each is available).
32793 * This is useful if you need to have a socket for incoming connections
32794 * but don't care about the specific port number.
32796 * @source_object will be passed out in the various calls
32797 * to accept to identify this particular source, which is
32798 * useful if you're listening on multiple addresses and do
32799 * different things depending on what address is connected to.
32801 * Returns: the port number, or 0 in case of failure.
32807 * g_socket_listener_add_inet_port:
32808 * @listener: a #GSocketListener
32809 * @port: an IP port number (non-zero)
32810 * @source_object: (allow-none): Optional #GObject identifying this source
32811 * @error: #GError for error reporting, or %NULL to ignore.
32813 * Helper function for g_socket_listener_add_address() that
32814 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
32815 * supported) on the specified port on all interfaces.
32817 * @source_object will be passed out in the various calls
32818 * to accept to identify this particular source, which is
32819 * useful if you're listening on multiple addresses and do
32820 * different things depending on what address is connected to.
32822 * Returns: %TRUE on success, %FALSE on error.
32828 * g_socket_listener_add_socket:
32829 * @listener: a #GSocketListener
32830 * @socket: a listening #GSocket
32831 * @source_object: (allow-none): Optional #GObject identifying this source
32832 * @error: #GError for error reporting, or %NULL to ignore.
32834 * Adds @socket to the set of sockets that we try to accept
32835 * new clients from. The socket must be bound to a local
32836 * address and listened to.
32838 * @source_object will be passed out in the various calls
32839 * to accept to identify this particular source, which is
32840 * useful if you're listening on multiple addresses and do
32841 * different things depending on what address is connected to.
32843 * Returns: %TRUE on success, %FALSE on error.
32849 * g_socket_listener_close:
32850 * @listener: a #GSocketListener
32852 * Closes all the sockets in the listener.
32859 * g_socket_listener_new:
32861 * Creates a new #GSocketListener with no sockets to listen for.
32862 * New listeners can be added with e.g. g_socket_listener_add_address()
32863 * or g_socket_listener_add_inet_port().
32865 * Returns: a new #GSocketListener.
32871 * g_socket_listener_set_backlog:
32872 * @listener: a #GSocketListener
32873 * @listen_backlog: an integer
32875 * Sets the listen backlog on the sockets in the listener.
32877 * See g_socket_set_listen_backlog() for details
32885 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
32886 * @type: the socket type to use.
32887 * @protocol: the id of the protocol to use, or 0 for default.
32888 * @error: #GError for error reporting, or %NULL to ignore.
32890 * Creates a new #GSocket with the defined family, type and protocol.
32891 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
32892 * for the family and type is used.
32894 * The @protocol is a family and type specific int that specifies what
32895 * kind of protocol to use. #GSocketProtocol lists several common ones.
32896 * Many families only support one protocol, and use 0 for this, others
32897 * support several and using 0 means to use the default protocol for
32898 * the family and type.
32900 * The protocol id is passed directly to the operating
32901 * system, so you can use protocols not listed in #GSocketProtocol if you
32902 * know the protocol number used for it.
32904 * Returns: a #GSocket or %NULL on error.
32905 * Free the returned object with g_object_unref().
32911 * g_socket_new_from_fd:
32912 * @fd: a native socket file descriptor.
32913 * @error: #GError for error reporting, or %NULL to ignore.
32915 * Creates a new #GSocket from a native file descriptor
32916 * or winsock SOCKET handle.
32918 * This reads all the settings from the file descriptor so that
32919 * all properties should work. Note that the file descriptor
32920 * will be set to non-blocking mode, independent on the blocking
32921 * mode of the #GSocket.
32923 * Returns: a #GSocket or %NULL on error.
32924 * Free the returned object with g_object_unref().
32930 * g_socket_receive:
32931 * @socket: a #GSocket
32932 * @buffer: (array length=size) (element-type guint8): a buffer to
32933 * read data into (which should be at least @size bytes long).
32934 * @size: the number of bytes you want to read from the socket
32935 * @cancellable: (allow-none): a %GCancellable or %NULL
32936 * @error: #GError for error reporting, or %NULL to ignore.
32938 * Receive data (up to @size bytes) from a socket. This is mainly used by
32939 * connection-oriented sockets; it is identical to g_socket_receive_from()
32940 * with @address set to %NULL.
32942 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
32943 * g_socket_receive() will always read either 0 or 1 complete messages from
32944 * the socket. If the received message is too large to fit in @buffer, then
32945 * the data beyond @size bytes will be discarded, without any explicit
32946 * indication that this has occurred.
32948 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
32949 * number of bytes, up to @size. If more than @size bytes have been
32950 * received, the additional data will be returned in future calls to
32951 * g_socket_receive().
32953 * If the socket is in blocking mode the call will block until there
32954 * is some data to receive, the connection is closed, or there is an
32955 * error. If there is no data available and the socket is in
32956 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
32957 * returned. To be notified when data is available, wait for the
32958 * %G_IO_IN condition.
32960 * On error -1 is returned and @error is set accordingly.
32962 * Returns: Number of bytes read, or 0 if the connection was closed by
32963 * the peer, or -1 on error
32969 * g_socket_receive_from:
32970 * @socket: a #GSocket
32971 * @address: (out) (allow-none): a pointer to a #GSocketAddress
32972 * pointer, or %NULL
32973 * @buffer: (array length=size) (element-type guint8): a buffer to
32974 * read data into (which should be at least @size bytes long).
32975 * @size: the number of bytes you want to read from the socket
32976 * @cancellable: (allow-none): a %GCancellable or %NULL
32977 * @error: #GError for error reporting, or %NULL to ignore.
32979 * Receive data (up to @size bytes) from a socket.
32981 * If @address is non-%NULL then @address will be set equal to the
32982 * source address of the received packet.
32983 * @address is owned by the caller.
32985 * See g_socket_receive() for additional information.
32987 * Returns: Number of bytes read, or 0 if the connection was closed by
32988 * the peer, or -1 on error
32994 * g_socket_receive_message:
32995 * @socket: a #GSocket
32996 * @address: (out) (allow-none): a pointer to a #GSocketAddress
32997 * pointer, or %NULL
32998 * @vectors: (array length=num_vectors): an array of #GInputVector structs
32999 * @num_vectors: the number of elements in @vectors, or -1
33000 * @messages: (array length=num_messages) (allow-none): a pointer which
33001 * may be filled with an array of #GSocketControlMessages, or %NULL
33002 * @num_messages: a pointer which will be filled with the number of
33003 * elements in @messages, or %NULL
33004 * @flags: a pointer to an int containing #GSocketMsgFlags flags
33005 * @cancellable: (allow-none): a %GCancellable or %NULL
33006 * @error: a #GError pointer, or %NULL
33008 * Receive data from a socket. This is the most complicated and
33009 * fully-featured version of this call. For easier use, see
33010 * g_socket_receive() and g_socket_receive_from().
33012 * If @address is non-%NULL then @address will be set equal to the
33013 * source address of the received packet.
33014 * @address is owned by the caller.
33016 * @vector must point to an array of #GInputVector structs and
33017 * @num_vectors must be the length of this array. These structs
33018 * describe the buffers that received data will be scattered into.
33019 * If @num_vectors is -1, then @vectors is assumed to be terminated
33020 * by a #GInputVector with a %NULL buffer pointer.
33022 * As a special case, if @num_vectors is 0 (in which case, @vectors
33023 * may of course be %NULL), then a single byte is received and
33024 * discarded. This is to facilitate the common practice of sending a
33025 * single '\0' byte for the purposes of transferring ancillary data.
33027 * @messages, if non-%NULL, will be set to point to a newly-allocated
33028 * array of #GSocketControlMessage instances or %NULL if no such
33029 * messages was received. These correspond to the control messages
33030 * received from the kernel, one #GSocketControlMessage per message
33031 * from the kernel. This array is %NULL-terminated and must be freed
33032 * by the caller using g_free() after calling g_object_unref() on each
33033 * element. If @messages is %NULL, any control messages received will
33036 * @num_messages, if non-%NULL, will be set to the number of control
33037 * messages received.
33039 * If both @messages and @num_messages are non-%NULL, then
33040 * @num_messages gives the number of #GSocketControlMessage instances
33041 * in @messages (ie: not including the %NULL terminator).
33043 * @flags is an in/out parameter. The commonly available arguments
33044 * for this are available in the #GSocketMsgFlags enum, but the
33045 * values there are the same as the system values, and the flags
33046 * are passed in as-is, so you can pass in system-specific flags too
33047 * (and g_socket_receive_message() may pass system-specific flags out).
33049 * As with g_socket_receive(), data may be discarded if @socket is
33050 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
33051 * provide enough buffer space to read a complete message. You can pass
33052 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
33053 * removing it from the receive queue, but there is no portable way to find
33054 * out the length of the message other than by reading it into a
33055 * sufficiently-large buffer.
33057 * If the socket is in blocking mode the call will block until there
33058 * is some data to receive, the connection is closed, or there is an
33059 * error. If there is no data available and the socket is in
33060 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
33061 * returned. To be notified when data is available, wait for the
33062 * %G_IO_IN condition.
33064 * On error -1 is returned and @error is set accordingly.
33066 * Returns: Number of bytes read, or 0 if the connection was closed by
33067 * the peer, or -1 on error
33073 * g_socket_receive_with_blocking:
33074 * @socket: a #GSocket
33075 * @buffer: (array length=size) (element-type guint8): a buffer to
33076 * read data into (which should be at least @size bytes long).
33077 * @size: the number of bytes you want to read from the socket
33078 * @blocking: whether to do blocking or non-blocking I/O
33079 * @cancellable: (allow-none): a %GCancellable or %NULL
33080 * @error: #GError for error reporting, or %NULL to ignore.
33082 * This behaves exactly the same as g_socket_receive(), except that
33083 * the choice of blocking or non-blocking behavior is determined by
33084 * the @blocking argument rather than by @socket's properties.
33086 * Returns: Number of bytes read, or 0 if the connection was closed by
33087 * the peer, or -1 on error
33094 * @socket: a #GSocket
33095 * @buffer: (array length=size) (element-type guint8): the buffer
33096 * containing the data to send.
33097 * @size: the number of bytes to send
33098 * @cancellable: (allow-none): a %GCancellable or %NULL
33099 * @error: #GError for error reporting, or %NULL to ignore.
33101 * Tries to send @size bytes from @buffer on the socket. This is
33102 * mainly used by connection-oriented sockets; it is identical to
33103 * g_socket_send_to() with @address set to %NULL.
33105 * If the socket is in blocking mode the call will block until there is
33106 * space for the data in the socket queue. If there is no space available
33107 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
33108 * will be returned. To be notified when space is available, wait for the
33109 * %G_IO_OUT condition. Note though that you may still receive
33110 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
33111 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
33112 * very common due to the way the underlying APIs work.)
33114 * On error -1 is returned and @error is set accordingly.
33116 * Returns: Number of bytes written (which may be less than @size), or -1
33123 * g_socket_send_message:
33124 * @socket: a #GSocket
33125 * @address: (allow-none): a #GSocketAddress, or %NULL
33126 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
33127 * @num_vectors: the number of elements in @vectors, or -1
33128 * @messages: (array length=num_messages) (allow-none): a pointer to an
33129 * array of #GSocketControlMessages, or %NULL.
33130 * @num_messages: number of elements in @messages, or -1.
33131 * @flags: an int containing #GSocketMsgFlags flags
33132 * @cancellable: (allow-none): a %GCancellable or %NULL
33133 * @error: #GError for error reporting, or %NULL to ignore.
33135 * Send data to @address on @socket. This is the most complicated and
33136 * fully-featured version of this call. For easier use, see
33137 * g_socket_send() and g_socket_send_to().
33139 * If @address is %NULL then the message is sent to the default receiver
33140 * (set by g_socket_connect()).
33142 * @vectors must point to an array of #GOutputVector structs and
33143 * @num_vectors must be the length of this array. (If @num_vectors is -1,
33144 * then @vectors is assumed to be terminated by a #GOutputVector with a
33145 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
33146 * that the sent data will be gathered from. Using multiple
33147 * #GOutputVector<!-- -->s is more memory-efficient than manually copying
33148 * data from multiple sources into a single buffer, and more
33149 * network-efficient than making multiple calls to g_socket_send().
33151 * @messages, if non-%NULL, is taken to point to an array of @num_messages
33152 * #GSocketControlMessage instances. These correspond to the control
33153 * messages to be sent on the socket.
33154 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
33157 * @flags modify how the message is sent. The commonly available arguments
33158 * for this are available in the #GSocketMsgFlags enum, but the
33159 * values there are the same as the system values, and the flags
33160 * are passed in as-is, so you can pass in system-specific flags too.
33162 * If the socket is in blocking mode the call will block until there is
33163 * space for the data in the socket queue. If there is no space available
33164 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
33165 * will be returned. To be notified when space is available, wait for the
33166 * %G_IO_OUT condition. Note though that you may still receive
33167 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
33168 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
33169 * very common due to the way the underlying APIs work.)
33171 * On error -1 is returned and @error is set accordingly.
33173 * Returns: Number of bytes written (which may be less than @size), or -1
33180 * g_socket_send_to:
33181 * @socket: a #GSocket
33182 * @address: (allow-none): a #GSocketAddress, or %NULL
33183 * @buffer: (array length=size) (element-type guint8): the buffer
33184 * containing the data to send.
33185 * @size: the number of bytes to send
33186 * @cancellable: (allow-none): a %GCancellable or %NULL
33187 * @error: #GError for error reporting, or %NULL to ignore.
33189 * Tries to send @size bytes from @buffer to @address. If @address is
33190 * %NULL then the message is sent to the default receiver (set by
33191 * g_socket_connect()).
33193 * See g_socket_send() for additional information.
33195 * Returns: Number of bytes written (which may be less than @size), or -1
33202 * g_socket_send_with_blocking:
33203 * @socket: a #GSocket
33204 * @buffer: (array length=size) (element-type guint8): the buffer
33205 * containing the data to send.
33206 * @size: the number of bytes to send
33207 * @blocking: whether to do blocking or non-blocking I/O
33208 * @cancellable: (allow-none): a %GCancellable or %NULL
33209 * @error: #GError for error reporting, or %NULL to ignore.
33211 * This behaves exactly the same as g_socket_send(), except that
33212 * the choice of blocking or non-blocking behavior is determined by
33213 * the @blocking argument rather than by @socket's properties.
33215 * Returns: Number of bytes written (which may be less than @size), or -1
33222 * g_socket_service_is_active:
33223 * @service: a #GSocketService
33225 * Check whether the service is active or not. An active
33226 * service will accept new clients that connect, while
33227 * a non-active service will let connecting clients queue
33228 * up until the service is started.
33230 * Returns: %TRUE if the service is active, %FALSE otherwise
33236 * g_socket_service_new:
33238 * Creates a new #GSocketService with no sockets to listen for.
33239 * New listeners can be added with e.g. g_socket_listener_add_address()
33240 * or g_socket_listener_add_inet_port().
33242 * Returns: a new #GSocketService.
33248 * g_socket_service_start:
33249 * @service: a #GSocketService
33251 * Starts the service, i.e. start accepting connections
33252 * from the added sockets when the mainloop runs.
33254 * This call is thread-safe, so it may be called from a thread
33255 * handling an incoming client request.
33262 * g_socket_service_stop:
33263 * @service: a #GSocketService
33265 * Stops the service, i.e. stops accepting connections
33266 * from the added sockets when the mainloop runs.
33268 * This call is thread-safe, so it may be called from a thread
33269 * handling an incoming client request.
33276 * g_socket_set_blocking:
33277 * @socket: a #GSocket.
33278 * @blocking: Whether to use blocking I/O or not.
33280 * Sets the blocking mode of the socket. In blocking mode
33281 * all operations block until they succeed or there is an error. In
33282 * non-blocking mode all functions return results immediately or
33283 * with a %G_IO_ERROR_WOULD_BLOCK error.
33285 * All sockets are created in blocking mode. However, note that the
33286 * platform level socket is always non-blocking, and blocking mode
33287 * is a GSocket level feature.
33294 * g_socket_set_broadcast:
33295 * @socket: a #GSocket.
33296 * @broadcast: whether @socket should allow sending to broadcast
33299 * Sets whether @socket should allow sending to broadcast addresses.
33300 * This is %FALSE by default.
33307 * g_socket_set_keepalive:
33308 * @socket: a #GSocket.
33309 * @keepalive: Value for the keepalive flag
33311 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
33312 * this flag is set on a socket, the system will attempt to verify that the
33313 * remote socket endpoint is still present if a sufficiently long period of
33314 * time passes with no data being exchanged. If the system is unable to
33315 * verify the presence of the remote endpoint, it will automatically close
33318 * This option is only functional on certain kinds of sockets. (Notably,
33319 * %G_SOCKET_PROTOCOL_TCP sockets.)
33321 * The exact time between pings is system- and protocol-dependent, but will
33322 * normally be at least two hours. Most commonly, you would set this flag
33323 * on a server socket if you want to allow clients to remain idle for long
33324 * periods of time, but also want to ensure that connections are eventually
33325 * garbage-collected if clients crash or become unreachable.
33332 * g_socket_set_listen_backlog:
33333 * @socket: a #GSocket.
33334 * @backlog: the maximum number of pending connections.
33336 * Sets the maximum number of outstanding connections allowed
33337 * when listening on this socket. If more clients than this are
33338 * connecting to the socket and the application is not handling them
33339 * on time then the new connections will be refused.
33341 * Note that this must be called before g_socket_listen() and has no
33342 * effect if called after that.
33349 * g_socket_set_multicast_loopback:
33350 * @socket: a #GSocket.
33351 * @loopback: whether @socket should receive messages sent to its
33352 * multicast groups from the local host
33354 * Sets whether outgoing multicast packets will be received by sockets
33355 * listening on that multicast address on the same host. This is %TRUE
33363 * g_socket_set_multicast_ttl:
33364 * @socket: a #GSocket.
33365 * @ttl: the time-to-live value for all multicast datagrams on @socket
33367 * Sets the time-to-live for outgoing multicast datagrams on @socket.
33368 * By default, this is 1, meaning that multicast packets will not leave
33369 * the local network.
33376 * g_socket_set_option:
33377 * @socket: a #GSocket
33378 * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>)
33379 * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
33380 * @value: the value to set the option to
33381 * @error: #GError for error reporting, or %NULL to ignore.
33383 * Sets the value of an integer-valued option on @socket, as with
33384 * <literal>setsockopt ()</literal>. (If you need to set a
33385 * non-integer-valued option, you will need to call
33386 * <literal>setsockopt ()</literal> directly.)
33388 * The <link linkend="gio-gnetworking.h"><literal><gio/gnetworking.h></literal></link>
33389 * header pulls in system headers that will define most of the
33390 * standard/portable socket options. For unusual socket protocols or
33391 * platform-dependent options, you may need to include additional
33394 * Returns: success or failure. On failure, @error will be set, and
33395 * the system error value (<literal>errno</literal> or
33396 * <literal>WSAGetLastError ()</literal>) will still be set to the
33397 * result of the <literal>setsockopt ()</literal> call.
33403 * g_socket_set_timeout:
33404 * @socket: a #GSocket.
33405 * @timeout: the timeout for @socket, in seconds, or 0 for none
33407 * Sets the time in seconds after which I/O operations on @socket will
33408 * time out if they have not yet completed.
33410 * On a blocking socket, this means that any blocking #GSocket
33411 * operation will time out after @timeout seconds of inactivity,
33412 * returning %G_IO_ERROR_TIMED_OUT.
33414 * On a non-blocking socket, calls to g_socket_condition_wait() will
33415 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
33416 * created with g_socket_create_source() will trigger after
33417 * @timeout seconds of inactivity, with the requested condition
33418 * set, at which point calling g_socket_receive(), g_socket_send(),
33419 * g_socket_check_connect_result(), etc, will fail with
33420 * %G_IO_ERROR_TIMED_OUT.
33422 * If @timeout is 0 (the default), operations will never time out
33425 * Note that if an I/O operation is interrupted by a signal, this may
33426 * cause the timeout to be reset.
33433 * g_socket_set_ttl:
33434 * @socket: a #GSocket.
33435 * @ttl: the time-to-live value for all unicast packets on @socket
33437 * Sets the time-to-live for outgoing unicast packets on @socket.
33438 * By default the platform-specific default value is used.
33445 * g_socket_shutdown:
33446 * @socket: a #GSocket
33447 * @shutdown_read: whether to shut down the read side
33448 * @shutdown_write: whether to shut down the write side
33449 * @error: #GError for error reporting, or %NULL to ignore.
33451 * Shut down part of a full-duplex connection.
33453 * If @shutdown_read is %TRUE then the receiving side of the connection
33454 * is shut down, and further reading is disallowed.
33456 * If @shutdown_write is %TRUE then the sending side of the connection
33457 * is shut down, and further writing is disallowed.
33459 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
33461 * One example where this is used is graceful disconnect for TCP connections
33462 * where you close the sending side, then wait for the other side to close
33463 * the connection, thus ensuring that the other side saw all sent data.
33465 * Returns: %TRUE on success, %FALSE on error
33471 * g_socket_speaks_ipv4:
33472 * @socket: a #GSocket
33474 * Checks if a socket is capable of speaking IPv4.
33476 * IPv4 sockets are capable of speaking IPv4. On some operating systems
33477 * and under some combinations of circumstances IPv6 sockets are also
33478 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
33481 * No other types of sockets are currently considered as being capable
33482 * of speaking IPv4.
33484 * Returns: %TRUE if this socket can be used with IPv4.
33490 * g_srv_target_copy:
33491 * @target: a #GSrvTarget
33495 * Returns: a copy of @target
33501 * g_srv_target_free:
33502 * @target: a #GSrvTarget
33511 * g_srv_target_get_hostname:
33512 * @target: a #GSrvTarget
33514 * Gets @target's hostname (in ASCII form; if you are going to present
33515 * this to the user, you should use g_hostname_is_ascii_encoded() to
33516 * check if it contains encoded Unicode segments, and use
33517 * g_hostname_to_unicode() to convert it if it does.)
33519 * Returns: @target's hostname
33525 * g_srv_target_get_port:
33526 * @target: a #GSrvTarget
33528 * Gets @target's port
33530 * Returns: @target's port
33536 * g_srv_target_get_priority:
33537 * @target: a #GSrvTarget
33539 * Gets @target's priority. You should not need to look at this;
33540 * #GResolver already sorts the targets according to the algorithm in
33543 * Returns: @target's priority
33549 * g_srv_target_get_weight:
33550 * @target: a #GSrvTarget
33552 * Gets @target's weight. You should not need to look at this;
33553 * #GResolver already sorts the targets according to the algorithm in
33556 * Returns: @target's weight
33562 * g_srv_target_list_sort: (skip)
33563 * @targets: a #GList of #GSrvTarget
33565 * Sorts @targets in place according to the algorithm in RFC 2782.
33567 * Returns: (transfer full): the head of the sorted list.
33573 * g_srv_target_new:
33574 * @hostname: the host that the service is running on
33575 * @port: the port that the service is running on
33576 * @priority: the target's priority
33577 * @weight: the target's weight
33579 * Creates a new #GSrvTarget with the given parameters.
33581 * You should not need to use this; normally #GSrvTarget<!-- -->s are
33582 * created by #GResolver.
33584 * Returns: a new #GSrvTarget.
33590 * g_static_resource_fini:
33591 * @static_resource: pointer to a static #GStaticResource
33593 * Finalized a GResource initialized by g_static_resource_init().
33595 * This is normally used by code generated by
33596 * <link linkend="glib-compile-resources">glib-compile-resources</link>
33597 * and is not typically used by other code.
33604 * g_static_resource_get_resource:
33605 * @static_resource: pointer to a static #GStaticResource
33607 * Gets the GResource that was registered by a call to g_static_resource_init().
33609 * This is normally used by code generated by
33610 * <link linkend="glib-compile-resources">glib-compile-resources</link>
33611 * and is not typically used by other code.
33613 * Returns: (transfer none): a #GResource
33619 * g_static_resource_init:
33620 * @static_resource: pointer to a static #GStaticResource
33622 * Initializes a GResource from static data using a
33625 * This is normally used by code generated by
33626 * <link linkend="glib-compile-resources">glib-compile-resources</link>
33627 * and is not typically used by other code.
33634 * g_subprocess_communicate:
33635 * @subprocess: a #GSubprocess
33636 * @stdin_buf: data to send to the stdin of the subprocess, or %NULL
33637 * @cancellable: a #GCancellable
33638 * @stdout_buf: (out): data read from the subprocess stdout
33639 * @stderr_buf: (out): data read from the subprocess stderr
33640 * @error: a pointer to a %NULL #GError pointer, or %NULL
33642 * Communicate with the subprocess until it terminates, and all input
33643 * and output has been completed.
33645 * If @stdin is given, the subprocess must have been created with
33646 * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
33647 * stdin of the subprocess and the pipe is closed (ie: EOF).
33649 * At the same time (as not to cause blocking when dealing with large
33650 * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
33651 * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
33652 * streams. The data that was read is returned in @stdout and/or
33655 * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
33656 * @stdout_buf will contain the data read from stdout. Otherwise, for
33657 * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
33658 * @stdout_buf will be set to %NULL. Similar provisions apply to
33659 * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
33661 * As usual, any output variable may be given as %NULL to ignore it.
33663 * If you desire the stdout and stderr data to be interleaved, create
33664 * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
33665 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
33666 * in @stdout_buf and @stderr_buf will be set to %NULL.
33668 * In case of any error (including cancellation), %FALSE will be
33669 * returned with @error set. Some or all of the stdin data may have
33670 * been written. Any stdout or stderr data that has been read will be
33671 * discarded. None of the out variables (aside from @error) will have
33672 * been set to anything in particular and should not be inspected.
33674 * In the case that %TRUE is returned, the subprocess has exited and the
33675 * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
33676 * g_subprocess_get_exit_status()) may be used.
33678 * You should not attempt to use any of the subprocess pipes after
33679 * starting this function, since they may be left in strange states,
33680 * even if the operation was cancelled. You should especially not
33681 * attempt to interact with the pipes while the operation is in progress
33682 * (either from another thread or if using the asynchronous version).
33684 * Returns: %TRUE if successful
33690 * g_subprocess_communicate_async:
33691 * @subprocess: Self
33692 * @stdin_buf: Input data
33693 * @cancellable: Cancellable
33694 * @callback: Callback
33695 * @user_data: User data
33697 * Asynchronous version of g_subprocess_communicate(). Complete
33698 * invocation with g_subprocess_communicate_finish().
33703 * g_subprocess_communicate_finish:
33704 * @subprocess: Self
33706 * @stdout_buf: (out): Return location for stdout data
33707 * @stderr_buf: (out): Return location for stderr data
33710 * Complete an invocation of g_subprocess_communicate_async().
33715 * g_subprocess_communicate_utf8:
33716 * @subprocess: a #GSubprocess
33717 * @stdin_buf: data to send to the stdin of the subprocess, or %NULL
33718 * @cancellable: a #GCancellable
33719 * @stdout_buf: (out): data read from the subprocess stdout
33720 * @stderr_buf: (out): data read from the subprocess stderr
33721 * @error: a pointer to a %NULL #GError pointer, or %NULL
33723 * Like g_subprocess_communicate(), but validates the output of the
33724 * process as UTF-8, and returns it as a regular NUL terminated string.
33729 * g_subprocess_communicate_utf8_async:
33730 * @subprocess: Self
33731 * @stdin_buf: Input data
33732 * @cancellable: Cancellable
33733 * @callback: Callback
33734 * @user_data: User data
33736 * Asynchronous version of g_subprocess_communicate_utf(). Complete
33737 * invocation with g_subprocess_communicate_utf8_finish().
33742 * g_subprocess_communicate_utf8_finish:
33743 * @subprocess: Self
33745 * @stdout_buf: (out): Return location for stdout data
33746 * @stderr_buf: (out): Return location for stderr data
33749 * Complete an invocation of g_subprocess_communicate_utf8_async().
33754 * g_subprocess_force_exit:
33755 * @subprocess: a #GSubprocess
33757 * Use an operating-system specific method to attempt an immediate,
33758 * forceful termination of the process. There is no mechanism to
33759 * determine whether or not the request itself was successful;
33760 * however, you can use g_subprocess_wait() to monitor the status of
33761 * the process after calling this function.
33763 * On Unix, this function sends %SIGKILL.
33770 * g_subprocess_get_exit_status:
33771 * @subprocess: a #GSubprocess
33773 * Check the exit status of the subprocess, given that it exited
33774 * normally. This is the value passed to the exit() system call or the
33775 * return value from main.
33777 * This is equivalent to the system WEXITSTATUS macro.
33779 * It is an error to call this function before g_subprocess_wait() and
33780 * unless g_subprocess_get_if_exited() returned %TRUE.
33782 * Returns: the exit status
33788 * g_subprocess_get_if_exited:
33789 * @subprocess: a #GSubprocess
33791 * Check if the given subprocess exited normally (ie: by way of exit()
33792 * or return from main()).
33794 * This is equivalent to the system WIFEXITED macro.
33796 * It is an error to call this function before g_subprocess_wait() has
33799 * Returns: %TRUE if the case of a normal exit
33805 * g_subprocess_get_if_signaled:
33806 * @subprocess: a #GSubprocess
33808 * Check if the given subprocess terminated in response to a signal.
33810 * This is equivalent to the system WIFSIGNALED macro.
33812 * It is an error to call this function before g_subprocess_wait() has
33815 * Returns: %TRUE if the case of termination due to a signal
33821 * g_subprocess_get_status:
33822 * @subprocess: a #GSubprocess
33824 * Gets the raw status code of the process, as from waitpid().
33826 * This value has no particular meaning, but it can be used with the
33827 * macros defined by the system headers such as WIFEXITED. It can also
33828 * be used with g_spawn_check_exit_status().
33830 * It is more likely that you want to use g_subprocess_get_if_exited()
33831 * followed by g_subprocess_get_exit_status().
33833 * It is an error to call this function before g_subprocess_wait() has
33836 * Returns: the (meaningless) waitpid() exit status from the kernel
33842 * g_subprocess_get_stderr_pipe:
33843 * @subprocess: a #GSubprocess
33845 * Gets the #GInputStream from which to read the stderr output of
33848 * The process must have been created with
33849 * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
33851 * Returns: the stderr pipe
33857 * g_subprocess_get_stdin_pipe:
33858 * @subprocess: a #GSubprocess
33860 * Gets the #GOutputStream that you can write to in order to give data
33861 * to the stdin of @subprocess.
33863 * The process must have been created with
33864 * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
33866 * Returns: the stdout pipe
33872 * g_subprocess_get_stdout_pipe:
33873 * @subprocess: a #GSubprocess
33875 * Gets the #GInputStream from which to read the stdout output of
33878 * The process must have been created with
33879 * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
33881 * Returns: the stdout pipe
33887 * g_subprocess_get_successful:
33888 * @subprocess: a #GSubprocess
33890 * Checks if the process was "successful". A process is considered
33891 * successful if it exited cleanly with an exit status of 0, either by
33892 * way of the exit() system call or return from main().
33894 * It is an error to call this function before g_subprocess_wait() has
33897 * Returns: %TRUE if the process exited cleanly with a exit status of 0
33903 * g_subprocess_get_term_sig:
33904 * @subprocess: a #GSubprocess
33906 * Get the signal number that caused the subprocess to terminate, given
33907 * that it terminated due to a signal.
33909 * This is equivalent to the system WTERMSIG macro.
33911 * It is an error to call this function before g_subprocess_wait() and
33912 * unless g_subprocess_get_if_signaled() returned %TRUE.
33914 * Returns: the signal causing termination
33920 * g_subprocess_launcher_getenv:
33921 * @self: a #GSubprocess
33922 * @variable: the environment variable to get
33924 * Returns the value of the environment variable @variable in the
33925 * environment of processes launched from this launcher.
33927 * The returned string is in the GLib file name encoding. On UNIX, this
33928 * means that it can be an arbitrary byte string. On Windows, it will
33931 * Returns: the value of the environment variable, %NULL if unset
33937 * g_subprocess_launcher_new:
33938 * @flags: #GSubprocessFlags
33940 * Creates a new #GSubprocessLauncher.
33942 * The launcher is created with the default options. A copy of the
33943 * environment of the calling process is made at the time of this call
33944 * and will be used as the environment that the process is launched in.
33951 * g_subprocess_launcher_set_child_setup:
33952 * @self: a #GSubprocessLauncher
33953 * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
33954 * @user_data: user data for @child_setup
33955 * @destroy_notify: a #GDestroyNotify for @user_data
33957 * Sets up a child setup function.
33959 * The child setup function will be called after fork() but before
33960 * exec() on the child's side.
33962 * @destroy_notify will not be automatically called on the child's side
33963 * of the fork(). It will only be called when the last reference on the
33964 * #GSubprocessLauncher is dropped or when a new child setup function is
33967 * %NULL can be given as @child_setup to disable the functionality.
33969 * Child setup functions are only available on UNIX.
33976 * g_subprocess_launcher_set_cwd:
33977 * @self: a #GSubprocess
33978 * @cwd: the cwd for launched processes
33980 * Sets the current working directory that processes will be launched
33983 * By default processes are launched with the current working directory
33984 * of the launching process at the time of launch.
33991 * g_subprocess_launcher_set_environ:
33992 * @self: a #GSubprocess
33993 * @environ: the replacement environment
33995 * Replace the entire environment of processes launched from this
33996 * launcher with the given 'environ' variable.
33998 * Typically you will build this variable by using g_listenv() to copy
33999 * the process 'environ' and using the functions g_environ_setenv(),
34000 * g_environ_unsetenv(), etc.
34002 * As an alternative, you can use g_subprocess_launcher_setenv(),
34003 * g_subprocess_launcher_unsetenv(), etc.
34005 * All strings in this array are expected to be in the GLib file name
34006 * encoding. On UNIX, this means that they can be arbitrary byte
34007 * strings. On Windows, they should be in UTF-8.
34014 * g_subprocess_launcher_set_flags:
34015 * @self: a #GSubprocessLauncher
34016 * @flags: #GSubprocessFlags
34018 * Sets the flags on the launcher.
34020 * The default flags are %G_SUBPROCESS_FLAGS_NONE.
34022 * You may not set flags that specify conflicting options for how to
34023 * handle a particular stdio stream (eg: specifying both
34024 * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
34025 * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
34027 * You may also not set a flag that conflicts with a previous call to a
34028 * function like g_subprocess_launcher_set_stdin_file_path() or
34029 * g_subprocess_launcher_take_stdout_fd().
34036 * g_subprocess_launcher_set_stderr_file_path:
34037 * @self: a #GSubprocessLauncher
34038 * @path: a filename or %NULL
34040 * Sets the file path to use as the stderr for spawned processes.
34042 * If @path is %NULL then any previously given path is unset.
34044 * The file will be created or truncated when the process is spawned, as
34045 * would be the case if using '2>' at the shell.
34047 * If you want to send both stdout and stderr to the same file then use
34048 * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
34050 * You may not set a stderr file path if a stderr fd is already set or
34051 * if the launcher flags contain any flags directing stderr elsewhere.
34053 * This feature is only available on UNIX.
34060 * g_subprocess_launcher_set_stdin_file_path:
34061 * @self: a #GSubprocessLauncher
34062 * @path: a filename or %NULL
34064 * Sets the file path to use as the stdin for spawned processes.
34066 * If @path is %NULL then any previously given path is unset.
34068 * The file must exist or spawning the process will fail.
34070 * You may not set a stdin file path if a stdin fd is already set or if
34071 * the launcher flags contain any flags directing stdin elsewhere.
34073 * This feature is only available on UNIX.
34080 * g_subprocess_launcher_set_stdout_file_path:
34081 * @self: a #GSubprocessLauncher
34082 * @path: a filename or %NULL
34084 * Sets the file path to use as the stdout for spawned processes.
34086 * If @path is %NULL then any previously given path is unset.
34088 * The file will be created or truncated when the process is spawned, as
34089 * would be the case if using '>' at the shell.
34091 * You may not set a stdout file path if a stdout fd is already set or
34092 * if the launcher flags contain any flags directing stdout elsewhere.
34094 * This feature is only available on UNIX.
34101 * g_subprocess_launcher_setenv:
34102 * @self: a #GSubprocess
34103 * @variable: the environment variable to set, must not contain '='
34104 * @value: the new value for the variable
34105 * @overwrite: whether to change the variable if it already exists
34107 * Sets the environment variable @variable in the environment of
34108 * processes launched from this launcher.
34110 * Both the variable's name and value should be in the GLib file name
34111 * encoding. On UNIX, this means that they can be arbitrary byte
34112 * strings. On Windows, they should be in UTF-8.
34119 * g_subprocess_launcher_spawn:
34120 * @self: a #GSubprocessLauncher
34122 * @argv0: Command line arguments
34123 * @...: Continued arguments, %NULL terminated
34125 * A convenience helper for creating a #GSubprocess given a provided
34126 * varargs list of arguments.
34129 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
34134 * g_subprocess_launcher_spawnv:
34135 * @self: a #GSubprocessLauncher
34136 * @argv: Command line arguments
34139 * A convenience helper for creating a #GSubprocess given a provided
34140 * array of arguments.
34143 * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
34148 * g_subprocess_launcher_take_fd:
34149 * @self: a #GSubprocessLauncher
34150 * @source_fd: File descriptor in parent process
34151 * @target_fd: Target descriptor for child process
34153 * Transfer an arbitrary file descriptor from parent process to the
34154 * child. This function takes "ownership" of the fd; it will be closed
34155 * in the parent when @self is freed.
34157 * By default, all file descriptors from the parent will be closed.
34158 * This function allows you to create (for example) a custom pipe() or
34159 * socketpair() before launching the process, and choose the target
34160 * descriptor in the child.
34162 * An example use case is GNUPG, which has a command line argument
34163 * --passphrase-fd providing a file descriptor number where it expects
34164 * the passphrase to be written.
34169 * g_subprocess_launcher_take_stderr_fd:
34170 * @self: a #GSubprocessLauncher
34171 * @fd: a file descriptor, or -1
34173 * Sets the file descriptor to use as the stderr for spawned processes.
34175 * If @fd is -1 then any previously given fd is unset.
34177 * Note that the default behaviour is to pass stderr through to the
34178 * stderr of the parent process.
34180 * The passed @fd belongs to the #GSubprocessLauncher. It will be
34181 * automatically closed when the launcher is finalized. The file
34182 * descriptor will also be closed on the child side when executing the
34185 * You may not set a stderr fd if a stderr file path is already set or
34186 * if the launcher flags contain any flags directing stderr elsewhere.
34188 * This feature is only available on UNIX.
34195 * g_subprocess_launcher_take_stdin_fd:
34196 * @self: a #GSubprocessLauncher
34197 * @fd: a file descriptor, or -1
34199 * Sets the file descriptor to use as the stdin for spawned processes.
34201 * If @fd is -1 then any previously given fd is unset.
34203 * Note that if your intention is to have the stdin of the calling
34204 * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
34205 * is a better way to go about doing that.
34207 * The passed @fd is noted but will not be touched in the current
34208 * process. It is therefore necessary that it be kept open by the
34209 * caller until the subprocess is spawned. The file descriptor will
34210 * also not be explicitly closed on the child side, so it must be marked
34211 * O_CLOEXEC if that's what you want.
34213 * You may not set a stdin fd if a stdin file path is already set or if
34214 * the launcher flags contain any flags directing stdin elsewhere.
34216 * This feature is only available on UNIX.
34223 * g_subprocess_launcher_take_stdout_fd:
34224 * @self: a #GSubprocessLauncher
34225 * @fd: a file descriptor, or -1
34227 * Sets the file descriptor to use as the stdout for spawned processes.
34229 * If @fd is -1 then any previously given fd is unset.
34231 * Note that the default behaviour is to pass stdout through to the
34232 * stdout of the parent process.
34234 * The passed @fd is noted but will not be touched in the current
34235 * process. It is therefore necessary that it be kept open by the
34236 * caller until the subprocess is spawned. The file descriptor will
34237 * also not be explicitly closed on the child side, so it must be marked
34238 * O_CLOEXEC if that's what you want.
34240 * You may not set a stdout fd if a stdout file path is already set or
34241 * if the launcher flags contain any flags directing stdout elsewhere.
34243 * This feature is only available on UNIX.
34250 * g_subprocess_launcher_unsetenv:
34251 * @self: a #GSubprocess
34252 * @variable: the environment variable to unset, must not contain '='
34254 * Removes the environment variable @variable from the environment of
34255 * processes launched from this launcher.
34257 * The variable name should be in the GLib file name encoding. On UNIX,
34258 * this means that they can be arbitrary byte strings. On Windows, they
34259 * should be in UTF-8.
34266 * g_subprocess_new: (skip)
34267 * @flags: flags that define the behaviour of the subprocess
34268 * @error: (allow-none): return location for an error, or %NULL
34269 * @argv0: first commandline argument to pass to the subprocess,
34270 * followed by more arguments, followed by %NULL
34272 * Create a new process with the given flags and varargs argument
34273 * list. By default, matching the g_spawn_async() defaults, the
34274 * child's stdin will be set to the system null device, and
34275 * stdout/stderr will be inherited from the parent. You can use
34276 * @flags to control this behavior.
34278 * The argument list must be terminated with %NULL.
34280 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
34287 * g_subprocess_newv: (rename-to g_subprocess_new)
34288 * @argv: commandline arguments for the subprocess
34289 * @flags: flags that define the behaviour of the subprocess
34290 * @error: (allow-none): return location for an error, or %NULL
34292 * Create a new process with the given flags and argument list.
34294 * The argument list is expected to be %NULL-terminated.
34296 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
34303 * g_subprocess_send_signal:
34304 * @subprocess: a #GSubprocess
34305 * @signal_num: the signal number to send
34307 * Sends the UNIX signal @signal_num to the subprocess, if it is still
34310 * This API is race-free. If the subprocess has terminated, it will not
34313 * This API is not available on Windows.
34320 * g_subprocess_wait:
34321 * @subprocess: a #GSubprocess
34322 * @cancellable: a #GCancellable
34323 * @error: a #GError
34325 * Synchronously wait for the subprocess to terminate.
34327 * After the process terminates you can query its exit status with
34328 * functions such as g_subprocess_get_if_exited() and
34329 * g_subprocess_get_exit_status().
34331 * This function does not fail in the case of the subprocess having
34332 * abnormal termination. See g_subprocess_wait_check() for that.
34334 * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
34340 * g_subprocess_wait_async:
34341 * @subprocess: a #GSubprocess
34342 * @cancellable: a #GCancellable, or %NULL
34343 * @callback: a #GAsyncReadyCallback to call when the operation is complete
34344 * @user_data: user_data for @callback
34346 * Wait for the subprocess to terminate.
34348 * This is the asynchronous version of g_subprocess_wait().
34355 * g_subprocess_wait_check:
34356 * @subprocess: a #GSubprocess
34357 * @cancellable: a #GCancellable
34358 * @error: a #GError
34360 * Combines g_subprocess_wait() with g_spawn_check_exit_status().
34362 * Returns: %TRUE on success, %FALSE if process exited abnormally, or
34363 * @cancellable was cancelled
34369 * g_subprocess_wait_check_async:
34370 * @subprocess: a #GSubprocess
34371 * @cancellable: a #GCancellable, or %NULL
34372 * @callback: a #GAsyncReadyCallback to call when the operation is complete
34373 * @user_data: user_data for @callback
34375 * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
34377 * This is the asynchronous version of g_subprocess_wait_check().
34384 * g_subprocess_wait_check_finish:
34385 * @subprocess: a #GSubprocess
34386 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
34387 * @error: a pointer to a %NULL #GError, or %NULL
34389 * Collects the result of a previous call to
34390 * g_subprocess_wait_check_async().
34392 * Returns: %TRUE if successful, or %FALSE with @error set
34398 * g_subprocess_wait_finish:
34399 * @subprocess: a #GSubprocess
34400 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
34401 * @error: a pointer to a %NULL #GError, or %NULL
34403 * Collects the result of a previous call to
34404 * g_subprocess_wait_async().
34406 * Returns: %TRUE if successful, or %FALSE with @error set
34412 * g_task_attach_source:
34414 * @source: the source to attach
34415 * @callback: the callback to invoke when @source triggers
34417 * A utility function for dealing with async operations where you need
34418 * to wait for a #GSource to trigger. Attaches @source to @task's
34419 * #GMainContext with @task's <link
34420 * linkend="io-priority">priority</link>, and sets @source's callback
34421 * to @callback, with @task as the callback's
34422 * <literal>user_data</literal>.
34424 * This takes a reference on @task until @source is destroyed.
34431 * g_task_get_cancellable:
34434 * Gets @task's #GCancellable
34436 * Returns: (transfer none): @task's #GCancellable
34442 * g_task_get_check_cancellable:
34443 * @task: the #GTask
34445 * Gets @task's check-cancellable flag. See
34446 * g_task_set_check_cancellable() for more details.
34453 * g_task_get_context:
34456 * Gets the #GMainContext that @task will return its result in (that
34457 * is, the context that was the <link
34458 * linkend="g-main-context-push-thread-default">thread-default main
34459 * context</link> at the point when @task was created).
34461 * This will always return a non-%NULL value, even if the task's
34462 * context is the default #GMainContext.
34464 * Returns: (transfer none): @task's #GMainContext
34470 * g_task_get_priority:
34473 * Gets @task's priority
34475 * Returns: @task's priority
34481 * g_task_get_return_on_cancel:
34482 * @task: the #GTask
34484 * Gets @task's return-on-cancel flag. See
34485 * g_task_set_return_on_cancel() for more details.
34492 * g_task_get_source_object:
34495 * Gets the source object from @task. Like
34496 * g_async_result_get_source_object(), but does not ref the object.
34498 * Returns: (transfer none) (type GObject): @task's source object, or %NULL
34504 * g_task_get_source_tag:
34507 * Gets @task's source tag. See g_task_set_source_tag().
34509 * Returns: (transfer none): @task's source tag
34515 * g_task_get_task_data:
34518 * Gets @task's <literal>task_data</literal>.
34520 * Returns: (transfer none): @task's <literal>task_data</literal>.
34526 * g_task_had_error:
34529 * Tests if @task resulted in an error.
34531 * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
34538 * @result: (type Gio.AsyncResult): A #GAsyncResult
34539 * @source_object: (allow-none) (type GObject): the source object
34540 * expected to be associated with the task
34542 * Checks that @result is a #GTask, and that @source_object is its
34543 * source object (or that @source_object is %NULL and @result has no
34544 * source object). This can be used in g_return_if_fail() checks.
34546 * Returns: %TRUE if @result and @source_object are valid, %FALSE
34554 * @source_object: (allow-none) (type GObject): the #GObject that owns
34555 * this task, or %NULL.
34556 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34557 * @callback: (scope async): a #GAsyncReadyCallback.
34558 * @callback_data: (closure): user data passed to @callback.
34560 * Creates a #GTask acting on @source_object, which will eventually be
34561 * used to invoke @callback in the current <link
34562 * linkend="g-main-context-push-thread-default">thread-default main
34565 * Call this in the "start" method of your asynchronous method, and
34566 * pass the #GTask around throughout the asynchronous operation. You
34567 * can use g_task_set_task_data() to attach task-specific data to the
34568 * object, which you can retrieve later via g_task_get_task_data().
34570 * By default, if @cancellable is cancelled, then the return value of
34571 * the task will always be %G_IO_ERROR_CANCELLED, even if the task had
34572 * already completed before the cancellation. This allows for
34573 * simplified handling in cases where cancellation may imply that
34574 * other objects that the task depends on have been destroyed. If you
34575 * do not want this behavior, you can use
34576 * g_task_set_check_cancellable() to change it.
34578 * Returns: a #GTask.
34584 * g_task_propagate_boolean:
34586 * @error: return location for a #GError
34588 * Gets the result of @task as a #gboolean.
34590 * If the task resulted in an error, or was cancelled, then this will
34591 * instead return %FALSE and set @error.
34593 * Since this method transfers ownership of the return value (or
34594 * error) to the caller, you may only call it once.
34596 * Returns: the task result, or %FALSE on error
34602 * g_task_propagate_int:
34604 * @error: return location for a #GError
34606 * Gets the result of @task as an integer (#gssize).
34608 * If the task resulted in an error, or was cancelled, then this will
34609 * instead return -1 and set @error.
34611 * Since this method transfers ownership of the return value (or
34612 * error) to the caller, you may only call it once.
34614 * Returns: the task result, or -1 on error
34620 * g_task_propagate_pointer:
34622 * @error: return location for a #GError
34624 * Gets the result of @task as a pointer, and transfers ownership
34625 * of that value to the caller.
34627 * If the task resulted in an error, or was cancelled, then this will
34628 * instead return %NULL and set @error.
34630 * Since this method transfers ownership of the return value (or
34631 * error) to the caller, you may only call it once.
34633 * Returns: (transfer full): the task result, or %NULL on error
34639 * g_task_report_error:
34640 * @source_object: (allow-none) (type GObject): the #GObject that owns
34641 * this task, or %NULL.
34642 * @callback: (scope async): a #GAsyncReadyCallback.
34643 * @callback_data: (closure): user data passed to @callback.
34644 * @source_tag: an opaque pointer indicating the source of this task
34645 * @error: (transfer full): error to report
34647 * Creates a #GTask and then immediately calls g_task_return_error()
34648 * on it. Use this in the wrapper function of an asynchronous method
34649 * when you want to avoid even calling the virtual method. You can
34650 * then use g_async_result_is_tagged() in the finish method wrapper to
34651 * check if the result there is tagged as having been created by the
34652 * wrapper method, and deal with it appropriately if so.
34654 * See also g_task_report_new_error().
34661 * g_task_report_new_error:
34662 * @source_object: (allow-none) (type GObject): the #GObject that owns
34663 * this task, or %NULL.
34664 * @callback: (scope async): a #GAsyncReadyCallback.
34665 * @callback_data: (closure): user data passed to @callback.
34666 * @source_tag: an opaque pointer indicating the source of this task
34667 * @domain: a #GQuark.
34668 * @code: an error code.
34669 * @format: a string with format characters.
34670 * @...: a list of values to insert into @format.
34672 * Creates a #GTask and then immediately calls
34673 * g_task_return_new_error() on it. Use this in the wrapper function
34674 * of an asynchronous method when you want to avoid even calling the
34675 * virtual method. You can then use g_async_result_is_tagged() in the
34676 * finish method wrapper to check if the result there is tagged as
34677 * having been created by the wrapper method, and deal with it
34678 * appropriately if so.
34680 * See also g_task_report_error().
34687 * g_task_return_boolean:
34689 * @result: the #gboolean result of a task function.
34691 * Sets @task's result to @result and completes the task (see
34692 * g_task_return_pointer() for more discussion of exactly what this
34700 * g_task_return_error:
34702 * @error: (transfer full): the #GError result of a task function.
34704 * Sets @task's result to @error (which @task assumes ownership of)
34705 * and completes the task (see g_task_return_pointer() for more
34706 * discussion of exactly what this means).
34708 * Note that since the task takes ownership of @error, and since the
34709 * task may be completed before returning from g_task_return_error(),
34710 * you cannot assume that @error is still valid after calling this.
34711 * Call g_error_copy() on the error if you need to keep a local copy
34714 * See also g_task_return_new_error().
34721 * g_task_return_error_if_cancelled:
34724 * Checks if @task's #GCancellable has been cancelled, and if so, sets
34725 * @task's error accordingly and completes the task (see
34726 * g_task_return_pointer() for more discussion of exactly what this
34729 * Returns: %TRUE if @task has been cancelled, %FALSE if not
34735 * g_task_return_int:
34737 * @result: the integer (#gssize) result of a task function.
34739 * Sets @task's result to @result and completes the task (see
34740 * g_task_return_pointer() for more discussion of exactly what this
34748 * g_task_return_new_error:
34750 * @domain: a #GQuark.
34751 * @code: an error code.
34752 * @format: a string with format characters.
34753 * @...: a list of values to insert into @format.
34755 * Sets @task's result to a new #GError created from @domain, @code,
34756 * @format, and the remaining arguments, and completes the task (see
34757 * g_task_return_pointer() for more discussion of exactly what this
34760 * See also g_task_return_error().
34767 * g_task_return_pointer:
34769 * @result: (allow-none) (transfer full): the pointer result of a task
34771 * @result_destroy: (allow-none): a #GDestroyNotify function.
34773 * Sets @task's result to @result and completes the task. If @result
34774 * is not %NULL, then @result_destroy will be used to free @result if
34775 * the caller does not take ownership of it with
34776 * g_task_propagate_pointer().
34778 * "Completes the task" means that for an ordinary asynchronous task
34779 * it will either invoke the task's callback, or else queue that
34780 * callback to be invoked in the proper #GMainContext, or in the next
34781 * iteration of the current #GMainContext. For a task run via
34782 * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this
34783 * method will save @result to be returned to the caller later, but
34784 * the task will not actually be completed until the #GTaskThreadFunc
34787 * Note that since the task may be completed before returning from
34788 * g_task_return_pointer(), you cannot assume that @result is still
34789 * valid after calling this, unless you are still holding another
34797 * g_task_run_in_thread:
34799 * @task_func: a #GTaskThreadFunc
34801 * Runs @task_func in another thread. When @task_func returns, @task's
34802 * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
34804 * This takes a ref on @task until the task completes.
34806 * See #GTaskThreadFunc for more details about how @task_func is handled.
34813 * g_task_run_in_thread_sync:
34815 * @task_func: a #GTaskThreadFunc
34817 * Runs @task_func in another thread, and waits for it to return or be
34818 * cancelled. You can use g_task_propagate_pointer(), etc, afterward
34819 * to get the result of @task_func.
34821 * See #GTaskThreadFunc for more details about how @task_func is handled.
34823 * Normally this is used with tasks created with a %NULL
34824 * <literal>callback</literal>, but note that even if the task does
34825 * have a callback, it will not be invoked when @task_func returns.
34832 * g_task_set_check_cancellable:
34833 * @task: the #GTask
34834 * @check_cancellable: whether #GTask will check the state of
34835 * its #GCancellable for you.
34837 * Sets or clears @task's check-cancellable flag. If this is %TRUE
34838 * (the default), then g_task_propagate_pointer(), etc, and
34839 * g_task_had_error() will check the task's #GCancellable first, and
34840 * if it has been cancelled, then they will consider the task to have
34841 * returned an "Operation was cancelled" error
34842 * (%G_IO_ERROR_CANCELLED), regardless of any other error or return
34843 * value the task may have had.
34845 * If @check_cancellable is %FALSE, then the #GTask will not check the
34846 * cancellable itself, and it is up to @task's owner to do this (eg,
34847 * via g_task_return_error_if_cancelled()).
34849 * If you are using g_task_set_return_on_cancel() as well, then
34850 * you must leave check-cancellable set %TRUE.
34857 * g_task_set_priority:
34858 * @task: the #GTask
34859 * @priority: the <link linkend="io-priority">priority</link>
34862 * Sets @task's priority. If you do not call this, it will default to
34863 * %G_PRIORITY_DEFAULT.
34865 * This will affect the priority of #GSources created with
34866 * g_task_attach_source() and the scheduling of tasks run in threads,
34867 * and can also be explicitly retrieved later via
34868 * g_task_get_priority().
34875 * g_task_set_return_on_cancel:
34876 * @task: the #GTask
34877 * @return_on_cancel: whether the task returns automatically when
34880 * Sets or clears @task's return-on-cancel flag. This is only
34881 * meaningful for tasks run via g_task_run_in_thread() or
34882 * g_task_run_in_thread_sync().
34884 * If @return_on_cancel is %TRUE, then cancelling @task's
34885 * #GCancellable will immediately cause it to return, as though the
34886 * task's #GTaskThreadFunc had called
34887 * g_task_return_error_if_cancelled() and then returned.
34889 * This allows you to create a cancellable wrapper around an
34890 * uninterruptable function. The #GTaskThreadFunc just needs to be
34891 * careful that it does not modify any externally-visible state after
34892 * it has been cancelled. To do that, the thread should call
34893 * g_task_set_return_on_cancel() again to (atomically) set
34894 * return-on-cancel %FALSE before making externally-visible changes;
34895 * if the task gets cancelled before the return-on-cancel flag could
34896 * be changed, g_task_set_return_on_cancel() will indicate this by
34897 * returning %FALSE.
34899 * You can disable and re-enable this flag multiple times if you wish.
34900 * If the task's #GCancellable is cancelled while return-on-cancel is
34901 * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
34902 * again will cause the task to be cancelled at that point.
34904 * If the task's #GCancellable is already cancelled before you call
34905 * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
34906 * #GTaskThreadFunc will still be run (for consistency), but the task
34907 * will also be completed right away.
34909 * Returns: %TRUE if @task's return-on-cancel flag was changed to
34910 * match @return_on_cancel. %FALSE if @task has already been
34917 * g_task_set_source_tag:
34918 * @task: the #GTask
34919 * @source_tag: an opaque pointer indicating the source of this task
34921 * Sets @task's source tag. You can use this to tag a task return
34922 * value with a particular pointer (usually a pointer to the function
34923 * doing the tagging) and then later check it using
34924 * g_task_get_source_tag() (or g_async_result_is_tagged()) in the
34925 * task's "finish" function, to figure out if the response came from a
34926 * particular place.
34933 * g_task_set_task_data:
34934 * @task: the #GTask
34935 * @task_data: (allow-none): task-specific data
34936 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
34938 * Sets @task's task data (freeing the existing task data, if any).
34945 * g_tcp_connection_get_graceful_disconnect:
34946 * @connection: a #GTcpConnection
34948 * Checks if graceful disconnects are used. See
34949 * g_tcp_connection_set_graceful_disconnect().
34951 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
34957 * g_tcp_connection_set_graceful_disconnect:
34958 * @connection: a #GTcpConnection
34959 * @graceful_disconnect: Whether to do graceful disconnects or not
34961 * This enabled graceful disconnects on close. A graceful disconnect
34962 * means that we signal the receiving end that the connection is terminated
34963 * and wait for it to close the connection before closing the connection.
34965 * A graceful disconnect means that we can be sure that we successfully sent
34966 * all the outstanding data to the other end, or get an error reported.
34967 * However, it also means we have to wait for all the data to reach the
34968 * other side and for it to acknowledge this by closing the socket, which may
34969 * take a while. For this reason it is disabled by default.
34976 * g_tcp_wrapper_connection_get_base_io_stream:
34977 * @conn: a #GTcpWrapperConnection
34979 * Get's @conn's base #GIOStream
34981 * Returns: (transfer none): @conn's base #GIOStream
34986 * g_tcp_wrapper_connection_new:
34987 * @base_io_stream: the #GIOStream to wrap
34988 * @socket: the #GSocket associated with @base_io_stream
34990 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
34992 * Returns: the new #GSocketConnection.
34998 * g_test_dbus_add_service_dir:
34999 * @self: a #GTestDBus
35000 * @path: path to a directory containing .service files
35002 * Add a path where dbus-daemon will lookup for .services files. This can't be
35003 * called after g_test_dbus_up().
35008 * g_test_dbus_down:
35009 * @self: a #GTestDBus
35011 * Stop the session bus started by g_test_dbus_up().
35013 * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
35014 * is destroyed. This is done to ensure that the next unit test won't get a
35015 * leaked singleton from this test.
35020 * g_test_dbus_get_bus_address:
35021 * @self: a #GTestDBus
35023 * Get the address on which dbus-daemon is running. if g_test_dbus_up() has not
35024 * been called yet, %NULL is returned. This can be used with
35025 * g_dbus_connection_new_for_address()
35027 * Returns: the address of the bus, or %NULL.
35032 * g_test_dbus_get_flags:
35033 * @self: a #GTestDBus
35035 * Gets the flags of the #GTestDBus object.
35037 * Returns: the value of #GTestDBus:flags property
35043 * @flags: a #GTestDBusFlags
35045 * Create a new #GTestDBus object.
35047 * Returns: (transfer full): a new #GTestDBus.
35052 * g_test_dbus_stop:
35053 * @self: a #GTestDBus
35055 * Stop the session bus started by g_test_dbus_up().
35057 * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
35058 * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
35059 * tests wanting to verify behaviour after the session bus has been stopped
35060 * can use this function but should still call g_test_dbus_down() when done.
35065 * g_test_dbus_unset:
35067 * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
35068 * won't use user's session bus.
35070 * This is useful for unit tests that want to verify behaviour when no session
35071 * bus is running. It is not necessary to call this if unit test already calls
35072 * g_test_dbus_up() before acquiring the session bus.
35078 * @self: a #GTestDBus
35080 * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
35081 * call, it is safe for unit tests to start sending messages on the session bus.
35083 * If this function is called from setup callback of g_test_add(),
35084 * g_test_dbus_down() must be called in its teardown callback.
35086 * If this function is called from unit test's main(), then g_test_dbus_down()
35087 * must be called after g_test_run().
35092 * g_themed_icon_append_name:
35093 * @icon: a #GThemedIcon
35094 * @iconname: name of icon to append to list of icons from within @icon.
35096 * Append a name to the list of icons from within @icon.
35099 * Note that doing so invalidates the hash computed by prior calls
35100 * to g_icon_hash().
35106 * g_themed_icon_get_names:
35107 * @icon: a #GThemedIcon.
35109 * Gets the names of icons from within @icon.
35111 * Returns: (transfer none): a list of icon names.
35116 * g_themed_icon_new:
35117 * @iconname: a string containing an icon name.
35119 * Creates a new themed icon for @iconname.
35121 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
35126 * g_themed_icon_new_from_names:
35127 * @iconnames: (array length=len): an array of strings containing icon names.
35128 * @len: the length of the @iconnames array, or -1 if @iconnames is
35131 * Creates a new themed icon for @iconnames.
35133 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
35138 * g_themed_icon_new_with_default_fallbacks:
35139 * @iconname: a string containing an icon name
35141 * Creates a new themed icon for @iconname, and all the names
35142 * that can be created by shortening @iconname at '-' characters.
35144 * In the following example, @icon1 and @icon2 are equivalent:
35146 * const char *names[] = {
35147 * "gnome-dev-cdrom-audio",
35148 * "gnome-dev-cdrom",
35153 * icon1 = g_themed_icon_new_from_names (names, 4);
35154 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
35157 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
35162 * g_themed_icon_prepend_name:
35163 * @icon: a #GThemedIcon
35164 * @iconname: name of icon to prepend to list of icons from within @icon.
35166 * Prepend a name to the list of icons from within @icon.
35169 * Note that doing so invalidates the hash computed by prior calls
35170 * to g_icon_hash().
35178 * g_threaded_socket_service_new:
35179 * @max_threads: the maximal number of threads to execute concurrently
35180 * handling incoming clients, -1 means no limit
35182 * Creates a new #GThreadedSocketService with no listeners. Listeners
35183 * must be added with one of the #GSocketListener "add" methods.
35185 * Returns: a new #GSocketService.
35191 * g_tls_backend_get_certificate_type:
35192 * @backend: the #GTlsBackend
35194 * Gets the #GType of @backend's #GTlsCertificate implementation.
35196 * Returns: the #GType of @backend's #GTlsCertificate
35203 * g_tls_backend_get_client_connection_type:
35204 * @backend: the #GTlsBackend
35206 * Gets the #GType of @backend's #GTlsClientConnection implementation.
35208 * Returns: the #GType of @backend's #GTlsClientConnection
35215 * g_tls_backend_get_default:
35217 * Gets the default #GTlsBackend for the system.
35219 * Returns: (transfer none): a #GTlsBackend
35225 * g_tls_backend_get_default_database:
35226 * @backend: the #GTlsBackend
35228 * Gets the default #GTlsDatabase used to verify TLS connections.
35230 * Returns: (transfer full): the default database, which should be
35231 * unreffed when done.
35237 * g_tls_backend_get_file_database_type:
35238 * @backend: the #GTlsBackend
35240 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
35242 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
35248 * g_tls_backend_get_server_connection_type:
35249 * @backend: the #GTlsBackend
35251 * Gets the #GType of @backend's #GTlsServerConnection implementation.
35253 * Returns: the #GType of @backend's #GTlsServerConnection
35260 * g_tls_backend_supports_tls:
35261 * @backend: the #GTlsBackend
35263 * Checks if TLS is supported; if this returns %FALSE for the default
35264 * #GTlsBackend, it means no "real" TLS backend is available.
35266 * Returns: whether or not TLS is supported
35272 * g_tls_certificate_get_issuer:
35273 * @cert: a #GTlsCertificate
35275 * Gets the #GTlsCertificate representing @cert's issuer, if known
35277 * Returns: (transfer none): The certificate of @cert's issuer,
35278 * or %NULL if @cert is self-signed or signed with an unknown
35285 * g_tls_certificate_is_same:
35286 * @cert_one: first certificate to compare
35287 * @cert_two: second certificate to compare
35289 * Check if two #GTlsCertificate objects represent the same certificate.
35290 * The raw DER byte data of the two certificates are checked for equality.
35291 * This has the effect that two certificates may compare equal even if
35292 * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
35293 * #GTlsCertificate:private-key-pem properties differ.
35295 * Returns: whether the same or not
35301 * g_tls_certificate_list_new_from_file:
35302 * @file: file containing PEM-encoded certificates to import
35303 * @error: #GError for error reporting, or %NULL to ignore.
35305 * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
35306 * data in @file. If @file cannot be read or parsed, the function will
35307 * return %NULL and set @error. If @file does not contain any
35308 * PEM-encoded certificates, this will return an empty list and not
35311 * Returns: (element-type Gio.TlsCertificate) (transfer full): a
35312 * #GList containing #GTlsCertificate objects. You must free the list
35313 * and its contents when you are done with it.
35319 * g_tls_certificate_new_from_file:
35320 * @file: file containing a PEM-encoded certificate to import
35321 * @error: #GError for error reporting, or %NULL to ignore.
35323 * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
35324 * @file cannot be read or parsed, the function will return %NULL and
35325 * set @error. Otherwise, this behaves like
35326 * g_tls_certificate_new_from_pem().
35328 * Returns: the new certificate, or %NULL on error
35334 * g_tls_certificate_new_from_files:
35335 * @cert_file: file containing a PEM-encoded certificate to import
35336 * @key_file: file containing a PEM-encoded private key to import
35337 * @error: #GError for error reporting, or %NULL to ignore.
35339 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
35340 * and @key_file. If either file cannot be read or parsed, the
35341 * function will return %NULL and set @error. Otherwise, this behaves
35342 * like g_tls_certificate_new_from_pem().
35344 * Returns: the new certificate, or %NULL on error
35350 * g_tls_certificate_new_from_pem:
35351 * @data: PEM-encoded certificate data
35352 * @length: the length of @data, or -1 if it's 0-terminated.
35353 * @error: #GError for error reporting, or %NULL to ignore.
35355 * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
35356 * If @data includes both a certificate and a private key, then the
35357 * returned certificate will include the private key data as well. (See
35358 * the #GTlsCertificate:private-key-pem property for information about
35359 * supported formats.)
35361 * If @data includes multiple certificates, only the first one will be
35364 * Returns: the new certificate, or %NULL if @data is invalid
35370 * g_tls_certificate_verify:
35371 * @cert: a #GTlsCertificate
35372 * @identity: (allow-none): the expected peer identity
35373 * @trusted_ca: (allow-none): the certificate of a trusted authority
35375 * This verifies @cert and returns a set of #GTlsCertificateFlags
35376 * indicating any problems found with it. This can be used to verify a
35377 * certificate outside the context of making a connection, or to
35378 * check a certificate against a CA that is not part of the system
35381 * If @identity is not %NULL, @cert's name(s) will be compared against
35382 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
35383 * value if it does not match. If @identity is %NULL, that bit will
35384 * never be set in the return value.
35386 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
35387 * in its chain) must be signed by it, or else
35388 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
35389 * @trusted_ca is %NULL, that bit will never be set in the return
35392 * (All other #GTlsCertificateFlags values will always be set or unset
35395 * Returns: the appropriate #GTlsCertificateFlags
35401 * g_tls_client_connection_get_accepted_cas:
35402 * @conn: the #GTlsClientConnection
35404 * Gets the list of distinguished names of the Certificate Authorities
35405 * that the server will accept certificates from. This will be set
35406 * during the TLS handshake if the server requests a certificate.
35407 * Otherwise, it will be %NULL.
35409 * Each item in the list is a #GByteArray which contains the complete
35410 * subject DN of the certificate authority.
35412 * Returns: (element-type GByteArray) (transfer full): the list of
35413 * CA DNs. You should unref each element with g_byte_array_unref() and then
35414 * the free the list with g_list_free().
35420 * g_tls_client_connection_get_server_identity:
35421 * @conn: the #GTlsClientConnection
35423 * Gets @conn's expected server identity
35425 * Returns: (transfer none): a #GSocketConnectable describing the
35426 * expected server identity, or %NULL if the expected identity is not
35433 * g_tls_client_connection_get_use_ssl3:
35434 * @conn: the #GTlsClientConnection
35436 * Gets whether @conn will use SSL 3.0 rather than the
35437 * highest-supported version of TLS; see
35438 * g_tls_client_connection_set_use_ssl3().
35440 * Returns: whether @conn will use SSL 3.0
35446 * g_tls_client_connection_get_validation_flags:
35447 * @conn: the #GTlsClientConnection
35449 * Gets @conn's validation flags
35451 * Returns: the validation flags
35457 * g_tls_client_connection_new:
35458 * @base_io_stream: the #GIOStream to wrap
35459 * @server_identity: (allow-none): the expected identity of the server
35460 * @error: #GError for error reporting, or %NULL to ignore.
35462 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
35463 * must have pollable input and output streams) which is assumed to
35464 * communicate with the server identified by @server_identity.
35466 * Returns: (transfer full) (type GTlsClientConnection): the new
35467 * #GTlsClientConnection, or %NULL on error
35473 * g_tls_client_connection_set_server_identity:
35474 * @conn: the #GTlsClientConnection
35475 * @identity: a #GSocketConnectable describing the expected server identity
35477 * Sets @conn's expected server identity, which is used both to tell
35478 * servers on virtual hosts which certificate to present, and also
35479 * to let @conn know what name to look for in the certificate when
35480 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
35487 * g_tls_client_connection_set_use_ssl3:
35488 * @conn: the #GTlsClientConnection
35489 * @use_ssl3: whether to use SSL 3.0
35491 * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
35492 * trying to properly negotiate the right version of TLS or SSL to use.
35493 * This can be used when talking to servers that do not implement the
35494 * fallbacks correctly and which will therefore fail to handshake with
35495 * a "modern" TLS handshake attempt.
35502 * g_tls_client_connection_set_validation_flags:
35503 * @conn: the #GTlsClientConnection
35504 * @flags: the #GTlsCertificateFlags to use
35506 * Sets @conn's validation flags, to override the default set of
35507 * checks performed when validating a server certificate. By default,
35508 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
35515 * g_tls_connection_emit_accept_certificate:
35516 * @conn: a #GTlsConnection
35517 * @peer_cert: the peer's #GTlsCertificate
35518 * @errors: the problems with @peer_cert
35520 * Used by #GTlsConnection implementations to emit the
35521 * #GTlsConnection::accept-certificate signal.
35523 * Returns: %TRUE if one of the signal handlers has returned
35524 * %TRUE to accept @peer_cert
35530 * g_tls_connection_get_certificate:
35531 * @conn: a #GTlsConnection
35533 * Gets @conn's certificate, as set by
35534 * g_tls_connection_set_certificate().
35536 * Returns: (transfer none): @conn's certificate, or %NULL
35542 * g_tls_connection_get_database:
35543 * @conn: a #GTlsConnection
35545 * Gets the certificate database that @conn uses to verify
35546 * peer certificates. See g_tls_connection_set_database().
35548 * Returns: (transfer none): the certificate database that @conn uses or %NULL
35554 * g_tls_connection_get_interaction:
35555 * @conn: a connection
35557 * Get the object that will be used to interact with the user. It will be used
35558 * for things like prompting the user for passwords. If %NULL is returned, then
35559 * no user interaction will occur for this connection.
35561 * Returns: (transfer none): The interaction object.
35567 * g_tls_connection_get_peer_certificate:
35568 * @conn: a #GTlsConnection
35570 * Gets @conn's peer's certificate after the handshake has completed.
35571 * (It is not set during the emission of
35572 * #GTlsConnection::accept-certificate.)
35574 * Returns: (transfer none): @conn's peer's certificate, or %NULL
35580 * g_tls_connection_get_peer_certificate_errors:
35581 * @conn: a #GTlsConnection
35583 * Gets the errors associated with validating @conn's peer's
35584 * certificate, after the handshake has completed. (It is not set
35585 * during the emission of #GTlsConnection::accept-certificate.)
35587 * Returns: @conn's peer's certificate errors
35593 * g_tls_connection_get_rehandshake_mode:
35594 * @conn: a #GTlsConnection
35596 * Gets @conn rehandshaking mode. See
35597 * g_tls_connection_set_rehandshake_mode() for details.
35599 * Returns: @conn's rehandshaking mode
35605 * g_tls_connection_get_require_close_notify:
35606 * @conn: a #GTlsConnection
35608 * Tests whether or not @conn expects a proper TLS close notification
35609 * when the connection is closed. See
35610 * g_tls_connection_set_require_close_notify() for details.
35612 * Returns: %TRUE if @conn requires a proper TLS close
35619 * g_tls_connection_get_use_system_certdb:
35620 * @conn: a #GTlsConnection
35622 * Gets whether @conn uses the system certificate database to verify
35623 * peer certificates. See g_tls_connection_set_use_system_certdb().
35625 * Returns: whether @conn uses the system certificate database
35626 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
35631 * g_tls_connection_handshake:
35632 * @conn: a #GTlsConnection
35633 * @cancellable: (allow-none): a #GCancellable, or %NULL
35634 * @error: a #GError, or %NULL
35636 * Attempts a TLS handshake on @conn.
35638 * On the client side, it is never necessary to call this method;
35639 * although the connection needs to perform a handshake after
35640 * connecting (or after sending a "STARTTLS"-type command) and may
35641 * need to rehandshake later if the server requests it,
35642 * #GTlsConnection will handle this for you automatically when you try
35643 * to send or receive data on the connection. However, you can call
35644 * g_tls_connection_handshake() manually if you want to know for sure
35645 * whether the initial handshake succeeded or failed (as opposed to
35646 * just immediately trying to write to @conn's output stream, in which
35647 * case if it fails, it may not be possible to tell if it failed
35648 * before or after completing the handshake).
35650 * Likewise, on the server side, although a handshake is necessary at
35651 * the beginning of the communication, you do not need to call this
35652 * function explicitly unless you want clearer error reporting.
35653 * However, you may call g_tls_connection_handshake() later on to
35654 * renegotiate parameters (encryption methods, etc) with the client.
35656 * #GTlsConnection::accept_certificate may be emitted during the
35659 * Returns: success or failure
35665 * g_tls_connection_handshake_async:
35666 * @conn: a #GTlsConnection
35667 * @io_priority: the <link linkend="io-priority">I/O priority</link>
35669 * @cancellable: (allow-none): a #GCancellable, or %NULL
35670 * @callback: callback to call when the handshake is complete
35671 * @user_data: the data to pass to the callback function
35673 * Asynchronously performs a TLS handshake on @conn. See
35674 * g_tls_connection_handshake() for more information.
35681 * g_tls_connection_handshake_finish:
35682 * @conn: a #GTlsConnection
35683 * @result: a #GAsyncResult.
35684 * @error: a #GError pointer, or %NULL
35686 * Finish an asynchronous TLS handshake operation. See
35687 * g_tls_connection_handshake() for more information.
35689 * Returns: %TRUE on success, %FALSE on failure, in which
35690 * case @error will be set.
35696 * g_tls_connection_set_certificate:
35697 * @conn: a #GTlsConnection
35698 * @certificate: the certificate to use for @conn
35700 * This sets the certificate that @conn will present to its peer
35701 * during the TLS handshake. For a #GTlsServerConnection, it is
35702 * mandatory to set this, and that will normally be done at construct
35705 * For a #GTlsClientConnection, this is optional. If a handshake fails
35706 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
35707 * requires a certificate, and if you try connecting again, you should
35708 * call this method first. You can call
35709 * g_tls_client_connection_get_accepted_cas() on the failed connection
35710 * to get a list of Certificate Authorities that the server will
35711 * accept certificates from.
35713 * (It is also possible that a server will allow the connection with
35714 * or without a certificate; in that case, if you don't provide a
35715 * certificate, you can tell that the server requested one by the fact
35716 * that g_tls_client_connection_get_accepted_cas() will return
35724 * g_tls_connection_set_database:
35725 * @conn: a #GTlsConnection
35726 * @database: a #GTlsDatabase
35728 * Sets the certificate database that is used to verify peer certificates.
35729 * This is set to the default database by default. See
35730 * g_tls_backend_get_default_database(). If set to %NULL, then
35731 * peer certificate validation will always set the
35732 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
35733 * #GTlsConnection::accept-certificate will always be emitted on
35734 * client-side connections, unless that bit is not set in
35735 * #GTlsClientConnection:validation-flags).
35742 * g_tls_connection_set_interaction:
35743 * @conn: a connection
35744 * @interaction: (allow-none): an interaction object, or %NULL
35746 * Set the object that will be used to interact with the user. It will be used
35747 * for things like prompting the user for passwords.
35749 * The @interaction argument will normally be a derived subclass of
35750 * #GTlsInteraction. %NULL can also be provided if no user interaction
35751 * should occur for this connection.
35758 * g_tls_connection_set_rehandshake_mode:
35759 * @conn: a #GTlsConnection
35760 * @mode: the rehandshaking mode
35762 * Sets how @conn behaves with respect to rehandshaking requests.
35764 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
35765 * rehandshake after the initial handshake is complete. (For a client,
35766 * this means it will refuse rehandshake requests from the server, and
35767 * for a server, this means it will close the connection with an error
35768 * if the client attempts to rehandshake.)
35770 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
35771 * rehandshake only if the other end of the connection supports the
35772 * TLS <literal>renegotiation_info</literal> extension. This is the
35773 * default behavior, but means that rehandshaking will not work
35774 * against older implementations that do not support that extension.
35776 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
35777 * rehandshaking even without the
35778 * <literal>renegotiation_info</literal> extension. On the server side
35779 * in particular, this is not recommended, since it leaves the server
35780 * open to certain attacks. However, this mode is necessary if you
35781 * need to allow renegotiation with older client software.
35788 * g_tls_connection_set_require_close_notify:
35789 * @conn: a #GTlsConnection
35790 * @require_close_notify: whether or not to require close notification
35792 * Sets whether or not @conn expects a proper TLS close notification
35793 * before the connection is closed. If this is %TRUE (the default),
35794 * then @conn will expect to receive a TLS close notification from its
35795 * peer before the connection is closed, and will return a
35796 * %G_TLS_ERROR_EOF error if the connection is closed without proper
35797 * notification (since this may indicate a network error, or
35798 * man-in-the-middle attack).
35800 * In some protocols, the application will know whether or not the
35801 * connection was closed cleanly based on application-level data
35802 * (because the application-level data includes a length field, or is
35803 * somehow self-delimiting); in this case, the close notify is
35804 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
35805 * in TLS 1.0 it is technically an error, but often done anyway.) You
35806 * can use g_tls_connection_set_require_close_notify() to tell @conn
35807 * to allow an "unannounced" connection close, in which case the close
35808 * will show up as a 0-length read, as in a non-TLS
35809 * #GSocketConnection, and it is up to the application to check that
35810 * the data has been fully received.
35812 * Note that this only affects the behavior when the peer closes the
35813 * connection; when the application calls g_io_stream_close() itself
35814 * on @conn, this will send a close notification regardless of the
35815 * setting of this property. If you explicitly want to do an unclean
35816 * close, you can close @conn's #GTlsConnection:base-io-stream rather
35817 * than closing @conn itself.
35824 * g_tls_connection_set_use_system_certdb:
35825 * @conn: a #GTlsConnection
35826 * @use_system_certdb: whether to use the system certificate database
35828 * Sets whether @conn uses the system certificate database to verify
35829 * peer certificates. This is %TRUE by default. If set to %FALSE, then
35830 * peer certificate validation will always set the
35831 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
35832 * #GTlsConnection::accept-certificate will always be emitted on
35833 * client-side connections, unless that bit is not set in
35834 * #GTlsClientConnection:validation-flags).
35836 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
35841 * g_tls_database_create_certificate_handle:
35842 * @self: a #GTlsDatabase
35843 * @certificate: certificate for which to create a handle.
35845 * Create a handle string for the certificate. The database will only be able
35846 * to create a handle for certificates that originate from the database. In
35847 * cases where the database cannot create a handle for a certificate, %NULL
35848 * will be returned.
35850 * This handle should be stable across various instances of the application,
35851 * and between applications. If a certificate is modified in the database,
35852 * then it is not guaranteed that this handle will continue to point to it.
35854 * Returns: (allow-none): a newly allocated string containing the handle.
35860 * g_tls_database_lookup_certificate_for_handle:
35861 * @self: a #GTlsDatabase
35862 * @handle: a certificate handle
35863 * @interaction: (allow-none): used to interact with the user if necessary
35864 * @flags: Flags which affect the lookup.
35865 * @cancellable: (allow-none): a #GCancellable, or %NULL
35866 * @error: (allow-none): a #GError, or %NULL
35868 * Lookup a certificate by its handle.
35870 * The handle should have been created by calling
35871 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
35872 * the same TLS backend. The handle is designed to remain valid across
35873 * instantiations of the database.
35875 * If the handle is no longer valid, or does not point to a certificate in
35876 * this database, then %NULL will be returned.
35878 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
35879 * the lookup operation asynchronously.
35881 * Returns: (transfer full) (allow-none): a newly allocated
35882 * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
35888 * g_tls_database_lookup_certificate_for_handle_async:
35889 * @self: a #GTlsDatabase
35890 * @handle: a certificate handle
35891 * @interaction: (allow-none): used to interact with the user if necessary
35892 * @flags: Flags which affect the lookup.
35893 * @cancellable: (allow-none): a #GCancellable, or %NULL
35894 * @callback: callback to call when the operation completes
35895 * @user_data: the data to pass to the callback function
35897 * Asynchronously lookup a certificate by its handle in the database. See
35898 * g_tls_database_lookup_certificate_for_handle() for more information.
35905 * g_tls_database_lookup_certificate_for_handle_finish:
35906 * @self: a #GTlsDatabase
35907 * @result: a #GAsyncResult.
35908 * @error: a #GError pointer, or %NULL
35910 * Finish an asynchronous lookup of a certificate by its handle. See
35911 * g_tls_database_lookup_certificate_handle() for more information.
35913 * If the handle is no longer valid, or does not point to a certificate in
35914 * this database, then %NULL will be returned.
35916 * Returns: (transfer full): a newly allocated #GTlsCertificate object.
35917 * Use g_object_unref() to release the certificate.
35923 * g_tls_database_lookup_certificate_issuer:
35924 * @self: a #GTlsDatabase
35925 * @certificate: a #GTlsCertificate
35926 * @interaction: (allow-none): used to interact with the user if necessary
35927 * @flags: flags which affect the lookup operation
35928 * @cancellable: (allow-none): a #GCancellable, or %NULL
35929 * @error: (allow-none): a #GError, or %NULL
35931 * Lookup the issuer of @certificate in the database.
35933 * The %issuer property
35934 * of @certificate is not modified, and the two certificates are not hooked
35937 * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
35938 * the lookup operation asynchronously.
35940 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
35941 * or %NULL. Use g_object_unref() to release the certificate.
35947 * g_tls_database_lookup_certificate_issuer_async:
35948 * @self: a #GTlsDatabase
35949 * @certificate: a #GTlsCertificate
35950 * @interaction: (allow-none): used to interact with the user if necessary
35951 * @flags: flags which affect the lookup operation
35952 * @cancellable: (allow-none): a #GCancellable, or %NULL
35953 * @callback: callback to call when the operation completes
35954 * @user_data: the data to pass to the callback function
35956 * Asynchronously lookup the issuer of @certificate in the database. See
35957 * g_tls_database_lookup_certificate_issuer() for more information.
35964 * g_tls_database_lookup_certificate_issuer_finish:
35965 * @self: a #GTlsDatabase
35966 * @result: a #GAsyncResult.
35967 * @error: a #GError pointer, or %NULL
35969 * Finish an asynchronous lookup issuer operation. See
35970 * g_tls_database_lookup_certificate_issuer() for more information.
35972 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
35973 * or %NULL. Use g_object_unref() to release the certificate.
35979 * g_tls_database_lookup_certificates_issued_by:
35980 * @self: a #GTlsDatabase
35981 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
35982 * @interaction: (allow-none): used to interact with the user if necessary
35983 * @flags: Flags which affect the lookup operation.
35984 * @cancellable: (allow-none): a #GCancellable, or %NULL
35985 * @error: (allow-none): a #GError, or %NULL
35987 * Lookup certificates issued by this issuer in the database.
35989 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
35990 * the lookup operation asynchronously.
35992 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
35993 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
35999 * g_tls_database_lookup_certificates_issued_by_async:
36000 * @self: a #GTlsDatabase
36001 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
36002 * @interaction: (allow-none): used to interact with the user if necessary
36003 * @flags: Flags which affect the lookup operation.
36004 * @cancellable: (allow-none): a #GCancellable, or %NULL
36005 * @callback: callback to call when the operation completes
36006 * @user_data: the data to pass to the callback function
36008 * Asynchronously lookup certificates issued by this issuer in the database. See
36009 * g_tls_database_lookup_certificates_issued_by() for more information.
36011 * The database may choose to hold a reference to the issuer byte array for the duration
36012 * of of this asynchronous operation. The byte array should not be modified during
36020 * g_tls_database_lookup_certificates_issued_by_finish:
36021 * @self: a #GTlsDatabase
36022 * @result: a #GAsyncResult.
36023 * @error: a #GError pointer, or %NULL
36025 * Finish an asynchronous lookup of certificates. See
36026 * g_tls_database_lookup_certificates_issued_by() for more information.
36028 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
36029 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
36035 * g_tls_database_verify_chain:
36036 * @self: a #GTlsDatabase
36037 * @chain: a #GTlsCertificate chain
36038 * @purpose: the purpose that this certificate chain will be used for.
36039 * @identity: (allow-none): the expected peer identity
36040 * @interaction: (allow-none): used to interact with the user if necessary
36041 * @flags: additional verify flags
36042 * @cancellable: (allow-none): a #GCancellable, or %NULL
36043 * @error: (allow-none): a #GError, or %NULL
36045 * Verify's a certificate chain after looking up and adding any missing
36046 * certificates to the chain.
36048 * @chain is a chain of #GTlsCertificate objects each pointing to the next
36049 * certificate in the chain by its %issuer property. The chain may initially
36050 * consist of one or more certificates. After the verification process is
36051 * complete, @chain may be modified by adding missing certificates, or removing
36052 * extra certificates. If a certificate anchor was found, then it is added to
36055 * @purpose describes the purpose (or usage) for which the certificate
36056 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
36057 * which means that the certificate is being used to authenticate a server
36058 * (and we are acting as the client).
36060 * The @identity is used to check for pinned certificates (trust exceptions)
36061 * in the database. These will override the normal verification process on a
36062 * host by host basis.
36064 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
36067 * This function can block, use g_tls_database_verify_chain_async() to perform
36068 * the verification operation asynchronously.
36070 * Returns: the appropriate #GTlsCertificateFlags which represents the
36071 * result of verification.
36077 * g_tls_database_verify_chain_async:
36078 * @self: a #GTlsDatabase
36079 * @chain: a #GTlsCertificate chain
36080 * @purpose: the purpose that this certificate chain will be used for.
36081 * @identity: (allow-none): the expected peer identity
36082 * @interaction: (allow-none): used to interact with the user if necessary
36083 * @flags: additional verify flags
36084 * @cancellable: (allow-none): a #GCancellable, or %NULL
36085 * @callback: callback to call when the operation completes
36086 * @user_data: the data to pass to the callback function
36088 * Asynchronously verify's a certificate chain after looking up and adding
36089 * any missing certificates to the chain. See g_tls_database_verify_chain()
36090 * for more information.
36097 * g_tls_database_verify_chain_finish:
36098 * @self: a #GTlsDatabase
36099 * @result: a #GAsyncResult.
36100 * @error: a #GError pointer, or %NULL
36102 * Finish an asynchronous verify chain operation. See
36103 * g_tls_database_verify_chain() for more information. *
36105 * Returns: the appropriate #GTlsCertificateFlags which represents the
36106 * result of verification.
36112 * g_tls_error_quark:
36114 * Gets the TLS error quark.
36116 * Returns: a #GQuark.
36122 * g_tls_file_database_new:
36123 * @anchors: filename of anchor certificate authorities.
36124 * @error: #GError for error reporting, or %NULL to ignore.
36126 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
36127 * in @anchors to verify certificate chains.
36129 * The certificates in @anchors must be PEM encoded.
36131 * Returns: (transfer full) (type GTlsFileDatabase): the new
36132 * #GTlsFileDatabase, or %NULL on error
36138 * g_tls_interaction_ask_password:
36139 * @interaction: a #GTlsInteraction object
36140 * @password: a #GTlsPassword object
36141 * @cancellable: an optional #GCancellable cancellation object
36142 * @error: an optional location to place an error on failure
36144 * Run synchronous interaction to ask the user for a password. In general,
36145 * g_tls_interaction_invoke_ask_password() should be used instead of this
36148 * Derived subclasses usually implement a password prompt, although they may
36149 * also choose to provide a password from elsewhere. The @password value will
36150 * be filled in and then @callback will be called. Alternatively the user may
36151 * abort this password request, which will usually abort the TLS connection.
36153 * If the interaction is cancelled by the cancellation object, or by the
36154 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36155 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36156 * not support immediate cancellation.
36158 * Returns: The status of the ask password interaction.
36164 * g_tls_interaction_ask_password_async:
36165 * @interaction: a #GTlsInteraction object
36166 * @password: a #GTlsPassword object
36167 * @cancellable: an optional #GCancellable cancellation object
36168 * @callback: (allow-none): will be called when the interaction completes
36169 * @user_data: (allow-none): data to pass to the @callback
36171 * Run asynchronous interaction to ask the user for a password. In general,
36172 * g_tls_interaction_invoke_ask_password() should be used instead of this
36175 * Derived subclasses usually implement a password prompt, although they may
36176 * also choose to provide a password from elsewhere. The @password value will
36177 * be filled in and then @callback will be called. Alternatively the user may
36178 * abort this password request, which will usually abort the TLS connection.
36180 * If the interaction is cancelled by the cancellation object, or by the
36181 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36182 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36183 * not support immediate cancellation.
36185 * Certain implementations may not support immediate cancellation.
36192 * g_tls_interaction_ask_password_finish:
36193 * @interaction: a #GTlsInteraction object
36194 * @result: the result passed to the callback
36195 * @error: an optional location to place an error on failure
36197 * Complete an ask password user interaction request. This should be once
36198 * the g_tls_interaction_ask_password_async() completion callback is called.
36200 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
36201 * to g_tls_interaction_ask_password() will have its password filled in.
36203 * If the interaction is cancelled by the cancellation object, or by the
36204 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36205 * contains a %G_IO_ERROR_CANCELLED error code.
36207 * Returns: The status of the ask password interaction.
36213 * g_tls_interaction_invoke_ask_password:
36214 * @interaction: a #GTlsInteraction object
36215 * @password: a #GTlsPassword object
36216 * @cancellable: an optional #GCancellable cancellation object
36217 * @error: an optional location to place an error on failure
36219 * Invoke the interaction to ask the user for a password. It invokes this
36220 * interaction in the main loop, specifically the #GMainContext returned by
36221 * g_main_context_get_thread_default() when the interaction is created. This
36222 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
36225 * Derived subclasses usually implement a password prompt, although they may
36226 * also choose to provide a password from elsewhere. The @password value will
36227 * be filled in and then @callback will be called. Alternatively the user may
36228 * abort this password request, which will usually abort the TLS connection.
36230 * The implementation can either be a synchronous (eg: modal dialog) or an
36231 * asynchronous one (eg: modeless dialog). This function will take care of
36232 * calling which ever one correctly.
36234 * If the interaction is cancelled by the cancellation object, or by the
36235 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36236 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36237 * not support immediate cancellation.
36239 * Returns: The status of the ask password interaction.
36245 * g_tls_interaction_invoke_request_certificate:
36246 * @interaction: a #GTlsInteraction object
36247 * @connection: a #GTlsConnection object
36248 * @flags: flags providing more information about the request
36249 * @cancellable: an optional #GCancellable cancellation object
36250 * @error: an optional location to place an error on failure
36252 * Invoke the interaction to ask the user to choose a certificate to
36253 * use with the connection. It invokes this interaction in the main
36254 * loop, specifically the #GMainContext returned by
36255 * g_main_context_get_thread_default() when the interaction is
36256 * created. This is called by called by #GTlsConnection when the peer
36257 * requests a certificate during the handshake.
36259 * Derived subclasses usually implement a certificate selector,
36260 * although they may also choose to provide a certificate from
36261 * elsewhere. Alternatively the user may abort this certificate
36262 * request, which may or may not abort the TLS connection.
36264 * The implementation can either be a synchronous (eg: modal dialog) or an
36265 * asynchronous one (eg: modeless dialog). This function will take care of
36266 * calling which ever one correctly.
36268 * If the interaction is cancelled by the cancellation object, or by the
36269 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36270 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36271 * not support immediate cancellation.
36273 * Returns: The status of the certificate request interaction.
36279 * g_tls_interaction_request_certificate:
36280 * @interaction: a #GTlsInteraction object
36281 * @connection: a #GTlsConnection object
36282 * @flags: flags providing more information about the request
36283 * @cancellable: an optional #GCancellable cancellation object
36284 * @error: an optional location to place an error on failure
36286 * Run synchronous interaction to ask the user to choose a certificate to use
36287 * with the connection. In general, g_tls_interaction_invoke_request_certificate()
36288 * should be used instead of this function.
36290 * Derived subclasses usually implement a certificate selector, although they may
36291 * also choose to provide a certificate from elsewhere. Alternatively the user may
36292 * abort this certificate request, which will usually abort the TLS connection.
36294 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
36295 * passed to g_tls_interaction_request_certificate() will have had its
36296 * #GTlsConnection:certificate filled in.
36298 * If the interaction is cancelled by the cancellation object, or by the
36299 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36300 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
36301 * not support immediate cancellation.
36303 * Returns: The status of the request certificate interaction.
36309 * g_tls_interaction_request_certificate_async:
36310 * @interaction: a #GTlsInteraction object
36311 * @connection: a #GTlsConnection object
36312 * @flags: flags providing more information about the request
36313 * @cancellable: an optional #GCancellable cancellation object
36314 * @callback: (allow-none): will be called when the interaction completes
36315 * @user_data: (allow-none): data to pass to the @callback
36317 * Run asynchronous interaction to ask the user for a certificate to use with
36318 * the connection. In general, g_tls_interaction_invoke_request_certificate() should
36319 * be used instead of this function.
36321 * Derived subclasses usually implement a certificate selector, although they may
36322 * also choose to provide a certificate from elsewhere. @callback will be called
36323 * when the operation completes. Alternatively the user may abort this certificate
36324 * request, which will usually abort the TLS connection.
36331 * g_tls_interaction_request_certificate_finish:
36332 * @interaction: a #GTlsInteraction object
36333 * @result: the result passed to the callback
36334 * @error: an optional location to place an error on failure
36336 * Complete an request certificate user interaction request. This should be once
36337 * the g_tls_interaction_request_certificate_async() completion callback is called.
36339 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection
36340 * passed to g_tls_interaction_request_certificate_async() will have had its
36341 * #GTlsConnection:certificate filled in.
36343 * If the interaction is cancelled by the cancellation object, or by the
36344 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
36345 * contains a %G_IO_ERROR_CANCELLED error code.
36347 * Returns: The status of the request certificate interaction.
36353 * g_tls_password_get_description:
36354 * @password: a #GTlsPassword object
36356 * Get a description string about what the password will be used for.
36358 * Returns: The description of the password.
36364 * g_tls_password_get_flags:
36365 * @password: a #GTlsPassword object
36367 * Get flags about the password.
36369 * Returns: The flags about the password.
36375 * g_tls_password_get_value:
36376 * @password: a #GTlsPassword object
36377 * @length: (allow-none): location to place the length of the password.
36379 * Get the password value. If @length is not %NULL then it will be
36380 * filled in with the length of the password value. (Note that the
36381 * password value is not nul-terminated, so you can only pass %NULL
36382 * for @length in contexts where you know the password will have a
36383 * certain fixed length.)
36385 * Returns: The password value (owned by the password object).
36391 * g_tls_password_get_warning:
36392 * @password: a #GTlsPassword object
36394 * Get a user readable translated warning. Usually this warning is a
36395 * representation of the password flags returned from
36396 * g_tls_password_get_flags().
36398 * Returns: The warning.
36404 * g_tls_password_new:
36405 * @flags: the password flags
36406 * @description: description of what the password is for
36408 * Create a new #GTlsPassword object.
36410 * Returns: (transfer full): The newly allocated password object
36415 * g_tls_password_set_description:
36416 * @password: a #GTlsPassword object
36417 * @description: The description of the password
36419 * Set a description string about what the password will be used for.
36426 * g_tls_password_set_flags:
36427 * @password: a #GTlsPassword object
36428 * @flags: The flags about the password
36430 * Set flags about the password.
36437 * g_tls_password_set_value:
36438 * @password: a #GTlsPassword object
36439 * @value: the new password value
36440 * @length: the length of the password, or -1
36442 * Set the value for this password. The @value will be copied by the password
36445 * Specify the @length, for a non-nul-terminated password. Pass -1 as
36446 * @length if using a nul-terminated password, and @length will be
36447 * calculated automatically. (Note that the terminating nul is not
36448 * considered part of the password in this case.)
36455 * g_tls_password_set_value_full: (virtual set_value)
36456 * @password: a #GTlsPassword object
36457 * @value: the value for the password
36458 * @length: the length of the password, or -1
36459 * @destroy: (allow-none): a function to use to free the password.
36461 * Provide the value for this password.
36463 * The @value will be owned by the password object, and later freed using
36464 * the @destroy function callback.
36466 * Specify the @length, for a non-nul-terminated password. Pass -1 as
36467 * @length if using a nul-terminated password, and @length will be
36468 * calculated automatically. (Note that the terminating nul is not
36469 * considered part of the password in this case.)
36476 * g_tls_password_set_warning:
36477 * @password: a #GTlsPassword object
36478 * @warning: The user readable warning
36480 * Set a user readable translated warning. Usually this warning is a
36481 * representation of the password flags returned from
36482 * g_tls_password_get_flags().
36489 * g_tls_server_connection_new:
36490 * @base_io_stream: the #GIOStream to wrap
36491 * @certificate: (allow-none): the default server certificate, or %NULL
36492 * @error: #GError for error reporting, or %NULL to ignore.
36494 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
36495 * must have pollable input and output streams).
36497 * Returns: (transfer full) (type GTlsServerConnection): the new
36498 * #GTlsServerConnection, or %NULL on error
36504 * g_unix_connection_receive_credentials:
36505 * @connection: A #GUnixConnection.
36506 * @cancellable: (allow-none): A #GCancellable or %NULL.
36507 * @error: Return location for error or %NULL.
36509 * Receives credentials from the sending end of the connection. The
36510 * sending end has to call g_unix_connection_send_credentials() (or
36511 * similar) for this to work.
36513 * As well as reading the credentials this also reads (and discards) a
36514 * single byte from the stream, as this is required for credentials
36515 * passing to work on some implementations.
36517 * Other ways to exchange credentials with a foreign peer includes the
36518 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
36520 * Returns: (transfer full): Received credentials on success (free with
36521 * g_object_unref()), %NULL if @error is set.
36527 * g_unix_connection_receive_credentials_async:
36528 * @connection: A #GUnixConnection.
36529 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36530 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
36531 * @user_data: (closure): the data to pass to callback function
36533 * Asynchronously receive credentials.
36535 * For more details, see g_unix_connection_receive_credentials() which is
36536 * the synchronous version of this call.
36538 * When the operation is finished, @callback will be called. You can then call
36539 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
36546 * g_unix_connection_receive_credentials_finish:
36547 * @connection: A #GUnixConnection.
36548 * @result: a #GAsyncResult.
36549 * @error: a #GError, or %NULL
36551 * Finishes an asynchronous receive credentials operation started with
36552 * g_unix_connection_receive_credentials_async().
36554 * Returns: (transfer full): a #GCredentials, or %NULL on error.
36555 * Free the returned object with g_object_unref().
36561 * g_unix_connection_receive_fd:
36562 * @connection: a #GUnixConnection
36563 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
36564 * @error: (allow-none): #GError for error reporting, or %NULL to ignore
36566 * Receives a file descriptor from the sending end of the connection.
36567 * The sending end has to call g_unix_connection_send_fd() for this
36570 * As well as reading the fd this also reads a single byte from the
36571 * stream, as this is required for fd passing to work on some
36574 * Returns: a file descriptor on success, -1 on error.
36580 * g_unix_connection_send_credentials:
36581 * @connection: A #GUnixConnection.
36582 * @cancellable: (allow-none): A #GCancellable or %NULL.
36583 * @error: Return location for error or %NULL.
36585 * Passes the credentials of the current user the receiving side
36586 * of the connection. The receiving end has to call
36587 * g_unix_connection_receive_credentials() (or similar) to accept the
36590 * As well as sending the credentials this also writes a single NUL
36591 * byte to the stream, as this is required for credentials passing to
36592 * work on some implementations.
36594 * Other ways to exchange credentials with a foreign peer includes the
36595 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
36597 * Returns: %TRUE on success, %FALSE if @error is set.
36603 * g_unix_connection_send_credentials_async:
36604 * @connection: A #GUnixConnection.
36605 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36606 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
36607 * @user_data: (closure): the data to pass to callback function
36609 * Asynchronously send credentials.
36611 * For more details, see g_unix_connection_send_credentials() which is
36612 * the synchronous version of this call.
36614 * When the operation is finished, @callback will be called. You can then call
36615 * g_unix_connection_send_credentials_finish() to get the result of the operation.
36622 * g_unix_connection_send_credentials_finish:
36623 * @connection: A #GUnixConnection.
36624 * @result: a #GAsyncResult.
36625 * @error: a #GError, or %NULL
36627 * Finishes an asynchronous send credentials operation started with
36628 * g_unix_connection_send_credentials_async().
36630 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
36636 * g_unix_connection_send_fd:
36637 * @connection: a #GUnixConnection
36638 * @fd: a file descriptor
36639 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36640 * @error: (allow-none): #GError for error reporting, or %NULL to ignore.
36642 * Passes a file descriptor to the receiving side of the
36643 * connection. The receiving end has to call g_unix_connection_receive_fd()
36644 * to accept the file descriptor.
36646 * As well as sending the fd this also writes a single byte to the
36647 * stream, as this is required for fd passing to work on some
36650 * Returns: a %TRUE on success, %NULL on error.
36656 * g_unix_credentials_message_get_credentials:
36657 * @message: A #GUnixCredentialsMessage.
36659 * Gets the credentials stored in @message.
36661 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
36667 * g_unix_credentials_message_is_supported:
36669 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
36671 * Returns: %TRUE if supported, %FALSE otherwise
36677 * g_unix_credentials_message_new:
36679 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
36681 * Returns: a new #GUnixCredentialsMessage
36687 * g_unix_credentials_message_new_with_credentials:
36688 * @credentials: A #GCredentials object.
36690 * Creates a new #GUnixCredentialsMessage holding @credentials.
36692 * Returns: a new #GUnixCredentialsMessage
36698 * g_unix_fd_list_append:
36699 * @list: a #GUnixFDList
36700 * @fd: a valid open file descriptor
36701 * @error: a #GError pointer
36703 * Adds a file descriptor to @list.
36705 * The file descriptor is duplicated using dup(). You keep your copy
36706 * of the descriptor and the copy contained in @list will be closed
36707 * when @list is finalized.
36709 * A possible cause of failure is exceeding the per-process or
36710 * system-wide file descriptor limit.
36712 * The index of the file descriptor in the list is returned. If you use
36713 * this index with g_unix_fd_list_get() then you will receive back a
36714 * duplicated copy of the same file descriptor.
36716 * Returns: the index of the appended fd in case of success, else -1
36717 * (and @error is set)
36723 * g_unix_fd_list_get:
36724 * @list: a #GUnixFDList
36725 * @index_: the index into the list
36726 * @error: a #GError pointer
36728 * Gets a file descriptor out of @list.
36730 * @index_ specifies the index of the file descriptor to get. It is a
36731 * programmer error for @index_ to be out of range; see
36732 * g_unix_fd_list_get_length().
36734 * The file descriptor is duplicated using dup() and set as
36735 * close-on-exec before being returned. You must call close() on it
36736 * when you are done.
36738 * A possible cause of failure is exceeding the per-process or
36739 * system-wide file descriptor limit.
36741 * Returns: the file descriptor, or -1 in case of error
36747 * g_unix_fd_list_get_length:
36748 * @list: a #GUnixFDList
36750 * Gets the length of @list (ie: the number of file descriptors
36751 * contained within).
36753 * Returns: the length of @list
36759 * g_unix_fd_list_new:
36761 * Creates a new #GUnixFDList containing no file descriptors.
36763 * Returns: a new #GUnixFDList
36769 * g_unix_fd_list_new_from_array:
36770 * @fds: (array length=n_fds): the initial list of file descriptors
36771 * @n_fds: the length of #fds, or -1
36773 * Creates a new #GUnixFDList containing the file descriptors given in
36774 * @fds. The file descriptors become the property of the new list and
36775 * may no longer be used by the caller. The array itself is owned by
36778 * Each file descriptor in the array should be set to close-on-exec.
36780 * If @n_fds is -1 then @fds must be terminated with -1.
36782 * Returns: a new #GUnixFDList
36788 * g_unix_fd_list_peek_fds:
36789 * @list: a #GUnixFDList
36790 * @length: (out) (allow-none): pointer to the length of the returned
36793 * Returns the array of file descriptors that is contained in this
36796 * After this call, the descriptors remain the property of @list. The
36797 * caller must not close them and must not free the array. The array is
36798 * valid only until @list is changed in any way.
36800 * If @length is non-%NULL then it is set to the number of file
36801 * descriptors in the returned array. The returned array is also
36802 * terminated with -1.
36804 * This function never returns %NULL. In case there are no file
36805 * descriptors contained in @list, an empty array is returned.
36807 * Returns: (array length=length) (transfer none): an array of file
36814 * g_unix_fd_list_steal_fds:
36815 * @list: a #GUnixFDList
36816 * @length: (out) (allow-none): pointer to the length of the returned
36819 * Returns the array of file descriptors that is contained in this
36822 * After this call, the descriptors are no longer contained in
36823 * @list. Further calls will return an empty list (unless more
36824 * descriptors have been added).
36826 * The return result of this function must be freed with g_free().
36827 * The caller is also responsible for closing all of the file
36828 * descriptors. The file descriptors in the array are set to
36831 * If @length is non-%NULL then it is set to the number of file
36832 * descriptors in the returned array. The returned array is also
36833 * terminated with -1.
36835 * This function never returns %NULL. In case there are no file
36836 * descriptors contained in @list, an empty array is returned.
36838 * Returns: (array length=length) (transfer full): an array of file
36845 * g_unix_fd_message_append_fd:
36846 * @message: a #GUnixFDMessage
36847 * @fd: a valid open file descriptor
36848 * @error: a #GError pointer
36850 * Adds a file descriptor to @message.
36852 * The file descriptor is duplicated using dup(). You keep your copy
36853 * of the descriptor and the copy contained in @message will be closed
36854 * when @message is finalized.
36856 * A possible cause of failure is exceeding the per-process or
36857 * system-wide file descriptor limit.
36859 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
36865 * g_unix_fd_message_get_fd_list:
36866 * @message: a #GUnixFDMessage
36868 * Gets the #GUnixFDList contained in @message. This function does not
36869 * return a reference to the caller, but the returned list is valid for
36870 * the lifetime of @message.
36872 * Returns: (transfer none): the #GUnixFDList from @message
36878 * g_unix_fd_message_new:
36880 * Creates a new #GUnixFDMessage containing an empty file descriptor
36883 * Returns: a new #GUnixFDMessage
36889 * g_unix_fd_message_new_with_fd_list:
36890 * @fd_list: a #GUnixFDList
36892 * Creates a new #GUnixFDMessage containing @list.
36894 * Returns: a new #GUnixFDMessage
36900 * g_unix_fd_message_steal_fds:
36901 * @message: a #GUnixFDMessage
36902 * @length: (out) (allow-none): pointer to the length of the returned
36905 * Returns the array of file descriptors that is contained in this
36908 * After this call, the descriptors are no longer contained in
36909 * @message. Further calls will return an empty list (unless more
36910 * descriptors have been added).
36912 * The return result of this function must be freed with g_free().
36913 * The caller is also responsible for closing all of the file
36916 * If @length is non-%NULL then it is set to the number of file
36917 * descriptors in the returned array. The returned array is also
36918 * terminated with -1.
36920 * This function never returns %NULL. In case there are no file
36921 * descriptors contained in @message, an empty array is returned.
36923 * Returns: (array length=length) (transfer full): an array of file
36930 * g_unix_input_stream_get_close_fd:
36931 * @stream: a #GUnixInputStream
36933 * Returns whether the file descriptor of @stream will be
36934 * closed when the stream is closed.
36936 * Returns: %TRUE if the file descriptor is closed when done
36942 * g_unix_input_stream_get_fd:
36943 * @stream: a #GUnixInputStream
36945 * Return the UNIX file descriptor that the stream reads from.
36947 * Returns: The file descriptor of @stream
36953 * g_unix_input_stream_new:
36954 * @fd: a UNIX file descriptor
36955 * @close_fd: %TRUE to close the file descriptor when done
36957 * Creates a new #GUnixInputStream for the given @fd.
36959 * If @close_fd is %TRUE, the file descriptor will be closed
36960 * when the stream is closed.
36962 * Returns: a new #GUnixInputStream
36967 * g_unix_input_stream_set_close_fd:
36968 * @stream: a #GUnixInputStream
36969 * @close_fd: %TRUE to close the file descriptor when done
36971 * Sets whether the file descriptor of @stream shall be closed
36972 * when the stream is closed.
36979 * g_unix_is_mount_path_system_internal:
36980 * @mount_path: a mount path, e.g. <filename>/media/disk</filename>
36981 * or <filename>/usr</filename>
36983 * Determines if @mount_path is considered an implementation of the
36984 * OS. This is primarily used for hiding mountable and mounted volumes
36985 * that only are used in the OS and has little to no relevance to the
36988 * Returns: %TRUE if @mount_path is considered an implementation detail
36994 * g_unix_mount_at: (skip)
36995 * @mount_path: path for a possible unix mount.
36996 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
36998 * Gets a #GUnixMountEntry for a given mount path. If @time_read
36999 * is set, it will be filled with a unix timestamp for checking
37000 * if the mounts have changed since with g_unix_mounts_changed_since().
37002 * Returns: (transfer full): a #GUnixMountEntry.
37007 * g_unix_mount_compare:
37008 * @mount1: first #GUnixMountEntry to compare.
37009 * @mount2: second #GUnixMountEntry to compare.
37011 * Compares two unix mounts.
37013 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
37014 * or less than @mount2, respectively.
37019 * g_unix_mount_free:
37020 * @mount_entry: a #GUnixMountEntry.
37022 * Frees a unix mount.
37027 * g_unix_mount_get_device_path:
37028 * @mount_entry: a #GUnixMount.
37030 * Gets the device path for a unix mount.
37032 * Returns: a string containing the device path.
37037 * g_unix_mount_get_fs_type:
37038 * @mount_entry: a #GUnixMount.
37040 * Gets the filesystem type for the unix mount.
37042 * Returns: a string containing the file system type.
37047 * g_unix_mount_get_mount_path:
37048 * @mount_entry: input #GUnixMountEntry to get the mount path for.
37050 * Gets the mount path for a unix mount.
37052 * Returns: the mount path for @mount_entry.
37057 * g_unix_mount_guess_can_eject:
37058 * @mount_entry: a #GUnixMountEntry
37060 * Guesses whether a Unix mount can be ejected.
37062 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
37067 * g_unix_mount_guess_icon:
37068 * @mount_entry: a #GUnixMountEntry
37070 * Guesses the icon of a Unix mount.
37072 * Returns: (transfer full): a #GIcon
37077 * g_unix_mount_guess_name:
37078 * @mount_entry: a #GUnixMountEntry
37080 * Guesses the name of a Unix mount.
37081 * The result is a translated string.
37083 * Returns: A newly allocated string that must
37084 * be freed with g_free()
37089 * g_unix_mount_guess_should_display:
37090 * @mount_entry: a #GUnixMountEntry
37092 * Guesses whether a Unix mount should be displayed in the UI.
37094 * Returns: %TRUE if @mount_entry is deemed to be displayable.
37099 * g_unix_mount_guess_symbolic_icon:
37100 * @mount_entry: a #GUnixMountEntry
37102 * Guesses the symbolic icon of a Unix mount.
37104 * Returns: (transfer full): a #GIcon
37110 * g_unix_mount_is_readonly:
37111 * @mount_entry: a #GUnixMount.
37113 * Checks if a unix mount is mounted read only.
37115 * Returns: %TRUE if @mount_entry is read only.
37120 * g_unix_mount_is_system_internal:
37121 * @mount_entry: a #GUnixMount.
37123 * Checks if a unix mount is a system path.
37125 * Returns: %TRUE if the unix mount is for a system path.
37130 * g_unix_mount_monitor_new:
37132 * Gets a new #GUnixMountMonitor. The default rate limit for which the
37133 * monitor will report consecutive changes for the mount and mount
37134 * point entry files is the default for a #GFileMonitor. Use
37135 * g_unix_mount_monitor_set_rate_limit() to change this.
37137 * Returns: a #GUnixMountMonitor.
37142 * g_unix_mount_monitor_set_rate_limit:
37143 * @mount_monitor: a #GUnixMountMonitor
37144 * @limit_msec: a integer with the limit in milliseconds to
37145 * poll for changes.
37147 * Sets the rate limit to which the @mount_monitor will report
37148 * consecutive change events to the mount and mount point entry files.
37155 * g_unix_mount_point_compare:
37156 * @mount1: a #GUnixMount.
37157 * @mount2: a #GUnixMount.
37159 * Compares two unix mount points.
37161 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
37162 * or less than @mount2, respectively.
37167 * g_unix_mount_point_free:
37168 * @mount_point: unix mount point to free.
37170 * Frees a unix mount point.
37175 * g_unix_mount_point_get_device_path:
37176 * @mount_point: a #GUnixMountPoint.
37178 * Gets the device path for a unix mount point.
37180 * Returns: a string containing the device path.
37185 * g_unix_mount_point_get_fs_type:
37186 * @mount_point: a #GUnixMountPoint.
37188 * Gets the file system type for the mount point.
37190 * Returns: a string containing the file system type.
37195 * g_unix_mount_point_get_mount_path:
37196 * @mount_point: a #GUnixMountPoint.
37198 * Gets the mount path for a unix mount point.
37200 * Returns: a string containing the mount path.
37205 * g_unix_mount_point_get_options:
37206 * @mount_point: a #GUnixMountPoint.
37208 * Gets the options for the mount point.
37210 * Returns: a string containing the options.
37216 * g_unix_mount_point_guess_can_eject:
37217 * @mount_point: a #GUnixMountPoint
37219 * Guesses whether a Unix mount point can be ejected.
37221 * Returns: %TRUE if @mount_point is deemed to be ejectable.
37226 * g_unix_mount_point_guess_icon:
37227 * @mount_point: a #GUnixMountPoint
37229 * Guesses the icon of a Unix mount point.
37231 * Returns: (transfer full): a #GIcon
37236 * g_unix_mount_point_guess_name:
37237 * @mount_point: a #GUnixMountPoint
37239 * Guesses the name of a Unix mount point.
37240 * The result is a translated string.
37242 * Returns: A newly allocated string that must
37243 * be freed with g_free()
37248 * g_unix_mount_point_guess_symbolic_icon:
37249 * @mount_point: a #GUnixMountPoint
37251 * Guesses the symbolic icon of a Unix mount point.
37253 * Returns: (transfer full): a #GIcon
37259 * g_unix_mount_point_is_loopback:
37260 * @mount_point: a #GUnixMountPoint.
37262 * Checks if a unix mount point is a loopback device.
37264 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
37269 * g_unix_mount_point_is_readonly:
37270 * @mount_point: a #GUnixMountPoint.
37272 * Checks if a unix mount point is read only.
37274 * Returns: %TRUE if a mount point is read only.
37279 * g_unix_mount_point_is_user_mountable:
37280 * @mount_point: a #GUnixMountPoint.
37282 * Checks if a unix mount point is mountable by the user.
37284 * Returns: %TRUE if the mount point is user mountable.
37289 * g_unix_mount_points_changed_since:
37290 * @time: guint64 to contain a timestamp.
37292 * Checks if the unix mount points have changed since a given unix time.
37294 * Returns: %TRUE if the mount points have changed since @time.
37299 * g_unix_mount_points_get: (skip)
37300 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
37302 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
37303 * If @time_read is set, it will be filled with the mount timestamp,
37304 * allowing for checking if the mounts have changed with
37305 * g_unix_mount_points_changed_since().
37307 * Returns: (element-type GUnixMountPoint) (transfer full):
37308 * a #GList of the UNIX mountpoints.
37313 * g_unix_mounts_changed_since:
37314 * @time: guint64 to contain a timestamp.
37316 * Checks if the unix mounts have changed since a given unix time.
37318 * Returns: %TRUE if the mounts have changed since @time.
37323 * g_unix_mounts_get: (skip)
37324 * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
37326 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
37327 * If @time_read is set, it will be filled with the mount
37328 * timestamp, allowing for checking if the mounts have changed
37329 * with g_unix_mounts_changed_since().
37331 * Returns: (element-type GUnixMountEntry) (transfer full):
37332 * a #GList of the UNIX mounts.
37337 * g_unix_output_stream_get_close_fd:
37338 * @stream: a #GUnixOutputStream
37340 * Returns whether the file descriptor of @stream will be
37341 * closed when the stream is closed.
37343 * Returns: %TRUE if the file descriptor is closed when done
37349 * g_unix_output_stream_get_fd:
37350 * @stream: a #GUnixOutputStream
37352 * Return the UNIX file descriptor that the stream writes to.
37354 * Returns: The file descriptor of @stream
37360 * g_unix_output_stream_new:
37361 * @fd: a UNIX file descriptor
37362 * @close_fd: %TRUE to close the file descriptor when done
37364 * Creates a new #GUnixOutputStream for the given @fd.
37366 * If @close_fd, is %TRUE, the file descriptor will be closed when
37367 * the output stream is destroyed.
37369 * Returns: a new #GOutputStream
37374 * g_unix_output_stream_set_close_fd:
37375 * @stream: a #GUnixOutputStream
37376 * @close_fd: %TRUE to close the file descriptor when done
37378 * Sets whether the file descriptor of @stream shall be closed
37379 * when the stream is closed.
37386 * g_unix_socket_address_abstract_names_supported:
37388 * Checks if abstract UNIX domain socket names are supported.
37390 * Returns: %TRUE if supported, %FALSE otherwise
37396 * g_unix_socket_address_get_address_type:
37397 * @address: a #GInetSocketAddress
37399 * Gets @address's type.
37401 * Returns: a #GUnixSocketAddressType
37407 * g_unix_socket_address_get_is_abstract:
37408 * @address: a #GInetSocketAddress
37410 * Tests if @address is abstract.
37412 * Returns: %TRUE if the address is abstract, %FALSE otherwise
37414 * Deprecated: Use g_unix_socket_address_get_address_type()
37419 * g_unix_socket_address_get_path:
37420 * @address: a #GInetSocketAddress
37422 * Gets @address's path, or for abstract sockets the "name".
37424 * Guaranteed to be zero-terminated, but an abstract socket
37425 * may contain embedded zeros, and thus you should use
37426 * g_unix_socket_address_get_path_len() to get the true length
37429 * Returns: the path for @address
37435 * g_unix_socket_address_get_path_len:
37436 * @address: a #GInetSocketAddress
37438 * Gets the length of @address's path.
37440 * For details, see g_unix_socket_address_get_path().
37442 * Returns: the length of the path
37448 * g_unix_socket_address_new:
37449 * @path: the socket path
37451 * Creates a new #GUnixSocketAddress for @path.
37453 * To create abstract socket addresses, on systems that support that,
37454 * use g_unix_socket_address_new_abstract().
37456 * Returns: a new #GUnixSocketAddress
37462 * g_unix_socket_address_new_abstract:
37463 * @path: (array length=path_len) (element-type gchar): the abstract name
37464 * @path_len: the length of @path, or -1
37466 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
37467 * #GUnixSocketAddress for @path.
37469 * Returns: a new #GUnixSocketAddress
37470 * Deprecated: Use g_unix_socket_address_new_with_type().
37475 * g_unix_socket_address_new_with_type:
37476 * @path: (array length=path_len) (element-type gchar): the name
37477 * @path_len: the length of @path, or -1
37478 * @type: a #GUnixSocketAddressType
37480 * Creates a new #GUnixSocketAddress of type @type with name @path.
37482 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
37483 * calling g_unix_socket_address_new().
37485 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
37486 * bytes of @path will be copied to the socket's path, and only those
37487 * bytes will be considered part of the name. (If @path_len is -1,
37488 * then @path is assumed to be NUL-terminated.) For example, if @path
37489 * was "test", then calling g_socket_address_get_native_size() on the
37490 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
37491 * abstract-socket indicator byte, and 4 bytes for the name "test").
37493 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
37494 * @path_len bytes of @path will be copied to the socket's path, the
37495 * rest of the path will be padded with 0 bytes, and the entire
37496 * zero-padded buffer will be considered the name. (As above, if
37497 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
37498 * this case, g_socket_address_get_native_size() will always return
37499 * the full size of a <literal>struct sockaddr_un</literal>, although
37500 * g_unix_socket_address_get_path_len() will still return just the
37503 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
37504 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
37505 * when connecting to a server created by another process, you must
37506 * use the appropriate type corresponding to how that process created
37507 * its listening socket.
37509 * Returns: a new #GUnixSocketAddress
37515 * g_vfs_get_default:
37517 * Gets the default #GVfs for the system.
37519 * Returns: (transfer none): a #GVfs.
37524 * g_vfs_get_file_for_path:
37526 * @path: a string containing a VFS path.
37528 * Gets a #GFile for @path.
37530 * Returns: (transfer full): a #GFile.
37531 * Free the returned object with g_object_unref().
37536 * g_vfs_get_file_for_uri:
37538 * @uri: a string containing a URI
37540 * Gets a #GFile for @uri.
37542 * This operation never fails, but the returned object
37543 * might not support any I/O operation if the URI
37544 * is malformed or if the URI scheme is not supported.
37546 * Returns: (transfer full): a #GFile.
37547 * Free the returned object with g_object_unref().
37554 * Gets the local #GVfs for the system.
37556 * Returns: (transfer none): a #GVfs.
37561 * g_vfs_get_supported_uri_schemes:
37564 * Gets a list of URI schemes supported by @vfs.
37566 * Returns: (transfer none): a %NULL-terminated array of strings.
37567 * The returned array belongs to GIO and must
37568 * not be freed or modified.
37576 * Checks if the VFS is active.
37578 * Returns: %TRUE if construction of the @vfs was successful
37579 * and it is now active.
37584 * g_vfs_parse_name:
37586 * @parse_name: a string to be parsed by the VFS module.
37588 * This operation never fails, but the returned object might
37589 * not support any I/O operations if the @parse_name cannot
37590 * be parsed by the #GVfs module.
37592 * Returns: (transfer full): a #GFile for the given @parse_name.
37593 * Free the returned object with g_object_unref().
37598 * g_volume_can_eject:
37599 * @volume: a #GVolume.
37601 * Checks if a volume can be ejected.
37603 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
37608 * g_volume_can_mount:
37609 * @volume: a #GVolume.
37611 * Checks if a volume can be mounted.
37613 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
37619 * @volume: a #GVolume.
37620 * @flags: flags affecting the unmount if required for eject
37621 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37622 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
37623 * @user_data: user data that gets passed to @callback
37625 * Ejects a volume. This is an asynchronous operation, and is
37626 * finished by calling g_volume_eject_finish() with the @volume
37627 * and #GAsyncResult returned in the @callback.
37629 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
37634 * g_volume_eject_finish:
37635 * @volume: pointer to a #GVolume.
37636 * @result: a #GAsyncResult.
37637 * @error: a #GError location to store an error, or %NULL to ignore
37639 * Finishes ejecting a volume. If any errors occurred during the operation,
37640 * @error will be set to contain the errors and %FALSE will be returned.
37642 * Returns: %TRUE, %FALSE if operation failed.
37643 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
37648 * g_volume_eject_with_operation:
37649 * @volume: a #GVolume.
37650 * @flags: flags affecting the unmount if required for eject
37651 * @mount_operation: (allow-none): a #GMountOperation or %NULL to
37652 * avoid user interaction.
37653 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37654 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
37655 * @user_data: user data passed to @callback.
37657 * Ejects a volume. This is an asynchronous operation, and is
37658 * finished by calling g_volume_eject_with_operation_finish() with the @volume
37659 * and #GAsyncResult data returned in the @callback.
37666 * g_volume_eject_with_operation_finish:
37667 * @volume: a #GVolume.
37668 * @result: a #GAsyncResult.
37669 * @error: a #GError location to store the error occurring, or %NULL to
37672 * Finishes ejecting a volume. If any errors occurred during the operation,
37673 * @error will be set to contain the errors and %FALSE will be returned.
37675 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise.
37681 * g_volume_enumerate_identifiers:
37682 * @volume: a #GVolume
37684 * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
37685 * that @volume has. Use g_volume_get_identifier() to obtain
37686 * the identifiers themselves.
37688 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
37689 * of strings containing kinds of identifiers. Use g_strfreev() to free.
37694 * g_volume_get_activation_root:
37695 * @volume: a #GVolume
37697 * Gets the activation root for a #GVolume if it is known ahead of
37698 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
37699 * is mounted, then the result of g_mount_get_root() on the
37700 * #GMount object obtained from g_volume_get_mount() will always
37701 * either be equal or a prefix of what this function returns. In
37702 * other words, in code
37706 * GFile *mount_root
37707 * GFile *volume_activation_root;
37709 * mount = g_volume_get_mount (volume); /* mounted, so never NULL */
37710 * mount_root = g_mount_get_root (mount);
37711 * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
37712 * </programlisting>
37714 * then the expression
37717 * (g_file_has_prefix (volume_activation_root, mount_root) ||
37718 * g_file_equal (volume_activation_root, mount_root))
37719 * </programlisting>
37721 * will always be %TRUE.
37723 * Activation roots are typically used in #GVolumeMonitor
37724 * implementations to find the underlying mount to shadow, see
37725 * g_mount_is_shadowed() for more details.
37727 * Returns: (transfer full): the activation root of @volume or %NULL. Use
37728 * g_object_unref() to free.
37734 * g_volume_get_drive:
37735 * @volume: a #GVolume.
37737 * Gets the drive for the @volume.
37739 * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive.
37740 * The returned object should be unreffed with g_object_unref()
37741 * when no longer needed.
37746 * g_volume_get_icon:
37747 * @volume: a #GVolume.
37749 * Gets the icon for @volume.
37751 * Returns: (transfer full): a #GIcon.
37752 * The returned object should be unreffed with g_object_unref()
37753 * when no longer needed.
37758 * g_volume_get_identifier:
37759 * @volume: a #GVolume
37760 * @kind: the kind of identifier to return
37762 * Gets the identifier of the given kind for @volume.
37763 * See the <link linkend="volume-identifier">introduction</link>
37764 * for more information about volume identifiers.
37766 * Returns: a newly allocated string containing the
37767 * requested identfier, or %NULL if the #GVolume
37768 * doesn't have this kind of identifier
37773 * g_volume_get_mount:
37774 * @volume: a #GVolume.
37776 * Gets the mount for the @volume.
37778 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
37779 * The returned object should be unreffed with g_object_unref()
37780 * when no longer needed.
37785 * g_volume_get_name:
37786 * @volume: a #GVolume.
37788 * Gets the name of @volume.
37790 * Returns: the name for the given @volume. The returned string should
37791 * be freed with g_free() when no longer needed.
37796 * g_volume_get_sort_key:
37797 * @volume: A #GVolume.
37799 * Gets the sort key for @volume, if any.
37801 * Returns: Sorting key for @volume or %NULL if no such key is available.
37807 * g_volume_get_symbolic_icon:
37808 * @volume: a #GVolume.
37810 * Gets the symbolic icon for @volume.
37812 * Returns: (transfer full): a #GIcon.
37813 * The returned object should be unreffed with g_object_unref()
37814 * when no longer needed.
37820 * g_volume_get_uuid:
37821 * @volume: a #GVolume.
37823 * Gets the UUID for the @volume. The reference is typically based on
37824 * the file system UUID for the volume in question and should be
37825 * considered an opaque string. Returns %NULL if there is no UUID
37828 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
37829 * The returned string should be freed with g_free()
37830 * when no longer needed.
37835 * g_volume_monitor_adopt_orphan_mount:
37836 * @mount: a #GMount object to find a parent for
37838 * This function should be called by any #GVolumeMonitor
37839 * implementation when a new #GMount object is created that is not
37840 * associated with a #GVolume object. It must be called just before
37841 * emitting the @mount_added signal.
37843 * If the return value is not %NULL, the caller must associate the
37844 * returned #GVolume object with the #GMount. This involves returning
37845 * it in its g_mount_get_volume() implementation. The caller must
37846 * also listen for the "removed" signal on the returned object
37847 * and give up its reference when handling that signal
37849 * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
37850 * the implementor must take a reference to @mount and return it in
37851 * its g_volume_get_mount() implemented. Also, the implementor must
37852 * listen for the "unmounted" signal on @mount and give up its
37853 * reference upon handling that signal.
37855 * There are two main use cases for this function.
37857 * One is when implementing a user space file system driver that reads
37858 * blocks of a block device that is already represented by the native
37859 * volume monitor (for example a CD Audio file system driver). Such
37860 * a driver will generate its own #GMount object that needs to be
37861 * associated with the #GVolume object that represents the volume.
37863 * The other is for implementing a #GVolumeMonitor whose sole purpose
37864 * is to return #GVolume objects representing entries in the users
37865 * "favorite servers" list or similar.
37867 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
37868 * if no wants to adopt the #GMount.
37869 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
37870 * implementations should instead create shadow mounts with the URI of
37871 * the mount they intend to adopt. See the proxy volume monitor in
37872 * gvfs for an example of this. Also see g_mount_is_shadowed(),
37873 * g_mount_shadow() and g_mount_unshadow() functions.
37878 * g_volume_monitor_get:
37880 * Gets the volume monitor used by gio.
37882 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
37883 * g_object_unref() when done with it.
37888 * g_volume_monitor_get_connected_drives:
37889 * @volume_monitor: a #GVolumeMonitor.
37891 * Gets a list of drives connected to the system.
37893 * The returned list should be freed with g_list_free(), after
37894 * its elements have been unreffed with g_object_unref().
37896 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
37901 * g_volume_monitor_get_mount_for_uuid:
37902 * @volume_monitor: a #GVolumeMonitor.
37903 * @uuid: the UUID to look for
37905 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
37907 * Returns: (transfer full): a #GMount or %NULL if no such mount is available.
37908 * Free the returned object with g_object_unref().
37913 * g_volume_monitor_get_mounts:
37914 * @volume_monitor: a #GVolumeMonitor.
37916 * Gets a list of the mounts on the system.
37918 * The returned list should be freed with g_list_free(), after
37919 * its elements have been unreffed with g_object_unref().
37921 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
37926 * g_volume_monitor_get_volume_for_uuid:
37927 * @volume_monitor: a #GVolumeMonitor.
37928 * @uuid: the UUID to look for
37930 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
37932 * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
37933 * Free the returned object with g_object_unref().
37938 * g_volume_monitor_get_volumes:
37939 * @volume_monitor: a #GVolumeMonitor.
37941 * Gets a list of the volumes on the system.
37943 * The returned list should be freed with g_list_free(), after
37944 * its elements have been unreffed with g_object_unref().
37946 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
37951 * g_volume_mount: (virtual mount_fn)
37952 * @volume: a #GVolume.
37953 * @flags: flags affecting the operation
37954 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
37955 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37956 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
37957 * @user_data: user data that gets passed to @callback
37959 * Mounts a volume. This is an asynchronous operation, and is
37960 * finished by calling g_volume_mount_finish() with the @volume
37961 * and #GAsyncResult returned in the @callback.
37966 * g_volume_mount_finish:
37967 * @volume: a #GVolume
37968 * @result: a #GAsyncResult
37969 * @error: a #GError location to store an error, or %NULL to ignore
37971 * Finishes mounting a volume. If any errors occurred during the operation,
37972 * @error will be set to contain the errors and %FALSE will be returned.
37974 * If the mount operation succeeded, g_volume_get_mount() on @volume
37975 * is guaranteed to return the mount right after calling this
37976 * function; there's no need to listen for the 'mount-added' signal on
37979 * Returns: %TRUE, %FALSE if operation failed.
37984 * g_volume_should_automount:
37985 * @volume: a #GVolume
37987 * Returns whether the volume should be automatically mounted.
37989 * Returns: %TRUE if the volume should be automatically mounted.
37994 * g_win32_input_stream_get_close_handle:
37995 * @stream: a #GWin32InputStream
37997 * Returns whether the handle of @stream will be
37998 * closed when the stream is closed.
38000 * Returns: %TRUE if the handle is closed when done
38006 * g_win32_input_stream_get_handle:
38007 * @stream: a #GWin32InputStream
38009 * Return the Windows file handle that the stream reads from.
38011 * Returns: The file handle of @stream
38017 * g_win32_input_stream_new:
38018 * @handle: a Win32 file handle
38019 * @close_handle: %TRUE to close the handle when done
38021 * Creates a new #GWin32InputStream for the given @handle.
38023 * If @close_handle is %TRUE, the handle will be closed
38024 * when the stream is closed.
38026 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
38027 * as used in the Windows C libraries.
38029 * Returns: a new #GWin32InputStream
38034 * g_win32_input_stream_set_close_handle:
38035 * @stream: a #GWin32InputStream
38036 * @close_handle: %TRUE to close the handle when done
38038 * Sets whether the handle of @stream shall be closed
38039 * when the stream is closed.
38046 * g_win32_output_stream_get_close_handle:
38047 * @stream: a #GWin32OutputStream
38049 * Returns whether the handle of @stream will be closed when the
38050 * stream is closed.
38052 * Returns: %TRUE if the handle is closed when done
38058 * g_win32_output_stream_get_handle:
38059 * @stream: a #GWin32OutputStream
38061 * Return the Windows handle that the stream writes to.
38063 * Returns: The handle descriptor of @stream
38069 * g_win32_output_stream_new:
38070 * @handle: a Win32 file handle
38071 * @close_handle: %TRUE to close the handle when done
38073 * Creates a new #GWin32OutputStream for the given @handle.
38075 * If @close_handle, is %TRUE, the handle will be closed when the
38076 * output stream is destroyed.
38078 * Returns: a new #GOutputStream
38084 * g_win32_output_stream_set_close_handle:
38085 * @stream: a #GWin32OutputStream
38086 * @close_handle: %TRUE to close the handle when done
38088 * Sets whether the handle of @stream shall be closed when the stream
38096 * g_zlib_compressor_get_file_info:
38097 * @compressor: a #GZlibCompressor
38099 * Returns the #GZlibCompressor:file-info property.
38101 * Returns: (transfer none): a #GFileInfo, or %NULL
38107 * g_zlib_compressor_new:
38108 * @format: The format to use for the compressed data
38109 * @level: compression level (0-9), -1 for default
38111 * Creates a new #GZlibCompressor.
38113 * Returns: a new #GZlibCompressor
38119 * g_zlib_compressor_set_file_info:
38120 * @compressor: a #GZlibCompressor
38121 * @file_info: (allow-none): a #GFileInfo
38123 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
38124 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
38125 * it will be used to set the file name and modification time in
38126 * the GZIP header of the compressed data.
38128 * Note: it is an error to call this function while a compression is in
38129 * progress; it may only be called immediately after creation of @compressor,
38130 * or after resetting it with g_converter_reset().
38137 * g_zlib_decompressor_get_file_info:
38138 * @decompressor: a #GZlibDecompressor
38140 * Retrieves the #GFileInfo constructed from the GZIP header data
38141 * of compressed data processed by @compressor, or %NULL if @decompressor's
38142 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
38143 * or the header data was not fully processed yet, or it not present in the
38144 * data stream at all.
38146 * Returns: (transfer none): a #GFileInfo, or %NULL
38152 * g_zlib_decompressor_new:
38153 * @format: The format to use for the compressed data
38155 * Creates a new #GZlibDecompressor.
38157 * Returns: a new #GZlibDecompressor
38163 * get_all_desktop_entries_for_mime_type:
38164 * @mime_type: a mime type.
38165 * @except: NULL or a strv list
38167 * Returns all the desktop ids for @mime_type. The desktop files
38168 * are listed in an order so that default applications are listed before
38169 * non-default ones, and handlers for inherited mimetypes are listed
38170 * after the base ones.
38172 * Optionally doesn't list the desktop ids given in the @except
38174 * Returns: a #GList containing the desktop ids which claim
38175 * to handle @mime_type.
38180 * mime_info_cache_reload:
38181 * @dir: directory path which needs reloading.
38183 * Reload the mime information for the @dir.
38188 /************************************************************/
38189 /* THIS FILE IS GENERATED DO NOT EDIT */
38190 /************************************************************/