diff options
Diffstat (limited to 'gir/gio-2.0.c')
| -rw-r--r-- | gir/gio-2.0.c | 10080 |
1 files changed, 7521 insertions, 2559 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 3f3b2222..0cc13e84 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -56,10 +56,17 @@ /** * GActionEntry: * @name: the name of the action - * @activate: the callback to connect to the "activate" signal of the action - * @parameter_type: the type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or %NULL for no parameter) - * @state: the initial state for this action, given in GVariant text format. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary. - * @change_state: the callback to connect to the "change-state" signal of the action + * @activate: the callback to connect to the "activate" signal of the + * action + * @parameter_type: the type of the parameter that must be passed to the + * activate function for this action, given as a single + * GVariant type string (or %NULL for no parameter) + * @state: the initial state for this action, given in GVariant text + * format. The state is parsed with no extra type information, + * so type tags must be added to the string if they are + * necessary. + * @change_state: the callback to connect to the "change-state" signal + * of the action * * This struct defines a single action. It is for use with * g_action_map_add_action_entries(). @@ -156,7 +163,8 @@ * @get_enabled: the virtual function pointer for g_action_get_enabled() * @get_state: the virtual function pointer for g_action_get_state() * @change_state: the virtual function pointer for g_action_change_state() - * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one. + * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an + * 'activate' signal but that implementations of it may have one. * * The virtual function table for #GAction. * @@ -177,6 +185,16 @@ /** + * GAppInfoMonitor: + * + * The only thing you can do with this is to get it via + * g_app_info_monitor_get() and connect to the "changed" signal. + * + * Since: 2.40 + */ + + +/** * GApplication::activate: * @application: the application * @@ -188,13 +206,71 @@ /** * GApplication::command-line: * @application: the application - * @command_line: a #GApplicationCommandLine representing the passed commandline + * @command_line: a #GApplicationCommandLine representing the + * passed commandline * * The ::command-line signal is emitted on the primary instance when * a commandline is not handled locally. See g_application_run() and * the #GApplicationCommandLine documentation for more information. * - * Returns: An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status(). + * Returns: An integer that is set as the exit status for the calling + * process. See g_application_command_line_set_exit_status(). + */ + + +/** + * GApplication::handle-local-options: + * @application: the application + * @options: the options dictionary + * + * The ::handle-local-options signal is emitted on the local instance + * after the parsing of the commandline options has occurred. + * + * You can add options to be recognised during commandline option + * parsing using g_application_add_main_option_entries() and + * g_application_add_option_group(). + * + * Signal handlers can inspect @options (along with values pointed to + * from the @arg_data of an installed #GOptionEntrys) in order to + * decide to perform certain actions, including direct local handling + * (which may be useful for options like --version). + * + * If the options have been "handled" then a non-negative value should + * be returned. In this case, the return value is the exit status: 0 + * for success and a positive value for failure. -1 means to continue + * normal processing. + * + * In the event that the application is marked + * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will + * send the @option dictionary to the primary instance where it can be + * read with g_application_command_line_get_options(). The signal + * handler can modify the dictionary before returning, and the + * modified dictionary will be sent. + * + * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set, + * "normal processing" will treat the remaining uncollected command + * line arguments as filenames or URIs. If there are no arguments, + * the application is activated by g_application_activate(). One or + * more arguments results in a call to g_application_open(). + * + * If you want to handle the local commandline arguments for yourself + * by converting them to calls to g_application_open() or + * g_action_group_activate_action() then you must be sure to register + * the application first. You should probably not call + * g_application_activate() for yourself, however: just return -1 and + * allow the default handler to do it for you. This will ensure that + * the `--gapplication-service` switch works properly (i.e. no activation + * in that case). + * + * Note that this signal is emitted from the default implementation of + * local_command_line(). If you override that function and don't + * chain up then this signal will never be emitted. + * + * You can override local_command_line() if you need more powerful + * capabilities than what is provided here, but this should not + * normally be required. + * + * Since: 2.40 */ @@ -231,18 +307,42 @@ /** * GApplicationClass: * @startup: invoked on the primary instance immediately after registration - * @shutdown: invoked only on the registered primary instance immediately after the main loop terminates + * @shutdown: invoked only on the registered primary instance immediately + * after the main loop terminates * @activate: invoked on the primary instance when an activation occurs * @open: invoked on the primary instance when there are files to open - * @command_line: invoked on the primary instance when a command-line is not handled locally - * @local_command_line: invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information. - * @before_emit: invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance - * @after_emit: invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance - * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions - * @quit_mainloop: Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32 - * @run_mainloop: Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore - * @dbus_register: invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the #GDBusConnection to to session bus, and the object path that #GApplication will use to export is D-Bus API. If this function returns %TRUE, registration will proceed; otherwise registration will abort. Since: 2.34 - * @dbus_unregister: invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the @dbus_register vfunc. Since: 2.34 + * @command_line: invoked on the primary instance when a command-line is + * not handled locally + * @local_command_line: invoked (locally) when the process has been invoked + * via commandline execution (as opposed to, say, D-Bus activation - which + * is not currently supported by GApplication). The virtual function has + * the chance to inspect (and possibly replace) the list of command line + * arguments. See g_application_run() for more information. + * @before_emit: invoked on the primary instance before 'activate', 'open', + * 'command-line' or any action invocation, gets the 'platform data' from + * the calling instance + * @after_emit: invoked on the primary instance after 'activate', 'open', + * 'command-line' or any action invocation, gets the 'platform data' from + * the calling instance + * @add_platform_data: invoked (locally) to add 'platform data' to be sent to + * the primary instance when activating, opening or invoking actions + * @quit_mainloop: Used to be invoked on the primary instance when the use + * count of the application drops to zero (and after any inactivity + * timeout, if requested). Not used anymore since 2.32 + * @run_mainloop: Used to be invoked on the primary instance from + * g_application_run() if the use-count is non-zero. Since 2.32, + * GApplication is iterating the main context directly and is not + * using @run_mainloop anymore + * @dbus_register: invoked locally during registration, if the application is + * using its D-Bus backend. You can use this to export extra objects on the + * bus, that need to exist before the application tries to own the bus name. + * The function is passed the #GDBusConnection to to session bus, and the + * object path that #GApplication will use to export is D-Bus API. + * If this function returns %TRUE, registration will proceed; otherwise + * registration will abort. Since: 2.34 + * @dbus_unregister: invoked locally during unregistration, if the application + * is using its D-Bus backend. Use this to undo anything done by the + * @dbus_register vfunc. Since: 2.34 * * Virtual function table for #GApplication. * @@ -253,14 +353,21 @@ /** * GApplicationCommandLineClass: * - * The <structname>GApplicationCommandLineClass</structname> structure - * contains private data only + * The #GApplicationCommandLineClass-struct + * contains private data only. * * Since: 2.28 */ /** + * GBytesIcon:bytes: + * + * The bytes containing the icon. + */ + + +/** * GCancellable::cancelled: * @cancellable: a #GCancellable. * @@ -273,16 +380,14 @@ * * Note that disconnecting from this signal (or any signal) in a * multi-threaded program is prone to race conditions. For instance - * it is possible that a signal handler may be invoked even - * <emphasis>after</emphasis> a call to - * g_signal_handler_disconnect() for that handler has already - * returned. + * it is possible that a signal handler may be invoked even after + * a call to g_signal_handler_disconnect() for that handler has + * already returned. * - * There is also a problem when cancellation happen - * right before connecting to the signal. If this happens the - * signal will unexpectedly not be emitted, and checking before - * connecting to the signal leaves a race condition where this is - * still happening. + * There is also a problem when cancellation happens right before + * connecting to the signal. If this happens the signal will + * unexpectedly not be emitted, and checking before connecting to + * the signal leaves a race condition where this is still happening. * * In order to make it safe and easy to connect handlers there * are two helper functions: g_cancellable_connect() and @@ -290,13 +395,13 @@ * like this. * * An example of how to us this: - * |[ - * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/ - * if (g_cancellable_set_error_if_cancelled (cancellable)) + * |[<!-- language="C" --> + * // Make sure we don't do unnecessary work if already cancelled + * if (g_cancellable_set_error_if_cancelled (cancellable, error)) * return; * - * /<!-- -->* Set up all the data needed to be able to - * * handle cancellation of the operation *<!-- -->/ + * // Set up all the data needed to be able to handle cancellation + * // of the operation * my_data = my_data_new (...); * * id = 0; @@ -305,12 +410,12 @@ * G_CALLBACK (cancelled_handler) * data, NULL); * - * /<!-- -->* cancellable operation here... *<!-- -->/ + * // cancellable operation here... * * g_cancellable_disconnect (cancellable, id); * - * /<!-- -->* cancelled_handler is never called after this, it - * * is now safe to free the data *<!-- -->/ + * // cancelled_handler is never called after this, it is now safe + * // to free the data * my_data_free (my_data); * ]| * @@ -370,7 +475,7 @@ /** * GDBusAuthObserver::allow-mechanism: * @observer: The #GDBusAuthObserver emitting the signal. - * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>. + * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. * * Emitted to check if @mechanism is allowed to be used. * @@ -415,28 +520,23 @@ /** * GDBusConnection::closed: - * @connection: The #GDBusConnection emitting the signal. - * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection. - * @error: (allow-none): A #GError with more details about the event or %NULL. + * @connection: the #GDBusConnection emitting the signal + * @remote_peer_vanished: %TRUE if @connection is closed because the + * remote peer closed its end of the connection + * @error: (allow-none): a #GError with more details about the event or %NULL * * Emitted when the connection is closed. * * The cause of this event can be - * <itemizedlist> - * <listitem><para> - * If g_dbus_connection_close() is called. In this case - * @remote_peer_vanished is set to %FALSE and @error is %NULL. - * </para></listitem> - * <listitem><para> - * If the remote peer closes the connection. In this case - * @remote_peer_vanished is set to %TRUE and @error is set. - * </para></listitem> - * <listitem><para> - * If the remote peer sends invalid or malformed data. In this - * case @remote_peer_vanished is set to %FALSE and @error - * is set. - * </para></listitem> - * </itemizedlist> + * + * - If g_dbus_connection_close() is called. In this case + * @remote_peer_vanished is set to %FALSE and @error is %NULL. + * + * - If the remote peer closes the connection. In this case + * @remote_peer_vanished is set to %TRUE and @error is set. + * + * - If the remote peer sends invalid or malformed data. In this + * case @remote_peer_vanished is set to %FALSE and @error is set. * * Upon receiving this signal, you should give up your reference to * @connection. You are guaranteed that this signal is emitted only @@ -488,11 +588,11 @@ * GDBusConnection:exit-on-close: * * A boolean specifying whether the process will be terminated (by - * calling <literal>raise(SIGTERM)</literal>) if the connection - * is closed by the remote peer. + * calling `raise(SIGTERM)`) if the connection is closed by the + * remote peer. * - * Note that #GDBusConnection objects returned by g_bus_get_finish() and - * g_bus_get_sync() will (usually) have this property set to %TRUE. + * Note that #GDBusConnection objects returned by g_bus_get_finish() + * and g_bus_get_sync() will (usually) have this property set to %TRUE. * * Since: 2.26 */ @@ -583,11 +683,11 @@ * * Note that this signal is emitted in a thread dedicated to * handling the method call so handlers are allowed to perform - * blocking IO. This means that it is appropriate to call - * e.g. <ulink - * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</ulink> - * with the <ulink - * 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. + * blocking IO. This means that it is appropriate to call e.g. + * [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync) + * with the + * [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS) + * flag set. * * If %FALSE is returned then no further handlers are run and the * signal handler must take a reference to @invocation and finish @@ -755,7 +855,7 @@ * connect signals to all interface proxies managed by @manager. * * This signal is emitted in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main context][g-main-context-push-thread-default] * that @manager was constructed in. * * Since: 2.30 @@ -777,7 +877,7 @@ * connect signals to all interface proxies managed by @manager. * * This signal is emitted in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main context][g-main-context-push-thread-default] * that @manager was constructed in. * * Since: 2.30 @@ -916,9 +1016,9 @@ * Emitted when a method is invoked by a remote caller and used to * determine if the method call is authorized. * - * This signal is like #GDBusInterfaceSkeleton<!-- -->'s - * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is - * for the enclosing object. + * This signal is like #GDBusInterfaceSkeleton's + * #GDBusInterfaceSkeleton::g-authorize-method signal, + * except that it is for the enclosing object. * * The default class handler just returns %TRUE. * @@ -952,8 +1052,8 @@ * @invalidated_properties will always be empty. * * This signal corresponds to the - * <literal>PropertiesChanged</literal> D-Bus signal on the - * <literal>org.freedesktop.DBus.Properties</literal> interface. + * `PropertiesChanged` D-Bus signal on the + * `org.freedesktop.DBus.Properties` interface. * * Since: 2.26 */ @@ -1024,27 +1124,23 @@ * Ensure that interactions with this proxy conform to the given * interface. This is mainly to ensure that malformed data received * from the other peer is ignored. The given #GDBusInterfaceInfo is - * said to be the <emphasis>expected interface</emphasis>. + * said to be the "expected interface". * * The checks performed are: - * <itemizedlist> - * <listitem><para> - * When completing a method call, if the type signature of - * the reply message isn't what's expected, the reply is - * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - * </para></listitem> - * <listitem><para> - * Received signals that have a type signature mismatch are dropped and - * a warning is logged via g_warning(). - * </para></listitem> - * <listitem><para> - * Properties received via the initial <literal>GetAll()</literal> call - * or via the <literal>::PropertiesChanged</literal> signal (on the - * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface) or - * set using g_dbus_proxy_set_cached_property() with a type signature - * mismatch are ignored and a warning is logged via g_warning(). - * </para></listitem> - * </itemizedlist> + * - When completing a method call, if the type signature of + * the reply message isn't what's expected, the reply is + * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. + * + * - Received signals that have a type signature mismatch are dropped and + * a warning is logged via g_warning(). + * + * - Properties received via the initial `GetAll()` call or via the + * `::PropertiesChanged` signal (on the + * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) + * interface) or set using g_dbus_proxy_set_cached_property() + * with a type signature mismatch are ignored and a warning is + * logged via g_warning(). + * * Note that these checks are never done on methods, signals and * properties that are not referenced in the given * #GDBusInterfaceInfo, since extending a D-Bus interface on the @@ -1120,16 +1216,17 @@ * * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD * then the signal is emitted in a new thread dedicated to the - * connection. Otherwise the signal is emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread that @server was constructed in. + * connection. Otherwise the signal is emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @server was constructed in. * * You are guaranteed that signal handlers for this signal runs * before incoming messages on @connection are processed. This means * that it's suitable to call g_dbus_connection_register_object() or * similar from the signal handler. * - * Returns: %TRUE to claim @connection, %FALSE to let other handlers run. + * Returns: %TRUE to claim @connection, %FALSE to let other handlers + * run. * Since: 2.26 */ @@ -1440,15 +1537,15 @@ /** * GInetSocketAddress: * - * An IPv4 or IPv6 socket address, corresponding to a <type>struct - * sockaddr_in</type> or <type>struct sockaddr_in6</type>. + * An IPv4 or IPv6 socket address, corresponding to a struct + * sockaddr_in or struct sockaddr_in6. */ /** * GInetSocketAddress:flowinfo: * - * The <literal>sin6_flowinfo</literal> field, for IPv6 addresses. + * The `sin6_flowinfo` field, for IPv6 addresses. * * Since: 2.32 */ @@ -1457,7 +1554,7 @@ /** * GInetSocketAddress:scope_id: * - * The <literal>sin6_scope_id</literal> field, for IPv6 addresses. + * The `sin6_scope_id` field, for IPv6 addresses. * * Since: 2.32 */ @@ -1675,7 +1772,8 @@ * GMountOperation::show-processes: * @op: a #GMountOperation. * @message: string containing a message to display to the user. - * @processes: (element-type GPid): an array of #GPid for processes blocking the operation. + * @processes: (element-type GPid): an array of #GPid for processes + * blocking the operation. * @choices: an array of strings for each possible choice. * * Emitted when one or more processes are blocking an operation @@ -1699,8 +1797,11 @@ * GMountOperation::show-unmount-progress: * @op: a #GMountOperation: * @message: string containing a mesage to display to the user - * @time_left: the estimated time left before the operation completes, in microseconds, or -1 - * @bytes_left: the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed + * @time_left: the estimated time left before the operation completes, + * in microseconds, or -1 + * @bytes_left: the amount of bytes to be written before the operation + * completes (or -1 if such amount is not known), or zero if the operation + * is completed * * Emitted when an unmount operation has been busy for more than some time * (typically 1.5 seconds). @@ -1813,10 +1914,9 @@ * connected to a functioning router that has lost its own upstream * connectivity. Some hosts might only be accessible when a VPN is * active. Other hosts might only be accessible when the VPN is - * <emphasis>not</emphasis> active. Thus, it is best to use - * g_network_monitor_can_reach() or - * g_network_monitor_can_reach_async() to test for reachability on a - * host-by-host basis. (On the other hand, when the property is + * not active. Thus, it is best to use g_network_monitor_can_reach() + * or g_network_monitor_can_reach_async() to test for reachability + * on a host-by-host basis. (On the other hand, when the property is * %FALSE, the application can reasonably expect that no remote * hosts at all are reachable, and should indicate this to the user * in its UI.) @@ -1836,6 +1936,16 @@ /** + * GNotification: + * + * This structure type is private and should only be accessed using the + * public APIs. + * + * Since: 2.40 + */ + + +/** * GPermission: * * #GPermission is an opaque data structure and can only be accessed @@ -1868,6 +1978,89 @@ /** + * GPropertyAction: + * + * This type is opaque. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:enabled: + * + * If @action is currently enabled. + * + * If the action is disabled then calls to g_action_activate() and + * g_action_change_state() have no effect. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:name: + * + * The name of the action. This is mostly meaningful for identifying + * the action once it has been added to a #GActionMap. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:object: + * + * The object to wrap a property on. + * + * The object must be a non-%NULL #GObject with properties. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:parameter-type: + * + * The type of the parameter that must be given when activating the + * action. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:property-name: + * + * The name of the property to wrap on the object. + * + * The property must exist on the passed-in object and it must be + * readable and writable (and not construct-only). + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:state: + * + * The state of the action, or %NULL if the action is stateless. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:state-type: + * + * The #GVariantType of the state that the action has, or %NULL if the + * action is stateless. + * + * Since: 2.38 + */ + + +/** * GProxyAddress: * * A #GInetSocketAddress representing a connection via a proxy server @@ -1897,6 +2090,25 @@ /** + * GProxyAddressEnumerator:default-port: + * + * The default port to use if #GProxyAddressEnumerator:uri does not + * specify one. + * + * Since: 2.38 + */ + + +/** + * GProxyAddressEnumerator:proxy-resolver: + * + * The proxy resolver to use. + * + * Since: 2.36 + */ + + +/** * GRemoteActionGroupInterface: * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full() * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full() @@ -1927,7 +2139,8 @@ /** * GSettings::change-event: * @settings: the object on which the signal was emitted - * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL + * @keys: (array length=n_keys) (element-type GQuark) (allow-none): + * an array of #GQuarks for the changed keys, or %NULL * @n_keys: the length of the @keys array, or 0 * * The "change-event" signal is emitted once per change event that @@ -1946,7 +2159,8 @@ * for each affected key. If any other connected handler returns * %TRUE then this default functionality will be suppressed. * - * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * Returns: %TRUE to stop other handlers from being invoked for the + * event. FALSE to propagate the event further. */ @@ -1989,7 +2203,8 @@ * connected handler returns %TRUE then this default functionality * will be suppressed. * - * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * Returns: %TRUE to stop other handlers from being invoked for the + * event. FALSE to propagate the event further. */ @@ -2053,7 +2268,8 @@ * 'settings-schema' property if you wish to pass in a * #GSettingsSchema. * - * Deprecated: 2.32:Use the 'schema-id' property instead. In a future version, this property may instead refer to a #GSettingsSchema. + * Deprecated: 2.32: Use the 'schema-id' property instead. In a future + * version, this property may instead refer to a #GSettingsSchema. */ @@ -2106,6 +2322,14 @@ * @parameter will always be of the expected type. In the event that * an incorrect type was given, no signal will be emitted. * + * Since GLib 2.40, if no handler is connected to this signal then the + * default behaviour for boolean-stated actions with a %NULL parameter + * type is to toggle them via the #GSimpleAction::change-state signal. + * For stateful actions where the state type is equal to the parameter + * type, the default is to forward them directly to + * #GSimpleAction::change-state. This should allow almost all users + * of #GSimpleAction to connect only one handler or the other. + * * Since: 2.28 */ @@ -2123,13 +2347,12 @@ * * If no handler is connected to this signal then the default * behaviour is to call g_simple_action_set_state() to set the state - * to the requested value. If you connect a signal handler then no - * default action is taken. If the state should change then you must + * to the requested value. If you connect a signal handler then no + * default action is taken. If the state should change then you must * call g_simple_action_set_state() from the handler. * - * <example> - * <title>Example 'change-state' handler</title> - * <programlisting> + * An example of a 'change-state' handler: + * |[<!-- language="C" --> * static void * change_volume_state (GSimpleAction *action, * GVariant *value, @@ -2143,11 +2366,10 @@ * if (0 <= requested && requested <= 10) * g_simple_action_set_state (action, value); * } - * </programlisting> - * </example> + * ]| * - * The handler need not set the state to the requested value. It - * could set it to any value at all, or take some other action. + * The handler need not set the state to the requested value. + * It could set it to any value at all, or take some other action. * * Since: 2.30 */ @@ -2168,7 +2390,7 @@ /** * GSimpleAction:name: * - * The name of the action. This is mostly meaningful for identifying + * The name of the action. This is mostly meaningful for identifying * the action once it has been added to a #GSimpleActionGroup. * * Since: 2.28 @@ -2213,9 +2435,62 @@ /** + * GSimpleProxyResolver:default-proxy: + * + * The default proxy URI that will be used for any URI that doesn't + * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any + * of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). + * + * Note that as a special case, if this URI starts with + * "socks://", #GSimpleProxyResolver will treat it as referring + * to all three of the socks5, socks4a, and socks4 proxy types. + */ + + +/** + * GSimpleProxyResolver:ignore-hosts: + * + * A list of hostnames and IP addresses that the resolver should + * allow direct connections to. + * + * Entries can be in one of 4 formats: + * + * - A hostname, such as "example.com", ".example.com", or + * "*.example.com", any of which match "example.com" or + * any subdomain of it. + * + * - An IPv4 or IPv6 address, such as "192.168.1.1", + * which matches only that address. + * + * - A hostname or IP address followed by a port, such as + * "example.com:80", which matches whatever the hostname or IP + * address would match, but only for URLs with the (explicitly) + * indicated port. In the case of an IPv6 address, the address + * part must appear in brackets: "[::1]:443" + * + * - An IP address range, given by a base address and prefix length, + * such as "fe80::/10", which matches any address in that range. + * + * Note that when dealing with Unicode hostnames, the matching is + * done against the ASCII form of the name. + * + * Also note that hostname exclusions apply only to connections made + * to hosts identified by name, and IP address exclusions apply only + * to connections made to hosts identified by address. That is, if + * example.com has an address of 192.168.1.1, and the :ignore-hosts list + * contains only "192.168.1.1", then a connection to "example.com" + * (eg, via a #GNetworkAddress) will use the proxy, and a connection to + * "192.168.1.1" (eg, via a #GInetSocketAddress) will not. + * + * These rules match the "ignore-hosts"/"noproxy" rules most + * commonly used by other applications. + */ + + +/** * GSocket:broadcast: * - * Whether the socket should allow sending to and receiving from broadcast addresses. + * Whether the socket should allow sending to broadcast addresses. * * Since: 2.32 */ @@ -2260,7 +2535,7 @@ /** * GSocketAddress: * - * A socket endpoint address, corresponding to <type>struct sockaddr</type> + * A socket endpoint address, corresponding to struct sockaddr * or one of its subtypes. */ @@ -2277,79 +2552,40 @@ * information about a network connection in the UI. The meanings of * the different @event values are as follows: * - * <variablelist> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_RESOLVING:</term> - * <listitem><para> - * @client is about to look up @connectable in DNS. - * @connection will be %NULL. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_RESOLVED:</term> - * <listitem><para> - * @client has successfully resolved @connectable in DNS. - * @connection will be %NULL. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_CONNECTING:</term> - * <listitem><para> - * @client is about to make a connection to a remote host; - * either a proxy server or the destination server itself. - * @connection is the #GSocketConnection, which is not yet - * connected. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_CONNECTED:</term> - * <listitem><para> - * @client has successfully connected to a remote host. - * @connection is the connected #GSocketConnection. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term> - * <listitem><para> - * @client is about to negotiate with a proxy to get it to - * connect to @connectable. @connection is the - * #GSocketConnection to the proxy server. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term> - * <listitem><para> - * @client has negotiated a connection to @connectable through - * a proxy server. @connection is the stream returned from - * g_proxy_connect(), which may or may not be a - * #GSocketConnection. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term> - * <listitem><para> - * @client is about to begin a TLS handshake. @connection is a - * #GTlsClientConnection. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term> - * <listitem><para> - * @client has successfully completed the TLS handshake. - * @connection is a #GTlsClientConnection. - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>%G_SOCKET_CLIENT_COMPLETE:</term> - * <listitem><para> - * @client has either successfully connected to @connectable - * (in which case @connection is the #GSocketConnection that - * it will be returning to the caller) or has failed (in which - * case @connection is %NULL and the client is about to return - * an error). - * </para></listitem> - * </varlistentry> - * </variablelist> + * - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable + * in DNS. @connection will be %NULL. + * + * - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved + * @connectable in DNS. @connection will be %NULL. + * + * - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection + * to a remote host; either a proxy server or the destination server + * itself. @connection is the #GSocketConnection, which is not yet + * connected. Since GLib 2.40, you can access the remote + * address via g_socket_connection_get_remote_address(). + * + * - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected + * to a remote host. @connection is the connected #GSocketConnection. + * + * - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate + * with a proxy to get it to connect to @connectable. @connection is + * the #GSocketConnection to the proxy server. + * + * - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a + * connection to @connectable through a proxy server. @connection is + * the stream returned from g_proxy_connect(), which may or may not + * be a #GSocketConnection. + * + * - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS + * handshake. @connection is a #GTlsClientConnection. + * + * - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed + * the TLS handshake. @connection is a #GTlsClientConnection. + * + * - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected + * to @connectable (in which case @connection is the #GSocketConnection + * that it will be returning to the caller) or has failed (in which + * case @connection is %NULL and the client is about to return an error). * * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted * multiple times (or not at all) for a given connectable (in @@ -2366,10 +2602,20 @@ /** + * GSocketClient:proxy-resolver: + * + * The proxy resolver to use + * + * Since: 2.36 + */ + + +/** * GSocketService::incoming: * @service: the #GSocketService * @connection: a new #GSocketConnection object - * @source_object: (allow-none): the source_object passed to g_socket_listener_add_address() + * @source_object: (allow-none): the source_object passed to + * g_socket_listener_add_address() * * The ::incoming signal is emitted when a new incoming connection * to @service needs to be handled. The handler must initiate the @@ -2392,6 +2638,41 @@ /** + * GTask: + * + * The opaque object representing a synchronous or asynchronous task + * and its result. + */ + + +/** + * GTaskThreadFunc: + * @task: the #GTask + * @source_object: (type GObject): @task's source object + * @task_data: @task's task data + * @cancellable: @task's #GCancellable, or %NULL + * + * The prototype for a task function to be run in a thread via + * g_task_run_in_thread() or g_task_run_in_thread_sync(). + * + * If the return-on-cancel flag is set on @task, and @cancellable gets + * cancelled, then the #GTask will be completed immediately (as though + * g_task_return_error_if_cancelled() had been called), without + * waiting for the task function to complete. However, the task + * function will continue running in its thread in the background. The + * function therefore needs to be careful about how it uses + * externally-visible state in this case. See + * g_task_set_return_on_cancel() for more details. + * + * Other than in that case, @task will be completed when the + * #GTaskThreadFunc returns, not when it calls a + * `g_task_return_` function. + * + * Since: 2.36 + */ + + +/** * GTestDBus: * * The #GTestDBus structure contains only private data and @@ -2404,7 +2685,7 @@ /** * GTestDBus:flags: * - * #GTestDBusFlags specifying the behaviour of the dbus session + * #GTestDBusFlags specifying the behaviour of the D-Bus session. * * Since: 2.34 */ @@ -2433,7 +2714,7 @@ * * For example, if the icon name was "gnome-dev-cdrom-audio", the array * would become - * |[ + * |[<!-- language="C" --> * { * "gnome-dev-cdrom-audio", * "gnome-dev-cdrom", @@ -2524,7 +2805,7 @@ * but cannot be read. * * PKCS#8 format is supported since 2.32; earlier releases only - * support PKCS#1. You can use the <literal>openssl rsa</literal> + * support PKCS#1. You can use the `openssl rsa` * tool to convert PKCS#8 keys to PKCS#1. * * Since: 2.28 @@ -2535,14 +2816,14 @@ * GTlsCertificate:private-key-pem: * * The PEM (ASCII) encoded representation of the certificate's - * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE - * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN - * PRIVATE KEY</literal>"). This property (or the + * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE + * KEY`") or unencrypted PKCS#8 format ("`BEGIN + * PRIVATE KEY`"). This property (or the * #GTlsCertificate:private-key property) can be set when * constructing a key (eg, from a file), but cannot be read. * * PKCS#8 format is supported since 2.32; earlier releases only - * support PKCS#1. You can use the <literal>openssl rsa</literal> + * support PKCS#1. You can use the `openssl rsa` * tool to convert PKCS#8 keys to PKCS#1. * * Since: 2.28 @@ -2671,7 +2952,10 @@ * need to worry about this, and can simply block in the signal * handler until the UI thread returns an answer. * - * Returns: %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. + * Returns: %TRUE to accept @peer_cert (which will also + * immediately end the signal emission). %FALSE to allow the signal + * emission to continue, which will cause the handshake to fail if + * no one else overrides it. * Since: 2.28 */ @@ -2820,9 +3104,15 @@ /** * GTlsInteractionClass: - * @ask_password: ask for a password synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument should have been filled in by using g_tls_password_set_value() or a similar function. + * @ask_password: ask for a password synchronously. If the implementation + * returns %G_TLS_INTERACTION_HANDLED, then the password argument should + * have been filled in by using g_tls_password_set_value() or a similar + * function. * @ask_password_async: ask for a password asynchronously. - * @ask_password_finish: complete operation to ask for a password asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument of the async method should have been filled in by using g_tls_password_set_value() or a similar function. + * @ask_password_finish: complete operation to ask for a password asynchronously. + * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the + * password argument of the async method should have been filled in by using + * g_tls_password_set_value() or a similar function. * * The class for #GTlsInteraction. Derived classes implement the various * virtual interaction methods to handle TLS interactions. @@ -2929,7 +3219,7 @@ * GUnixSocketAddress: * * A UNIX-domain (local) socket address, corresponding to a - * <type>struct sockaddr_un</type>. + * struct sockaddr_un. */ @@ -2938,7 +3228,9 @@ * * Whether or not this is an abstract address * - * Deprecated: Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses. + * Deprecated: Use #GUnixSocketAddress:address-type, which + * distinguishes between zero-padded and non-zero-padded + * abstract addresses. */ @@ -3190,14 +3482,14 @@ * SECTION:extensionpoints * @short_description: Extension Points * @include: gio.h - * @see_also: <link linkend="extending-gio">Extending GIO</link> + * @see_also: [Extending GIO][extending-gio] * * #GIOExtensionPoint provides a mechanism for modules to extend the * functionality of the library or application that loaded it in an * organized fashion. * * An extension point is identified by a name, and it may optionally - * require that any implementation must by of a certain type (or derived + * require that any implementation must be of a certain type (or derived * thereof). Use g_io_extension_point_register() to register an * extension point, and g_io_extension_point_set_required_type() to * set a required type. @@ -3207,16 +3499,16 @@ * of an extension point has a name, and a priority. Use * g_io_extension_point_implement() to implement an extension point. * - * |[ + * |[<!-- language="C" --> * GIOExtensionPoint *ep; * - * /* Register an extension point */ + * // Register an extension point * ep = g_io_extension_point_register ("my-extension-point"); * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); * ]| * - * |[ - * /* Implement an extension point */ + * |[<!-- language="C" --> + * // Implement an extension point * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE); * g_io_extension_point_implement ("my-extension-point", * my_example_impl_get_type (), @@ -3232,14 +3524,14 @@ * * To avoid opening all modules just to find out what extension * points they implement, GIO makes use of a caching mechanism, - * see <link linkend="gio-querymodules">gio-querymodules</link>. + * see [gio-querymodules][gio-querymodules]. * You are expected to run this command after installing a * GIO module. * - * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be - * used to specify additional directories to automatically load modules + * The `GIO_EXTRA_MODULES` environment variable can be used to + * specify additional directories to automatically load modules * from. This environment variable has the same syntax as the - * <envar>PATH</envar>. If two modules have the same base name in different + * `PATH`. If two modules have the same base name in different * directories, then the latter one will be ignored. If additional * directories are specified GIO will load modules from the built-in * directory last. @@ -3250,6 +3542,7 @@ * SECTION:gaction * @title: GAction * @short_description: An action interface + * @include: gio/gio.h * * #GAction represents a single named action. * @@ -3269,7 +3562,7 @@ * * #GAction is merely the interface to the concept of an action, as * described above. Various implementations of actions exist, including - * #GSimpleAction and #GtkAction. + * #GSimpleAction. * * In all cases, the implementing class is responsible for storing the * name of the action, the parameter type, the enabled state, the @@ -3287,6 +3580,7 @@ * SECTION:gactiongroup * @title: GActionGroup * @short_description: A group of actions + * @include: gio/gio.h * @see_also: #GAction * * #GActionGroup represents a group of actions. Actions can be used to @@ -3324,7 +3618,7 @@ * with actions. 'Internal' APIs (ie: ones meant only to be accessed by * the action group implementation) are found on subclasses. This is * why you will find - for example - g_action_group_get_action_enabled() - * but not an equivalent <function>set()</function> call. + * but not an equivalent set() call. * * Signals are emitted on the action group in response to state changes * on individual actions. @@ -3340,6 +3634,7 @@ /** * SECTION:gactiongroupexporter * @title: GActionGroup exporter + * @include: gio/gio.h * @short_description: Export GActionGroups on D-Bus * @see_also: #GActionGroup, #GDBusActionGroup * @@ -3355,6 +3650,7 @@ /** * SECTION:gactionmap * @title: GActionMap + * @include: gio/gio.h * @short_description: Interface for action containers * * The GActionMap interface is implemented by #GActionGroup @@ -3375,6 +3671,7 @@ * SECTION:gappinfo * @short_description: Application information and launch contexts * @include: gio/gio.h + * @see_also: #GAppInfoMonitor * * #GAppInfo and #GAppLaunchContext are used for describing and launching * applications installed on the system. @@ -3382,15 +3679,13 @@ * As of GLib 2.20, URIs will always be converted to POSIX paths * (using g_file_get_path()) when using g_app_info_launch() even if * the application requested an URI and not a POSIX path. For example - * for an desktop-file based application with Exec key <literal>totem - * %U</literal> and a single URI, - * <literal>sftp://foo/file.avi</literal>, then - * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be - * passed. This will only work if a set of suitable GIO extensions - * (such as gvfs 2.26 compiled with FUSE support), is available and - * operational; if this is not the case, the URI will be passed - * unmodified to the application. Some URIs, such as - * <literal>mailto:</literal>, of course cannot be mapped to a POSIX + * for an desktop-file based application with Exec key `totem + * \%U` and a single URI, `sftp://foo/file.avi`, then + * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will + * only work if a set of suitable GIO extensions (such as gvfs 2.26 + * compiled with FUSE support), is available and operational; if this + * is not the case, the URI will be passed unmodified to the application. + * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX * path (in gvfs there's no FUSE mount for it); such URIs will be * passed unmodified to the application. * @@ -3403,14 +3698,14 @@ * equal to the result of g_file_get_uri(). The following snippet * illustrates this: * - * <programlisting> + * |[ * GFile *f; * char *uri; * * file = g_file_new_for_commandline_arg (uri_from_commandline); * * uri = g_file_get_uri (file); - * strcmp (uri, uri_from_commandline) == 0; // FALSE + * strcmp (uri, uri_from_commandline) == 0; * g_free (uri); * * if (g_file_has_uri_scheme (file, "cdda")) @@ -3418,14 +3713,40 @@ * // do something special with uri * } * g_object_unref (file); - * </programlisting> + * ]| + * + * This code will work when both `cdda://sr0/Track 1.wav` and + * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the + * application. It should be noted that it's generally not safe + * for applications to rely on the format of a particular URIs. + * Different launcher applications (e.g. file managers) may have + * different ideas of what a given URI means. + */ + + +/** + * SECTION:gappinfomonitor + * @short_description: Monitor application information for changes * - * This code will work when both <literal>cdda://sr0/Track - * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track - * 1.wav</literal> is passed to the application. It should be noted - * that it's generally not safe for applications to rely on the format - * of a particular URIs. Different launcher applications (e.g. file - * managers) may have different ideas of what a given URI means. + * #GAppInfoMonitor is a very simple object used for monitoring the app + * info database for changes (ie: newly installed or removed + * applications). + * + * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect + * to the "changed" signal. + * + * In the usual case, applications should try to make note of the change + * (doing things like invalidating caches) but not act on it. In + * particular, applications should avoid making calls to #GAppInfo APIs + * in response to the change signal, deferring these until the time that + * the data is actually required. The exception to this case is when + * application information is actually being displayed on the screen + * (eg: during a search or when the list of all applications is shown). + * The reason for this is that changes to the list of installed + * applications often come in groups (like during system updates) and + * rescanning the list on every change is pointless and expensive. + * + * Since: 2.40 */ @@ -3433,6 +3754,7 @@ * SECTION:gapplication * @title: GApplication * @short_description: Core application class + * @include: gio/gio.h * * A #GApplication is the foundation of an application. It wraps some * low-level platform-specific services and is intended to act as the @@ -3441,41 +3763,40 @@ * this class outside of a higher level framework. * * GApplication provides convenient life cycle management by maintaining - * a <firstterm>use count</firstterm> for the primary application instance. - * The use count can be changed using g_application_hold() and - * g_application_release(). If it drops to zero, the application exits. - * Higher-level classes such as #GtkApplication employ the use count to - * ensure that the application stays alive as long as it has any opened - * windows. + * a "use count" for the primary application instance. The use count can + * be changed using g_application_hold() and g_application_release(). If + * it drops to zero, the application exits. Higher-level classes such as + * #GtkApplication employ the use count to ensure that the application + * stays alive as long as it has any opened windows. * * Another feature that GApplication (optionally) provides is process - * uniqueness. Applications can make use of this functionality by - * providing a unique application ID. If given, only one application - * with this ID can be running at a time per session. The session + * uniqueness. Applications can make use of this functionality by + * providing a unique application ID. If given, only one application + * with this ID can be running at a time per session. The session * concept is platform-dependent, but corresponds roughly to a graphical - * desktop login. When your application is launched again, its + * desktop login. When your application is launched again, its * arguments are passed through platform communication to the already - * running program. The already running instance of the program is - * called the <firstterm>primary instance</firstterm>; for non-unique - * applications this is the always the current instance. - * On Linux, the D-Bus session bus is used for communication. + * running program. The already running instance of the program is + * called the "primary instance"; for non-unique applications this is + * the always the current instance. On Linux, the D-Bus session bus + * is used for communication. * * The use of #GApplication differs from some other commonly-used - * uniqueness libraries (such as libunique) in important ways. The - * application is not expected to manually register itself and check if - * it is the primary instance. Instead, the <code>main()</code> - * function of a #GApplication should do very little more than - * instantiating the application instance, possibly connecting signal - * handlers, then calling g_application_run(). All checks for - * uniqueness are done internally. If the application is the primary - * instance then the startup signal is emitted and the mainloop runs. - * If the application is not the primary instance then a signal is sent - * to the primary instance and g_application_run() promptly returns. - * See the code examples below. + * uniqueness libraries (such as libunique) in important ways. The + * application is not expected to manually register itself and check + * if it is the primary instance. Instead, the main() function of a + * #GApplication should do very little more than instantiating the + * application instance, possibly connecting signal handlers, then + * calling g_application_run(). All checks for uniqueness are done + * internally. If the application is the primary instance then the + * startup signal is emitted and the mainloop runs. If the application + * is not the primary instance then a signal is sent to the primary + * instance and g_application_run() promptly returns. See the code + * examples below. * * If used, the expected form of an application identifier is very close * to that of of a - * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>. + * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface). * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator". * For details on valid application identifiers, see g_application_id_is_valid(). * @@ -3502,23 +3823,26 @@ * for remote access to exported #GMenuModels. * * There is a number of different entry points into a GApplication: - * <itemizedlist> - * <listitem>via 'Activate' (i.e. just starting the application)</listitem> - * <listitem>via 'Open' (i.e. opening some files)</listitem> - * <listitem>by handling a command-line</listitem> - * <listitem>via activating an action</listitem> - * </itemizedlist> + * + * - via 'Activate' (i.e. just starting the application) + * + * - via 'Open' (i.e. opening some files) + * + * - by handling a command-line + * + * - via activating an action + * * The #GApplication::startup signal lets you handle the application * initialization for all of these in a single place. * - * Regardless of which of these entry points is used to start the application, - * GApplication passes some <firstterm id="platform-data">platform - * data</firstterm> from the launching instance to the primary instance, - * in the form of a #GVariant dictionary mapping strings to variants. - * To use platform data, override the @before_emit or @after_emit virtual - * functions in your #GApplication subclass. When dealing with - * #GApplicationCommandLine objects, the platform data is directly - * available via g_application_command_line_get_cwd(), + * Regardless of which of these entry points is used to start the + * application, GApplication passes some "platform data from the + * launching instance to the primary instance, in the form of a + * #GVariant dictionary mapping strings to variants. To use platform + * data, override the @before_emit or @after_emit virtual functions + * in your #GApplication subclass. When dealing with + * #GApplicationCommandLine objects, the platform data is + * directly available via g_application_command_line_get_cwd(), * g_application_command_line_get_environ() and * g_application_command_line_get_platform_data(). * @@ -3537,37 +3861,14 @@ * vfunc, to parse them in either the primary instance or the local instance, * respectively. * - * <example id="gapplication-example-open"><title>Opening files with a GApplication</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-actions"><title>A GApplication with actions</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-menu"><title>A GApplication with menus</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-dbushooks.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> + * For an example of opening files with a GApplication, see + * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). + * + * For an example of using actions with GApplication, see + * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). + * + * For an example of using extra D-Bus hooks with GApplication, see + * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). */ @@ -3575,6 +3876,7 @@ * SECTION:gapplicationcommandline * @title: GApplicationCommandLine * @short_description: A command-line invocation of an application + * @include: gio/gio.h * @see_also: #GApplication * * #GApplicationCommandLine represents a command-line invocation of @@ -3590,7 +3892,8 @@ * The GApplicationCommandLine object can provide the @argc and @argv * parameters for use with the #GOptionContext command-line parsing API, * with the g_application_command_line_get_arguments() function. See - * <xref linkend="gapplication-example-cmdline3"/> for an example. + * [gapplication-example-cmdline3.c][gapplication-example-cmdline3] + * for an example. * * The exit status of the originally-invoked process may be set and * messages can be printed to stdout or stderr of that process. The @@ -3600,64 +3903,136 @@ * * The main use for #GApplicationCommandLine (and the * #GApplication::command-line signal) is 'Emacs server' like use cases: - * You can set the <envar>EDITOR</envar> environment variable to have - * e.g. git use your favourite editor to edit commit messages, and if you - * already have an instance of the editor running, the editing will happen + * You can set the `EDITOR` environment variable to have e.g. git use + * your favourite editor to edit commit messages, and if you already + * have an instance of the editor running, the editing will happen * in the running instance, instead of opening a new one. An important * aspect of this use case is that the process that gets started by git * does not return until the editing is done. * - * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title> - * <para> - * A simple example where the commandline is completely handled - * in the #GApplication::command-line handler. The launching instance exits - * once the signal handler in the primary instance has returned, and the - * return value of the signal handler becomes the exit status of the launching - * instance. - * </para> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title> - * <para> - * An example of split commandline handling. Options that start with - * <literal>--local-</literal> are handled locally, all other options are - * passed to the #GApplication::command-line handler which runs in the primary + * Normally, the commandline is completely handled in the + * #GApplication::command-line handler. The launching instance exits + * once the signal handler in the primary instance has returned, and + * the return value of the signal handler becomes the exit status + * of the launching instance. + * |[<!-- language="C" --> + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * gchar **argv; + * gint argc; + * gint i; + * + * argv = g_application_command_line_get_arguments (cmdline, &argc); + * + * g_application_command_line_print (cmdline, + * "This text is written back\n" + * "to stdout of the caller\n"); + * + * for (i = 0; i < argc; i++) + * g_print ("argument %d: %s\n", i, argv[i]); + * + * g_strfreev (argv); + * + * return 0; + * } + * ]| + * The complete example can be found here: + * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) + * + * In more complicated cases, the handling of the comandline can be + * split between the launcher and the primary instance. + * |[<!-- language="C" --> + * static gboolean + * test_local_cmdline (GApplication *application, + * gchar ***arguments, + * gint *exit_status) + * { + * gint i, j; + * gchar **argv; + * + * argv = *arguments; + * + * i = 1; + * while (argv[i]) + * { + * if (g_str_has_prefix (argv[i], "--local-")) + * { + * g_print ("handling argument %s locally\n", argv[i]); + * g_free (argv[i]); + * for (j = i; argv[j]; j++) + * argv[j] = argv[j + 1]; + * } + * else + * { + * g_print ("not handling argument %s locally\n", argv[i]); + * i++; + * } + * } + * + * *exit_status = 0; + * + * return FALSE; + * } + * + * static void + * test_application_class_init (TestApplicationClass *class) + * { + * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; + * + * ... + * } + * ]| + * In this example of split commandline handling, options that start + * with `--local-` are handled locally, all other options are passed + * to the #GApplication::command-line handler which runs in the primary * instance. - * </para> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title> - * <para> - * An example of deferred commandline handling. Here, the commandline is - * not completely handled before the #GApplication::command-line handler - * returns. Instead, we keep a reference to the GApplicationCommandLine - * object and handle it later(in this example, in an idle). Note that it - * is necessary to hold the application until you are done with the - * commandline. - * </para> - * <para> - * This example also shows how to use #GOptionContext for parsing the - * commandline arguments. Note that it is necessary to disable the - * built-in help-handling of #GOptionContext, since it calls exit() - * after printing help, which is not what you want to happen in - * the primary instance. - * </para> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> + * + * The complete example can be found here: + * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) + * + * If handling the commandline requires a lot of work, it may + * be better to defer it. + * |[<!-- language="C" --> + * static gboolean + * my_cmdline_handler (gpointer data) + * { + * GApplicationCommandLine *cmdline = data; + * + * // do the heavy lifting in an idle + * + * g_application_command_line_set_exit_status (cmdline, 0); + * g_object_unref (cmdline); // this releases the application + * + * return G_SOURCE_REMOVE; + * } + * + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * // keep the application running until we are done with this commandline + * g_application_hold (application); + * + * g_object_set_data_full (G_OBJECT (cmdline), + * "application", application, + * (GDestroyNotify)g_application_release); + * + * g_object_ref (cmdline); + * g_idle_add (my_cmdline_handler, cmdline); + * + * return 0; + * } + * ]| + * In this example the commandline is not completely handled before + * the #GApplication::command-line handler returns. Instead, we keep + * a reference to the #GApplicationCommandLine object and handle it + * later (in this example, in an idle). Note that it is necessary to + * hold the application until you are done with the commandline. + * + * The complete example can be found here: + * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c) */ @@ -3682,7 +4057,7 @@ * * A typical implementation might look something like this: * - * |[ + * |[<!-- language="C" --> * enum { * NOT_INITIALIZED, * INITIALIZING, @@ -3698,13 +4073,13 @@ * * for (l = self->priv->init_results; l != NULL; l = l->next) * { - * GSimpleAsyncResult *simple = l->data; - * - * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); + * GTask *task = l->data; * - * g_simple_async_result_complete (simple); - * g_object_unref (simple); + * if (self->priv->success) + * g_task_return_boolean (task, TRUE); + * else + * g_task_return_new_error (task, ...); + * g_object_unref (task); * } * * g_list_free (self->priv->init_results); @@ -3719,31 +4094,28 @@ * gpointer user_data) * { * Foo *self = FOO (initable); - * GSimpleAsyncResult *simple; + * GTask *task; * - * simple = g_simple_async_result_new (G_OBJECT (initable) - * callback, - * user_data, - * foo_init_async); + * task = g_task_new (initable, cancellable, callback, user_data); * * switch (self->priv->state) * { * case NOT_INITIALIZED: * _foo_get_ready (self); * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); + * task); * self->priv->state = INITIALIZING; * break; * case INITIALIZING: * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); + * task); * break; * case INITIALIZED: * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); - * - * g_simple_async_result_complete_in_idle (simple); - * g_object_unref (simple); + * g_task_return_new_error (task, ...); + * else + * g_task_return_boolean (task, TRUE); + * g_object_unref (task); * break; * } * } @@ -3753,14 +4125,9 @@ * GAsyncResult *result, * GError **error) * { - * g_return_val_if_fail (g_simple_async_result_is_valid (result, - * G_OBJECT (initable), foo_init_async), FALSE); - * - * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), - * error)) - * return FALSE; + * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE); * - * return TRUE; + * return g_task_propagate_boolean (G_TASK (result), error); * } * * static void @@ -3780,7 +4147,7 @@ * SECTION:gasyncresult * @short_description: Asynchronous Function Results * @include: gio/gio.h - * @see_also: #GSimpleAsyncResult + * @see_also: #GTask * * Provides a base class for implementing asynchronous function results. * @@ -3809,10 +4176,10 @@ * however, the "_finish()" function may be called at most once. * * Example of a typical asynchronous operation flow: - * |[ + * |[<!-- language="C" --> * void _theoretical_frobnitz_async (Theoretical *t, * GCancellable *c, - * GAsyncReadyCallback *cb, + * GAsyncReadyCallback cb, * gpointer u); * * gboolean _theoretical_frobnitz_finish (Theoretical *t, @@ -3833,26 +4200,36 @@ * else * g_printf ("Uh oh!\n"); * - * /<!-- -->* ... *<!-- -->/ + * ... * * } * * int main (int argc, void *argv[]) * { - * /<!-- -->* ... *<!-- -->/ + * ... * * _theoretical_frobnitz_async (theoretical_data, * NULL, * frobnitz_result_func, * NULL); * - * /<!-- -->* ... *<!-- -->/ + * ... * } * ]| * * The callback for an asynchronous operation is called only once, and is * always called, even in the case of a cancelled operation. On cancellation * the result is a %G_IO_ERROR_CANCELLED error. + * + * ## I/O Priority # {#io-priority} + * + * Many I/O-related asynchronous operations have a priority parameter, + * which is used in certain cases to determine the order in which + * operations are executed. They are not used to determine system-wide + * I/O scheduling. Priorities are integers, with lower numbers indicating + * higher priority. It is recommended to choose priorities between + * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT + * as a default. */ @@ -3903,6 +4280,19 @@ /** + * SECTION:gbytesicon + * @short_description: An icon stored in memory as a GBytes + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon, #GBytes + * + * #GBytesIcon specifies an image held in memory in a common format (usually + * png) to be used as icon. + * + * Since: 2.38 + */ + + +/** * SECTION:gcancellable * @short_description: Thread-safe Operation Cancellation Stack * @include: gio/gio.h @@ -3929,7 +4319,9 @@ * @include: gio/gio.h * * A content type is a platform specific string that defines the type - * 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". + * of a file. On UNIX it is a + * [mime type](http://www.wikipedia.org/wiki/Internet_media_type) + * like "text/plain" or "image/png". * On Win32 it is an extension string like ".doc", ".txt" or a perceived * string like "audio". Such strings can be looked up in the registry at * HKEY_CLASSES_ROOT. @@ -4000,17 +4392,20 @@ * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and * g_unix_connection_receive_credentials() for details. * - * On Linux, the native credential type is a <type>struct ucred</type> - * - see the - * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> - * man page for details. This corresponds to + * On Linux, the native credential type is a struct ucred - see the + * unix(7) man page for details. This corresponds to * %G_CREDENTIALS_TYPE_LINUX_UCRED. * - * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>. - * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. + * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native + * credential type is a struct cmsgcred. This corresponds + * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. * - * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>. + * On OpenBSD, the native credential type is a struct sockpeercred. * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. + * + * On Solaris (including OpenSolaris and its derivatives), the native + * credential type is a ucred_t. This corresponds to + * %G_CREDENTIALS_TYPE_SOLARIS_UCRED. */ @@ -4040,7 +4435,8 @@ * SECTION:gdbusactiongroup * @title: GDBusActionGroup * @short_description: A D-Bus GActionGroup implementation - * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link> + * @include: gio/gio.h + * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter] * * #GDBusActionGroup is an implementation of the #GActionGroup * interface that can be used as a proxy for an action group @@ -4056,7 +4452,7 @@ * * Routines for working with D-Bus addresses. A D-Bus address is a string * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses - * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>. + * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses). */ @@ -4071,10 +4467,13 @@ * signals you are interested in. Note that new signals may be added * in the future * + * ## Controlling Authentication # {#auth-observer} + * * For example, if you only want to allow D-Bus connections from * processes owned by the same uid as the server, you would use a * signal handler like the following: - * <example id="auth-observer"><title>Controlling Authentication</title><programlisting> + * + * |[ * static gboolean * on_authorize_authenticated_peer (GDBusAuthObserver *observer, * GIOStream *stream, @@ -4095,7 +4494,7 @@ * * return authorized; * } - * </programlisting></example> + * ]| */ @@ -4113,14 +4512,10 @@ * an D-Bus client, it is often easier to use the g_bus_own_name(), * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. * - * As an exception to the usual GLib rule that a particular object must not be - * used by two threads at the same time, #GDBusConnection's methods may be - * called from any thread<footnote> - * <para> - * This is so that g_bus_get() and g_bus_get_sync() can safely return the - * same #GDBusConnection when called from any thread. - * </para> - * </footnote>. + * As an exception to the usual GLib rule that a particular object must not + * be used by two threads at the same time, #GDBusConnection's methods may be + * called from any thread. This is so that g_bus_get() and g_bus_get_sync() + * can safely return the same #GDBusConnection when called from any thread. * * Most of the ways to obtain a #GDBusConnection automatically initialize it * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and @@ -4138,13 +4533,25 @@ * #GError, the only valid thing you can do with that #GDBusConnection is to * free it with g_object_unref(). * - * <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> + * ## An example D-Bus server # {#gdbus-server} + * + * Here is an example for a D-Bus server: + * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c) + * + * ## An example for exporting a subtree # {#gdbus-subtree-server} + * + * Here is an example for exporting a subtree: + * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c) * - * <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> + * ## An example for file descriptor passing # {#gdbus-unix-fd-client} * - * <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> + * Here is an example for passing UNIX file descriptors: + * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c) * - * <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> + * ## An example for exporting a GObject # {#gdbus-export} + * + * Here is an example for exporting a #GObject: + * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c) */ @@ -4172,8 +4579,8 @@ * automatically map from D-Bus errors to #GError and back. This * is typically done in the function returning the #GQuark for the * error domain: - * <example id="error-registration"><title>Error Registration</title><programlisting> - * /<!-- -->* foo-bar-error.h: *<!-- -->/ + * |[<!-- language="C" --> + * // foo-bar-error.h: * * #define FOO_BAR_ERROR (foo_bar_error_quark ()) * GQuark foo_bar_error_quark (void); @@ -4183,10 +4590,10 @@ * FOO_BAR_ERROR_FAILED, * FOO_BAR_ERROR_ANOTHER_ERROR, * FOO_BAR_ERROR_SOME_THIRD_ERROR, - * FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/ + * FOO_BAR_N_ERRORS / *< skip >* / * } FooBarError; * - * /<!-- -->* foo-bar-error.c: *<!-- -->/ + * // foo-bar-error.c: * * static const GDBusErrorEntry foo_bar_error_entries[] = * { @@ -4195,7 +4602,7 @@ * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, * }; * - * /<!-- -->* Ensure that every error code has an associated D-Bus error name *<!-- -->/ + * // Ensure that every error code has an associated D-Bus error name * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); * * GQuark @@ -4208,12 +4615,15 @@ * G_N_ELEMENTS (foo_bar_error_entries)); * return (GQuark) quark_volatile; * } - * </programlisting></example> + * ]| * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and - * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>. - * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead + * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError. + * + * If the other peer is using GDBus, and has registered the association with + * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark + * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover - * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error(). + * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). * * Note that errors in the %G_DBUS_ERROR error domain is intended only * for returning errors from a remote message bus process. Errors @@ -4253,7 +4663,7 @@ * used when registering objects with g_dbus_connection_register_object(). * * The format of D-Bus introspection XML is specified in the - * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>. + * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) */ @@ -4261,7 +4671,8 @@ * SECTION:gdbusmenumodel * @title: GDBusMenuModel * @short_description: A D-Bus GMenuModel implementation - * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link> + * @include: gio/gio.h + * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter] * * #GDBusMenuModel is an implementation of #GMenuModel that can be used * as a proxy for a menu model that is exported over D-Bus with @@ -4302,7 +4713,8 @@ * * Convenience API for owning bus names. * - * <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> + * A simple example for owning a name can be found in + * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c) */ @@ -4314,7 +4726,8 @@ * * Convenience API for watching bus names. * - * <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> + * A simple example for watching a name can be found in + * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c) */ @@ -4336,8 +4749,8 @@ * @include: gio/gio.h * * The #GDBusObjectManager type is the base type for service- and - * client-side implementations of the standardized <ulink - * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> + * client-side implementations of the standardized + * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface. * * See #GDBusObjectManagerClient for the client-side implementation @@ -4352,8 +4765,8 @@ * * #GDBusObjectManagerClient is used to create, monitor and delete object * proxies for remote objects exported by a #GDBusObjectManagerServer (or any - * code implementing the <ulink - * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> + * code implementing the + * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface). * * Once an instance of this type has been created, you can connect to @@ -4393,18 +4806,17 @@ * is set to the new name owner (this includes emission of the * #GObject::notify signal). Furthermore, you are guaranteed that * #GDBusObjectManagerClient:name-owner will alternate between a name owner - * (e.g. <literal>:1.42</literal>) and %NULL even in the case where + * (e.g. `:1.42`) and %NULL even in the case where * the name of interest is atomically replaced * * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy * instances. All signals (including the - * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal> - * signal) delivered to #GDBusProxy instances are guaranteed to - * originate from the name owner. This guarantee along with the - * behavior described above, means that certain race conditions - * including the <emphasis><quote>half the proxy is from the old owner - * and the other half is from the new owner</quote></emphasis> problem - * cannot happen. + * org.freedesktop.DBus.Properties::PropertiesChanged signal) + * delivered to #GDBusProxy instances are guaranteed to originate + * from the name owner. This guarantee along with the behavior + * described above, means that certain race conditions including the + * "half the proxy is from the old owner and the other half is from + * the new owner" problem cannot happen. * * To avoid having the application connect to signals on the returned * #GDBusObjectProxy and #GDBusProxy objects, the @@ -4420,7 +4832,7 @@ * #GDBusObjectManagerClient::interface-proxy-signal. * * Note that all callbacks and signals are emitted in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main context][g-main-context-push-thread-default] * that the #GDBusObjectManagerClient object was constructed * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects * originating from the #GDBusObjectManagerClient object will be created in @@ -4435,8 +4847,8 @@ * @include: gio/gio.h * * #GDBusObjectManagerServer is used to export #GDBusObject instances using - * the standardized <ulink - * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> + * the standardized + * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface. For example, remote D-Bus clients can get all objects * and properties in a single call. Additionally, any change in the * object hierarchy is broadcast using signals. This means that D-Bus @@ -4506,21 +4918,20 @@ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). * * The generic #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals are not very convenient to work - * with. Therefore, the recommended way of working with proxies is to - * subclass #GDBusProxy, and have more natural properties and signals - * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/> - * for how this can easily be done using the - * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command> - * tool. + * #GDBusProxy::g-signal signals are not very convenient to work with. + * Therefore, the recommended way of working with proxies is to subclass + * #GDBusProxy, and have more natural properties and signals in your derived + * class. This [example][gdbus-example-gdbus-codegen] shows how this can + * easily be done using the [gdbus-codegen][gdbus-codegen] tool. * * A #GDBusProxy instance can be used from multiple threads but note * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed * and #GObject::notify) are emitted in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main context][g-main-context-push-thread-default] * of the thread where the instance was constructed. * - * <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> + * An example using a proxy for a well-known name can be found in + * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c) */ @@ -4538,14 +4949,15 @@ * To just export an object on a well-known name on a message bus, such as the * session or system bus, you should instead use g_bus_own_name(). * - * <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> + * An example of peer-to-peer communication with G-DBus can be found + * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). */ /** * SECTION:gdbusutils * @title: D-Bus Utilities - * @short_description: Various utilities related to D-Bus. + * @short_description: Various utilities related to D-Bus * @include: gio/gio.h * * Various utility routines related to D-Bus. @@ -4561,9 +4973,9 @@ * #GDesktopAppInfo is an implementation of #GAppInfo based on * desktop files. * - * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific + * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -4579,7 +4991,7 @@ * #GDrive is a container class for #GVolume objects that stem from * the same piece of media. As such, #GDrive abstracts a drive with * (or without) removable media and provides operations for querying - * whether media is available, determing whether media change is + * whether media is available, determining whether media change is * automatically detected and ejecting the media. * * If the #GDrive reports that media isn't automatically detected, one @@ -4645,13 +5057,11 @@ * (see #GInputStream and #GOutputStream). * * To construct a #GFile, you can use: - * <simplelist> - * <member>g_file_new_for_path() if you have a path.</member> - * <member>g_file_new_for_uri() if you have a URI.</member> - * <member>g_file_new_for_commandline_arg() for a command line argument.</member> - * <member>g_file_new_tmp() to create a temporary file from a template.</member> - * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member> - * </simplelist> + * - g_file_new_for_path() if you have a path. + * - g_file_new_for_uri() if you have a URI. + * - g_file_new_for_commandline_arg() for a command line argument. + * - g_file_new_tmp() to create a temporary file from a template. + * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). * * One way to think of a #GFile is as an abstraction of a pathname. For * normal files the system pathname is what is stored internally, but as @@ -4700,20 +5110,19 @@ * Some #GFile operations do not have synchronous analogs, as they may * take a very long time to finish, and blocking may leave an application * unusable. Notable cases include: - * <simplelist> - * <member>g_file_mount_mountable() to mount a mountable file.</member> - * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member> - * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member> - * </simplelist> + * - g_file_mount_mountable() to mount a mountable file. + * - g_file_unmount_mountable_with_operation() to unmount a mountable file. + * - g_file_eject_mountable_with_operation() to eject a mountable file. + * + * ## Entity Tags # {#gfile-etag} * - * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm> * One notable feature of #GFiles are entity tags, or "etags" for * short. Entity tags are somewhat like a more abstract version of the - * traditional mtime, and can be used to quickly determine if the file has - * been modified from the version on the file system. See the HTTP 1.1 - * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink> + * traditional mtime, and can be used to quickly determine if the file + * has been modified from the version on the file system. See the + * HTTP 1.1 + * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) * for HTTP Etag headers, which are a very similar concept. - * </para> */ @@ -4726,7 +5135,7 @@ * File attributes in GIO consist of a list of key-value pairs. * * Keys are strings that contain a key namespace and a key name, separated - * by a colon, e.g. "namespace:keyname". Namespaces are included to sort + * by a colon, e.g. "namespace::keyname". Namespaces are included to sort * key-value pairs by namespaces for relevance. Keys can be retrived * using wildcards, e.g. "standard::*" will return all of the keys in the * "standard" namespace. @@ -4745,70 +5154,62 @@ * and other possible implementation details (e.g., on a UNIX system, a file * attribute key will be registered for the user id for a given file). * - * <para> - * <table> - * <title>GFileAttributes Default Namespaces</title> - * <tgroup cols='2' align='left'><thead> - * <row><entry>Namspace</entry><entry>Description</entry></row> - * </thead> - * <tbody> - * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file - * information that any application may need should be put in this namespace. - * Examples include the file's name, type, and size.</entry></row> - * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link> - * namespace. Currently, the only key in this namespace is "value", which contains - * the value of the current entity tag.</entry></row> - * <row><entry>"id"</entry><entry>The "Identification" namespace. This - * namespace is used by file managers and applications that list directories - * to check for loops and to uniquely identify files.</entry></row> - * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check - * if a user has the proper privilidges to access files and perform - * file operations. Keys in this namespace are made to be generic - * and easily understood, e.g. the "can_read" key is %TRUE if - * the current user has permission to read the file. UNIX permissions and - * NTFS ACLs in Windows should be mapped to these values.</entry></row> - * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes - * simple boolean keys for checking if a file or path supports mount operations, e.g. - * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row> - * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file - * access, changed, created times. </entry></row> - * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific - * information and may not be available for all files. Examples include - * the UNIX "UID", "GID", etc.</entry></row> - * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific - * information and may not be available for all files. Examples include - * "is_system" for checking if a file is marked as a system file, and "is_archive" - * for checking if a file is marked as an archive file.</entry></row> - * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information - * about who owns a file. May not be available for all file systems. Examples include - * "user" for getting the user name of the file owner. This information is often mapped from - * some backend specific data such as a unix UID.</entry></row> - * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes - * information about file thumbnails and their location within the file system. Examples of - * keys in this namespace include "path" to get the location of a thumbnail, and "failed" - * to check if thumbnailing of the file failed.</entry></row> - * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information - * about the file system where a file is located, such as its type, how much - * space is left available, and the overall size of the file system.</entry></row> - * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace - * contain information about the current GVFS backend in use. </entry></row> - * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information - * about extended user attributes. See attr(5). The "user." prefix of the - * extended user attribute name is stripped away when constructing keys in - * this namespace, e.g. "xattr::mime_type" for the extended attribute with - * the name "user.mime_type". Note that this information is only available - * if GLib has been built with extended attribute support.</entry></row> - * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace. - * Gets information about extended attributes which are not user-specific. - * See attr(5). Note that this information is only available if GLib - * has been built with extended attribute support.</entry></row> - * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes - * information about the SELinux context of files. Note that this information - * is only available if GLib has been built with SELinux support.</entry></row> - * </tbody> - * </tgroup> - * </table> - * </para> + * ## Default Namespaces + * + * - `"standard"`: The "Standard" namespace. General file information that + * any application may need should be put in this namespace. Examples + * include the file's name, type, and size. + * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key + * in this namespace is "value", which contains the value of the current + * entity tag. + * - `"id"`: The "Identification" namespace. This namespace is used by file + * managers and applications that list directories to check for loops and + * to uniquely identify files. + * - `"access"`: The "Access" namespace. Used to check if a user has the + * proper privileges to access files and perform file operations. Keys in + * this namespace are made to be generic and easily understood, e.g. the + * "can_read" key is %TRUE if the current user has permission to read the + * file. UNIX permissions and NTFS ACLs in Windows should be mapped to + * these values. + * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys + * for checking if a file or path supports mount operations, e.g. mount, + * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. + * - `"time"`: The "Time" namespace. Includes file access, changed, created + * times. + * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and + * may not be available for all files. Examples include the UNIX "UID", + * "GID", etc. + * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may + * not be available for all files. Examples include "is_system" for checking + * if a file is marked as a system file, and "is_archive" for checking if a + * file is marked as an archive file. + * - `"owner"`: The "Owner" namespace. Includes information about who owns a + * file. May not be available for all file systems. Examples include "user" + * for getting the user name of the file owner. This information is often + * mapped from some backend specific data such as a UNIX UID. + * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file + * thumbnails and their location within the file system. Examples of keys in + * this namespace include "path" to get the location of a thumbnail, "failed" + * to check if thumbnailing of the file failed, and "is-valid" to check if + * the thumbnail is outdated. + * - `"filesystem"`: The "Filesystem" namespace. Gets information about the + * file system where a file is located, such as its type, how much space is + * left available, and the overall size of the file system. + * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information + * about the current GVFS backend in use. + * - `"xattr"`: The "xattr" namespace. Gets information about extended + * user attributes. See attr(5). The "user." prefix of the extended user + * attribute name is stripped away when constructing keys in this namespace, + * e.g. "xattr::mime_type" for the extended attribute with the name + * "user.mime_type". Note that this information is only available if + * GLib has been built with extended attribute support. + * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about + * extended attributes which are not user-specific. See attr(5). Note + * that this information is only available if GLib has been built with + * extended attribute support. + * - `"selinux"`: The "SELinux" namespace. Includes information about the + * SELinux context of files. Note that this information is only available + * if GLib has been built with SELinux support. * * Please note that these are not all of the possible namespaces. * More namespaces can be added from GIO modules or by individual applications. @@ -4817,76 +5218,10 @@ * <!-- TODO: Implementation note about using extended attributes on supported * file systems --> * - * <para><table> - * <title>GFileAttributes Built-in Keys and Value Types</title> - * <tgroup cols='3' align='left'><thead> - * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row> - * </thead><tbody> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_USED</entry><entry>filesystem::used</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row> - * </tbody></tgroup></table></para> + * ## Default Keys + * + * For a list of the built-in keys and their types, see the + * [GFileInfo][GFileInfo] documentation. * * Note that there are no predefined keys in the "xattr" and "xattr-sys" * namespaces. Keys for the "xattr" namespace are constructed by stripping @@ -4894,8 +5229,8 @@ * "xattr::". Keys for the "xattr-sys" namespace are constructed by * concatenating "xattr-sys::" with the extended attribute name. All extended * attribute values are returned as hex-encoded strings in which bytes outside - * the ASCII range are encoded as hexadecimal escape sequences of the form - * \x<replaceable>nn</replaceable>. + * the ASCII range are encoded as escape sequences of the form \x`nn` + * where `nn` is a 2-digit hexadecimal number. */ @@ -4908,9 +5243,9 @@ * #GFileDescriptorBased is implemented by streams (implementations of * #GInputStream or #GOutputStream) that are based on file descriptors. * - * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific + * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. * * Since: 2.24 */ @@ -4921,7 +5256,7 @@ * @short_description: Enumerated Files Routines * @include: gio/gio.h * - * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, + * #GFileEnumerator allows you to operate on a set of #GFiles, * returning a #GFileInfo structure for each file enumerated (e.g. * g_file_enumerate_children() will return a #GFileEnumerator for each * of the children within a directory). @@ -4929,9 +5264,20 @@ * To get the next file's information from a #GFileEnumerator, use * g_file_enumerator_next_file() or its asynchronous version, * g_file_enumerator_next_files_async(). Note that the asynchronous - * version will return a list of #GFileInfo<!---->s, whereas the + * version will return a list of #GFileInfos, whereas the * synchronous will only return the next file in the enumerator. * + * The ordering of returned files is unspecified for non-Unix + * platforms; for more information, see g_dir_read_name(). On Unix, + * when operating on local files, returned files will be sorted by + * inode number. Effectively you can assume that the ordering of + * returned files will be stable between successive calls (and + * applications) assuming the directory is unchanged. + * + * If your application needs a specific ordering, such as by name or + * modification time, you will have to implement that in your + * application code. + * * To close a #GFileEnumerator, use g_file_enumerator_close(), or * its asynchronous version, g_file_enumerator_close_async(). Once * a #GFileEnumerator is closed, no further actions may be performed @@ -4954,14 +5300,14 @@ * SECTION:gfileinfo * @short_description: File Information and Attributes * @include: gio/gio.h - * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link> + * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute] * * Functionality for manipulating basic metadata for files. #GFileInfo * implements methods for getting information that all files should * contain, and allows for manipulation of extended attributes. * - * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more - * information on how GIO handles file attributes. + * See [GFileAttribute][gio-GFileAttribute for more information on how + * GIO handles file attributes. * * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its * async variant). To obtain a #GFileInfo for a file input or output @@ -5045,9 +5391,9 @@ * * To get informed about changes to the file or directory you are * monitoring, connect to the #GFileMonitor::changed signal. The - * signal will be emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link> of the thread that the monitor was created in + * signal will be emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that the monitor was created in * (though if the global default main context is blocked, this may * cause notifications to be blocked even if the thread-default * context is still running). @@ -5129,18 +5475,29 @@ * * To check if two #GIcons are equal, see g_icon_equal(). * - * For serializing a #GIcon, use g_icon_to_string() and - * g_icon_new_for_string(). + * For serializing a #GIcon, use g_icon_serialize() and + * g_icon_deserialize(). + * + * If you want to consume #GIcon (for example, in a toolkit) you must + * be prepared to handle at least the three following cases: + * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make + * sense to have fast-paths for other cases (like handling #GdkPixbuf + * directly, for example) but all compliant #GIcon implementations + * outside of GIO must implement #GLoadableIcon. * * If your application or library provides one or more #GIcon - * implementations you need to ensure that each #GType is registered - * with the type system prior to calling g_icon_new_for_string(). + * implementations you need to ensure that your new implementation also + * implements #GLoadableIcon. Additionally, you must provide an + * implementation of g_icon_serialize() that gives a result that is + * understood by g_icon_deserialize(), yielding one of the built-in icon + * types. */ /** * SECTION:ginetaddress * @short_description: An IPv4/IPv6 address + * @include: gio/gio.h * * #GInetAddress represents an IPv4 or IPv6 internet address. Use * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to @@ -5158,6 +5515,7 @@ /** * SECTION:ginetaddressmask * @short_description: An IPv4/IPv6 address mask + * @include: gio/gio.h * * #GInetAddressMask represents a range of IPv4 or IPv6 addresses * described by a base address and a length indicating how many bits @@ -5169,6 +5527,7 @@ /** * SECTION:ginetsocketaddress * @short_description: Internet GSocketAddress + * @include: gio/gio.h * * An IPv4 or IPv6 socket address; that is, the combination of a * #GInetAddress and a port number. @@ -5249,17 +5608,11 @@ * @short_description: I/O Scheduler * @include: gio/gio.h * + * As of GLib 2.36, #GIOScheduler is deprecated in favor of + * #GThreadPool and #GTask. + * * Schedules asynchronous I/O operations. #GIOScheduler integrates * into the main event loop (#GMainLoop) and uses threads. - * - * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm> - * Each I/O operation has a priority, and the scheduler uses the priorities - * to determine the order in which operations are executed. They are - * <emphasis>not</emphasis> used to determine system-wide I/O scheduling. - * Priorities are integers, with lower numbers indicating higher priority. - * It is recommended to choose priorities between %G_PRIORITY_LOW and - * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. - * </para> */ @@ -5290,9 +5643,9 @@ * To close a stream use g_io_stream_close() which will close the common * stream object and also the individual substreams. You can also close * the substreams themselves. In most cases this only marks the - * substream as closed, so further I/O on it fails. However, some streams - * may support "half-closed" states where one direction of the stream - * is actually shut down. + * substream as closed, so further I/O on it fails but common state in the + * #GIOStream may still be open. However, some streams may support + * "half-closed" states where one direction of the stream is actually shut down. * * Since: 2.22 */ @@ -5332,8 +5685,8 @@ * #GMemoryOutputStream is a class for using arbitrary * memory chunks as output for GIO streaming output operations. * - * As of GLib 2.34, #GMemoryOutputStream implements - * #GPollableOutputStream. + * As of GLib 2.34, #GMemoryOutputStream trivially implements + * #GPollableOutputStream: it always polls as ready. */ @@ -5341,6 +5694,7 @@ * SECTION:gmenu * @title: GMenu * @short_description: A simple implementation of GMenuModel + * @include: gio/gio.h * * #GMenu is a simple implementation of #GMenuModel. * You populate a #GMenu by adding #GMenuItem instances to it. @@ -5357,6 +5711,7 @@ * SECTION:gmenuexporter * @title: GMenuModel exporter * @short_description: Export GMenuModels on D-Bus + * @include: gio/gio.h * @see_also: #GMenuModel, #GDBusMenuModel * * These functions support exporting a #GMenuModel on D-Bus. @@ -5372,6 +5727,7 @@ * SECTION:gmenumodel * @title: GMenuModel * @short_description: An abstract class representing the contents of a menu + * @include: gio/gio.h * @see_also: #GActionGroup * * #GMenuModel represents the contents of a menu -- an ordered list of @@ -5389,39 +5745,35 @@ * it (or, in the case of the 'root' menu, is defined by the context * in which it is used). * - * As an example, consider the visible portions of the menu in - * <xref linkend="menu-example"/>. + * As an example, consider the visible portions of this menu: + * + * ## An example menu # {#menu-example} * - * <figure id="menu-example"> - * <title>An example menu</title> - * <graphic fileref="menu-example.png" format="PNG"></graphic> - * </figure> + *  * * There are 8 "menus" visible in the screenshot: one menubar, two * submenus and 5 sections: - * <itemizedlist> - * <listitem>the toplevel menubar (containing 4 items)</listitem> - * <listitem>the View submenu (containing 3 sections)</listitem> - * <listitem>the first section of the View submenu (containing 2 items)</listitem> - * <listitem>the second section of the View submenu (containing 1 item)</listitem> - * <listitem>the final section of the View submenu (containing 1 item)</listitem> - * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem> - * <listitem>the Sources section (containing 2 items)</listitem> - * <listitem>the Markup section (containing 2 items)</listitem> - * </itemizedlist> - * - * <xref linkend="menu-model"/> illustrates the conceptual connection between + * + * - the toplevel menubar (containing 4 items) + * - the View submenu (containing 3 sections) + * - the first section of the View submenu (containing 2 items) + * - the second section of the View submenu (containing 1 item) + * - the final section of the View submenu (containing 1 item) + * - the Highlight Mode submenu (containing 2 sections) + * - the Sources section (containing 2 items) + * - the Markup section (containing 2 items) + * + * The [example][menu-model] illustrates the conceptual connection between * these 8 menus. Each large block in the figure represents a menu and the * smaller blocks within the large block represent items in that menu. Some * items contain references to other menus. * - * <figure id="menu-model"> - * <title>A menu model</title> - * <graphic fileref="menu-model.png" format="PNG"></graphic> - * </figure> + * ## A menu example # {#menu-model} * - * Notice that the separators visible in <xref linkend="menu-example"/> - * appear nowhere in <xref linkend="menu-model"/>. This is because + *  + * + * Notice that the separators visible in the [example][menu-example] + * appear nowhere in the [menu model][menu-model]. This is because * separators are not explicitly represented in the menu model. Instead, * a separator is inserted between any two non-empty sections of a menu. * Section items can have labels just like any other item. In that case, @@ -5432,12 +5784,10 @@ * outside the application. Examples include global menus, jumplists, * dash boards, etc. To support such uses, it is necessary to 'export' * information about actions and their representation in menus, which - * is exactly what the - * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link> - * and the - * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link> - * do for #GActionGroup and #GMenuModel. The client-side counterparts - * to make use of the exported information are #GDBusActionGroup and + * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] + * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for + * #GActionGroup and #GMenuModel. The client-side counterparts to + * make use of the exported information are #GDBusActionGroup and * #GDBusMenuModel. * * The API of #GMenuModel is very generic, with iterators for the @@ -5462,48 +5812,37 @@ * While a wide variety of stateful actions is possible, the following * is the minimum that is expected to be supported by all users of exported * menu information: - * <itemizedlist> - * <listitem>an action with no parameter type and no state</listitem> - * <listitem>an action with no parameter type and boolean state</listitem> - * <listitem>an action with string parameter type and string state</listitem> - * </itemizedlist> - * - * <formalpara><title>Stateless</title> - * <para> + * - an action with no parameter type and no state + * - an action with no parameter type and boolean state + * - an action with string parameter type and string state + * + * ## Stateless + * * A stateless action typically corresponds to an ordinary menu item. - * </para> - * <para> + * * Selecting such a menu item will activate the action (with no parameter). - * </para> - * </formalpara> * - * <formalpara><title>Boolean State</title> - * <para> + * ## Boolean State + * * An action with a boolean state will most typically be used with a "toggle" * or "switch" menu item. The state can be set directly, but activating the * action (with no parameter) results in the state being toggled. - * </para> - * <para> + * * Selecting a toggle menu item will activate the action. The menu item should * be rendered as "checked" when the state is true. - * </para> - * </formalpara> * - * <formalpara><title>String Parameter and State</title> - * <para> + * ## String Parameter and State + * * Actions with string parameters and state will most typically be used to * represent an enumerated choice over the items available for a group of * radio menu items. Activating the action with a string parameter is * equivalent to setting that parameter as the state. - * </para> - * <para> + * * Radio menu items, in addition to being associated with the action, will * have a target value. Selecting that menu item will result in activation * of the action with the target value as the parameter. The menu item should * be rendered as "selected" when the state of the action is equal to the * target value of the menu item. - * </para> - * </formalpara> */ @@ -5523,7 +5862,7 @@ * * Unmounting a #GMount instance is an asynchronous operation. For * more information about asynchronous operations, see #GAsyncResult - * and #GSimpleAsyncResult. To unmount a #GMount instance, first call + * and #GTask. To unmount a #GMount instance, first call * g_mount_unmount_with_operation() with (at least) the #GMount instance and a * #GAsyncReadyCallback. The callback will be fired when the * operation has resolved (either with success or failure), and a @@ -5573,6 +5912,32 @@ /** + * SECTION:gnetworking + * @title: gnetworking.h + * @short_description: System networking includes + * @include: gio/gnetworking.h + * + * The `<gio/gnetworking.h>` header can be included to get + * various low-level networking-related system headers, automatically + * taking care of certain portability issues for you. + * + * This can be used, for example, if you want to call setsockopt() + * on a #GSocket. + * + * Note that while WinSock has many of the same APIs as the + * traditional UNIX socket API, most of them behave at least slightly + * differently (particularly with respect to error handling). If you + * want your code to work under both UNIX and Windows, you will need + * to take these differences into account. + * + * Also, under GNU libc, certain non-portable functions are only visible + * in the headers if you define %_GNU_SOURCE before including them. Note + * that this symbol must be defined before including any headers, or it + * may not take effect. + */ + + +/** * SECTION:gnetworkmonitor * @title: GNetworkMonitor * @short_description: Network status monitor @@ -5580,7 +5945,7 @@ * * #GNetworkMonitor provides an easy-to-use cross-platform API * for monitoring network connectivity. On Linux, the implementation - * is based on the kernels netlink interface. + * is based on the kernel's netlink interface. */ @@ -5602,6 +5967,37 @@ /** + * SECTION:gnotification + * @short_description: User Notifications (pop up messages) + * @include: gio/gio.h + * + * #GNotification is a mechanism for creating a notification to be shown + * to the user -- typically as a pop-up notification presented by the + * desktop environment shell. + * + * The key difference between #GNotification and other similar APIs is + * that, if supported by the desktop environment, notifications sent + * with #GNotification will persist after the application has exited, + * and even across system reboots. + * + * Since the user may click on a notification while the application is + * not running, applications using #GNotification should be able to be + * started as a D-Bus service, using #GApplication. + * + * User interaction with a notification (either the default action, or + * buttons) must be associated with actions on the application (ie: + * "app." actions). It is not possible to route user interaction + * through the notification itself, because the object will not exist if + * the application is autostarted as a result of a notification being + * clicked. + * + * A notification can be sent with g_application_send_notification(). + * + * Since: 2.40 + */ + + +/** * SECTION:goutputstream * @short_description: Base class for implementing streaming output * @include: gio/gio.h @@ -5620,7 +6016,9 @@ /** * SECTION:gpermission * @title: GPermission - * @short_description: An object representing the permission to perform a certain action + * @short_description: An object representing the permission + * to perform a certain action + * @include: gio/gio.h * * A #GPermission represents the status of the caller's permission to * perform a certain action. @@ -5672,7 +6070,7 @@ /** * SECTION:gpollableutils - * @short_description: #GPollableInputStream / #GPollableOutputStream utilities + * @short_description: Utilities for pollable streams * @include: gio/gio.h * * Utility functions for #GPollableInputStream and @@ -5681,8 +6079,71 @@ /** + * SECTION:gpropertyaction + * @title: GPropertyAction + * @short_description: A GAction reflecting a GObject property + * @include: gio/gio.h + * + * A #GPropertyAction is a way to get a #GAction with a state value + * reflecting and controlling the value of a #GObject property. + * + * The state of the action will correspond to the value of the property. + * Changing it will change the property (assuming the requested value + * matches the requirements as specified in the #GParamSpec). + * + * Only the most common types are presently supported. Booleans are + * mapped to booleans, strings to strings, signed/unsigned integers to + * int32/uint32 and floats and doubles to doubles. + * + * If the property is an enum then the state will be string-typed and + * conversion will automatically be performed between the enum value and + * "nick" string as per the #GEnumValue table. + * + * Flags types are not currently supported. + * + * Properties of object types, boxed types and pointer types are not + * supported and probably never will be. + * + * Properties of #GVariant types are not currently supported. + * + * If the property is boolean-valued then the action will have a NULL + * parameter type, and activating the action (with no parameter) will + * toggle the value of the property. + * + * In all other cases, the parameter type will correspond to the type of + * the property. + * + * The general idea here is to reduce the number of locations where a + * particular piece of state is kept (and therefore has to be synchronised + * between). #GPropertyAction does not have a separate state that is kept + * in sync with the property value -- its state is the property value. + * + * For example, it might be useful to create a #GAction corresponding to + * the "visible-child-name" property of a #GtkStack so that the current + * page can be switched from a menu. The active radio indication in the + * menu is then directly determined from the active page of the + * #GtkStack. + * + * An anti-example would be binding the "active-id" property on a + * #GtkComboBox. This is because the state of the combobox itself is + * probably uninteresting and is actually being used to control + * something else. + * + * Another anti-example would be to bind to the "visible-child-name" + * property of a #GtkStack if this value is actually stored in + * #GSettings. In that case, the real source of the value is + * #GSettings. If you want a #GAction to control a setting stored in + * #GSettings, see g_settings_create_action() instead, and possibly + * combine its use with g_settings_bind(). + * + * Since: 2.38 + */ + + +/** * SECTION:gproxy * @short_description: Interface for proxy handling + * @include: gio/gio.h * * A #GProxy handles connecting to a remote host via a given type of * proxy server. It is implemented by the 'gio-proxy' extension point. @@ -5698,6 +6159,7 @@ /** * SECTION:gproxyaddress * @short_description: An internet address with proxy information + * @include: gio/gio.h * * Support for proxied #GInetSocketAddress. */ @@ -5717,17 +6179,18 @@ /** * SECTION:gremoteactiongroup * @title: GRemoteActionGroup - * @short_description: a #GActionGroup that interacts with other processes + * @short_description: A GActionGroup that interacts with other processes + * @include: gio/gio.h * * The GRemoteActionGroup interface is implemented by #GActionGroup * instances that either transmit action invocations to other processes * or receive action invocations in the local process from other * processes. * - * The interface has <literal>_full</literal> variants of the two + * The interface has `_full` variants of the two * methods on #GActionGroup used to activate actions: * g_action_group_activate_action() and - * g_action_group_change_action_state(). These variants allow a + * g_action_group_change_action_state(). These variants allow a * "platform data" #GVariant to be specified: a dictionary providing * context for the action invocation (for example: timestamps, startup * notification IDs, etc). @@ -5737,7 +6200,7 @@ * * Additionally, g_dbus_connection_export_action_group() will check if * the exported #GActionGroup implements #GRemoteActionGroup and use the - * <literal>_full</literal> variants of the calls if available. This + * `_full` variants of the calls if available. This * provides a mechanism by which to receive platform data for action * invocations that arrive by way of D-Bus. * @@ -5766,12 +6229,13 @@ * @short_description: Resource framework * @include: gio/gio.h * - * Applications and libraries often contain binary or textual data that is really part of the - * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images, - * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or + * Applications and libraries often contain binary or textual data that is + * really part of the application, rather than user data. For instance + * #GtkBuilder .ui files, splashscreen images, GMenu markup xml, CSS files, + * icons, etc. These are often shipped as files in `$datadir/appname`, or * manually included as literal strings in the code. * - * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program + * The #GResource API and the [glib-compile-resources][glib-compile-resources] program * provide a convenient and efficient alternative to this which has some nice properties. You * maintain the files as normal files, so its easy to edit them, but during the build the files * are combined into a binary bundle that is linked into the executable. This means that loading @@ -5784,27 +6248,28 @@ * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. * * Resource files can also be marked to be preprocessed, by setting the value of the - * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options. + * `preprocess` attribute to a comma-separated list of preprocessing options. * The only options currently supported are: * - * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip - * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar> - * environment variable must be set to the full path to the xmllint executable, or xmllint - * must be in the PATH; otherwise the preprocessing step is skipped. + * `xml-stripblanks` which will use the xmllint command + * to strip ignorable whitespace from the xml file. For this to work, + * the `XMLLINT` environment variable must be set to the full path to + * the xmllint executable, or xmllint must be in the `PATH`; otherwise + * the preprocessing step is skipped. * - * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert + * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata - * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be + * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will * abort. * - * Resource bundles are created by the <link linkend="glib-compile-resources">glib-compile-resources</link> program + * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program * which takes an xml file that describes the bundle, and a set of files that the xml references. These * are combined into a binary resource bundle. * - * <example id="resource-example"><title>Example resource description</title> - * <programlisting><![CDATA[ + * An example resource description: + * |[ * <?xml version="1.0" encoding="UTF-8"?> * <gresources> * <gresource prefix="/org/gtk/Example"> @@ -5813,19 +6278,19 @@ * <file preprocess="xml-stripblanks">menumarkup.xml</file> * </gresource> * </gresources> - * ]]></programlisting></example> + * ]| * * This will create a resource bundle with the following files: - * <programlisting><![CDATA[ + * |[ * /org/gtk/Example/data/splashscreen.png * /org/gtk/Example/dialog.ui * /org/gtk/Example/menumarkup.xml - * ]]></programlisting> + * ]| * * Note that all resources in the process share the same namespace, so use java-style * path prefixes (like in the above example) to avoid conflicts. * - * You can then use <link linkend="glib-compile-resources">glib-compile-resources</link> to compile the xml to a + * You can then use [glib-compile-resources][glib-compile-resources] to compile the xml to a * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and * --generate-header arguments to create a source file and header to link directly into your application. * @@ -5857,12 +6322,25 @@ * * #GSeekable is implemented by streams (implementations of * #GInputStream or #GOutputStream) that support seeking. + * + * Seekable streams largely fall into two categories: resizable and + * fixed-size. + * + * #GSeekable on fixed-sized streams is approximately the same as POSIX + * lseek() on a block device (for example: attmepting to seek past the + * end of the device is an error). Fixed streams typically cannot be + * truncated. + * + * #GSeekable on resizable streams is approximately the same as POSIX + * lseek() on a normal file. Seeking past the end and writing data will + * usually cause the stream to resize by introducing zero bytes. */ /** * SECTION:gsettings * @short_description: High-level API for application settings + * @include: gio/gio.h * * The #GSettings class provides a convenient API for storing and retrieving * application settings. @@ -5912,40 +6390,39 @@ * Similar to GConf, the default values in GSettings schemas can be * localized, but the localized values are stored in gettext catalogs * and looked up with the domain that is specified in the - * <tag class="attribute">gettext-domain</tag> attribute of the - * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag> - * elements and the category that is specified in the l10n attribute of the - * <tag class="starttag">key</tag> element. + * gettext-domain attribute of the <schemalist> or <schema> + * elements and the category that is specified in the l10n attribute of + * the <key> element. * * GSettings uses schemas in a compact binary form that is created - * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link> - * utility. The input is a schema description in an XML format that can be - * described by the following DTD: - * |[<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>]| - * - * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename> - * - * At runtime, schemas are identified by their id (as specified - * in the <tag class="attribute">id</tag> attribute of the - * <tag class="starttag">schema</tag> element). The - * convention for schema ids is to use a dotted name, similar in - * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular, - * if the settings are for a specific service that owns a D-Bus bus name, - * the D-Bus bus name and schema id should match. For schemas which deal - * with settings not associated with one named application, the id should - * not use StudlyCaps, e.g. "org.gnome.font-rendering". - * - * In addition to #GVariant types, keys can have types that have enumerated - * types. These can be described by a <tag class="starttag">choice</tag>, - * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see - * <xref linkend="schema-enumerated"/>. The underlying type of - * such a key is string, but you can use g_settings_get_enum(), - * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags() - * access the numeric values corresponding to the string value of enum - * and flags keys. - * - * <example id="schema-default-values"><title>Default values</title> - * <programlisting><![CDATA[ + * by the [glib-compile-schemas][glib-compile-schemas] + * utility. The input is a schema description in an XML format. + * + * A DTD for the gschema XML format can be found here: + * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd) + * + * The [glib-compile-schemas][glib-compile-schemas] tool expects schema + * files to have the extension `.gschema.xml`. + * + * At runtime, schemas are identified by their id (as specified in the + * id attribute of the <schema> element). The convention for schema + * ids is to use a dotted name, similar in style to a D-Bus bus name, + * e.g. "org.gnome.SessionManager". In particular, if the settings are + * for a specific service that owns a D-Bus bus name, the D-Bus bus name + * and schema id should match. For schemas which deal with settings not + * associated with one named application, the id should not use + * StudlyCaps, e.g. "org.gnome.font-rendering". + * + * In addition to #GVariant types, keys can have types that have + * enumerated types. These can be described by a <choice>, + * <enum> or <flags> element, as seen in the + * [example][schema-enumerated]. The underlying type of such a key + * is string, but you can use g_settings_get_enum(), g_settings_set_enum(), + * g_settings_get_flags(), g_settings_set_flags() access the numeric values + * corresponding to the string value of enum and flags keys. + * + * An example for default value: + * |[ * <schemalist> * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> * @@ -5963,10 +6440,10 @@ * * </schema> * </schemalist> - * ]]></programlisting></example> + * ]| * - * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title> - * <programlisting><![CDATA[ + * An example for ranges, choices and enumerated types: + * |[ * <schemalist> * * <enum id="org.gtk.Test.myenum"> @@ -6009,51 +6486,42 @@ * </key> * </schema> * </schemalist> - * ]]></programlisting></example> - * - * <refsect2> - * <title>Vendor overrides</title> - * <para> - * Default values are defined in the schemas that get installed by - * an application. Sometimes, it is necessary for a vendor or distributor - * to adjust these defaults. Since patching the XML source for the schema - * is inconvenient and error-prone, - * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads - * so-called 'vendor override' files. These are keyfiles in the same - * directory as the XML schema sources which can override default values. - * The schema id serves as the group name in the key file, and the values - * are expected in serialized GVariant form, as in the following example: - * <informalexample><programlisting> + * ]| + * + * ## Vendor overrides + * + * Default values are defined in the schemas that get installed by + * an application. Sometimes, it is necessary for a vendor or distributor + * to adjust these defaults. Since patching the XML source for the schema + * is inconvenient and error-prone, + * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor + * override' files. These are keyfiles in the same directory as the XML + * schema sources which can override default values. The schema id serves + * as the group name in the key file, and the values are expected in + * serialized GVariant form, as in the following example: + * |[ * [org.gtk.Example] * key1='string' * key2=1.5 - * </programlisting></informalexample> - * </para> - * <para> - * glib-compile-schemas expects schema files to have the extension - * <filename>.gschema.override</filename> - * </para> - * </refsect2> - * - * <refsect2> - * <title>Binding</title> - * <para> - * A very convenient feature of GSettings lets you bind #GObject properties - * directly to settings, using g_settings_bind(). Once a GObject property - * has been bound to a setting, changes on either side are automatically - * propagated to the other side. GSettings handles details like - * mapping between GObject and GVariant types, and preventing infinite - * cycles. - * </para> - * <para> - * This makes it very easy to hook up a preferences dialog to the - * underlying settings. To make this even more convenient, GSettings - * looks for a boolean property with the name "sensitivity" and - * automatically binds it to the writability of the bound setting. - * If this 'magic' gets in the way, it can be suppressed with the - * #G_SETTINGS_BIND_NO_SENSITIVITY flag. - * </para> - * </refsect2> + * ]| + * + * glib-compile-schemas expects schema files to have the extension + * `.gschema.override`. + * + * ## Binding + * + * A very convenient feature of GSettings lets you bind #GObject properties + * directly to settings, using g_settings_bind(). Once a GObject property + * has been bound to a setting, changes on either side are automatically + * propagated to the other side. GSettings handles details like mapping + * between GObject and GVariant types, and preventing infinite cycles. + * + * This makes it very easy to hook up a preferences dialog to the + * underlying settings. To make this even more convenient, GSettings + * looks for a boolean property with the name "sensitivity" and + * automatically binds it to the writability of the bound setting. + * If this 'magic' gets in the way, it can be suppressed with the + * #G_SETTINGS_BIND_NO_SENSITIVITY flag. */ @@ -6083,19 +6551,19 @@ * g_settings_backend_create_tree() is a convenience function to create * suitable trees. * - * <note><para> - * The #GSettingsBackend API is exported to allow third-party + * The GSettingsBackend API is exported to allow third-party * implementations, but does not carry the same stability guarantees * as the public GIO API. For this reason, you have to define the - * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including - * <filename>gio/gsettingsbackend.h</filename> - * </para></note> + * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including + * `gio/gsettingsbackend.h`. */ /** * SECTION:gsettingsschema - * @short_description: introspecting and controlling the loading of GSettings schemas + * @short_description: Introspecting and controlling the loading + * of GSettings schemas + * @include: gio/gio.h * * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a * mechanism for advanced control over the loading of schemas and a @@ -6115,7 +6583,7 @@ * * Consider the following example: * - * |[ + * |[<!-- language="C" --> * typedef struct * { * ... @@ -6172,7 +6640,7 @@ * ships a gschemas.compiled file as part of itself, and then simply do * the following: * - * |[ + * |[<!-- language="C" --> * { * GSettings *settings; * gint some_value; @@ -6196,6 +6664,7 @@ * SECTION:gsimpleaction * @title: GSimpleAction * @short_description: A simple GAction implementation + * @include: gio/gio.h * * A #GSimpleAction is the obvious simple implementation of the #GAction * interface. This is the easiest way to create an action for purposes of @@ -6209,6 +6678,7 @@ * SECTION:gsimpleactiongroup * @title: GSimpleActionGroup * @short_description: A simple GActionGroup implementation + * @include: gio/gio.h * * #GSimpleActionGroup is a hash table filled with #GAction objects, * implementing the #GActionGroup and #GActionMap interfaces. @@ -6219,14 +6689,14 @@ * SECTION:gsimpleasyncresult * @short_description: Simple asynchronous results implementation * @include: gio/gio.h - * @see_also: #GAsyncResult + * @see_also: #GAsyncResult, #GTask * - * Implements #GAsyncResult for simple cases. Most of the time, this - * will be all an application needs, and will be used transparently. - * Because of this, #GSimpleAsyncResult is used throughout GIO for - * handling asynchronous functions. + * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of + * #GTask, which provides a simpler API. * - * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error + * #GSimpleAsyncResult implements #GAsyncResult. + * + * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error * reporting, operation cancellation and the final state of an operation, * completely transparent to the application. Results can be returned * as a pointer e.g. for functions that return data that is collected @@ -6264,12 +6734,12 @@ * cause a leak if cancelled before being run). * * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, - * or it can use #GThread<!-- -->s. + * or it can use #GThreads. * g_simple_async_result_complete() will finish an I/O task directly * from the point where it is called. g_simple_async_result_complete_in_idle() - * will finish it from an idle handler in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link>. g_simple_async_result_run_in_thread() will run the + * will finish it from an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * . g_simple_async_result_run_in_thread() will run the * job in a separate thread and then deliver the result to the * thread-default main context. * @@ -6291,14 +6761,13 @@ * #GAsyncResult. A typical implementation of an asynchronous operation * using GSimpleAsyncResult looks something like this: * - * |[ + * |[<!-- language="C" --> * static void * baked_cb (Cake *cake, * gpointer user_data) * { - * /* In this example, this callback is not given a reference to the cake, so - * * the GSimpleAsyncResult has to take a reference to it. - * */ + * // In this example, this callback is not given a reference to the cake, + * // so the GSimpleAsyncResult has to take a reference to it. * GSimpleAsyncResult *result = user_data; * * if (cake == NULL) @@ -6312,12 +6781,11 @@ * g_object_unref); * * - * /* In this example, we assume that baked_cb is called as a callback from - * * the mainloop, so it's safe to complete the operation synchronously here. - * * If, however, _baker_prepare_cake () might call its callback without - * * first returning to the mainloop — inadvisable, but some APIs do so — - * * we would need to use g_simple_async_result_complete_in_idle(). - * */ + * // In this example, we assume that baked_cb is called as a callback from + * // the mainloop, so it's safe to complete the operation synchronously here. + * // If, however, _baker_prepare_cake () might call its callback without + * // first returning to the mainloop — inadvisable, but some APIs do so — + * // we would need to use g_simple_async_result_complete_in_idle(). * g_simple_async_result_complete (result); * g_object_unref (result); * } @@ -6356,9 +6824,8 @@ * g_object_unref); * g_simple_async_result_complete_in_idle (simple); * g_object_unref (simple); - * /* Drop the reference returned by _baker_get_cached_cake(); the - * * GSimpleAsyncResult has taken its own reference. - * */ + * // Drop the reference returned by _baker_get_cached_cake(); + * // the GSimpleAsyncResult has taken its own reference. * g_object_unref (cake); * return; * } @@ -6395,6 +6862,7 @@ * SECTION:gsimplepermission * @title: GSimplePermission * @short_description: A GPermission that doesn't change value + * @include: gio/gio.h * * #GSimplePermission is a trivial implementation of #GPermission that * represents a permission that is either always or never allowed. The @@ -6405,10 +6873,29 @@ /** + * SECTION:gsimpleproxyresolver + * @short_description: Simple proxy resolver implementation + * @include: gio/gio.h + * @see_also: g_socket_client_set_proxy_resolver() + * + * #GSimpleProxyResolver is a simple #GProxyResolver implementation + * that handles a single default proxy, multiple URI-scheme-specific + * proxies, and a list of hosts that proxies should not be used for. + * + * #GSimpleProxyResolver is never the default proxy resolver, but it + * can be used as the base class for another proxy resolver + * implementation, or it can be created and used manually, such as + * with g_socket_client_set_proxy_resolver(). + * + * Since: 2.36 + */ + + +/** * SECTION:gsocket * @short_description: Low-level socket object * @include: gio/gio.h - * @see_also: #GInitable + * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h] * * A #GSocket is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. @@ -6443,7 +6930,7 @@ * reasons. For instance, on Windows a socket is always seen as writable * until a write returns %G_IO_ERROR_WOULD_BLOCK. * - * #GSocket<!-- -->s can be either connection oriented or datagram based. + * #GSockets can be either connection oriented or datagram based. * For connection oriented types you must first establish a connection by * either connecting to an address or accepting a connection from another * address. For connectionless socket types the target/source address is @@ -6463,12 +6950,13 @@ /** * SECTION:gsocketaddress - * @short_description: Abstract base class representing endpoints for socket communication + * @short_description: Abstract base class representing endpoints + * for socket communication + * @include: gio/gio.h * - * #GSocketAddress is the equivalent of <type>struct sockaddr</type> - * in the BSD sockets API. This is an abstract class; use - * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress - * for UNIX domain sockets. + * #GSocketAddress is the equivalent of struct sockaddr in the BSD + * sockets API. This is an abstract class; use #GInetSocketAddress + * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. */ @@ -6499,6 +6987,7 @@ /** * SECTION:gsocketconnectable * @short_description: Interface for potential socket endpoints + * @include: gio/gio.h * * Objects that describe one or more potential socket endpoints * implement #GSocketConnectable. Callers can then use @@ -6506,7 +6995,7 @@ * to try out each socket address in turn until one succeeds, as shown * in the sample code below. * - * |[ + * |[<!-- language="C" --> * MyConnectionType * * connect_to_host (const char *hostname, * guint16 port, @@ -6519,14 +7008,13 @@ * GSocketAddress *sockaddr; * GError *conn_error = NULL; * - * addr = g_network_address_new ("www.gnome.org", 80); + * addr = g_network_address_new (hostname, port); * enumerator = g_socket_connectable_enumerate (addr); * g_object_unref (addr); * - * /<!-- -->* Try each sockaddr until we succeed. Record the first - * * connection error, but not any further ones (since they'll probably - * * be basically the same as the first). - * *<!-- -->/ + * // Try each sockaddr until we succeed. Record the first connection error, + * // but not any further ones (since they'll probably be basically the same + * // as the first). * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) * { * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); @@ -6538,18 +7026,15 @@ * { * if (conn_error) * { - * /<!-- -->* We couldn't connect to the first address, but we succeeded - * * in connecting to a later address. - * *<!-- -->/ + * // We couldn't connect to the first address, but we succeeded + * // in connecting to a later address. * g_error_free (conn_error); * } * return conn; * } * else if (error) * { - * /<!-- -->* Either the initial lookup failed, or else the caller - * * cancelled us. - * *<!-- -->/ + * /// Either initial lookup failed, or else the caller cancelled us. * if (conn_error) * g_error_free (conn_error); * return NULL; @@ -6583,6 +7068,10 @@ * custom socket connection types for specific combination of socket * family/type/protocol using g_socket_connection_factory_register_type(). * + * To close a #GSocketConnection, use g_io_stream_close(). Closing both + * substreams of the #GIOStream separately will not close the underlying + * #GSocket. + * * Since: 2.22 */ @@ -6591,6 +7080,7 @@ * SECTION:gsocketcontrolmessage * @title: GSocketControlMessage * @short_description: A GSocket control message + * @include: gio/gio.h * @see_also: #GSocket. * * A #GSocketControlMessage is a special-purpose utility message that @@ -6599,7 +7089,7 @@ * * The message can represent some sort of special instruction to or * information from the socket or can represent a special kind of - * transfer to the peer (for example, sending a file description over + * transfer to the peer (for example, sending a file descriptor over * a UNIX socket). * * These messages are sent with g_socket_send_message() and received @@ -6622,6 +7112,7 @@ * SECTION:gsocketlistener * @title: GSocketListener * @short_description: Helper for accepting network client connections + * @include: gio/gio.h * @see_also: #GThreadedSocketService, #GSocketService. * * A #GSocketListener is an object that keeps track of a set @@ -6640,6 +7131,7 @@ * SECTION:gsocketservice * @title: GSocketService * @short_description: Make it easy to implement a network service + * @include: gio/gio.h * @see_also: #GThreadedSocketService, #GSocketListener. * * A #GSocketService is an object that represents a service that @@ -6662,9 +7154,9 @@ * If you are interested in writing connection handlers that contain * blocking code then see #GThreadedSocketService. * - * The socket service runs on the main loop of the <link - * linkend="g-main-context-push-thread-default-context">thread-default - * context</link> of the thread it is created in, and is not + * The socket service runs on the main loop of the + * [thread-default context][g-main-context-push-thread-default-context] + * of the thread it is created in, and is not * threadsafe in general. However, the calls to start and stop the * service are thread-safe so these can be used from threads that * handle incoming clients. @@ -6687,7 +7179,7 @@ * then connect to whatever host was pointed to by that record. * * You can use g_resolver_lookup_service() or - * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s + * g_resolver_lookup_service_async() to find the #GSrvTargets * for a given service. However, if you are simply planning to connect * to the remote service, you can use #GNetworkService's * #GSocketConnectable interface and not need to worry about @@ -6696,9 +7188,595 @@ /** + * SECTION:gsubprocess + * @title: GSubprocess + * @short_description: Child processes + * @include: gio/gio.h + * @see_also: #GSubprocessLauncher + * + * #GSubprocess allows the creation of and interaction with child + * processes. + * + * Processes can be communicated with using standard GIO-style APIs (ie: + * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for + * process termination (ie: cancellable and with an asynchronous + * variant). + * + * There is an API to force a process to terminate, as well as a + * race-free API for sending UNIX signals to a subprocess. + * + * One major advantage that GIO brings over the core GLib library is + * comprehensive API for asynchronous I/O, such + * g_output_stream_splice_async(). This makes GSubprocess + * significantly more powerful and flexible than equivalent APIs in + * some other languages such as the `subprocess.py` + * included with Python. For example, using #GSubprocess one could + * create two child processes, reading standard output from the first, + * processing it, and writing to the input stream of the second, all + * without blocking the main loop. + * + * A powerful g_subprocess_communicate() API is provided similar to the + * `communicate()` method of `subprocess.py`. This enables very easy + * interaction with a subprocess that has been opened with pipes. + * + * #GSubprocess defaults to tight control over the file descriptors open + * in the child process, avoiding dangling-fd issues that are caused by + * a simple fork()/exec(). The only open file descriptors in the + * spawned process are ones that were explicitly specified by the + * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was + * specified). + * + * #GSubprocess will quickly reap all child processes as they exit, + * avoiding "zombie processes" remaining around for long periods of + * time. g_subprocess_wait() can be used to wait for this to happen, + * but it will happen even without the call being explicitly made. + * + * As a matter of principle, #GSubprocess has no API that accepts + * shell-style space-separated strings. It will, however, match the + * typical shell behaviour of searching the PATH for executables that do + * not contain a directory separator in their name. + * + * #GSubprocess attempts to have a very simple API for most uses (ie: + * spawning a subprocess with arguments and support for most typical + * kinds of input and output redirection). See g_subprocess_new(). The + * #GSubprocessLauncher API is provided for more complicated cases + * (advanced types of redirection, environment variable manipulation, + * change of working directory, child setup functions, etc). + * + * A typical use of #GSubprocess will involve calling + * g_subprocess_new(), followed by g_subprocess_wait_async() or + * g_subprocess_wait(). After the process exits, the status can be + * checked using functions such as g_subprocess_get_if_exited() (which + * are similar to the familiar WIFEXITED-style POSIX macros). + * + * Since: 2.40 + */ + + +/** + * SECTION:gsubprocesslauncher + * @title: GSubprocess Launcher + * @short_description: Environment options for launching a child process + * @include: gio/gio.h + * + * This class contains a set of options for launching child processes, + * such as where its standard input and output will be directed, the + * argument list, the environment, and more. + * + * While the #GSubprocess class has high level functions covering + * popular cases, use of this class allows access to more advanced + * options. It can also be used to launch multiple subprocesses with + * a similar configuration. + * + * Since: 2.40 + */ + + +/** + * SECTION:gtask + * @short_description: Cancellable synchronous or asynchronous task + * and result + * @include: gio/gio.h + * @see_also: #GAsyncResult + * + * A #GTask represents and manages a cancellable "task". + * + * ## Asynchronous operations + * + * The most common usage of #GTask is as a #GAsyncResult, to + * manage data during an asynchronous operation. You call + * g_task_new() in the "start" method, followed by + * g_task_set_task_data() and the like if you need to keep some + * additional data associated with the task, and then pass the + * task object around through your asynchronous operation. + * Eventually, you will call a method such as + * g_task_return_pointer() or g_task_return_error(), which will + * save the value you give it and then invoke the task's callback + * function (waiting until the next iteration of the main + * loop first, if necessary). The caller will pass the #GTask back + * to the operation's finish function (as a #GAsyncResult), and + * you can use g_task_propagate_pointer() or the like to extract + * the return value. + * + * Here is an example for using GTask as a GAsyncResult: + * |[<!-- language="C" --> + * typedef struct { + * CakeFrostingType frosting; + * char *message; + * } DecorationData; + * + * static void + * decoration_data_free (DecorationData *decoration) + * { + * g_free (decoration->message); + * g_slice_free (DecorationData, decoration); + * } + * + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * GTask *task = user_data; + * DecorationData *decoration = g_task_get_task_data (task); + * GError *error = NULL; + * + * if (cake == NULL) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * g_object_unref (task); + * return; + * } + * + * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) + * { + * g_object_unref (cake); + * // g_task_return_error() takes ownership of error + * g_task_return_error (task, error); + * g_object_unref (task); + * return; + * } + * + * g_task_return_pointer (task, cake, g_object_unref); + * g_object_unref (task); + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GTask *task; + * DecorationData *decoration; + * Cake *cake; + * + * task = g_task_new (self, cancellable, callback, user_data); + * if (radius < 3) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, + * "%ucm radius cakes are silly", + * radius); + * g_object_unref (task); + * return; + * } + * + * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); + * if (cake != NULL) + * { + * // _baker_get_cached_cake() returns a reffed cake + * g_task_return_pointer (task, cake, g_object_unref); + * g_object_unref (task); + * return; + * } + * + * decoration = g_slice_new (DecorationData); + * decoration->frosting = frosting; + * decoration->message = g_strdup (message); + * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); + * + * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * ]| + * + * ## Chained asynchronous operations + * + * #GTask also tries to simplify asynchronous operations that + * internally chain together several smaller asynchronous + * operations. g_task_get_cancellable(), g_task_get_context(), + * and g_task_get_priority() allow you to get back the task's + * #GCancellable, #GMainContext, and [I/O priority][io-priority] + * when starting a new subtask, so you don't have to keep track + * of them yourself. g_task_attach_source() simplifies the case + * of waiting for a source to fire (automatically using the correct + * #GMainContext and priority). + * + * Here is an example for chained asynchronous operations: + * |[<!-- language="C" --> + * typedef struct { + * Cake *cake; + * CakeFrostingType frosting; + * char *message; + * } BakingData; + * + * static void + * decoration_data_free (BakingData *bd) + * { + * if (bd->cake) + * g_object_unref (bd->cake); + * g_free (bd->message); + * g_slice_free (BakingData, bd); + * } + * + * static void + * decorated_cb (Cake *cake, + * GAsyncResult *result, + * gpointer user_data) + * { + * GTask *task = user_data; + * GError *error = NULL; + * + * if (!cake_decorate_finish (cake, result, &error)) + * { + * g_object_unref (cake); + * g_task_return_error (task, error); + * g_object_unref (task); + * return; + * } + * + * // baking_data_free() will drop its ref on the cake, so we have to + * // take another here to give to the caller. + * g_task_return_pointer (result, g_object_ref (cake), g_object_unref); + * g_object_unref (task); + * } + * + * static void + * decorator_ready (gpointer user_data) + * { + * GTask *task = user_data; + * BakingData *bd = g_task_get_task_data (task); + * + * cake_decorate_async (bd->cake, bd->frosting, bd->message, + * g_task_get_cancellable (task), + * decorated_cb, task); + * } + * + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * GTask *task = user_data; + * BakingData *bd = g_task_get_task_data (task); + * GError *error = NULL; + * + * if (cake == NULL) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * g_object_unref (task); + * return; + * } + * + * bd->cake = cake; + * + * // Bail out now if the user has already cancelled + * if (g_task_return_error_if_cancelled (task)) + * { + * g_object_unref (task); + * return; + * } + * + * if (cake_decorator_available (cake)) + * decorator_ready (task); + * else + * { + * GSource *source; + * + * source = cake_decorator_wait_source_new (cake); + * // Attach @source to @task's GMainContext and have it call + * // decorator_ready() when it is ready. + * g_task_attach_source (task, source, + * G_CALLBACK (decorator_ready)); + * g_source_unref (source); + * } + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * gint priority, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GTask *task; + * BakingData *bd; + * + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_priority (task, priority); + * + * bd = g_slice_new0 (BakingData); + * bd->frosting = frosting; + * bd->message = g_strdup (message); + * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); + * + * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * ]| + * + * ## Asynchronous operations from synchronous ones + * + * You can use g_task_run_in_thread() to turn a synchronous + * operation into an asynchronous one, by running it in a thread + * which will then dispatch the result back to the caller's + * #GMainContext when it completes. + * + * Running a task in a thread: + * |[<!-- language="C" --> + * typedef struct { + * guint radius; + * CakeFlavor flavor; + * CakeFrostingType frosting; + * char *message; + * } CakeData; + * + * static void + * cake_data_free (CakeData *cake_data) + * { + * g_free (cake_data->message); + * g_slice_free (CakeData, cake_data); + * } + * + * static void + * bake_cake_thread (GTask *task, + * gpointer source_object, + * gpointer task_data, + * GCancellable *cancellable) + * { + * Baker *self = source_object; + * CakeData *cake_data = task_data; + * Cake *cake; + * GError *error = NULL; + * + * cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + * cake_data->frosting, cake_data->message, + * cancellable, &error); + * if (cake) + * g_task_return_pointer (task, cake, g_object_unref); + * else + * g_task_return_error (task, error); + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * CakeData *cake_data; + * GTask *task; + * + * cake_data = g_slice_new (CakeData); + * cake_data->radius = radius; + * cake_data->flavor = flavor; + * cake_data->frosting = frosting; + * cake_data->message = g_strdup (message); + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_run_in_thread (task, bake_cake_thread); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * ]| + * + * ## Adding cancellability to uncancellable tasks + * + * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() + * can be used to turn an uncancellable operation into a + * cancellable one. If you call g_task_set_return_on_cancel(), + * passing %TRUE, then if the task's #GCancellable is cancelled, + * it will return control back to the caller immediately, while + * allowing the task thread to continue running in the background + * (and simply discarding its result when it finally does finish). + * Provided that the task thread is careful about how it uses + * locks and other externally-visible resources, this allows you + * to make "GLib-friendly" asynchronous and cancellable + * synchronous variants of blocking APIs. + * + * Cancelling a task: + * |[<!-- language="C" --> + * static void + * bake_cake_thread (GTask *task, + * gpointer source_object, + * gpointer task_data, + * GCancellable *cancellable) + * { + * Baker *self = source_object; + * CakeData *cake_data = task_data; + * Cake *cake; + * GError *error = NULL; + * + * cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + * cake_data->frosting, cake_data->message, + * &error); + * if (error) + * { + * g_task_return_error (task, error); + * return; + * } + * + * // If the task has already been cancelled, then we don't want to add + * // the cake to the cake cache. Likewise, we don't want to have the + * // task get cancelled in the middle of updating the cache. + * // g_task_set_return_on_cancel() will return %TRUE here if it managed + * // to disable return-on-cancel, or %FALSE if the task was cancelled + * // before it could. + * if (g_task_set_return_on_cancel (task, FALSE)) + * { + * // If the caller cancels at this point, their + * // GAsyncReadyCallback won't be invoked until we return, + * // so we don't have to worry that this code will run at + * // the same time as that code does. But if there were + * // other functions that might look at the cake cache, + * // then we'd probably need a GMutex here as well. + * baker_add_cake_to_cache (baker, cake); + * g_task_return_pointer (task, cake, g_object_unref); + * } + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * CakeData *cake_data; + * GTask *task; + * + * cake_data = g_slice_new (CakeData); + * + * ... + * + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_set_return_on_cancel (task, TRUE); + * g_task_run_in_thread (task, bake_cake_thread); + * } + * + * Cake * + * baker_bake_cake_sync (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GError **error) + * { + * CakeData *cake_data; + * GTask *task; + * Cake *cake; + * + * cake_data = g_slice_new (CakeData); + * + * ... + * + * task = g_task_new (self, cancellable, NULL, NULL); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_set_return_on_cancel (task, TRUE); + * g_task_run_in_thread_sync (task, bake_cake_thread); + * + * cake = g_task_propagate_pointer (task, error); + * g_object_unref (task); + * return cake; + * } + * ]| + * + * ## Porting from GSimpleAsyncResult + * + * #GTask's API attempts to be simpler than #GSimpleAsyncResult's + * in several ways: + * - You can save task-specific data with g_task_set_task_data(), and + * retrieve it later with g_task_get_task_data(). This replaces the + * abuse of g_simple_async_result_set_op_res_gpointer() for the same + * purpose with #GSimpleAsyncResult. + * - In addition to the task data, #GTask also keeps track of the + * [priority][io-priority], #GCancellable, and + * #GMainContext associated with the task, so tasks that consist of + * a chain of simpler asynchronous operations will have easy access + * to those values when starting each sub-task. + * - g_task_return_error_if_cancelled() provides simplified + * handling for cancellation. In addition, cancellation + * overrides any other #GTask return value by default, like + * #GSimpleAsyncResult does when + * g_simple_async_result_set_check_cancellable() is called. + * (You can use g_task_set_check_cancellable() to turn off that + * behavior.) On the other hand, g_task_run_in_thread() + * guarantees that it will always run your + * `task_func`, even if the task's #GCancellable + * is already cancelled before the task gets a chance to run; + * you can start your `task_func` with a + * g_task_return_error_if_cancelled() check if you need the + * old behavior. + * - The "return" methods (eg, g_task_return_pointer()) + * automatically cause the task to be "completed" as well, and + * there is no need to worry about the "complete" vs "complete + * in idle" distinction. (#GTask automatically figures out + * whether the task's callback can be invoked directly, or + * if it needs to be sent to another #GMainContext, or delayed + * until the next iteration of the current #GMainContext.) + * - The "finish" functions for #GTask-based operations are generally + * much simpler than #GSimpleAsyncResult ones, normally consisting + * of only a single call to g_task_propagate_pointer() or the like. + * Since g_task_propagate_pointer() "steals" the return value from + * the #GTask, it is not necessary to juggle pointers around to + * prevent it from being freed twice. + * - With #GSimpleAsyncResult, it was common to call + * g_simple_async_result_propagate_error() from the + * `_finish()` wrapper function, and have + * virtual method implementations only deal with successful + * returns. This behavior is deprecated, because it makes it + * difficult for a subclass to chain to a parent class's async + * methods. Instead, the wrapper function should just be a + * simple wrapper, and the virtual method should call an + * appropriate `g_task_propagate_` function. + * Note that wrapper methods can now use + * g_async_result_legacy_propagate_error() to do old-style + * #GSimpleAsyncResult error-returning behavior, and + * g_async_result_is_tagged() to check if a result is tagged as + * having come from the `_async()` wrapper + * function (for "short-circuit" results, such as when passing + * 0 to g_input_stream_read_async()). + */ + + +/** * SECTION:gtcpconnection * @title: GTcpConnection * @short_description: A TCP GSocketConnection + * @include: gio/gio.h * @see_also: #GSocketConnection. * * This is the subclass of #GSocketConnection that is created @@ -6711,7 +7789,9 @@ /** * SECTION:gtcpwrapperconnection * @title: GTcpWrapperConnection - * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams + * @short_description: Wrapper for non-GSocketConnection-based, + * GSocket-based GIOStreams + * @include: gio/gio.h * @see_also: #GSocketConnection. * * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is @@ -6729,7 +7809,78 @@ * @short_description: D-Bus testing helper * @include: gio/gio.h * - * Helper to test D-Bus code wihtout messing up with user' session bus. + * A helper class for testing code which uses D-Bus without touching the user's + * session bus. + * + * Note that #GTestDBus modifies the user’s environment, calling setenv(). + * This is not thread-safe, so all #GTestDBus calls should be completed before + * threads are spawned, or should have appropriate locking to ensure no access + * conflicts to environment variables shared between #GTestDBus and other + * threads. + * + * ## Creating unit tests using GTestDBus + * + * Testing of D-Bus services can be tricky because normally we only ever run + * D-Bus services over an existing instance of the D-Bus daemon thus we + * usually don't activate D-Bus services that are not yet installed into the + * target system. The #GTestDBus object makes this easier for us by taking care + * of the lower level tasks such as running a private D-Bus daemon and looking + * up uninstalled services in customizable locations, typically in your source + * code tree. + * + * The first thing you will need is a separate service description file for the + * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory + * is a good place to put this file. + * + * The service file should list your service along with an absolute path to the + * uninstalled service executable in your source tree. Using autotools we would + * achieve this by adding a file such as `my-server.service.in` in the services + * directory and have it processed by configure. + * |[ + * [D-BUS Service] + * Name=org.gtk.GDBus.Examples.ObjectManager + * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server + * ]| + * You will also need to indicate this service directory in your test + * fixtures, so you will need to pass the path while compiling your + * test cases. Typically this is done with autotools with an added + * preprocessor flag specified to compile your tests such as: + * |[ + * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" + * ]| + * Once you have a service definition file which is local to your source tree, + * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. + * + * An example of a test fixture for D-Bus services can be found + * here: + * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c) + * + * Note that these examples only deal with isolating the D-Bus aspect of your + * service. To successfully run isolated unit tests on your service you may need + * some additional modifications to your test case fixture. For example; if your + * service uses GSettings and installs a schema then it is important that your test service + * not load the schema in the ordinary installed location (chances are that your service + * and schema files are not yet installed, or worse; there is an older version of the + * schema file sitting in the install location). + * + * Most of the time we can work around these obstacles using the + * environment. Since the environment is inherited by the D-Bus daemon + * created by #GTestDBus and then in turn inherited by any services the + * D-Bus daemon activates, using the setup routine for your fixture is + * a practical place to help sandbox your runtime environment. For the + * rather typical GSettings case we can work around this by setting + * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas + * in the above fixture_setup() routine. + * + * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved + * by compiling the schemas locally as a step before running test cases, an autotools setup might + * do the following in the directory holding schemas: + * |[ + * all-am: + * $(GLIB_COMPILE_SCHEMAS) . + * + * CLEANFILES += gschemas.compiled + * ]| */ @@ -6753,6 +7904,7 @@ * SECTION:gthreadedsocketservice * @title: GThreadedSocketService * @short_description: A threaded GSocketService + * @include: gio/gio.h * @see_also: #GSocketService. * * A #GThreadedSocketService is a simple subclass of #GSocketService @@ -6810,8 +7962,6 @@ * @title: GTlsBackend * @short_description: TLS backend implementation * @include: gio/gio.h - * - * */ @@ -6819,6 +7969,7 @@ * SECTION:gtlscertificate * @title: GTlsCertificate * @short_description: TLS certificate + * @include: gio/gio.h * @see_also: #GTlsConnection * * A certificate used for TLS authentication and encryption. @@ -6877,7 +8028,7 @@ * @include: gio/gio.h * * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load - * their certificate information from a file. It is in interface which + * their certificate information from a file. It is an interface which * TLS library specific subtypes implement. * * Since: 2.30 @@ -6947,9 +8098,9 @@ * It contains functions to do some of the UNIX socket specific * functionality like passing file descriptors. * - * Note that <filename><gio/gunixconnection.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific + * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` + * pkg-config file when using it. * * Since: 2.22 */ @@ -6990,9 +8141,9 @@ * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message() * and received using g_socket_receive_message(). * - * Note that <filename><gio/gunixfdlist.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7013,9 +8164,9 @@ * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and * g_unix_connection_receive_fd(). * - * Note that <filename><gio/gunixfdmessage.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7031,9 +8182,9 @@ * asynchronous I/O. If it refers to a regular file, it will fall back * to doing asynchronous I/O in another thread.) * - * Note that <filename><gio/gunixinputstream.h></filename> belongs - * to the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7044,9 +8195,9 @@ * * Routines for managing mounted UNIX mount points and paths. * - * Note that <filename><gio/gunixmounts.h></filename> belongs to the - * UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7062,9 +8213,9 @@ * asynchronous I/O. If it refers to a regular file, it will fall back * to doing asynchronous I/O in another thread.) * - * Note that <filename><gio/gunixoutputstream.h></filename> belongs - * to the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file + * when using it. */ @@ -7084,9 +8235,9 @@ * errors. You can use g_unix_socket_address_abstract_names_supported() * to see if abstract names are supported. * - * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file + * when using it. */ @@ -7110,9 +8261,9 @@ * * Mounting a #GVolume instance is an asynchronous operation. For more * information about asynchronous operations, see #GAsyncResult and - * #GSimpleAsyncResult. To mount a #GVolume, first call - * g_volume_mount() with (at least) the #GVolume instance, optionally - * a #GMountOperation object and a #GAsyncReadyCallback. + * #GTask. To mount a #GVolume, first call g_volume_mount() with (at + * least) the #GVolume instance, optionally a #GMountOperation object + * and a #GAsyncReadyCallback. * * Typically, one will only want to pass %NULL for the * #GMountOperation if automounting all volumes when a desktop session @@ -7127,18 +8278,18 @@ * successfully. If an @error is present when g_volume_mount_finish() * is called, then it will be filled with any error information. * - * <para id="volume-identifier"> + * ## Volume Identifiers # {#volume-identifier} + * * It is sometimes necessary to directly access the underlying * operating system object behind a volume (e.g. for passing a volume * to an application via the commandline). For this purpose, GIO * allows to obtain an 'identifier' for the volume. There can be * different kinds of identifiers, such as Hal UDIs, filesystem labels, - * traditional Unix devices (e.g. <filename>/dev/sda2</filename>), - * uuids. GIO uses predefind strings as names for the different kinds - * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, - * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier() - * to obtain an identifier for a volume. - * </para> + * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined + * strings as names for the different kinds of identifiers: + * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. + * Use g_volume_get_identifier() to obtain an identifier for a volume. + * * * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available * when the gvfs hal volume monitor is in use. Other volume monitors @@ -7158,10 +8309,10 @@ * on the computer. In other words, what a file selector or file manager * would show in a sidebar. * - * #GVolumeMonitor is not <link - * linkend="g-main-context-push-thread-default">thread-default-context - * aware</link>, and so should not be used other than from the main - * thread, with no thread-default-context active. + * #GVolumeMonitor is not + * [thread-default-context aware][g-main-context-push-thread-default], + * and so should not be used other than from the main thread, with no + * thread-default-context active. */ @@ -7174,9 +8325,9 @@ * #GWin32InputStream implements #GInputStream for reading from a * Windows file handle. * - * Note that <filename><gio/gwin32inputstream.h></filename> belongs - * to the Windows-specific GIO interfaces, thus you have to use the - * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO + * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file + * when using it. */ @@ -7189,9 +8340,9 @@ * #GWin32OutputStream implements #GOutputStream for writing to a * Windows file handle. * - * Note that <filename><gio/gwin32outputstream.h></filename> belongs - * to the Windows-specific GIO interfaces, thus you have to use the - * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO + * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file + * when using it. */ @@ -8661,8 +9812,10 @@ /** * _g_io_module_get_default: * @extension_point: the name of an extension point - * @envvar: (allow-none): the name of an environment variable to override the default implementation. - * @verify_func: (allow-none): a function to call to verify that a given implementation is usable in the current environment. + * @envvar: (allow-none): the name of an environment variable to + * override the default implementation. + * @verify_func: (allow-none): a function to call to verify that + * a given implementation is usable in the current environment. * * Retrieves the default object implementing @extension_point. * @@ -8680,7 +9833,37 @@ * The result is cached after it is generated the first time, and * the function is thread-safe. * - * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations. + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. + */ + + +/** + * _g_io_module_get_default_type: + * @extension_point: the name of an extension point + * @envvar: (allow-none): the name of an environment variable to + * override the default implementation. + * @is_supported_offset: a vtable offset, or zero + * + * Retrieves the default class implementing @extension_point. + * + * If @envvar is not %NULL, and the environment variable with that + * name is set, then the implementation it specifies will be tried + * first. After that, or if @envvar is not set, all other + * implementations will be tried in order of decreasing priority. + * + * If @is_supported_offset is non-zero, then it is the offset into the + * class vtable at which there is a function that takes no arguments and + * returns a boolean. This function will be called on each candidate + * implementation to check if it is actually usable or not. + * + * The result is cached after it is generated the first time, and + * the function is thread-safe. + * + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. */ @@ -8695,6 +9878,8 @@ * the parameter type given at construction time). If the parameter * type was %NULL then @parameter must also be %NULL. * + * If the @parameter GVariant is floating, it is consumed. + * * Since: 2.28 */ @@ -9058,7 +10243,8 @@ * The caller is responsible for freeing the list with g_strfreev() when * it is no longer required. * - * Returns: (transfer full): a %NULL-terminated array of the names of the actions in the groupb + * Returns: (transfer full): a %NULL-terminated array of the names of the + * actions in the groupb * Since: 2.28 */ @@ -9125,7 +10311,8 @@ /** * g_action_map_add_action_entries: * @action_map: a #GActionMap - * @entries: a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to + * the first item in an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated * @user_data: the user data for signal connections * @@ -9134,9 +10321,7 @@ * * Each action is constructed as per one #GActionEntry. * - * <example> - * <title>Using g_action_map_add_action_entries()</title> - * <programlisting> + * |[<!-- language="C" --> * static void * activate_quit (GSimpleAction *simple, * GVariant *parameter, @@ -9167,8 +10352,7 @@ * * return G_ACTION_GROUP (group); * } - * </programlisting> - * </example> + * ]| * * Since: 2.32 */ @@ -9202,6 +10386,82 @@ /** + * g_action_name_is_valid: + * @action_name: an potential action name + * + * Checks if @action_name is valid. + * + * @action_name is valid if it consists only of alphanumeric characters, + * plus '-' and '.'. The empty string is not a valid action name. + * + * It is an error to call this function with a non-utf8 @action_name. + * @action_name must not be %NULL. + * + * Returns: %TRUE if @action_name is valid + * Since: 2.38 + */ + + +/** + * g_action_parse_detailed_name: + * @detailed_name: a detailed action name + * @action_name: (out): the action name + * @target_value: (out): the target value, or %NULL for no target + * @error: a pointer to a %NULL #GError, or %NULL + * + * Parses a detailed action name into its separate name and target + * components. + * + * Detailed action names can have three formats. + * + * The first format is used to represent an action name with no target + * value and consists of just an action name containing no whitespace + * nor the characters ':', '(' or ')'. For example: "app.action". + * + * The second format is used to represent an action with a target value + * that is a non-empty string consisting only of alphanumerics, plus '-' + * and '.'. In that case, the action name and target value are + * separated by a double colon ("::"). For example: + * "app.action::target". + * + * The third format is used to represent an action with any type of + * target value, including strings. The target value follows the action + * name, surrounded in parens. For example: "app.action(42)". The + * target value is parsed using g_variant_parse(). If a tuple-typed + * value is desired, it must be specified in the same way, resulting in + * two sets of parens, for example: "app.action((1,2,3))". A string + * target can be specified this way as well: "app.action('target')". + * For strings, this third format must be used if * target value is + * empty or contains characters other than alphanumerics, '-' and '.'. + * + * Returns: %TRUE if successful, else %FALSE with @error set + * Since: 2.38 + */ + + +/** + * g_action_print_detailed_name: + * @action_name: a valid action name + * @target_value: (allow-none): a #GVariant target value, or %NULL + * + * Formats a detailed action name from @action_name and @target_value. + * + * It is an error to call this function with an invalid action name. + * + * This function is the opposite of + * g_action_parse_detailed_action_name(). It will produce a string that + * can be parsed back to the @action_name and @target_value by that + * function. + * + * See that function for the types of strings that will be printed by + * this function. + * + * Returns: a detailed format string + * Since: 2.38 + */ + + +/** * g_app_info_add_supports_type: * @appinfo: a #GAppInfo. * @content_type: a string. @@ -9232,7 +10492,8 @@ * * Checks if a supported content type can be removed from an application. * - * Returns: %TRUE if it is possible to remove supported content types from a given @appinfo, %FALSE if not. + * Returns: %TRUE if it is possible to remove supported + * content types from a given @appinfo, %FALSE if not. */ @@ -9246,8 +10507,8 @@ * Creates a new #GAppInfo from the given information. * * Note that for @commandline, the quoting rules of the Exec key of the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">freedesktop.org Desktop - * Entry Specification</ulink> are applied. For example, if the @commandline contains + * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) + * are applied. For example, if the @commandline contains * percent-encoded URIs, the percent-character must be doubled in order to prevent it from * being swallowed by Exec key unquoting. See the specification for exact quoting rules. * @@ -9256,16 +10517,15 @@ /** - * g_app_info_delete: + * g_app_info_delete: (virtual do_delete) * @appinfo: a #GAppInfo * * Tries to delete a #GAppInfo. * * On some platforms, there may be a difference between user-defined - * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which - * cannot. See g_app_info_can_delete(). + * #GAppInfos which can be deleted, and system-wide ones which cannot. + * See g_app_info_can_delete(). * - * Virtual: do_delete * Returns: %TRUE if @appinfo has been deleted * Since: 2.20 */ @@ -9286,7 +10546,7 @@ * @appinfo1: the first #GAppInfo. * @appinfo2: the second #GAppInfo. * - * Checks if two #GAppInfo<!-- -->s are equal. + * Checks if two #GAppInfos are equal. * * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. */ @@ -9299,13 +10559,12 @@ * on this system. * * For desktop files, this includes applications that have - * <literal>NoDisplay=true</literal> set or are excluded from - * display by means of <literal>OnlyShowIn</literal> or - * <literal>NotShowIn</literal>. See g_app_info_should_show(). + * `NoDisplay=true` set or are excluded from display by means + * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). * The returned list does not include applications which have - * the <literal>Hidden</literal> key set. + * the `Hidden` key set. * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s. + * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos. */ @@ -9318,7 +10577,8 @@ * g_app_info_get_recommended_for_type() and * g_app_info_get_fallback_for_type(). * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. */ @@ -9329,7 +10589,8 @@ * Gets the commandline with which the application will be * started. * - * Returns: a string containing the @appinfo's commandline, or %NULL if this information is not available + * Returns: a string containing the @appinfo's commandline, + * or %NULL if this information is not available * Since: 2.20 */ @@ -9337,11 +10598,13 @@ /** * g_app_info_get_default_for_type: * @content_type: the content type to find a #GAppInfo for - * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs + * @must_support_uris: if %TRUE, the #GAppInfo is expected to + * support URIs * * Gets the default #GAppInfo for a given content type. * - * Returns: (transfer full): #GAppInfo for given @content_type or %NULL on error. + * Returns: (transfer full): #GAppInfo for given @content_type or + * %NULL on error. */ @@ -9364,7 +10627,8 @@ * * Gets a human-readable description of an installed application. * - * Returns: a string containing a description of the application @appinfo, or %NULL if none. + * Returns: a string containing a description of the + * application @appinfo, or %NULL if none. */ @@ -9375,7 +10639,8 @@ * Gets the display name of the application. The display name is often more * descriptive to the user than the name itself. * - * Returns: the display name of the application for @appinfo, or the name if no display name is available. + * Returns: the display name of the application for @appinfo, or the name if + * no display name is available. * Since: 2.24 */ @@ -9386,7 +10651,8 @@ * * Gets the executable's name for the installed application. * - * Returns: a string containing the @appinfo's application binaries name + * Returns: a string containing the @appinfo's application + * binaries name */ @@ -9398,7 +10664,8 @@ * those applications which claim to support the given content type * by MIME type subclassing and not directly. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ @@ -9409,7 +10676,8 @@ * * Gets the icon for the application. * - * Returns: (transfer none): the default #GIcon for @appinfo or %NULL if there is no default icon. + * Returns: (transfer none): the default #GIcon for @appinfo or %NULL + * if there is no default icon. */ @@ -9450,7 +10718,8 @@ * the last one for which g_app_info_set_as_last_used_for_type() has been * called. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ @@ -9466,7 +10735,8 @@ * g_app_info_add_supports_type(), but only those exported directly by * the application. * - * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): a list of content types. + * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): + * a list of content types. * Since: 2.34 */ @@ -9495,17 +10765,16 @@ * g_app_info_launch_uris() instead. * * The launched application inherits the environment of the launching - * process, but it can be modified with g_app_launch_context_setenv() and - * g_app_launch_context_unsetenv(). + * process, but it can be modified with g_app_launch_context_setenv() + * and g_app_launch_context_unsetenv(). * - * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar> + * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` * environment variable with the path of the launched desktop file and - * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process - * id of the launched process. This can be used to ignore - * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited - * by further processes. The <envar>DISPLAY</envar> and - * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also - * set, based on information provided in @launch_context. + * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched + * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, + * should it be inherited by further processes. The `DISPLAY` and + * `DESKTOP_STARTUP_ID` environment variables are also set, based + * on information provided in @launch_context. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ @@ -9549,6 +10818,24 @@ /** + * g_app_info_monitor_get: + * + * Gets the #GAppInfoMonitor for the current thread-default main + * context. + * + * The #GAppInfoMonitor will emit a "changed" signal in the + * thread-default main context whenever the list of installed + * applications (as reported by g_app_info_get_all()) may have changed. + * + * You must only call g_object_unref() on the return value from under + * the same main context as you created it. + * + * Returns: (transfer full): a reference to a #GAppInfoMonitor + * Since: 2.40 + */ + + +/** * g_app_info_remove_supports_type: * @appinfo: a #GAppInfo. * @content_type: a string. @@ -9652,7 +10939,7 @@ * * Gets the display string for the @context. This is used to ensure new * applications are started on the same display as the launching - * application, by setting the <envar>DISPLAY</envar> environment variable. + * application, by setting the `DISPLAY` environment variable. * * Returns: a display string for the display. */ @@ -9665,9 +10952,10 @@ * Gets the complete environment variable list to be passed to * the child process when @context is used to launch an application. * This is a %NULL-terminated array of strings, where each string has - * the form <literal>KEY=VALUE</literal>. + * the form `KEY=VALUE`. * - * Returns: (array zero-terminated=1) (transfer full): the child's environment + * Returns: (array zero-terminated=1) (transfer full): the + * child's environment * Since: 2.32 */ @@ -9679,14 +10967,13 @@ * @files: (element-type GFile): a #GList of of #GFile objects * * Initiates startup notification for the application and returns the - * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation, - * if supported. + * `DESKTOP_STARTUP_ID` for the launched operation, if supported. * - * Startup notification IDs are defined in the <ulink - * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> - * FreeDesktop.Org Startup Notifications standard</ulink>. + * Startup notification IDs are defined in the + * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"). * - * Returns: a startup notification ID for the application, or %NULL if not supported. + * Returns: a startup notification ID for the application, or %NULL if + * not supported. */ @@ -9751,18 +11038,129 @@ /** + * g_application_add_main_option_entries: + * @application: a #GApplication + * @entries: a %NULL-terminated list of #GOptionEntrys + * + * Adds main option entries to be handled by @application. + * + * This function is comparable to g_option_context_add_main_entries(). + * + * After the commandline arguments are parsed, the + * #GApplication::handle-local-options signal will be emitted. At this + * point, the application can inspect the values pointed to by @arg_data + * in the given #GOptionEntrys. + * + * Unlike #GOptionContext, #GApplication supports giving a %NULL + * @arg_data for a non-callback #GOptionEntry. This results in the + * argument in question being packed into a #GVariantDict which is also + * passed to #GApplication::handle-local-options, where it can be + * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is + * set, then the resulting dictionary is sent to the primary instance, + * where g_application_command_line_get_options_dict() will return it. + * This "packing" is done according to the type of the argument -- + * booleans for normal flags, strings for strings, bytestrings for + * filenames, etc. The packing only occurs if the flag is given (ie: we + * do not pack a "false" #GVariant in the case that a flag is missing). + * + * In general, it is recommended that all commandline arguments are + * parsed locally. The options dictionary should then be used to + * transmit the result of the parsing to the primary instance, where + * g_variant_dict_lookup() can be used. For local options, it is + * possible to either use @arg_data in the usual way, or to consult (and + * potentially remove) the option from the options dictionary. + * + * This function is new in GLib 2.40. Before then, the only real choice + * was to send all of the commandline arguments (options and all) to the + * primary instance for handling. #GApplication ignored them completely + * on the local side. Calling this function "opts in" to the new + * behaviour, and in particular, means that unrecognised options will be + * treated as errors. Unrecognised options have never been ignored when + * %G_APPLICATION_HANDLES_COMMAND_LINE is unset. + * + * If #GApplication::handle-local-options needs to see the list of + * filenames, then the use of %G_OPTION_REMAINING is recommended. If + * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into + * the options dictionary. If you do use %G_OPTION_REMAINING then you + * need to handle these arguments for yourself because once they are + * consumed, they will no longer be visible to the default handling + * (which treats them as filenames to be opened). + * + * Since: 2.40 + */ + + +/** + * g_application_add_option_group: + * @application: the #GApplication + * @group: a #GOptionGroup + * + * Adds a #GOptionGroup to the commandline handling of @application. + * + * This function is comparable to g_option_context_add_group(). + * + * Unlike g_application_add_main_option_entries(), this function does + * not deal with %NULL @arg_data and never transmits options to the + * primary instance. + * + * The reason for that is because, by the time the options arrive at the + * primary instance, it is typically too late to do anything with them. + * Taking the GTK option group as an example: GTK will already have been + * initialised by the time the #GApplication::command-line handler runs. + * In the case that this is not the first-running instance of the + * application, the existing instance may already have been running for + * a very long time. + * + * This means that the options from #GOptionGroup are only really usable + * in the case that the instance of the application being run is the + * first instance. Passing options like `--display=` or `--gdk-debug=` + * on future runs will have no effect on the existing primary instance. + * + * Calling this function will cause the options in the supplied option + * group to be parsed, but it does not cause you to be "opted in" to the + * new functionality whereby unrecognised options are rejected even if + * %G_APPLICATION_HANDLES_COMMAND_LINE was given. + * + * Since: 2.40 + */ + + +/** + * g_application_command_line_create_file_for_arg: + * @cmdline: a #GApplicationCommandLine + * @arg: an argument from @cmdline + * + * Creates a #GFile corresponding to a filename that was given as part + * of the invocation of @cmdline. + * + * This differs from g_file_new_for_commandline_arg() in that it + * resolves relative pathnames using the current working directory of + * the invoking process rather than the local process. + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 + */ + + +/** * g_application_command_line_get_arguments: * @cmdline: a #GApplicationCommandLine * @argc: (out) (allow-none): the length of the arguments array, or %NULL * * Gets the list of arguments that was passed on the command line. * - * The strings in the array may contain non-utf8 data. + * The strings in the array may contain non-UTF-8 data on UNIX (such as + * filenames or arguments given in the system locale) but are always in + * UTF-8 on Windows. + * + * If you wish to use the return value with #GOptionContext, you must + * use g_option_context_parse_strv(). * * The return value is %NULL-terminated and should be freed using * g_strfreev(). * - * Returns: (array length=argc) (transfer full): the string array containing the arguments (the argv) + * Returns: (array length=argc) (transfer full): the string array + * containing the arguments (the argv) * Since: 2.28 */ @@ -9805,7 +11203,8 @@ * See g_application_command_line_getenv() if you are only interested * in the value of a single environment variable. * - * Returns: (array zero-terminated=1) (transfer none): the environment strings, or %NULL if they were not sent + * Returns: (array zero-terminated=1) (transfer none): the environment + * strings, or %NULL if they were not sent * Since: 2.28 */ @@ -9834,6 +11233,25 @@ /** + * g_application_command_line_get_options_dict: + * @cmdline: a #GApplicationCommandLine + * + * Gets the options there were passed to g_application_command_line(). + * + * If you did not override local_command_line() then these are the same + * options that were parsed according to the #GOptionEntrys added to the + * application with g_application_add_main_option_entries() and possibly + * modified from your GApplication::handle-local-options handler. + * + * If no options were sent then an empty dictionary is returned so that + * you don't need to check for %NULL. + * + * Returns: (transfer none): a #GVariantDict with the options + * Since: 2.40 + */ + + +/** * g_application_command_line_get_platform_data: * @cmdline: #GApplicationCommandLine * @@ -9852,6 +11270,26 @@ /** + * g_application_command_line_get_stdin: + * @cmdline: a #GApplicationCommandLine + * + * Gets the stdin of the invoking process. + * + * The #GInputStream can be used to read data passed to the standard + * input of the invoking process. + * This doesn't work on all platforms. Presently, it is only available + * on UNIX when using a DBus daemon capable of passing file descriptors. + * If stdin is not available then %NULL will be returned. In the + * future, support may be expanded to other platforms. + * + * You must only call this function once per commandline invocation. + * + * Returns: (transfer full): a #GInputStream for stdin + * Since: 2.34 + */ + + +/** * g_application_command_line_getenv: * @cmdline: a #GApplicationCommandLine * @name: the environment variable to get @@ -10098,27 +11536,51 @@ * * For convenience, the restrictions on application identifiers are * reproduced here: - * <itemizedlist> - * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem> - * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem> - * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem> - * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem> - * <listitem>Application identifiers must not exceed 255 characters.</listitem> - * </itemizedlist> + * + * - Application identifiers must contain only the ASCII characters + * "[A-Z][a-z][0-9]_-." and must not begin with a digit. + * + * - Application identifiers must contain at least one '.' (period) + * character (and thus at least three elements). + * + * - Application identifiers must not begin or end with a '.' (period) + * character. + * + * - Application identifiers must not contain consecutive '.' (period) + * characters. + * + * - Application identifiers must not exceed 255 characters. * * Returns: %TRUE if @application_id is valid */ /** + * g_application_mark_busy: + * @application: a #GApplication + * + * Increases the busy count of @application. + * + * Use this function to indicate that the application is busy, for instance + * while a long running operation is pending. + * + * The busy state will be exposed to other processes, so a session shell will + * use that information to indicate the state to the user (e.g. with a + * spinner). + * + * To cancel the busy indication, use g_application_unmark_busy(). + * + * Since: 2.38 + */ + + +/** * g_application_new: * @application_id: (allow-none): the application id * @flags: the application flags * * Creates a new #GApplication instance. * - * This function calls g_type_init() for you. - * * If non-%NULL, the application id must be valid. See * g_application_id_is_valid(). * @@ -10240,66 +11702,76 @@ * is intended to be returned by main(). Although you are expected to pass * the @argc, @argv parameters from main() to this function, it is possible * to pass %NULL if @argv is not available or commandline handling is not - * required. - * - * First, the local_command_line() virtual function is invoked. - * This function always runs on the local instance. It gets passed a pointer - * to a %NULL-terminated copy of @argv and is expected to remove the arguments - * that it handled (shifting up remaining arguments). See - * <xref linkend="gapplication-example-cmdline2"/> for an example of - * parsing @argv manually. Alternatively, you may use the #GOptionContext API, - * after setting <literal>argc = g_strv_length (argv);</literal>. - * - * The last argument to local_command_line() is a pointer to the @status - * variable which can used to set the exit status that is returned from - * g_application_run(). - * - * If local_command_line() returns %TRUE, the command line is expected - * to be completely handled, including possibly registering as the primary - * instance, calling g_application_activate() or g_application_open(), etc. - * - * If local_command_line() returns %FALSE then the application is registered - * and the #GApplication::command-line signal is emitted in the primary - * instance (which may or may not be this instance). The signal handler - * gets passed a #GApplicationCommandLine object that (among other things) - * contains the remaining commandline arguments that have not been handled - * by local_command_line(). - * - * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE - * flag set then the default implementation of local_command_line() - * always returns %FALSE immediately, resulting in the commandline - * always being handled in the primary instance. - * - * Otherwise, the default implementation of local_command_line() tries - * to do a couple of things that are probably reasonable for most - * applications. First, g_application_register() is called to attempt - * to register the application. If that works, then the command line - * arguments are inspected. If no commandline arguments are given, then - * g_application_activate() is called. If commandline arguments are - * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they - * are assumed to be filenames and g_application_open() is called. - * - * If you need to handle commandline arguments that are not filenames, - * and you don't mind commandline handling to happen in the primary - * instance, you should set %G_APPLICATION_HANDLES_COMMAND_LINE and - * process the commandline arguments in your #GApplication::command-line - * signal handler, either manually or using the #GOptionContext API. + * required. Note that on Windows, @argc and @argv are ignored, and + * g_win32_get_command_line() is called internally (for proper support + * of Unicode commandline arguments). + * + * #GApplication will attempt to parse the commandline arguments. You + * can add commandline flags to the list of recognised options by way of + * g_application_add_main_option_entries(). After this, the + * #GApplication::handle-local-options signal is emitted, from which the + * application can inspect the values of its #GOptionEntrys. + * + * #GApplication::handle-local-options is a good place to handle options + * such as `--version`, where an immediate reply from the local process is + * desired (instead of communicating with an already-running instance). + * A #GApplication::handle-local-options handler can stop further processing + * by returning a non-negative value, which then becomes the exit status of + * the process. + * + * What happens next depends on the flags: if + * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining + * commandline arguments are sent to the primary instance, where a + * #GApplication::command-line signal is emitted. Otherwise, the + * remaining commandline arguments are assumed to be a list of files. + * If there are no files listed, the application is activated via the + * #GApplication::activate signal. If there are one or more files, and + * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened + * via the #GApplication::open signal. * * If you are interested in doing more complicated local handling of the * commandline then you should implement your own #GApplication subclass * and override local_command_line(). In this case, you most likely want * to return %TRUE from your local_command_line() implementation to * suppress the default handling. See - * <xref linkend="gapplication-example-cmdline2"/> for an example. + * [gapplication-example-cmdline2.c][gapplication-example-cmdline2] + * for an example. * * If, after the above is done, the use count of the application is zero * then the exit status is returned immediately. If the use count is * non-zero then the default main context is iterated until the use count * falls to zero, at which point 0 is returned. * - * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at - * use count of zero is delayed for a while (ie: the instance stays - * around to provide its <emphasis>service</emphasis> to others). + * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will + * run for as much as 10 seconds with a use count of zero while waiting + * for the message that caused the activation to arrive. After that, + * if the use count falls to zero the application will exit immediately, + * except in the case that g_application_set_inactivity_timeout() is in + * use. + * + * This function sets the prgname (g_set_prgname()), if not already set, + * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE + * is specified, the prgname is set to the application ID. The main + * impact of this is is that the wmclass of windows created by Gtk+ will + * be set accordingly, which helps the window manager determine which + * application is showing the window. + * + * Since 2.40, applications that are not explicitly flagged as services + * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or + * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the + * default handler for local_command_line) if "--gapplication-service" + * was given in the command line. If this flag is present then normal + * commandline processing is interrupted and the + * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" + * solution whereby running an application directly from the commandline + * will invoke it in the normal way (which can be useful for debugging) + * while still allowing applications to be D-Bus activated in service + * mode. The D-Bus service file should invoke the executable with + * "--gapplication-service" as the sole commandline argument. This + * approach is suitable for use by most graphical applications but + * should not be used from applications like editors that need precise + * control over when processes invoked via the commandline will exit and + * what their exit status will be. * * Returns: the exit status * Since: 2.28 @@ -10307,6 +11779,43 @@ /** + * g_application_send_notification: + * @application: a #GApplication + * @id: (allow-none): id of the notification, or %NULL + * @notification: the #GNotification to send + * + * Sends a notification on behalf of @application to the desktop shell. + * There is no guarantee that the notification is displayed immediately, + * or even at all. + * + * Notifications may persist after the application exits. It will be + * D-Bus-activated when the notification or one of its actions is + * activated. + * + * Modifying @notification after this call has no effect. However, the + * object can be reused for a later call to this function. + * + * @id may be any string that uniquely identifies the event for the + * application. It does not need to be in any special format. For + * example, "new-message" might be appropriate for a notification about + * new messages. + * + * If a previous notification was sent with the same @id, it will be + * replaced with @notification and shown again as if it was a new + * notification. This works even for notifications sent from a previous + * execution of the application, as long as @id is the same string. + * + * @id may be %NULL, but it is impossible to replace or withdraw + * notifications without an id. + * + * If @notification is no longer relevant, it can be withdrawn with + * g_application_withdraw_notification(). + * + * Since: 2.40 + */ + + +/** * g_application_set_action_group: * @application: a #GApplication * @action_group: (allow-none): a #GActionGroup, or %NULL @@ -10315,7 +11824,11 @@ * Now there is #GActionMap for that. * * Since: 2.28 - * Deprecated: 2.32:Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead. + * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever + * mix use of this API with use of #GActionMap on the same @application + * or things will go very badly wrong. This function is known to + * introduce buggy behaviour (ie: signals not emitted on changes to the + * action group), so you should really use #GActionMap instead. */ @@ -10386,9 +11899,48 @@ /** + * g_application_unmark_busy: + * @application: a #GApplication + * + * Decreases the busy count of @application. + * + * When the busy count reaches zero, the new state will be propagated + * to other processes. + * + * This function must only be called to cancel the effect of a previous + * call to g_application_mark_busy(). + * + * Since: 2.38 + */ + + +/** + * g_application_withdraw_notification: + * @application: a #GApplication + * @id: id of a previously sent notification + * + * Withdraws a notification that was sent with + * g_application_send_notification(). + * + * This call does nothing if a notification with @id doesn't exist or + * the notification was never sent. + * + * This function works even for notifications sent in previous + * executions of this application, as long @id is the same as it was for + * the sent notification. + * + * Note that notifications are dismissed when the user clicks on one + * of the buttons in a notification or triggers its default action, so + * there is no need to explicitly withdraw the notification in that case. + * + * Since: 2.40 + */ + + +/** * g_async_initable_init_async: * @initable: a #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -10435,12 +11987,14 @@ * g_async_initable_init_finish: * @initable: a #GAsyncInitable. * @res: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes asynchronous initialization and returns the result. * See g_async_initable_init_async(). * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. * Since: 2.22 */ @@ -10448,12 +12002,15 @@ /** * g_async_initable_new_async: * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function - * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties - * @...: the value of the first property, followed by other property value pairs, and ended by %NULL. + * @first_property_name: (allow-none): the name of the first property, or %NULL if no + * properties + * @...: the value of the first property, followed by other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GAsyncInitable object. This is * similar to g_object_new() but also initializes the object asynchronously. @@ -10475,7 +12032,8 @@ * Finishes the async construction for the various g_async_initable_new * calls, returning the created object or %NULL on error. * - * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref(). + * Returns: (type GObject.Object) (transfer full): a newly created #GObject, + * or %NULL on error. Free with g_object_unref(). * Since: 2.22 */ @@ -10483,11 +12041,13 @@ /** * g_async_initable_new_valist_async: * @object_type: a #GType supporting #GAsyncInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, followed by + * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function * * Helper function for constructing #GAsyncInitable object. This is @@ -10507,9 +12067,10 @@ * @object_type: a #GType supporting #GAsyncInitable. * @n_parameters: the number of parameters in @parameters * @parameters: the parameters to use to construct the object - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function * * Helper function for constructing #GAsyncInitable object. This is @@ -10529,7 +12090,8 @@ * * Gets the source object from a #GAsyncResult. * - * Returns: (transfer full): a new reference to the source object for the @res, or %NULL if there is none. + * Returns: (transfer full): a new reference to the source object for the @res, + * or %NULL if there is none. */ @@ -10551,7 +12113,8 @@ * Checks if @res has the given @source_tag (generally a function * pointer indicating the function @res was created by). * - * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if not. + * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if + * not. * Since: 2.34 */ @@ -10565,15 +12128,15 @@ * g_simple_async_result_propagate_error(). Otherwise it returns * %FALSE. * - * This can be used for legacy error handling in async - * <literal>_finish ()</literal> wrapper functions that traditionally - * handled #GSimpleAsyncResult error returns themselves rather than - * calling into the virtual method. This should not be used in new - * code; #GAsyncResult errors that are set by virtual methods should - * also be extracted by virtual methods, to enable subclasses to chain - * up correctly. + * This can be used for legacy error handling in async *_finish() + * wrapper functions that traditionally handled #GSimpleAsyncResult + * error returns themselves rather than calling into the virtual method. + * This should not be used in new code; #GAsyncResult errors that are + * set by virtual methods should also be extracted by virtual methods, + * to enable subclasses to chain up correctly. * - * Returns: %TRUE if @error is has been filled in with an error from @res, %FALSE if not. + * Returns: %TRUE if @error is has been filled in with an error from + * @res, %FALSE if not. * Since: 2.34 */ @@ -10610,7 +12173,8 @@ * For the asynchronous, non-blocking, version of this function, see * g_buffered_input_stream_fill_async(). * - * Returns: the number of bytes read into @stream's buffer, up to @count, or -1 on error. + * Returns: the number of bytes read into @stream's buffer, up to @count, + * or -1 on error. */ @@ -10618,7 +12182,7 @@ * g_buffered_input_stream_fill_async: * @stream: a #GBufferedInputStream * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer @@ -10690,7 +12254,8 @@ /** * g_buffered_input_stream_peek: * @stream: a #GBufferedInputStream - * @buffer: (array length=count) (element-type guint8): a pointer to an allocated chunk of memory + * @buffer: (array length=count) (element-type guint8): a pointer to + * an allocated chunk of memory * @offset: a #gsize * @count: a #gsize * @@ -10710,7 +12275,8 @@ * buffer must not be modified and will become invalid when reading from * the stream or filling the buffer. * - * Returns: (array length=count) (element-type guint8) (transfer none): read-only buffer + * Returns: (array length=count) (element-type guint8) (transfer none): + * read-only buffer */ @@ -10755,7 +12321,8 @@ * * Checks if the buffer automatically grows as data is added. * - * Returns: %TRUE if the @stream's buffer automatically grows, %FALSE otherwise. + * Returns: %TRUE if the @stream's buffer automatically grows, + * %FALSE otherwise. */ @@ -10813,10 +12380,10 @@ /** * g_bus_get: - * @bus_type: A #GBusType. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * @bus_type: a #GBusType + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * * Asynchronously connects to the message bus specified by @bus_type. * @@ -10832,8 +12399,9 @@ /** * g_bus_get_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_bus_get() + * @error: return location for error or %NULL * * Finishes an operation started with g_bus_get(). * @@ -10846,16 +12414,17 @@ * Note that the returned #GDBusConnection object will (usually) have * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ /** * g_bus_get_sync: - * @bus_type: A #GBusType. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @bus_type: a #GBusType + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously connects to the message bus specified by @bus_type. * Note that the returned object may shared with other callers, @@ -10874,51 +12443,51 @@ * Note that the returned #GDBusConnection object will (usually) have * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ /** * g_bus_own_name: - * @bus_type: The type of bus to own a name on. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_handler: (allow-none): Handler to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL. - * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL. + * @bus_type: the type of bus to own a name on + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @bus_acquired_handler: (allow-none): handler to invoke when connected to the bus of type @bus_type or %NULL + * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL + * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL + * @user_data: user data to pass to handlers + * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL * * Starts acquiring @name on the bus specified by @bus_type and calls * @name_acquired_handler and @name_lost_handler when the name is - * acquired respectively lost. Callbacks 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 function from. + * acquired respectively lost. Callbacks will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this function from. * * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler * callbacks will be invoked after calling this function - there are three * possible cases: - * <itemizedlist> - * <listitem><para> - * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made). - * </para></listitem> - * <listitem><para> - * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained) - * </para></listitem> - * <listitem><para> - * @bus_acquired_handler then @name_acquired_handler (if the name was obtained). - * </para></listitem> - * </itemizedlist> + * + * - @name_lost_handler with a %NULL connection (if a connection to the bus + * can't be made). + * + * - @bus_acquired_handler then @name_lost_handler (if the name can't be + * obtained) + * + * - @bus_acquired_handler then @name_acquired_handler (if the name was + * obtained). + * * When you are done owning the name, just call g_bus_unown_name() * with the owner id this function returns. * * If the name is acquired or lost (for example another application * could acquire the name if you allow replacement or the application - * currently owning the name exits), the handlers are also invoked. If the - * #GDBusConnection that is used for attempting to own the name - * closes, then @name_lost_handler is invoked since it is no - * longer possible for other processes to access the process. + * currently owning the name exits), the handlers are also invoked. + * If the #GDBusConnection that is used for attempting to own the name + * closes, then @name_lost_handler is invoked since it is no longer + * possible for other processes to access the process. * * You cannot use g_bus_own_name() several times for the same name (unless * interleaved with calls to g_bus_unown_name()) - only the first call @@ -10937,71 +12506,78 @@ * before @name is requested from the bus. * * This behavior makes it very simple to write applications that wants - * to own names and export objects, see <xref linkend="gdbus-owning-names"/>. + * to [own names][gdbus-owning-names] and export objects. * Simply register objects to be exported in @bus_acquired_handler and * unregister the objects (if any) in @name_lost_handler. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ /** * g_bus_own_name_on_connection: - * @connection: A #GDBusConnection. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL. - * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL. + * @connection: a #GDBusConnection + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL + * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL + * @user_data: user data to pass to handlers + * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL * * Like g_bus_own_name() but takes a #GDBusConnection instead of a * #GBusType. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name * Since: 2.26 */ /** - * g_bus_own_name_on_connection_with_closures: - * @connection: A #GDBusConnection. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection) + * @connection: a #GDBusConnection + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is + * acquired or %NULL + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost + * or %NULL * - * Version of g_bus_own_name_on_connection() using closures instead of callbacks for - * easier binding in other languages. + * Version of g_bus_own_name_on_connection() using closures instead of + * callbacks for easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. - * Rename to: g_bus_own_name_on_connection + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ /** - * g_bus_own_name_with_closures: - * @bus_type: The type of bus to own a name on. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * g_bus_own_name_with_closures: (rename-to g_bus_own_name) + * @bus_type: the type of bus to own a name on + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to + * the bus of type @bus_type or %NULL + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is + * acquired or %NULL + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or + * %NULL * * Version of g_bus_own_name() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. - * Rename to: g_bus_own_name + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ /** * g_bus_unown_name: - * @owner_id: An identifier obtained from g_bus_own_name() + * @owner_id: an identifier obtained from g_bus_own_name() * * Stops owning a name. * @@ -11032,9 +12608,9 @@ * Starts watching @name on the bus specified by @bus_type and calls * @name_appeared_handler and @name_vanished_handler when the name is * known to have a owner respectively known to lose its - * owner. Callbacks 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 function from. + * owner. Callbacks will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this function from. * * You are guaranteed that one of the handlers will be invoked after * calling this function. When you are done watching the name, just @@ -11053,13 +12629,14 @@ * guaranteed that the next time one of the handlers is invoked, it * will be @name_vanished_handler. The reverse is also true. * - * This behavior makes it very simple to write applications that wants - * to take action when a certain name exists, see <xref - * linkend="gdbus-watching-names"/>. Basically, the application - * should create object proxies in @name_appeared_handler and destroy - * them again (if any) in @name_vanished_handler. + * This behavior makes it very simple to write applications that want + * to take action when a certain [name exists][gdbus-watching-names]. + * Basically, the application should create object proxies in + * @name_appeared_handler and destroy them again (if any) in + * @name_vanished_handler. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ @@ -11077,46 +12654,74 @@ * Like g_bus_watch_name() but takes a #GDBusConnection instead of a * #GBusType. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ /** - * g_bus_watch_name_on_connection_with_closures: + * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection) * @connection: A #GDBusConnection. * @name: The name (well-known or unique) to watch. * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known + * to not exist or %NULL. * * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. - * Rename to: g_bus_watch_name_on_connection + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ /** - * g_bus_watch_name_with_closures: + * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name) * @bus_type: The type of bus to watch a name on. * @name: The name (well-known or unique) to watch. * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known + * to not exist or %NULL. * * Version of g_bus_watch_name() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. - * Rename to: g_bus_watch_name + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ /** + * g_bytes_icon_get_bytes: + * @icon: a #GIcon. + * + * Gets the #GBytes associated with the given @icon. + * + * Returns: (transfer none): a #GBytes, or %NULL. + * Since: 2.38 + */ + + +/** + * g_bytes_icon_new: + * @bytes: a #GBytes. + * + * Creates a new icon for a bytes. + * + * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given + * @bytes, or %NULL on error. + * Since: 2.38 + */ + + +/** * g_cancellable_cancel: * @cancellable: a #GCancellable object. * @@ -11158,7 +12763,13 @@ * * See #GCancellable::cancelled for details on how to use this. * - * Returns: The id of the signal handler or 0 if @cancellable has already been cancelled. + * Since GLib 2.40, the lock protecting @cancellable is not held when + * @callback is invoked. This lifts a restriction in place for + * earlier GLib versions which now makes it easier to write cleanup + * code that unconditionally invokes e.g. g_cancellable_cancel(). + * + * Returns: The id of the signal handler or 0 if @cancellable has already + * been cancelled. * Since: 2.22 */ @@ -11192,7 +12803,8 @@ * * Gets the top cancellable from the stack. * - * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL if the stack is empty. + * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL + * if the stack is empty. */ @@ -11214,7 +12826,8 @@ * * See also g_cancellable_make_pollfd(). * - * Returns: A valid file descriptor. %-1 if the file descriptor is not supported, or on errors. + * Returns: A valid file descriptor. %-1 if the file descriptor + * is not supported, or on errors. */ @@ -11224,7 +12837,8 @@ * * Checks if a cancellable job has been cancelled. * - * Returns: %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled. + * Returns: %TRUE if @cancellable is cancelled, + * FALSE if called with %NULL or if item is not cancelled. */ @@ -11252,7 +12866,8 @@ * readable status. Reading to unset the readable status is done * with g_cancellable_reset(). * - * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable. + * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on + * failure to prepare the cancellable. * Since: 2.22 */ @@ -11408,7 +13023,8 @@ * Checks if a content type can be executable. Note that for instance * things like text files can be executables (i.e. scripts and batch files). * - * Returns: %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise. + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. */ @@ -11419,7 +13035,8 @@ * * Compares two content types for equality. * - * Returns: %TRUE if the two strings are identical or equivalent, %FALSE otherwise. + * Returns: %TRUE if the two strings are identical or equivalent, + * %FALSE otherwise. */ @@ -11429,7 +13046,8 @@ * * Tries to find a content type based on the mime type name. * - * Returns: (allow-none): Newly allocated string with content type or %NULL. Free with g_free() + * Returns: (allow-none): Newly allocated string with content type + * or %NULL. Free with g_free() * Since: 2.18 */ @@ -11440,7 +13058,8 @@ * * Gets the human readable description of the content type. * - * Returns: a short description of the content type @type. Free the returned string with g_free() + * Returns: a short description of the content type @type. Free the + * returned string with g_free() */ @@ -11450,10 +13069,12 @@ * * Gets the generic icon name for a content type. * - * See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) * specification for more on the generic icon name. * - * Returns: (allow-none): the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free() + * Returns: (allow-none): the registered generic icon name for the given @type, + * or %NULL if unknown. Free with g_free() * Since: 2.34 */ @@ -11464,7 +13085,8 @@ * * Gets the icon for a content type. * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned object with g_object_unref() + * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned + * object with g_object_unref() */ @@ -11474,7 +13096,8 @@ * * Gets the mime type for the content type, if one is registered. * - * Returns: (allow-none): the registered mime type for the given @type, or %NULL if unknown. + * Returns: (allow-none): the registered mime type for the given @type, + * or %NULL if unknown. */ @@ -11484,7 +13107,8 @@ * * Gets the symbolic icon for a content type. * - * Returns: (transfer full): symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref() + * Returns: (transfer full): symbolic #GIcon corresponding to the content type. + * Free the returned object with g_object_unref() * Since: 2.34 */ @@ -11494,14 +13118,16 @@ * @filename: (allow-none): a string, or %NULL * @data: (allow-none) (array length=data_size): a stream of data, or %NULL * @data_size: the size of @data - * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL + * @result_uncertain: (allow-none) (out): return location for the certainty + * of the result, or %NULL * * Guesses the content type based on example data. If the function is * uncertain, @result_uncertain will be set to %TRUE. Either @filename * or @data may be %NULL, in which case the guess will be based solely * on the other argument. * - * Returns: a string indicating a guessed content type for the given data. Free with g_free() + * Returns: a string indicating a guessed content type for the + * given data. Free with g_free() */ @@ -11515,13 +13141,15 @@ * * The types returned all have the form x-content/foo, e.g. * x-content/audio-cdda (for audio CDs) or x-content/image-dcf - * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * (for a camera memory card). See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) * specification for more on x-content types. * * This function is useful in the implementation of * g_mount_guess_content_type(). * - * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated array of zero or more content types. Free with g_strfreev() + * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated + * array of zero or more content types. Free with g_strfreev() * Since: 2.18 */ @@ -11533,7 +13161,8 @@ * * Determines if @type is a subset of @supertype. * - * Returns: %TRUE if @type is a kind of @supertype, %FALSE otherwise. + * Returns: %TRUE if @type is a kind of @supertype, + * %FALSE otherwise. */ @@ -11554,18 +13183,18 @@ * * Gets a list of strings containing all the registered content types * known to the system. The list and its data should be freed using - * <programlisting> - * g_list_free_full (list, g_free); - * </programlisting> + * g_list_free_full (list, g_free). * - * Returns: (element-type utf8) (transfer full): #GList of the registered content types + * Returns: (element-type utf8) (transfer full): list of the registered + * content types */ /** * g_converter_convert: * @converter: a #GConverter. - * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert. + * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer + * containing the data to convert. * @inbuf_size: the number of bytes in @inbuf * @outbuf: a buffer to write converted data in. * @outbuf_size: the number of bytes in @outbuf, must be at least one @@ -11730,12 +13359,32 @@ * logged) to use this method if there is no #GCredentials support for * the OS or if @native_type isn't supported by the OS. * - * Returns: The pointer to native credentials or %NULL if the operation there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Do not free the returned data, it is owned by @credentials. + * Returns: The pointer to native credentials or %NULL if the + * operation there is no #GCredentials support for the OS or if + * @native_type isn't supported by the OS. Do not free the returned + * data, it is owned by @credentials. * Since: 2.26 */ /** + * g_credentials_get_unix_pid: + * @credentials: A #GCredentials + * @error: Return location for error or %NULL. + * + * Tries to get the UNIX process identifier from @credentials. This + * method is only available on UNIX platforms. + * + * This operation can fail if #GCredentials is not supported on the + * OS or if the native credentials type does not contain information + * about the UNIX process ID. + * + * Returns: The UNIX process ID, or -1 if @error is set. + * Since: 2.36 + */ + + +/** * g_credentials_get_unix_user: * @credentials: A #GCredentials * @error: Return location for error or %NULL. @@ -11763,7 +13412,8 @@ * This operation can fail if #GCredentials is not supported on the * the OS. * - * Returns: %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set. + * Returns: %TRUE if @credentials and @other_credentials has the same + * user, %FALSE otherwise or if @error is set. * Since: 2.26 */ @@ -11807,7 +13457,8 @@ * * This operation can fail if #GCredentials is not supported on the * OS or if the native credentials type does not contain information - * about the UNIX user. + * about the UNIX user. It can also fail if the OS does not allow the + * use of "spoofed" credentials. * * Returns: %TRUE if @uid was set, %FALSE if error is set. * Since: 2.26 @@ -11865,7 +13516,8 @@ * * Reads an unsigned 8-bit/1-byte value from @stream. * - * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 + * if an error occurred. */ @@ -11880,7 +13532,8 @@ * In order to get the correct byte order for this read operation, * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). * - * Returns: a signed 16-bit/2-byte value read from @stream or %0 if an error occurred. + * Returns: a signed 16-bit/2-byte value read from @stream or %0 if + * an error occurred. */ @@ -11899,7 +13552,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if an error occurred. + * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ @@ -11918,7 +13572,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a signed 64-bit/8-byte value read from @stream or %0 if an error occurred. + * Returns: a signed 64-bit/8-byte value read from @stream or %0 if + * an error occurred. */ @@ -11937,14 +13592,19 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a + * NUL terminated byte array with the line that was read in (without + * the newlines). Set @length to a #gsize to get the length of the + * read line. On an error, it will return %NULL and @error will be + * set. If there's no content to read, it will still return %NULL, + * but @error won't be set. */ /** * g_data_input_stream_read_line_async: * @stream: a given #GDataInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -11972,7 +13632,12 @@ * string encoding in g_data_input_stream_read_line() applies here as * well. * - * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL-terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a + * NUL-terminated byte array with the line that was read in + * (without the newlines). Set @length to a #gsize to get the + * length of the read line. On an error, it will return %NULL and + * @error will be set. If there's no content to read, it will + * still return %NULL, but @error won't be set. * Since: 2.20 */ @@ -11987,7 +13652,12 @@ * Finish an asynchronous call started by * g_data_input_stream_read_line_async(). * - * Returns: (transfer full): a string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full): a string with the line that was read in + * (without the newlines). Set @length to a #gsize to get the length + * of the read line. On an error, it will return %NULL and @error + * will be set. For UTF-8 conversion errors, the set error domain is + * %G_CONVERT_ERROR. If there's no content to read, it will still + * return %NULL, but @error won't be set. * Since: 2.30 */ @@ -12005,7 +13675,12 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full): a NUL terminated UTF-8 string with the + * line that was read in (without the newlines). Set @length to a + * #gsize to get the length of the read line. On an error, it will + * return %NULL and @error will be set. For UTF-8 conversion errors, + * the set error domain is %G_CONVERT_ERROR. If there's no content to + * read, it will still return %NULL, but @error won't be set. * Since: 2.30 */ @@ -12021,7 +13696,8 @@ * In order to get the correct byte order for this read operation, * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). * - * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if + * an error occurred. */ @@ -12040,7 +13716,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ @@ -12059,7 +13736,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if an error occurred. + * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if + * an error occurred. */ @@ -12083,7 +13761,10 @@ * g_data_input_stream_read_upto() instead, but note that that function * does not consume the stop character. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. */ @@ -12091,7 +13772,7 @@ * g_data_input_stream_read_until_async: * @stream: a given #GDataInputStream. * @stop_chars: characters to terminate the read. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -12127,7 +13808,10 @@ * g_data_input_stream_read_until_async(). * * Since: 2.20 - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. */ @@ -12135,7 +13819,8 @@ * g_data_input_stream_read_upto: * @stream: a #GDataInputStream * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is + * nul-terminated * @length: (out): a #gsize to get the length of the data read in * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @error: #GError for error reporting @@ -12144,14 +13829,17 @@ * occurrence of any of the stop characters. * * In contrast to g_data_input_stream_read_until(), this function - * does <emphasis>not</emphasis> consume the stop character. You have - * to use g_data_input_stream_read_byte() to get it before calling + * does not consume the stop character. You have to use + * g_data_input_stream_read_byte() to get it before calling * g_data_input_stream_read_upto() again. * * Note that @stop_chars may contain '\0' if @stop_chars_len is * specified. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error * Since: 2.26 */ @@ -12160,8 +13848,9 @@ * g_data_input_stream_read_upto_async: * @stream: a #GDataInputStream * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is + * nul-terminated + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -12170,8 +13859,8 @@ * It is an error to have two outstanding calls to this function. * * In contrast to g_data_input_stream_read_until(), this function - * does <emphasis>not</emphasis> consume the stop character. You have - * to use g_data_input_stream_read_byte() to get it before calling + * does not consume the stop character. You have to use + * g_data_input_stream_read_byte() to get it before calling * g_data_input_stream_read_upto() again. * * Note that @stop_chars may contain '\0' if @stop_chars_len is @@ -12195,11 +13884,14 @@ * Finish an asynchronous call started by * g_data_input_stream_read_upto_async(). * - * Note that this function does <emphasis>not</emphasis> consume the - * stop character. You have to use g_data_input_stream_read_byte() to - * get it before calling g_data_input_stream_read_upto_async() again. + * Note that this function does not consume the stop character. You + * have to use g_data_input_stream_read_byte() to get it before calling + * g_data_input_stream_read_upto_async() again. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. * Since: 2.24 */ @@ -12386,16 +14078,36 @@ /** + * g_dbus_address_escape_value: + * @string: an unescaped string to be included in a D-Bus address + * as the value in a key-value pair + * + * Escape @string so it can appear in a D-Bus address as the value + * part of a key-value pair. + * + * For instance, if @string is "/run/bus-for-:0", + * this function would return "/run/bus-for-%3A0", + * which could be used in a D-Bus address like + * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0". + * + * Returns: (transfer full): a copy of @string with all + * non-optionally-escaped bytes escaped + * Since: 2.36 + */ + + +/** * g_dbus_address_get_for_bus_sync: - * @bus_type: A #GBusType. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @bus_type: a #GBusType + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously looks up the D-Bus address for the well-known message * bus instance specified by @bus_type. This may involve using various * platform specific mechanisms. * - * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set. + * Returns: a valid D-Bus address string for @bus_type or %NULL if + * @error is set * Since: 2.26 */ @@ -12461,7 +14173,7 @@ * * Looks up the value of an annotation. * - * This cost of this function is O(n) in number of annotations. + * The cost of this function is O(n) in number of annotations. * * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. * Since: 2.26 @@ -12519,7 +14231,7 @@ /** * g_dbus_auth_observer_allow_mechanism: * @observer: A #GDBusAuthObserver. - * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>. + * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. * * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. * @@ -12553,10 +14265,11 @@ /** * g_dbus_connection_add_filter: - * @connection: A #GDBusConnection. - * @filter_function: A filter function. - * @user_data: User data to pass to @filter_function. - * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL. + * @connection: a #GDBusConnection + * @filter_function: a filter function + * @user_data: user data to pass to @filter_function + * @user_data_free_func: function to free @user_data with when filter + * is removed or %NULL * * Adds a message filter. Filters are handlers that are run on all * incoming and outgoing messages, prior to standard dispatch. Filters @@ -12579,25 +14292,31 @@ * message. Similary, if a filter consumes an outgoing message, the * message will not be sent to the other peer. * - * Returns: A filter identifier that can be used with g_dbus_connection_remove_filter(). + * Returns: a filter identifier that can be used with + * g_dbus_connection_remove_filter() * Since: 2.26 */ /** * g_dbus_connection_call: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL if + * @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request + * is satisfied or %NULL if you don't care about the result of the + * method invocation + * @user_data: the data to pass to @callback * * Asynchronously invokes the @method_name method on the * @interface_name D-Bus interface on the remote object at @@ -12615,7 +14334,7 @@ * * If the @parameters #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g.: - * |[ + * |[<!-- language="C" --> * g_dbus_connection_call (connection, * "org.freedesktop.StringThings", * "/org/freedesktop/StringThings", @@ -12632,8 +14351,9 @@ * NULL); * ]| * - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * This is an asynchronous method. When the operation is finished, + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can then call * g_dbus_connection_call_finish() to get the result of the operation. * See g_dbus_connection_call_sync() for the synchronous version of this @@ -12648,30 +14368,34 @@ /** * g_dbus_connection_call_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ /** * g_dbus_connection_call_sync: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL if + * @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously invokes the @method_name method on the * @interface_name D-Bus interface on the remote object at @@ -12690,7 +14414,7 @@ * * If the @parameters #GVariant is floating, it is consumed. * This allows convenient 'inline' use of g_variant_new(), e.g.: - * |[ + * |[<!-- language="C" --> * g_dbus_connection_call_sync (connection, * "org.freedesktop.StringThings", * "/org/freedesktop/StringThings", @@ -12703,32 +14427,38 @@ * G_DBUS_CALL_FLAGS_NONE, * -1, * NULL, - * &error); + * &error); * ]| * * The calling thread is blocked until a reply is received. See * g_dbus_connection_call() for the asynchronous version of * this method. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ /** * g_dbus_connection_call_with_unix_fd_list: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @fd_list: (allow-none): A #GUnixFDList or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL if + * @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @fd_list: (allow-none): a #GUnixFDList or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't * care about the result of the + * method invocation * @user_data: The data to pass to @callback. * * Like g_dbus_connection_call() but also takes a #GUnixFDList object. @@ -12741,49 +14471,56 @@ /** * g_dbus_connection_call_with_unix_fd_list_finish: - * @connection: A #GDBusConnection. - * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + * g_dbus_connection_call_with_unix_fd_list() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ /** * g_dbus_connection_call_with_unix_fd_list_sync: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @fd_list: (allow-none): A #GUnixFDList or %NULL. - * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL + * if @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for + * the method or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @fd_list: (allow-none): a #GUnixFDList or %NULL + * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ /** * g_dbus_connection_close: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback * * Closes @connection. Note that this never causes the process to * exit (this might only happen if the other end of a shared message @@ -12798,16 +14535,16 @@ * %G_IO_ERROR_CLOSED. * * When @connection has been closed, the #GDBusConnection::closed - * signal is emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread that @connection was constructed in. + * signal is emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @connection was constructed in. * * This is an asynchronous method. 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. You can + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. You can * then call g_dbus_connection_close_finish() to get the result of the - * operation. See g_dbus_connection_close_sync() for the synchronous + * operation. See g_dbus_connection_close_sync() for the synchronous * version. * * Since: 2.26 @@ -12816,42 +14553,45 @@ /** * g_dbus_connection_close_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_close() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_close(). * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_close_sync: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously closees @connection. The calling thread is blocked * until this is done. See g_dbus_connection_close() for the * asynchronous version of this method and more details about what it * does. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_emit_signal: - * @connection: A #GDBusConnection. - * @destination_bus_name: (allow-none): The unique bus name for the destination for the signal or %NULL to emit to all listeners. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to emit a signal on. - * @signal_name: The name of the signal to emit. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @destination_bus_name: (allow-none): the unique bus name for the destination + * for the signal or %NULL to emit to all listeners + * @object_path: path of remote object + * @interface_name: D-Bus interface to emit a signal on + * @signal_name: the name of the signal to emit + * @parameters: (allow-none): a #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters + * @error: Return location for error or %NULL * * Emits a signal. * @@ -12859,7 +14599,7 @@ * * This can only fail if @parameters is not compatible with the D-Bus protocol. * - * Returns: %TRUE unless @error is set. + * Returns: %TRUE unless @error is set * Since: 2.26 */ @@ -12910,7 +14650,7 @@ * The implemented D-Bus API should be considered private. * It is subject to change in the future. * - * An object path can only have one action group exported on it. If this + * An object path can only have one menu model exported on it. If this * constraint is violated, the export will fail and 0 will be * returned (with @error set accordingly). * @@ -12925,25 +14665,25 @@ /** * g_dbus_connection_flush: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the + * request is satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback * * Asynchronously flushes @connection, that is, writes all queued * outgoing message to the transport and then flushes the transport * (using g_output_stream_flush_async()). This is useful in programs - * that wants to emit a D-Bus signal and then exit - * immediately. Without flushing the connection, there is no guarantee - * that the message has been sent to the networking buffers in the OS - * kernel. + * that wants to emit a D-Bus signal and then exit immediately. Without + * flushing the connection, there is no guaranteed that the message has + * been sent to the networking buffers in the OS kernel. * * This is an asynchronous method. 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. You can + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. You can * then call g_dbus_connection_flush_finish() to get the result of the - * operation. See g_dbus_connection_flush_sync() for the synchronous + * operation. See g_dbus_connection_flush_sync() for the synchronous * version. * * Since: 2.26 @@ -12952,72 +14692,75 @@ /** * g_dbus_connection_flush_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_flush() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_flush(). * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_flush_sync: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously flushes @connection. The calling thread is blocked * until this is done. See g_dbus_connection_flush() for the * asynchronous version of this method and more details about what it * does. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_get_capabilities: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets the capabilities negotiated with the remote peer * - * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration. + * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration * Since: 2.26 */ /** * g_dbus_connection_get_exit_on_close: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets whether the process is terminated when @connection is * closed by the remote peer. See * #GDBusConnection:exit-on-close for more details. * - * Returns: Whether the process is terminated when @connection is closed by the remote peer. + * Returns: whether the process is terminated when @connection is + * closed by the remote peer * Since: 2.26 */ /** * g_dbus_connection_get_guid: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * The GUID of the peer performing the role of server when * authenticating. See #GDBusConnection:guid for more details. * - * Returns: The GUID. Do not free this string, it is owned by @connection. + * Returns: The GUID. Do not free this string, it is owned by + * @connection. * Since: 2.26 */ /** * g_dbus_connection_get_last_serial: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Retrieves the last serial number assigned to a #GDBusMessage on * the current thread. This includes messages sent via both low-level @@ -13025,14 +14768,15 @@ * high-level API such as g_dbus_connection_emit_signal(), * g_dbus_connection_call() or g_dbus_proxy_call(). * - * Returns: the last used serial or zero when no message has been sent within the current thread. + * Returns: the last used serial or zero when no message has been sent + * within the current thread * Since: 2.34 */ /** * g_dbus_connection_get_peer_credentials: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets the credentials of the authenticated peer. This will always * return %NULL unless @connection acted as a server @@ -13044,7 +14788,8 @@ * each application is a client. So this method will always return * %NULL for message bus clients. * - * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection. + * Returns: (transfer none): a #GCredentials or %NULL if not available. + * Do not free this object, it is owned by @connection. * Since: 2.26 */ @@ -13066,37 +14811,39 @@ /** * g_dbus_connection_get_unique_name: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets the unique name of @connection as assigned by the message * bus. This can also be used to figure out if @connection is a * message bus connection. * - * Returns: The unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection. + * Returns: the unique name or %NULL if @connection is not a message + * bus connection. Do not free this string, it is owned by + * @connection. * Since: 2.26 */ /** * g_dbus_connection_is_closed: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets whether @connection is closed. * - * Returns: %TRUE if the connection is closed, %FALSE otherwise. + * Returns: %TRUE if the connection is closed, %FALSE otherwise * Since: 2.26 */ /** * g_dbus_connection_new: - * @stream: A #GIOStream. - * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * @stream: a #GIOStream + * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages * with the end represented by @stream. @@ -13125,24 +14872,26 @@ /** * g_dbus_connection_new_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback + * passed to g_dbus_connection_new(). + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_new(). * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_new_for_address: - * @address: A D-Bus address. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * @address: a D-Bus address + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * * Asynchronously connects and sets up a D-Bus client connection for * exchanging D-Bus messages with an endpoint specified by @address @@ -13171,23 +14920,25 @@ /** * g_dbus_connection_new_for_address_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_new() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_new_for_address(). * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_new_for_address_sync: - * @address: A D-Bus address. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @address: a D-Bus address + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously connects and sets up a D-Bus client connection for * exchanging D-Bus messages with an endpoint specified by @address @@ -13205,19 +14956,20 @@ * If @observer is not %NULL it may be used to control the * authentication process. * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_new_sync: - * @stream: A #GIOStream. - * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @stream: a #GIOStream + * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously sets up a D-Bus connection for exchanging D-Bus messages * with the end represented by @stream. @@ -13235,37 +14987,38 @@ * This is a synchronous failable constructor. See * g_dbus_connection_new() for the asynchronous version. * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_register_object: - * @connection: A #GDBusConnection. - * @object_path: The object path to register at. - * @interface_info: Introspection data for the interface. - * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL. - * @user_data: (allow-none): Data to pass to functions in @vtable. - * @user_data_free_func: Function to call when the object path is unregistered. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @object_path: the object path to register at + * @interface_info: introspection data for the interface + * @vtable: (allow-none): a #GDBusInterfaceVTable to call into or %NULL + * @user_data: (allow-none): data to pass to functions in @vtable + * @user_data_free_func: function to call when the object path is unregistered + * @error: return location for error or %NULL * * Registers callbacks for exported objects at @object_path with the * D-Bus interface that is described in @interface_info. * - * Calls to functions in @vtable (and @user_data_free_func) will - * happen in the <link linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this method from. + * Calls to functions in @vtable (and @user_data_free_func) will happen + * in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * Note that all #GVariant values passed to functions in @vtable will match * the signature given in @interface_info - if a remote caller passes - * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> + * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` * is returned to the remote caller. * * Additionally, if the remote caller attempts to invoke methods or * access properties not mentioned in @interface_info the - * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp. - * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors + * `org.freedesktop.DBus.Error.UnknownMethod` resp. + * `org.freedesktop.DBus.Error.InvalidArgs` errors * are returned to the caller. * * It is considered a programming error if the @@ -13277,34 +15030,35 @@ * * GDBus automatically implements the standard D-Bus interfaces * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable - * and org.freedesktop.Peer, so you don't have to implement those for - * the objects you export. You <emphasis>can</emphasis> implement - * org.freedesktop.DBus.Properties yourself, e.g. to handle getting - * and setting of properties asynchronously. + * and org.freedesktop.Peer, so you don't have to implement those for the + * objects you export. You can implement org.freedesktop.DBus.Properties + * yourself, e.g. to handle getting and setting of properties asynchronously. * * Note that the reference count on @interface_info will be * incremented by 1 (unless allocated statically, e.g. if the * reference count is -1, see g_dbus_interface_info_ref()) for as long * as the object is exported. Also note that @vtable will be copied. * - * See <xref linkend="gdbus-server"/> for an example of how to use this method. + * See this [server][gdbus-server] for an example of how to use this method. * - * Returns: 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() . + * Returns: 0 if @error is set, otherwise a registration id (never 0) + * that can be used with g_dbus_connection_unregister_object() * Since: 2.26 */ /** * g_dbus_connection_register_subtree: - * @connection: A #GDBusConnection. - * @object_path: The object path to register the subtree at. - * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree. - * @flags: Flags used to fine tune the behavior of the subtree. - * @user_data: Data to pass to functions in @vtable. - * @user_data_free_func: Function to call when the subtree is unregistered. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @object_path: the object path to register the subtree at + * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and + * dispatch nodes in the subtree + * @flags: flags used to fine tune the behavior of the subtree + * @user_data: data to pass to functions in @vtable + * @user_data_free_func: function to call when the subtree is unregistered + * @error: return location for error or %NULL * - * Registers a whole subtree of <quote>dynamic</quote> objects. + * Registers a whole subtree of dynamic objects. * * The @enumerate and @introspection functions in @vtable are used to * convey, to remote callers, what nodes exist in the subtree rooted @@ -13319,9 +15073,9 @@ * #gpointer will be used to call into the interface vtable for processing * the request. * - * All calls into user-provided code 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. + * All calls into user-provided code will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * If an existing subtree is already registered at @object_path or * then @error is set to #G_IO_ERROR_EXISTS. @@ -13330,16 +15084,17 @@ * g_dbus_connection_register_object()) in a subtree registered with * g_dbus_connection_register_subtree() - if so, the subtree handler * is tried as the last resort. One way to think about a subtree - * handler is to consider it a <quote>fallback handler</quote> - * for object paths not registered via g_dbus_connection_register_object() - * or other bindings. + * handler is to consider it a fallback handler for object paths not + * registered via g_dbus_connection_register_object() or other bindings. * * Note that @vtable will be copied so you cannot change it after * registration. * - * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method. + * See this [server][gdbus-subtree-server] for an example of how to use + * this method. * - * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) that can be used with g_dbus_connection_unregister_subtree() . + * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) + * that can be used with g_dbus_connection_unregister_subtree() . * Since: 2.26 */ @@ -13357,11 +15112,12 @@ /** * g_dbus_connection_send_message: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage - * @flags: Flags affecting how the message is sent. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent + * @out_serial: (out) (allow-none): return location for serial number assigned + * to @message when sending it or %NULL + * @error: Return location for error or %NULL * * Asynchronously sends @message to the peer represented by @connection. * @@ -13376,28 +15132,32 @@ * %G_IO_ERROR_CLOSED. If @message is not well-formed, * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. * - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * Returns: %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set. + * Returns: %TRUE if the message was well-formed and queued for + * transmission, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_send_message_with_reply: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage. - * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @out_serial: (out) (allow-none): return location for serial number assigned + * to @message when sending it or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request + * is satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback * * Asynchronously sends @message to the peer represented by @connection. * @@ -13413,8 +15173,9 @@ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. * - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * This is an asynchronous method. When the operation is finished, @callback + * will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can then call * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. @@ -13422,9 +15183,9 @@ * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Since: 2.26 */ @@ -13433,8 +15194,9 @@ /** * g_dbus_connection_send_message_with_reply_finish: * @connection: a #GDBusConnection - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + * g_dbus_connection_send_message_with_reply() + * @error: teturn location for error or %NULL * * Finishes an operation started with g_dbus_connection_send_message_with_reply(). * @@ -13443,24 +15205,26 @@ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use * g_dbus_message_to_gerror() to transcode this to a #GError. * - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * - * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set. + * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set * Since: 2.26 */ /** * g_dbus_connection_send_message_with_reply_sync: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage. - * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent. + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @out_serial: (out) (allow-none): return location for serial number + * assigned to @message when sending it or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously sends @message to the peer represented by @connection * and blocks the calling thread until a reply is received or the @@ -13484,22 +15248,24 @@ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use * g_dbus_message_to_gerror() to transcode this to a #GError. * - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set. + * Returns: (transfer full): a locked #GDBusMessage that is the reply + * to @message or %NULL if @error is set * Since: 2.26 */ /** * g_dbus_connection_set_exit_on_close: - * @connection: A #GDBusConnection. - * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer. + * @connection: a #GDBusConnection + * @exit_on_close: whether the process should be terminated + * when @connection is closed by the remote peer * * Sets whether the process should be terminated when @connection is * closed by the remote peer. See #GDBusConnection:exit-on-close for @@ -13518,22 +15284,27 @@ /** * g_dbus_connection_signal_subscribe: - * @connection: A #GDBusConnection. - * @sender: (allow-none): Sender name to match on (unique or well-known name) or %NULL to listen from all senders. - * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to match on all interfaces. - * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals. - * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths. - * @arg0: (allow-none): Contents of first string argument to match on or %NULL to match on all kinds of arguments. - * @flags: Flags describing how to subscribe to the signal (currently unused). - * @callback: Callback to invoke when there is a signal matching the requested data. - * @user_data: User data to pass to @callback. - * @user_data_free_func: (allow-none): Function to free @user_data with when subscription is removed or %NULL. + * @connection: a #GDBusConnection + * @sender: (allow-none): sender name to match on (unique or well-known name) + * or %NULL to listen from all senders + * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to + * match on all interfaces + * @member: (allow-none): D-Bus signal name to match on or %NULL to match on + * all signals + * @object_path: (allow-none): object path to match on or %NULL to match on + * all object paths + * @arg0: (allow-none): contents of first string argument to match on or %NULL + * to match on all kinds of arguments + * @flags: flags describing how to subscribe to the signal (currently unused) + * @callback: callback to invoke when there is a signal matching the requested data + * @user_data: user data to pass to @callback + * @user_data_free_func: (allow-none): function to free @user_data with when + * subscription is removed or %NULL * - * Subscribes to signals on @connection and invokes @callback with a - * whenever the signal is received. Note that @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. + * Subscribes to signals on @connection and invokes @callback with a whenever + * the signal is received. Note that @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * If @connection is not a message bus connection, @sender must be * %NULL. @@ -13545,15 +15316,21 @@ * tracking the name owner of the well-known name and use that when * processing the received signal. * - * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe(). + * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or + * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is + * interpreted as part of a namespace or path. The first argument + * of a signal is matched against that part as specified by D-Bus. + * + * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() * Since: 2.26 */ /** * g_dbus_connection_signal_unsubscribe: - * @connection: A #GDBusConnection. - * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe(). + * @connection: a #GDBusConnection + * @subscription_id: a subscription id obtained from + * g_dbus_connection_signal_subscribe() * * Unsubscribes from signals. * @@ -13563,7 +15340,7 @@ /** * g_dbus_connection_start_message_processing: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * If @connection was created with * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method @@ -13608,24 +15385,26 @@ /** * g_dbus_connection_unregister_object: - * @connection: A #GDBusConnection. - * @registration_id: A registration id obtained from g_dbus_connection_register_object(). + * @connection: a #GDBusConnection + * @registration_id: a registration id obtained from + * g_dbus_connection_register_object() * * Unregisters an object. * - * Returns: %TRUE if the object was unregistered, %FALSE otherwise. + * Returns: %TRUE if the object was unregistered, %FALSE otherwise * Since: 2.26 */ /** * g_dbus_connection_unregister_subtree: - * @connection: A #GDBusConnection. - * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree(). + * @connection: a #GDBusConnection + * @registration_id: a subtree registration id obtained from + * g_dbus_connection_register_subtree() * * Unregisters a subtree. * - * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise. + * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise * Since: 2.26 */ @@ -13639,7 +15418,7 @@ * D-Bus error name will be returned. * * Otherwise the a name of the form - * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal> + * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE` * will be used. This allows other GDBus applications to map the error * on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). * @@ -13653,16 +15432,17 @@ /** * g_dbus_error_get_remote_error: - * @error: A #GError. + * @error: a #GError * * Gets the D-Bus error name used for @error, if any. * * This function is guaranteed to return a D-Bus error name for all - * #GError<!-- -->s returned from functions handling remote method - * calls (e.g. g_dbus_connection_call_finish()) unless + * #GErrors returned from functions handling remote method calls + * (e.g. g_dbus_connection_call_finish()) unless * g_dbus_error_strip_remote_error() has been used on @error. * - * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). + * Returns: an allocated string or %NULL if the D-Bus error name + * could not be found. Free with g_free(). * Since: 2.26 */ @@ -13674,7 +15454,8 @@ * Checks if @error represents an error received via D-Bus from a remote peer. If so, * use g_dbus_error_get_remote_error() to get the name of the error. * - * Returns: %TRUE if @error represents an error from a remote peer, %FALSE otherwise. + * Returns: %TRUE if @error represents an error from a remote peer, + * %FALSE otherwise. * Since: 2.26 */ @@ -13723,12 +15504,13 @@ * @dbus_error_name: A D-Bus error name. * * Creates an association to map between @dbus_error_name and - * #GError<!-- -->s specified by @error_domain and @error_code. + * #GErrors specified by @error_domain and @error_code. * * This is typically done in the routine that returns the #GQuark for * an error domain. * - * Returns: %TRUE if the association was created, %FALSE if it already exists. + * Returns: %TRUE if the association was created, %FALSE if it already + * exists. * Since: 2.26 */ @@ -13821,80 +15603,41 @@ /** * g_dbus_gvalue_to_gvariant: - * @gvalue: A #GValue to convert to a #GVariant. - * @type: A #GVariantType. + * @gvalue: A #GValue to convert to a #GVariant + * @type: A #GVariantType * - * Converts a #GValue to a #GVariant of the type indicated by the @type parameter. + * Converts a #GValue to a #GVariant of the type indicated by the @type + * parameter. * * The conversion is using the following rules: - * <table frame='all'> - * <title>#GValue / #GVariant conversion rules</title> - * <tgroup cols='2' align='left' colsep='1' rowsep='1'> - * <thead> - * <row> - * <entry>If the #GType for @gvalue is...</entry> - * <entry>... then @type must be</entry> - * </row> - * </thead> - * <tbody> - * <row> - * <entry>#G_TYPE_STRING</entry> - * <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> - * </row> - * <row> - * <entry>#G_TYPE_STRV</entry> - * <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> - * </row> - * <row> - * <entry>#G_TYPE_BOOLEAN</entry> - * <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_UCHAR</entry> - * <entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_INT</entry> - * <entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_UINT</entry> - * <entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_INT64</entry> - * <entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_UINT64</entry> - * <entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_DOUBLE</entry> - * <entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry> - * </row> - * <row> - * <entry>#G_TYPE_VARIANT</entry> - * <entry>Any #GVariantType</entry> - * </row> - * </tbody> - * </tgroup> - * </table> + * + * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay' + * - #G_TYPE_STRV: 'as', 'ao' or 'aay' + * - #G_TYPE_BOOLEAN: 'b' + * - #G_TYPE_UCHAR: 'y' + * - #G_TYPE_INT: 'i', 'n' + * - #G_TYPE_UINT: 'u', 'q' + * - #G_TYPE_INT64 'x' + * - #G_TYPE_UINT64: 't' + * - #G_TYPE_DOUBLE: 'd' + * - #G_TYPE_VARIANT: Any #GVariantType + * * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type - * is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will - * also fail for any #GType (including e.g. #G_TYPE_OBJECT and - * #G_TYPE_BOXED derived-types) not in the table above. + * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType + * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not + * in the table above. * * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is - * %NULL, the <emphasis>empty</emphasis> #GVariant instance (never - * %NULL) for @type is returned (e.g. 0 for scalar types, the empty - * string for string types, <literal>'/'</literal> for object path - * types, the empty array for any array type and so on). + * %NULL, the empty #GVariant instance (never %NULL) for @type is + * returned (e.g. 0 for scalar types, the empty string for string types, + * '/' for object path types, the empty array for any array type and so on). * * See the g_dbus_gvariant_to_gvalue() function for how to convert a * #GVariant to a #GValue. * - * Returns: A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or %NULL in case of failure. Free with g_variant_unref(). + * Returns: A #GVariant (never floating) of #GVariantType @type holding + * the data from @gvalue or %NULL in case of failure. Free with + * g_variant_unref(). * Since: 2.30 */ @@ -13917,14 +15660,14 @@ /** - * g_dbus_interface_dup_object: + * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object) * @interface_: An exported D-Bus interface. * * Gets the #GDBusObject that @interface_ belongs to, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). + * Returns: (transfer full): A #GDBusObject or %NULL. The returned + * reference should be freed with g_object_unref(). * Since: 2.32 - * Rename to: g_dbus_interface_get_object */ @@ -13942,16 +15685,16 @@ /** * g_dbus_interface_get_object: (skip) - * @interface_: An exported D-Bus interface. + * @interface_: An exported D-Bus interface * * Gets the #GDBusObject that @interface_ belongs to, if any. * - * <warning>It is not safe to use the returned object if @interface_ - * or the returned object is being used from other threads. See - * g_dbus_interface_dup_object() for a thread-safe - * alternative.</warning> + * It is not safe to use the returned object if @interface_ or + * the returned object is being used from other threads. See + * g_dbus_interface_dup_object() for a thread-safe alternative. * - * Returns: (transfer none): A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. + * Returns: (transfer none): A #GDBusObject or %NULL. The returned + * reference belongs to @interface_ and should not be freed. * Since: 2.30 */ @@ -13997,7 +15740,7 @@ * * This function is typically used for generating introspection XML * documents at run-time for handling the - * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> + * `org.freedesktop.DBus.Introspectable.Introspect` * method. * * Since: 2.26 @@ -14011,7 +15754,7 @@ * * Looks up information about a method. * - * This cost of this function is O(n) in number of methods unless + * The cost of this function is O(n) in number of methods unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14026,7 +15769,7 @@ * * Looks up information about a property. * - * This cost of this function is O(n) in number of properties unless + * The cost of this function is O(n) in number of properties unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14041,7 +15784,7 @@ * * Looks up information about a signal. * - * This cost of this function is O(n) in number of signals unless + * The cost of this function is O(n) in number of signals unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14101,7 +15844,8 @@ * * Use g_dbus_interface_skeleton_unexport() to unexport the object. * - * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set. + * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with + * @error set. * Since: 2.30 */ @@ -14115,7 +15859,7 @@ * * For example, an exported D-Bus interface may queue up property * changes and emit the - * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal> + * `org.freedesktop.DBus.Properties::Propert`` * signal later (e.g. in an idle handler). This technique is useful * for collapsing multiple property changes into one. * @@ -14129,7 +15873,8 @@ * * Gets the first connection that @interface_ is exported on, if any. * - * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. + * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is + * not exported anywhere. Do not free, the object belongs to @interface_. * Since: 2.30 */ @@ -14140,7 +15885,10 @@ * * Gets a list of the connections that @interface_ is exported on. * - * Returns: (element-type GDBusConnection) (transfer full): A list of all the connections that @interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). + * Returns: (element-type GDBusConnection) (transfer full): A list of + * all the connections that @interface_ is exported on. The returned + * list should be freed with g_list_free() after each element has + * been freed with g_object_unref(). * Since: 2.32 */ @@ -14175,7 +15923,8 @@ * * Gets the object path that @interface_ is exported on, if any. * - * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. + * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported + * anywhere. Do not free, the string belongs to @interface_. * Since: 2.30 */ @@ -14186,7 +15935,9 @@ * * Gets all D-Bus properties for @interface_. * - * Returns: (transfer full): A #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref(). + * Returns: (transfer full): A #GVariant of type + * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + * Free with g_variant_unref(). * Since: 2.30 */ @@ -14209,7 +15960,7 @@ * @interface_: A #GDBusInterfaceSkeleton. * @connection: A #GDBusConnection. * - * Checks if @interface_ is export on @connection. + * Checks if @interface_ is exported on @connection. * * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise. * Since: 2.32 @@ -14325,7 +16076,8 @@ * transports in @string and that key/value pairs for each transport * are valid. * - * Returns: %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set. + * Returns: %TRUE if @string is a valid D-Bus address that is + * supported by this library, %FALSE if @error is set. * Since: 2.26 */ @@ -14356,7 +16108,8 @@ * (and linked models) must also originate from this same context, with * the thread default main context unchanged. * - * Returns: (transfer full): a #GDBusMenuModel object. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusMenuModel object. Free with + * g_object_unref(). * Since: 2.32 */ @@ -14370,7 +16123,9 @@ * Utility function to calculate how many bytes are needed to * completely deserialize the D-Bus message stored at @blob. * - * Returns: Number of bytes needed or -1 if @error is set (e.g. if @blob contains invalid data or not enough data is available to determine the size). + * Returns: Number of bytes needed or -1 if @error is set (e.g. if + * @blob contains invalid data or not enough data is available to + * determine the size). * Since: 2.26 */ @@ -14387,7 +16142,8 @@ * This operation can fail if e.g. @message contains file descriptors * and the per-process or system-wide open files limit is reached. * - * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ @@ -14398,7 +16154,8 @@ * * Convenience to get the first item in the body of @message. * - * Returns: The string item or %NULL if the first item in the body of @message is not a string. + * Returns: The string item or %NULL if the first item in the body of + * @message is not a string. * Since: 2.26 */ @@ -14464,7 +16221,8 @@ * * Gets a header field on @message. * - * Returns: A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message. + * Returns: A #GVariant with the value if the header was found, %NULL + * otherwise. Do not free, it is owned by @message. * Since: 2.26 */ @@ -14475,7 +16233,9 @@ * * Gets an array of all header fields on @message that are set. * - * Returns: (array zero-terminated=1): An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free(). + * Returns: (array zero-terminated=1): An array of header fields + * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element + * is a #guchar. Free with g_free(). * Since: 2.26 */ @@ -14600,7 +16360,8 @@ * * This method is only available on UNIX. * - * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. + * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are + * associated. Do not free, this object is owned by @message. * Since: 2.26 */ @@ -14636,7 +16397,8 @@ * order that the message was in can be retrieved using * g_dbus_message_get_byte_order(). * - * Returns: A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). + * Returns: A new #GDBusMessage or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ @@ -14657,7 +16419,8 @@ /** * g_dbus_message_new_method_error: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message_format: The D-Bus error message in a printf() format. * @...: Arguments for @error_message_format. @@ -14671,7 +16434,8 @@ /** * g_dbus_message_new_method_error_literal: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message: The D-Bus error message. * @@ -14684,7 +16448,8 @@ /** * g_dbus_message_new_method_error_valist: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message_format: The D-Bus error message in a printf() format. * @var_args: Arguments for @error_message_format. @@ -14698,7 +16463,8 @@ /** * g_dbus_message_new_method_reply: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * * Creates a new #GDBusMessage that is a reply to @method_call_message. * @@ -14721,7 +16487,7 @@ /** - * g_dbus_message_print: + * g_dbus_message_print: (type method-return) * @message: A #GDBusMessage. * @indent: Indentation level. * @@ -14730,35 +16496,33 @@ * The contents of the description has no ABI guarantees, the contents * and formatting is subject to change at any time. Typical output * looks something like this: - * <programlisting> - * Type: method-call - * Flags: none - * Version: 0 - * Serial: 4 - * Headers: + * |[ + * Flags: none + * Version: 0 + * Serial: 4 + * Headers: * path -> objectpath '/org/gtk/GDBus/TestObject' * interface -> 'org.gtk.GDBus.TestInterface' * member -> 'GimmeStdout' * destination -> ':1.146' - * Body: () + * Body: () * UNIX File Descriptors: * (none) - * </programlisting> + * ]| * or - * <programlisting> - * Type: method-return - * Flags: no-reply-expected - * Version: 0 - * Serial: 477 - * Headers: + * |[ + * Flags: no-reply-expected + * Version: 0 + * Serial: 477 + * Headers: * reply-serial -> uint32 4 * destination -> ':1.159' * sender -> ':1.146' * num-unix-fds -> uint32 1 - * Body: () - * UNIX File Descriptors: + * Body: () + * UNIX File Descriptors: * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 - * </programlisting> + * ]| * * Returns: A string that should be freed with g_free(). * Since: 2.26 @@ -14814,7 +16578,8 @@ /** * g_dbus_message_set_flags: * @message: A #GDBusMessage. - * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). + * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags + * enumeration bitwise ORed together). * * Sets the flags to set on @message. * @@ -14961,7 +16726,9 @@ * Serializes @message to a blob. The byte order returned by * g_dbus_message_get_byte_order() will be used. * - * Returns: (array length=out_size) (transfer full): A pointer to a valid binary D-Bus message of @out_size bytes generated by @message or %NULL if @error is set. Free with g_free(). + * Returns: (array length=out_size) (transfer full): A pointer to a + * valid binary D-Bus message of @out_size bytes generated by @message + * or %NULL if @error is set. Free with g_free(). * Since: 2.26 */ @@ -15025,6 +16792,11 @@ * * Gets the name of the D-Bus interface the method was invoked on. * + * If this method call is a property Get, Set or GetAll call that has + * been redirected to the method call handler then + * "org.freedesktop.DBus.Properties" will be returned. See + * #GDBusInterfaceVTable for more information. + * * Returns: A string. Do not free, it is owned by @invocation. * Since: 2.26 */ @@ -15039,9 +16811,9 @@ * descriptor passing, that cannot be properly expressed in the * #GVariant API. * - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. * Since: 2.26 @@ -15054,6 +16826,11 @@ * * Gets information about the method call, if any. * + * If this method invocation is a property Get, Set or GetAll call that + * has been redirected to the method call handler then %NULL will be + * returned. See g_dbus_method_invocation_get_property_info() and + * #GDBusInterfaceVTable for more information. + * * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. * Since: 2.26 */ @@ -15094,6 +16871,27 @@ /** + * g_dbus_method_invocation_get_property_info: + * @invocation: A #GDBusMethodInvocation + * + * Gets information about the property that this method call is for, if + * any. + * + * This will only be set in the case of an invocation in response to a + * property Get or Set call that has been directed to the method call + * handler for an object on account of its property_get() or + * property_set() vtable pointers being unset. + * + * See #GDBusInterfaceVTable for more information. + * + * If the call was GetAll, %NULL will be returned. + * + * Returns: (transfer none): a #GDBusPropertyInfo or %NULL + * Since: 2.38 + */ + + +/** * g_dbus_method_invocation_get_sender: * @invocation: A #GDBusMethodInvocation. * @@ -15143,12 +16941,11 @@ * will be returned on the wire. In a nutshell, if the given error is * registered using g_dbus_error_register_error() the name given * during registration is used. Otherwise, a name of the form - * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is - * used. This provides transparent mapping of #GError between - * applications using GDBus. + * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides + * transparent mapping of #GError between applications using GDBus. * * If you are writing an application intended to be portable, - * <emphasis>always</emphasis> register errors with g_dbus_error_register_error() + * always register errors with g_dbus_error_register_error() * or use g_dbus_method_invocation_return_dbus_error(). * * This method will free @invocation, you cannot use it afterwards. @@ -15258,7 +17055,7 @@ * Appends an XML representation of @info (and its children) to @string_builder. * * This function is typically used for generating introspection XML documents at run-time for - * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method. + * handling the `org.freedesktop.DBus.Introspectable.Introspect` method. * * Since: 2.26 */ @@ -15271,7 +17068,7 @@ * * Looks up information about an interface. * - * This cost of this function is O(n) in number of interfaces. + * The cost of this function is O(n) in number of interfaces. * * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. * Since: 2.26 @@ -15286,13 +17083,14 @@ * Parses @xml_data and returns a #GDBusNodeInfo representing the data. * * The introspection XML must contain exactly one top-level - * <tag class="starttag">node</tag> element. + * <node> element. * * Note that this routine is using a - * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based + * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based * parser that only accepts a subset of valid XML documents. * - * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref(). + * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free + * with g_dbus_node_info_unref(). * Since: 2.26 */ @@ -15329,7 +17127,8 @@ * Gets the D-Bus interface with name @interface_name associated with * @object, if any. * - * Returns: (transfer full): %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). + * Returns: (transfer full): %NULL if not found, otherwise a + * #GDBusInterface that must be freed with g_object_unref(). * Since: 2.30 */ @@ -15340,7 +17139,9 @@ * * Gets the D-Bus interfaces associated with @object. * - * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). + * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. + * The returned list must be freed by g_list_free() after each element has been freed + * with g_object_unref(). * Since: 2.30 */ @@ -15362,7 +17163,8 @@ * * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer none): A #GDBusConnection object. Do not free, the object belongs to @manager. + * Returns: (transfer none): A #GDBusConnection object. Do not free, + * the object belongs to @manager. * Since: 2.30 */ @@ -15373,7 +17175,8 @@ * * Gets the flags that @manager was constructed with. * - * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags enumeration. + * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags + * enumeration. * Since: 2.30 */ @@ -15382,9 +17185,11 @@ * g_dbus_object_manager_client_get_name: * @manager: A #GDBusObjectManagerClient * - * Gets the name that @manager is for. + * Gets the name that @manager is for, or %NULL if not a message bus + * connection. * - * Returns: A unique or well-known name. Do not free, the string belongs to @manager. + * Returns: A unique or well-known name. Do not free, the string + * belongs to @manager. * Since: 2.30 */ @@ -15398,7 +17203,8 @@ * #GObject::notify signal to track changes to the * #GDBusObjectManagerClient:name-owner property. * - * Returns: The name owner or %NULL if no name owner exists. Free with g_free(). + * Returns: The name owner or %NULL if no name owner exists. Free with + * g_free(). * Since: 2.30 */ @@ -15420,7 +17226,7 @@ * * This is an asynchronous failable constructor. When the result is * ready, @callback will be invoked in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can * then call g_dbus_object_manager_client_new_finish() to get the result. See * g_dbus_object_manager_client_new_sync() for the synchronous version. @@ -15436,7 +17242,9 @@ * * Finishes an operation started with g_dbus_object_manager_client_new(). * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15459,7 +17267,7 @@ * * This is an asynchronous failable constructor. When the result is * ready, @callback will be invoked in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main loop][g-main-context-push-thread-default] * of the thread you are calling this method from. You can * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. @@ -15475,7 +17283,9 @@ * * Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15499,7 +17309,9 @@ * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() * for the asynchronous version. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15508,7 +17320,7 @@ * g_dbus_object_manager_client_new_sync: * @connection: A #GDBusConnection. * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: The owner of the control object (unique or well-known name). + * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. * @object_path: The object path of the control object. * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. @@ -15522,7 +17334,9 @@ * blocked until a reply is received. See g_dbus_object_manager_client_new() * for the asynchronous version. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15536,7 +17350,8 @@ * Gets the interface proxy for @interface_name at @object_path, if * any. * - * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free with g_object_unref(). + * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15548,7 +17363,8 @@ * * Gets the #GDBusObjectProxy at @object_path, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. Free with g_object_unref(). + * Returns: (transfer full): A #GDBusObject or %NULL. Free with + * g_object_unref(). * Since: 2.30 */ @@ -15570,7 +17386,10 @@ * * Gets all #GDBusObject objects known to @manager. * - * Returns: (transfer full) (element-type GDBusObject): A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). + * Returns: (transfer full) (element-type GDBusObject): A list of + * #GDBusObject objects. The returned list should be freed with + * g_list_free() after each element has been freed with + * g_object_unref(). * Since: 2.30 */ @@ -15601,10 +17420,9 @@ * @object: An object. * * Like g_dbus_object_manager_server_export() but appends a string of - * the form <literal>_N</literal> (with N being a natural number) to - * @object<!-- -->'s object path if an object with the given path - * already exists. As such, the #GDBusObjectProxy:g-object-path property - * of @object may be modified. + * the form _N (with N being a natural number) to @object's object path + * if an object with the given path already exists. As such, the + * #GDBusObjectProxy:g-object-path property of @object may be modified. * * Since: 2.30 */ @@ -15616,7 +17434,9 @@ * * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer full): A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref(). + * Returns: (transfer full): A #GDBusConnection object or %NULL if + * @manager isn't exported on a connection. The returned object should + * be freed with g_object_unref(). * Since: 2.30 */ @@ -15682,7 +17502,8 @@ * * Gets the connection that @proxy is for. * - * Returns: (transfer none): A #GDBusConnection. Do not free, the object is owned by @proxy. + * Returns: (transfer none): A #GDBusConnection. Do not free, the + * object is owned by @proxy. * Since: 2.30 */ @@ -15806,9 +17627,11 @@ * @method_name: Name of method to invoke. * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. * @user_data: The data to pass to @callback. * * Asynchronously invokes the @method_name method on @proxy. @@ -15826,7 +17649,7 @@ * * If the @parameters #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g.: - * |[ + * |[<!-- language="C" --> * g_dbus_proxy_call (proxy, * "TwoStrings", * g_variant_new ("(ss)", @@ -15836,7 +17659,7 @@ * -1, * NULL, * (GAsyncReadyCallback) two_strings_done, - * &data); + * &data); * ]| * * If @proxy has an expected interface (see @@ -15845,7 +17668,7 @@ * * This is an asynchronous method. When the operation is finished, * @callback will be invoked in the - * <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. * You can then call g_dbus_proxy_call_finish() to get the result of * the operation. See g_dbus_proxy_call_sync() for the synchronous @@ -15866,7 +17689,8 @@ * * Finishes an operation started with g_dbus_proxy_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -15875,9 +17699,11 @@ * g_dbus_proxy_call_sync: * @proxy: A #GDBusProxy. * @method_name: Name of method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. * @error: Return location for error or %NULL. * @@ -15896,7 +17722,7 @@ * * If the @parameters #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g.: - * |[ + * |[<!-- language="C" --> * g_dbus_proxy_call_sync (proxy, * "TwoStrings", * g_variant_new ("(ss)", @@ -15905,7 +17731,7 @@ * G_DBUS_CALL_FLAGS_NONE, * -1, * NULL, - * &error); + * &error); * ]| * * The calling thread is blocked until a reply is received. See @@ -15916,7 +17742,8 @@ * #GDBusProxy:g-interface-info) and @method_name is referenced by it, * then the return value is checked against the return type. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -15927,10 +17754,12 @@ * @method_name: Name of method to invoke. * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. * @user_data: The data to pass to @callback. * * Like g_dbus_proxy_call() but also takes a #GUnixFDList object. @@ -15950,7 +17779,8 @@ * * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -15959,9 +17789,11 @@ * g_dbus_proxy_call_with_unix_fd_list_sync: * @proxy: A #GDBusProxy. * @method_name: Name of method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. @@ -15971,7 +17803,8 @@ * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -15988,7 +17821,9 @@ * #GDBusProxy:g-interface-info) and @property_name is referenced by * it, then @value is checked against the type of the property. * - * Returns: A reference to the #GVariant instance that holds the value for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref(). + * Returns: A reference to the #GVariant instance that holds the value + * for @property_name or %NULL if the value is not in the cache. The + * returned reference must be freed with g_variant_unref(). * Since: 2.26 */ @@ -15999,7 +17834,9 @@ * * Gets the names of all cached properties on @proxy. * - * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev(). + * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if + * @proxy has no cached properties. Free the returned array with + * g_strfreev(). * Since: 2.26 */ @@ -16049,7 +17886,8 @@ * that @proxy conforms to. See the #GDBusProxy:g-interface-info * property for more details. * - * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy. + * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned + * object, it is owned by @proxy. * Since: 2.26 */ @@ -16125,9 +17963,9 @@ * to handle signals from the remote object. * * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION + * flags aren't set and no name owner currently exists, the message bus + * will be requested to launch a name owner for the name. * * This is a failable asynchronous constructor - when the proxy is * ready, @callback will be invoked and you can use @@ -16135,7 +17973,7 @@ * * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. * - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -16167,7 +18005,7 @@ * * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -16189,7 +18027,8 @@ * g_dbus_proxy_new_for_bus_sync: * @bus_type: A #GBusType. * @flags: Flags used when constructing the proxy. - * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface + * that @proxy conforms to or %NULL. * @name: A bus name (well-known or unique). * @object_path: An object path. * @interface_name: A D-Bus interface name. @@ -16198,7 +18037,7 @@ * * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 @@ -16226,14 +18065,14 @@ * to handle signals from the remote object. * * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION + * flags aren't set and no name owner currently exists, the message bus + * will be requested to launch a name owner for the name. * * This is a synchronous failable constructor. See g_dbus_proxy_new() * and g_dbus_proxy_new_finish() for the asynchronous version. * - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 @@ -16258,7 +18097,7 @@ * * If the @value #GVariant is floating, it is consumed. This allows * convenient 'inline' use of g_variant_new(), e.g. - * |[ + * |[<!-- language="C" --> * g_dbus_proxy_set_cached_property (proxy, * "SomeProperty", * g_variant_new ("(si)", @@ -16266,20 +18105,19 @@ * 42)); * ]| * - * Normally you will not need to use this method since @proxy is - * tracking changes using the - * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> - * D-Bus signal. However, for performance reasons an object may decide - * to not use this signal for some properties and instead use a - * proprietary out-of-band mechanism to transmit changes. + * Normally you will not need to use this method since @proxy + * is tracking changes using the + * `org.freedesktop.DBus.Properties.PropertiesChanged` + * D-Bus signal. However, for performance reasons an object may + * decide to not use this signal for some properties and instead + * use a proprietary out-of-band mechanism to transmit changes. * * As a concrete example, consider an object with a property - * <literal>ChatroomParticipants</literal> which is an array of - * strings. Instead of transmitting the same (long) array every time - * the property changes, it is more efficient to only transmit the - * delta using e.g. signals <literal>ChatroomParticipantJoined(String - * name)</literal> and <literal>ChatroomParticipantParted(String - * name)</literal>. + * `ChatroomParticipants` which is an array of strings. Instead of + * transmitting the same (long) array every time the property changes, + * it is more efficient to only transmit the delta using e.g. signals + * `ChatroomParticipantJoined(String name)` and + * `ChatroomParticipantParted(String name)`. * * Since: 2.26 */ @@ -16320,7 +18158,8 @@ * Gets a D-Bus address string that can be used by clients to connect * to @server. * - * Returns: A D-Bus address string. Do not free, the string is owned by @server. + * Returns: A D-Bus address string. Do not free, the string is owned + * by @server. * Since: 2.26 */ @@ -16379,13 +18218,13 @@ * The returned #GDBusServer isn't active - you have to start it with * g_dbus_server_start(). * - * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can - * be used. + * #GDBusServer is used in this [example][gdbus-peer-to-peer]. * * This is a synchronous failable constructor. See * g_dbus_server_new() for the asynchronous version. * - * Returns: A #GDBusServer or %NULL if @error is set. Free with g_object_unref(). + * Returns: A #GDBusServer or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ @@ -16435,12 +18274,45 @@ /** + * g_desktop_app_info_get_action_name: + * @info: a #GDesktopAppInfo + * @action_name: the name of the action as from + * g_desktop_app_info_list_actions() + * + * Gets the user-visible display name of the "additional application + * action" specified by @action_name. + * + * This corresponds to the "Name" key within the keyfile group for the + * action. + * + * Returns: (transfer full): the locale-specific action name + * Since: 2.38 + */ + + +/** + * g_desktop_app_info_get_boolean: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Looks up a boolean value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: the boolean value, or %FALSE if the key + * is not found + * Since: 2.36 + */ + + +/** * g_desktop_app_info_get_categories: * @info: a #GDesktopAppInfo * * Gets the categories from the desktop file. * - * Returns: The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it. + * Returns: The unparsed Categories key from the desktop file; + * i.e. no attempt is made to split it by ';' or validate it. */ @@ -16509,7 +18381,7 @@ * * Checks if the application info should be shown in menus that list available * applications for a specific name of the desktop, based on the - * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys. + * `OnlyShowIn` and `NotShowIn` keys. * * If @desktop_env is %NULL, then the name of the desktop set with * g_desktop_app_info_set_desktop_env() is used. @@ -16517,7 +18389,9 @@ * Note that g_app_info_should_show() for @info will include this check (with * %NULL for @desktop_env) as well as additional checks. * - * Returns: %TRUE if the @info should be shown in @desktop_env according to the <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE otherwise. + * Returns: %TRUE if the @info should be shown in @desktop_env according to the + * `OnlyShowIn` and `NotShowIn` keys, %FALSE + * otherwise. * Since: 2.30 */ @@ -16530,21 +18404,78 @@ * WM_CLASS property of the main window of the application, if launched * through @info. * - * Returns: (transfer none): the startup WM class, or %NULL if none is set in the desktop file. + * Returns: (transfer none): the startup WM class, or %NULL if none is set + * in the desktop file. * Since: 2.34 */ /** + * g_desktop_app_info_get_string: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Looks up a string value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: a newly allocated string, or %NULL if the key + * is not found + * Since: 2.36 + */ + + +/** + * g_desktop_app_info_has_key: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Returns whether @key exists in the "Desktop Entry" group + * of the keyfile backing @info. + * + * Returns: %TRUE if the @key exists + * Since: 2.36 + */ + + +/** + * g_desktop_app_info_launch_action: + * @info: a #GDesktopAppInfo + * @action_name: the name of the action as from + * g_desktop_app_info_list_actions() + * @launch_context: (allow-none): a #GAppLaunchContext + * + * Activates the named application action. + * + * You may only call this function on action names that were + * returned from g_desktop_app_info_list_actions(). + * + * Note that if the main entry of the desktop file indicates that the + * application supports startup notification, and @launch_context is + * non-%NULL, then startup notification will be used when activating the + * action (and as such, invocation of the action on the receiving side + * must signal the end of startup notification when it is completed). + * This is the expected behaviour of applications declaring additional + * actions, as per the desktop file specification. + * + * As with g_app_info_launch() there is no way to detect failures that + * occur while using this function. + * + * Since: 2.38 + */ + + +/** * g_desktop_app_info_launch_uris_as_manager: * @appinfo: a #GDesktopAppInfo * @uris: (element-type utf8): List of URIs - * @launch_context: a #GAppLaunchContext + * @launch_context: (allow-none): a #GAppLaunchContext * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process. - * @user_setup_data: (closure user_setup): User data for @user_setup - * @pid_callback: (scope call): Callback for child processes - * @pid_callback_data: (closure pid_callback): User data for @callback + * @user_setup: (scope call) (allow-none): a #GSpawnChildSetupFunc, used once + * for each process. + * @user_setup_data: (closure user_setup) (allow-none): User data for @user_setup + * @pid_callback: (scope call) (allow-none): Callback for child processes + * @pid_callback_data: (closure pid_callback) (allow-none): User data for @callback * @error: return location for a #GError, or %NULL * * This function performs the equivalent of g_app_info_launch_uris(), @@ -16552,21 +18483,36 @@ * launch applications. Ordinary applications should use * g_app_info_launch_uris(). * - * In contrast to g_app_info_launch_uris(), all processes created will - * always be run directly as children as if by the UNIX fork()/exec() - * calls. + * If the application is launched via traditional UNIX fork()/exec() + * then @spawn_flags, @user_setup and @user_setup_data are used for the + * call to g_spawn_async(). Additionally, @pid_callback (with + * @pid_callback_data) will be called to inform about the PID of the + * created process. * - * This guarantee allows additional control over the exact environment - * of the child processes, which is provided via a setup function - * @user_setup, as well as the process identifier of each child process - * via @pid_callback. See g_spawn_async() for more information about the - * semantics of the @user_setup function. + * If application launching occurs via some other mechanism (eg: D-Bus + * activation) then @spawn_flags, @user_setup, @user_setup_data, + * @pid_callback and @pid_callback_data are ignored. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** + * g_desktop_app_info_list_actions: + * @info: a #GDesktopAppInfo + * + * Returns the list of "additional application actions" supported on the + * desktop file, as per the desktop file specification. + * + * As per the specification, this is the list of actions that are + * explicitly listed in the "Actions" key of the [Desktop Entry] group. + * + * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL + * Since: 2.38 + */ + + +/** * g_desktop_app_info_lookup_get_default_for_uri_scheme: * @lookup: a #GDesktopAppInfoLookup * @uri_scheme: a string containing a URI scheme. @@ -16593,13 +18539,13 @@ * * A desktop file id is the basename of the desktop file, including the * .desktop extension. GIO is looking for a desktop file with this name - * in the <filename>applications</filename> subdirectories of the XDG data - * directories (i.e. the directories specified in the - * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment - * variables). GIO also supports the prefix-to-subdirectory mapping that is - * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink> + * in the `applications` subdirectories of the XDG + * data directories (i.e. the directories specified in the `XDG_DATA_HOME` + * and `XDG_DATA_DIRS` environment variables). GIO also supports the + * prefix-to-subdirectory mapping that is described in the + * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) * (i.e. a desktop id of kde-foo.desktop will match - * <filename>/usr/share/applications/kde/foo.desktop</filename>). + * `/usr/share/applications/kde/foo.desktop`). * * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id */ @@ -16627,26 +18573,44 @@ /** + * g_desktop_app_info_search: + * @search_string: the search string to use + * + * Searches desktop files for ones that match @search_string. + * + * The return value is an array of strvs. Each strv contains a list of + * applications that matched @search_string with an equal score. The + * outer list is sorted by score so that the first strv contains the + * best-matching applications, and so on. + * The algorithm for determining matches is undefined and may change at + * any time. + * + * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a + * list of strvs. Free each item with g_strfreev() and free the outer + * list with g_free(). + */ + + +/** * g_desktop_app_info_set_desktop_env: * @desktop_env: a string specifying what desktop this is * * Sets the name of the desktop that the application is running in. * This is used by g_app_info_should_show() and * g_desktop_app_info_get_show_in() to evaluate the - * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> + * `OnlyShowIn` and `NotShowIn` * desktop entry fields. * - * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop - * Menu specification</ulink> recognizes the following: - * <simplelist> - * <member>GNOME</member> - * <member>KDE</member> - * <member>ROX</member> - * <member>XFCE</member> - * <member>LXDE</member> - * <member>Unity</member> - * <member>Old</member> - * </simplelist> + * The + * [Desktop Menu specification](http://standards.freedesktop.org/menu-spec/latest/) + * recognizes the following: + * - GNOME + * - KDE + * - ROX + * - XFCE + * - LXDE + * - Unity + * - Old * * Should be called only once; subsequent calls are ignored. */ @@ -16668,7 +18632,8 @@ * * Checks if a drive can be polled for media changes. * - * Returns: %TRUE if the @drive can be polled for media changes, %FALSE otherwise. + * Returns: %TRUE if the @drive can be polled for media changes, + * %FALSE otherwise. */ @@ -16731,7 +18696,8 @@ * * Finishes ejecting a drive. * - * Returns: %TRUE if the drive has been ejected successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been ejected successfully, + * %FALSE otherwise. * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. */ @@ -16740,7 +18706,8 @@ * g_drive_eject_with_operation: * @drive: a #GDrive. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -16757,7 +18724,8 @@ * g_drive_eject_with_operation_finish: * @drive: a #GDrive. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a drive. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -16775,7 +18743,9 @@ * Use g_drive_get_identifier() to obtain the identifiers * themselves. * - * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. + * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated + * array of strings containing kinds of identifiers. Use g_strfreev() + * to free. */ @@ -16785,7 +18755,8 @@ * * Gets the icon for @drive. * - * Returns: (transfer full): #GIcon for the @drive. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GIcon for the @drive. + * Free the returned object with g_object_unref(). */ @@ -16796,7 +18767,9 @@ * * Gets the identifier of the given kind for @drive. * - * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier. + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GDrive + * doesn't have this kind of identifier. */ @@ -16806,7 +18779,8 @@ * * Gets the name of @drive. * - * Returns: a string containing @drive's name. The returned string should be freed when no longer needed. + * Returns: a string containing @drive's name. The returned + * string should be freed when no longer needed. */ @@ -16838,7 +18812,8 @@ * * Gets the icon for @drive. * - * Returns: (transfer full): symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). + * Returns: (transfer full): symbolic #GIcon for the @drive. + * Free the returned object with g_object_unref(). * Since: 2.34 */ @@ -16884,7 +18859,8 @@ * * Checks if @drive is capabable of automatically detecting media changes. * - * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise. + * Returns: %TRUE if the @drive is capabable of automatically detecting + * media changes, %FALSE otherwise. */ @@ -16921,7 +18897,8 @@ * * Finishes an operation started with g_drive_poll_for_media() on a drive. * - * Returns: %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been poll_for_mediaed successfully, + * %FALSE otherwise. */ @@ -16929,7 +18906,8 @@ * g_drive_start: * @drive: a #GDrive. * @flags: flags affecting the start operation. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data to pass to @callback @@ -16952,7 +18930,8 @@ * * Finishes starting a drive. * - * Returns: %TRUE if the drive has been started successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been started successfully, + * %FALSE otherwise. * Since: 2.22 */ @@ -16961,7 +18940,8 @@ * g_drive_stop: * @drive: a #GDrive. * @flags: flags affecting the unmount if required for stopping. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data to pass to @callback @@ -16984,7 +18964,8 @@ * * Finishes stopping a drive. * - * Returns: %TRUE if the drive has been stopped successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been stopped successfully, + * %FALSE otherwise. * Since: 2.22 */ @@ -16995,7 +18976,8 @@ * * Gives back the icon from @emblem. * - * Returns: (transfer none): a #GIcon. The returned object belongs to the emblem and should not be modified or freed. + * Returns: (transfer none): a #GIcon. The returned object belongs to + * the emblem and should not be modified or freed. * Since: 2.18 */ @@ -17039,7 +19021,7 @@ * @emblemed: a #GEmblemedIcon * @emblem: a #GEmblem * - * Adds @emblem to the #GList of #GEmblem <!-- -->s. + * Adds @emblem to the #GList of #GEmblems. * * Since: 2.18 */ @@ -17061,7 +19043,8 @@ * * Gets the list of emblems for the @icon. * - * Returns: (element-type Gio.Emblem) (transfer none): a #GList of #GEmblem <!-- -->s that is owned by @emblemed + * Returns: (element-type Gio.Emblem) (transfer none): a #GList of + * #GEmblems that is owned by @emblemed * Since: 2.18 */ @@ -17093,7 +19076,8 @@ * g_file_append_to: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Gets an output stream for appending data to the file. @@ -17114,7 +19098,8 @@ * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are * possible too, and depend on what kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17122,9 +19107,11 @@ * g_file_append_to_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for appending. @@ -17147,7 +19134,9 @@ * Finishes an asynchronous file append operation started with * g_file_append_to_async(). * - * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a valid #GFileOutputStream + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17180,7 +19169,8 @@ * * Gets the file attribute with the name @name from @list. * - * Returns: a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found. + * Returns: a #GFileAttributeInfo for the @name, or %NULL if an + * attribute isn't found. */ @@ -17224,7 +19214,8 @@ * * TODO: this is awkwardly worded. * - * Returns: %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise. + * Returns: %TRUE if the matcher matches all of the entries + * in the given @ns, %FALSE otherwise. */ @@ -17234,7 +19225,8 @@ * * Gets the next matched attribute from a #GFileAttributeMatcher. * - * Returns: a string containing the next attribute or %NULL if no more attribute exist. + * Returns: a string containing the next attribute or %NULL if + * no more attribute exist. */ @@ -17268,7 +19260,7 @@ * @attributes: an attribute string to match. * * Creates a new file attribute matcher, which matches attributes - * against a given string. #GFileAttributeMatcher<!-- -->s are reference + * against a given string. #GFileAttributeMatchers are reference * counted structures, and are created with a reference count of 1. If * the number of references falls to 0, the #GFileAttributeMatcher is * automatically destroyed. @@ -17279,20 +19271,15 @@ * The wildcard "*" may be used to match all keys and namespaces, or * "namespace::*" will match all keys in a given namespace. * - * Examples of strings to use: - * <table> - * <title>File Attribute Matcher strings and results</title> - * <tgroup cols='2' align='left'><thead> - * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead> - * <tbody> - * <row><entry>"*"</entry><entry>matches all attributes.</entry></row> - * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row> - * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and - * all keys in the unix namespace.</entry></row> - * </tbody></tgroup> - * </table> + * ## Examples of file attribute matcher strings and results * - * Returns: a #GFileAttributeMatcher. + * - `"*"`: matches all attributes. + * - `"standard::is-hidden"`: matches only the key is-hidden in the + * standard namespace. + * - `"standard::type,unix::*"`: matches the type key in the standard + * namespace and all keys in the unix namespace. + * + * Returns: a #GFileAttributeMatcher */ @@ -17320,7 +19307,8 @@ * is a limitation of the current implementation, but may be fixed * in the future. * - * Returns: A file attribute matcher matching all attributes of @matcher that are not matched by @subtract + * Returns: A file attribute matcher matching all attributes of + * @matcher that are not matched by @subtract */ @@ -17333,7 +19321,8 @@ * The output however, might not be identical, as the matcher may * decide to use a different order or omit needless parts. * - * Returns: a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL. + * Returns: a string describing the attributes the matcher matches + * against or %NULL if @matcher was %NULL. * Since: 2.32 */ @@ -17352,8 +19341,10 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none) (scope call): function to callback with progress information, or %NULL if progress information is not needed + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none) (scope call): function to callback with + * progress information, or %NULL if progress information is not needed * @progress_callback_data: (closure): user data to pass to @progress_callback * @error: #GError to set on error, or %NULL * @@ -17403,9 +19394,11 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none): function to callback with progress information, or %NULL if progress information is not needed + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none): function to callback with progress + * information, or %NULL if progress information is not needed * @progress_callback_data: (closure): user data to pass to @progress_callback * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -17427,7 +19420,8 @@ * @source: a #GFile with attributes * @destination: a #GFile to copy attributes to * @flags: a set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, %NULL to ignore * * Copies the file attributes from @source to @destination. @@ -17439,7 +19433,8 @@ * all the metadata that is possible to copy is copied. This * is useful when implementing move by copy + delete source. * - * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise. + * Returns: %TRUE if the attributes were copied successfully, + * %FALSE otherwise. */ @@ -17459,7 +19454,8 @@ * g_file_create: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a new file and returns an output stream for writing to it. @@ -17482,7 +19478,9 @@ * be returned. Other errors are possible too, and depend on what kind * of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream for the newly created + * file, or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17490,9 +19488,11 @@ * g_file_create_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously creates a new file and returns an output stream @@ -17516,7 +19516,8 @@ * Finishes an asynchronous file create operation started with * g_file_create_async(). * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17524,7 +19525,8 @@ * g_file_create_readwrite: * @file: a #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: return location for a #GError, or %NULL * * Creates a new file and returns a stream for reading and @@ -17551,7 +19553,9 @@ * not supported, so make sure you really need to do read and write * streaming, rather than just opening for reading or writing. * - * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream for the newly created + * file, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -17560,9 +19564,11 @@ * g_file_create_readwrite_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously creates a new file and returns a stream @@ -17588,15 +19594,17 @@ * Finishes an asynchronous file create operation started with * g_file_create_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ /** - * g_file_delete: + * g_file_delete: (virtual delete_file) * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Deletes a file. If the @file is a directory, it will only be @@ -17606,37 +19614,37 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Virtual: delete_file * Returns: %TRUE if the file was deleted. %FALSE otherwise. */ /** - * g_file_delete_async: + * g_file_delete_async: (virtual delete_file_async) * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: the data to pass to callback function * * Asynchronously delete a file. If the @file is a directory, it will * only be deleted if it is empty. This has the same semantics as * g_unlink(). * - * Virtual: delete_file_async * Since: 2.34 */ /** - * g_file_delete_finish: + * g_file_delete_finish: (virtual delete_file_finish) * @file: input #GFile * @result: a #GAsyncResult * @error: a #GError, or %NULL * * Finishes deleting a file started with g_file_delete_async(). * - * Virtual: delete_file_finish + * Returns: %TRUE if the file was deleted. %FALSE otherwise. * Since: 2.34 */ @@ -17662,7 +19670,8 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile. + * Returns: (transfer full): a new #GFile that is a duplicate + * of the given #GFile. */ @@ -17670,8 +19679,10 @@ * g_file_eject_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Starts an asynchronous eject on a mountable. @@ -17696,8 +19707,10 @@ * Finishes an asynchronous eject operation started by * g_file_eject_mountable(). * - * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise. - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead. + * Returns: %TRUE if the @file was ejected successfully. + * %FALSE otherwise. + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() + * instead. */ @@ -17705,9 +19718,12 @@ * g_file_eject_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Starts an asynchronous eject on a mountable. @@ -17732,7 +19748,8 @@ * Finishes an asynchronous eject operation started by * g_file_eject_mountable_with_operation(). * - * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise. + * Returns: %TRUE if the @file was ejected successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -17742,7 +19759,8 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: #GError for error reporting * * Gets the requested information about the files in a directory. @@ -17766,10 +19784,11 @@ * returned. * * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will - * be returned. If the file is not a directory, the %G_FILE_ERROR_NOTDIR + * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY * error will be returned. Other errors are possible too. * - * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): A #GFileEnumerator if successful, + * %NULL on error. Free the returned object with g_object_unref(). */ @@ -17778,9 +19797,11 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about the files @@ -17805,7 +19826,9 @@ * Finishes an async enumerate children operation. * See g_file_enumerate_children_async(). * - * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileEnumerator or %NULL + * if an error occurred. + * Free the returned object with g_object_unref(). */ @@ -17829,7 +19852,7 @@ /** * g_file_enumerator_close_async: * @enumerator: a #GFileEnumerator. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -17847,7 +19870,8 @@ * g_file_enumerator_close_finish: * @enumerator: a #GFileEnumerator. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). * @@ -17865,6 +19889,28 @@ /** + * g_file_enumerator_get_child: + * @enumerator: a #GFileEnumerator + * @info: a #GFileInfo gotten from g_file_enumerator_next_file() + * or the async equivalents. + * + * Return a new #GFile which refers to the file named by @info in the source + * directory of @enumerator. This function is primarily intended to be used + * inside loops with g_file_enumerator_next_file(). + * + * This is a convenience method that's equivalent to: + * |[<!-- language="C" --> + * gchar *name = g_file_info_get_name (info); + * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), + * name); + * ]| + * + * Returns: (transfer full): a #GFile for the #GFileInfo passed it. + * Since: 2.36 + */ + + +/** * g_file_enumerator_get_container: * @enumerator: a #GFileEnumerator * @@ -17906,11 +19952,15 @@ * returned from this function will contain attributes that match the * attribute string that was passed when the #GFileEnumerator was created. * + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * * On error, returns %NULL and sets @error to the error. If the * enumerator is at the end, %NULL will be returned and @error will * be unset. * - * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. + * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. + * Free the returned object with g_object_unref() when no longer needed. */ @@ -17918,7 +19968,7 @@ * g_file_enumerator_next_files_async: * @enumerator: a #GFileEnumerator. * @num_files: the number of file info objects to request - * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -17927,6 +19977,9 @@ * When all i/o for the operation is finished the @callback will be called with * the requested information. * + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * * The callback can be called with less than @num_files files in case of error * or at the end of the enumerator. In case of a partial error the callback will * be called with any succeeding items and no error, and on the next request the @@ -17946,11 +19999,14 @@ * g_file_enumerator_next_files_finish: * @enumerator: a #GFileEnumerator. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). * - * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. + * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with + * g_list_free() and unref the infos with g_object_unref() when you're + * done with them. */ @@ -17976,14 +20032,16 @@ * * This call does no blocking I/O. * - * Returns: %TRUE if @file1 and @file2 are equal. %FALSE if either is not a #GFile. + * Returns: %TRUE if @file1 and @file2 are equal. + * %FALSE if either is not a #GFile. */ /** * g_file_find_enclosing_mount: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Gets a #GMount for the #GFile. @@ -17996,16 +20054,20 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GMount where the @file is located + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_find_enclosing_mount_async: * @file: a #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the mount for the file. @@ -18028,7 +20090,8 @@ * Finishes an asynchronous find mount request. * See g_file_find_enclosing_mount_async(). * - * Returns: (transfer full): #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GMount for given @file or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -18050,7 +20113,9 @@ * * This call does no blocking I/O. * - * Returns: string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. + * Returns: string containing the #GFile's base name, or %NULL + * if given #GFile is invalid. The returned string should be + * freed with g_free() when no longer needed. */ @@ -18067,7 +20132,8 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile to a child specified by @name. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile to a child specified by @name. + * Free the returned object with g_object_unref(). */ @@ -18086,7 +20152,9 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile to the specified child, or + * %NULL if the display name couldn't be converted. + * Free the returned object with g_object_unref(). */ @@ -18100,7 +20168,9 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile structure to the + * parent of the given #GFile or %NULL if there is + * no parent. Free the returned object with g_object_unref(). */ @@ -18123,7 +20193,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's parse name. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -18135,7 +20207,9 @@ * * This call does no blocking I/O. * - * Returns: string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. + * Returns: string containing the #GFile's path, or %NULL if + * no such path exists. The returned string should be + * freed with g_free() when no longer needed. */ @@ -18148,7 +20222,10 @@ * * This call does no blocking I/O. * - * Returns: string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. + * Returns: string with the relative path from @descendant + * to @parent, or %NULL if @descendant doesn't have @parent + * as prefix. The returned string should be freed with g_free() + * when no longer needed. */ @@ -18160,7 +20237,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's URI. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's URI. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -18170,14 +20249,16 @@ * * Gets the URI scheme for a #GFile. * RFC 3986 decodes the scheme as: - * <programlisting> + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * </programlisting> + * ]| * Common schemes include "file", "http", "ftp", etc. * * This call does no blocking I/O. * - * Returns: a string containing the URI scheme for the given #GFile. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the URI scheme for the given + * #GFile. The returned string should be freed with g_free() + * when no longer needed. */ @@ -18192,13 +20273,14 @@ * parent at all. If @parent is non-%NULL then %TRUE is only returned * if @file is a child of @parent. * - * Returns: %TRUE if @file is a child of @parent (or any parent in the case that @parent is %NULL). + * Returns: %TRUE if @file is a child of @parent (or any parent in the + * case that @parent is %NULL). * Since: 2.24 */ /** - * g_file_has_prefix: + * g_file_has_prefix: (virtual prefix_matches) * @file: input #GFile * @prefix: input #GFile * @@ -18214,8 +20296,8 @@ * filesystem point of view), because the prefix of @file is an alias * of @prefix. * - * Virtual: prefix_matches - * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, %FALSE otherwise. + * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, + * %FALSE otherwise. */ @@ -18228,20 +20310,24 @@ * * This call does no blocking I/O. * - * Returns: %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. + * Returns: %TRUE if #GFile's backend supports the + * given URI scheme, %FALSE if URI scheme is %NULL, + * not supported, or #GFile is invalid. */ /** - * g_file_hash: + * g_file_hash: (virtual hash) * @file: (type GFile): #gconstpointer to a #GFile * * Creates a hash value for a #GFile. * * This call does no blocking I/O. * - * Virtual: hash - * Returns: 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. + * Returns: 0 if @file is not a valid #GFile, otherwise an + * integer that can be used as hash value for the #GFile. + * This function is intended for easily hashing a #GFile to + * add to a #GHashTable or similar data structure. */ @@ -18261,7 +20347,8 @@ * * Creates a new icon for a file. * - * Returns: (transfer full) (type GFileIcon): a #GIcon for the given @file, or %NULL on error. + * Returns: (transfer full) (type GFileIcon): a #GIcon for the given + * @file, or %NULL on error. */ @@ -18278,7 +20365,7 @@ * @src_info: source to copy attributes from. * @dest_info: destination to copy attributes to. * - * Copies all of the <link linkend="gio-GFileAttribute">GFileAttribute</link>s + * Copies all of the [GFileAttribute][gio-GFileAttribute] * from @src_info to @dest_info. */ @@ -18302,7 +20389,8 @@ * This escapes things as needed to make the string valid * utf8. * - * Returns: a UTF-8 string associated with the given @attribute. When you're done with the string it must be freed with g_free(). + * Returns: a UTF-8 string associated with the given @attribute. + * When you're done with the string it must be freed with g_free(). */ @@ -18326,7 +20414,8 @@ * Gets the value of a byte string attribute. If the attribute does * not contain a byte string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a byte string, or %NULL otherwise. + * Returns: the contents of the @attribute value as a byte string, or + * %NULL otherwise. */ @@ -18340,7 +20429,8 @@ * * Gets the attribute type, value and status for an attribute key. * - * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, %FALSE otherwise. + * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, + * %FALSE otherwise. */ @@ -18378,7 +20468,8 @@ * Gets the value of a #GObject attribute. If the attribute does * not contain a #GObject, %NULL will be returned. * - * Returns: (transfer none): a #GObject associated with the given @attribute, or %NULL otherwise. + * Returns: (transfer none): a #GObject associated with the given @attribute, or + * %NULL otherwise. */ @@ -18389,7 +20480,8 @@ * * Gets the attribute status for an attribute key. * - * Returns: a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. + * Returns: a #GFileAttributeStatus for the given @attribute, or + * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. */ @@ -18401,7 +20493,8 @@ * Gets the value of a string attribute. If the attribute does * not contain a string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. + * Returns: the contents of the @attribute value as a UTF-8 string, or + * %NULL otherwise. */ @@ -18413,7 +20506,8 @@ * Gets the value of a stringv attribute. If the attribute does * not contain a stringv, %NULL will be returned. * - * Returns: (transfer none): the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8. + * Returns: (transfer none): the contents of the @attribute value as a stringv, or + * %NULL otherwise. Do not free. These returned strings are UTF-8. * Since: 2.22 */ @@ -18425,7 +20519,8 @@ * * Gets the attribute type for an attribute key. * - * Returns: a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. + * Returns: a #GFileAttributeType for the given @attribute, or + * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. */ @@ -18466,6 +20561,19 @@ /** + * g_file_info_get_deletion_date: + * @info: a #GFileInfo. + * + * Returns the #GDateTime representing the deletion date of the file, as + * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the + * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. + * + * Returns: a #GDateTime, or %NULL. + * Since: 2.36 + */ + + +/** * g_file_info_get_display_name: * @info: a #GFileInfo. * @@ -18489,7 +20597,7 @@ * g_file_info_get_etag: * @info: a #GFileInfo. * - * Gets the <link linkend="gfile-etag">entity tag</link> for a given + * Gets the [entity tag][gfile-etag] for a given * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * * Returns: a string containing the value of the "etag:value" attribute. @@ -18616,7 +20724,8 @@ * * Checks if a file info structure has an attribute named @attribute. * - * Returns: %TRUE if @Ginfo has an attribute named @attribute, %FALSE otherwise. + * Returns: %TRUE if @Ginfo has an attribute named @attribute, + * %FALSE otherwise. */ @@ -18628,7 +20737,8 @@ * Checks if a file info structure has an attribute in the * specified @name_space. * - * Returns: %TRUE if @Ginfo has an attribute in @name_space, %FALSE otherwise. + * Returns: %TRUE if @Ginfo has an attribute in @name_space, + * %FALSE otherwise. * Since: 2.22 */ @@ -18640,7 +20750,9 @@ * * Lists the file info structure's attributes. * - * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error. + * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the + * possible attribute types for the given @name_space, or + * %NULL on error. */ @@ -18805,7 +20917,7 @@ /** * g_file_info_set_content_type: * @info: a #GFileInfo. - * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>. + * @content_type: a content type. See [GContentType][gio-GContentType] * * Sets the content type attribute for a given #GFileInfo. * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. @@ -18857,7 +20969,7 @@ * @info: a #GFileInfo. * @is_hidden: a #gboolean. * - * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink. + * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. */ @@ -18948,7 +21060,8 @@ * @stream: a #GFileInputStream. * @attributes: a file attribute query string. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Queries a file input stream the given @attributes. This function blocks * while querying the stream. For the asynchronous (non-blocking) version @@ -18964,7 +21077,7 @@ * g_file_input_stream_query_info_async: * @stream: a #GFileInputStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -18987,7 +21100,8 @@ * g_file_input_stream_query_info_finish: * @stream: a #GFileInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, + * or %NULL to ignore. * * Finishes an asynchronous info query operation. * @@ -19042,7 +21156,7 @@ * g_file_io_stream_query_info_async: * @stream: a #GFileIOStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -19097,8 +21211,10 @@ * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Loads the content of the file into memory. The data is always @@ -19110,7 +21226,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors. + * Returns: %TRUE if the @file's contents were successfully loaded. + * %FALSE if there were errors. */ @@ -19142,8 +21259,10 @@ * @file: input #GFile * @res: a #GAsyncResult * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous load of the @file's contents. @@ -19152,7 +21271,8 @@ * g_free() when no longer needed. If @etag_out is present, it will be * set to the new entity tag for the @file. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ @@ -19160,7 +21280,8 @@ * g_file_load_partial_contents_async: (skip) * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read + * @read_more_callback: a #GFileReadMoreCallback to receive partial data + * and to specify whether further data should be read * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to the callback functions * @@ -19183,8 +21304,10 @@ * @file: input #GFile * @res: a #GAsyncResult * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous partial load operation that was started @@ -19193,14 +21316,16 @@ * The returned @content should be freed with g_free() when no longer * needed. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ /** * g_file_make_directory: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a directory. Note that this will only create a child directory @@ -19223,9 +21348,40 @@ /** + * g_file_make_directory_async: (virtual make_directory_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously creates a directory. + * + * Since: 2.38 + */ + + +/** + * g_file_make_directory_finish: (virtual make_directory_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous directory creation, started with + * g_file_make_directory_async(). + * + * Returns: %TRUE on successful directory creation, %FALSE otherwise. + * Since: 2.38 + */ + + +/** * g_file_make_directory_with_parents: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a directory and any parent directories that may not @@ -19242,7 +21398,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if all directories have been successfully created, %FALSE otherwise. + * Returns: %TRUE if all directories have been successfully created, %FALSE + * otherwise. * Since: 2.18 */ @@ -19251,7 +21408,8 @@ * g_file_make_symbolic_link: * @file: a #GFile with the name of the symlink to create * @symlink_value: a string with the path for the target of the new symlink - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Creates a symbolic link named @file which contains the string @@ -19266,10 +21424,87 @@ /** + * g_file_measure_disk_usage: + * @file: a #GFile + * @flags: #GFileMeasureFlags + * @cancellable: (allow-none): optional #GCancellable + * @progress_callback: (allow-none): a #GFileMeasureProgressCallback + * @progress_data: user_data for @progress_callback + * @disk_usage: (allow-none) (out): the number of bytes of disk space used + * @num_dirs: (allow-none) (out): the number of directories encountered + * @num_files: (allow-none) (out): the number of non-directories encountered + * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer + * + * Recursively measures the disk usage of @file. + * + * This is essentially an analog of the 'du' command, but it also + * reports the number of directories and non-directory files encountered + * (including things like symbolic links). + * + * By default, errors are only reported against the toplevel file + * itself. Errors found while recursing are silently ignored, unless + * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags. + * + * The returned size, @disk_usage, is in bytes and should be formatted + * with g_format_size() in order to get something reasonable for showing + * in a user interface. + * + * @progress_callback and @progress_data can be given to request + * periodic progress updates while scanning. See the documentation for + * #GFileMeasureProgressCallback for information about when and how the + * callback will be invoked. + * + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. + * Since: 2.38 + */ + + +/** + * g_file_measure_disk_usage_async: + * @file: a #GFile + * @flags: #GFileMeasureFlags + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable + * @progress_callback: (allow-none): a #GFileMeasureProgressCallback + * @progress_data: user_data for @progress_callback + * @callback: (allow-none): a #GAsyncReadyCallback to call when complete + * @user_data: the data to pass to callback function + * + * Recursively measures the disk usage of @file. + * + * This is the asynchronous version of g_file_measure_disk_usage(). See + * there for more information. + * + * Since: 2.38 + */ + + +/** + * g_file_measure_disk_usage_finish: + * @file: a #GFile + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @disk_usage: (allow-none) (out): the number of bytes of disk space used + * @num_dirs: (allow-none) (out): the number of directories encountered + * @num_files: (allow-none) (out): the number of non-directories encountered + * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer + * + * Collects the results from an earlier call to + * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for + * more information. + * + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. + * Since: 2.38 + */ + + +/** * g_file_monitor: * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a file or directory monitor for the given file, @@ -19279,7 +21514,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.18 */ @@ -19295,10 +21532,11 @@ /** - * g_file_monitor_directory: + * g_file_monitor_directory: (virtual monitor_dir) * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a directory monitor for the given file. @@ -19308,8 +21546,15 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Virtual: monitor_dir - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * It does not make sense for @flags to contain + * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to + * directories. It is not possible to monitor all the files in a + * directory for changes made via hard links; if you want to do this then + * you must register individual watches with g_file_monitor(). + * + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19324,9 +21569,8 @@ * has taken place. Should be called from file monitor * implementations only. * - * The signal will be emitted from an idle handler (in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link>). + * The signal will be emitted from an idle handler (in the + * [thread-default main context][g-main-context-push-thread-default]). */ @@ -19334,7 +21578,8 @@ * g_file_monitor_file: * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a file monitor for the given file. If no file notification @@ -19344,7 +21589,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor + * will also attempt to report changes made to the file via another + * filename (ie, a hard link). Without this flag, you can only rely on + * changes made through the filename contained in @file to be + * reported. Using this flag may result in an increase in resource + * usage, and may not have any effect depending on the #GFileMonitor + * backend and/or filesystem type. + * + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19361,7 +21616,8 @@ /** * g_file_monitor_set_rate_limit: * @monitor: a #GFileMonitor. - * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes + * @limit_msecs: a non-negative integer with the limit in milliseconds + * to poll for changes * * Sets the rate limit to which the @monitor will report * consecutive change events to the same file. @@ -19372,9 +21628,12 @@ * g_file_mount_enclosing_volume: * @location: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Starts a @mount_operation, mounting the volume that contains @@ -19398,7 +21657,9 @@ * * Finishes a mount operation started by g_file_mount_enclosing_volume(). * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, + * this function will return %FALSE and set @error + * appropriately if present. */ @@ -19406,9 +21667,12 @@ * g_file_mount_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Mounts a file of type G_FILE_TYPE_MOUNTABLE. @@ -19436,7 +21700,8 @@ * Finish an asynchronous mount operation that was started * with g_file_mount_mountable(). * - * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19445,9 +21710,12 @@ * @source: #GFile pointing to the source location * @destination: #GFile pointing to the destination location * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none) (scope call): #GFileProgressCallback function for updates - * @progress_callback_data: (closure): gpointer to user data for the callback function + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none) (scope call): #GFileProgressCallback + * function for updates + * @progress_callback_data: (closure): gpointer to user data for + * the callback function * @error: #GError for returning error conditions, or %NULL * * Tries to move the file or directory @source to the location specified @@ -19502,19 +21770,53 @@ * This operation never fails, but the returned object might not * support any I/O operation if @arg points to a malformed path. * - * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref(). + * Note that on Windows, this function expects its argument to be in + * UTF-8 -- not the system code page. This means that you + * should not use this function with string from argv as it is passed + * to main(). g_win32_get_command_line() will return a UTF-8 version of + * the commandline. #GApplication also uses UTF-8 but + * g_application_command_line_create_file_for_arg() may be more useful + * for you there. It is also always possible to use this function with + * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. + * + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). + */ + + +/** + * g_file_new_for_commandline_arg_and_cwd: + * @arg: a command line string + * @cwd: the current working directory of the commandline + * + * Creates a #GFile with the given argument from the command line. + * + * This function is similar to g_file_new_for_commandline_arg() except + * that it allows for passing the current working directory as an + * argument instead of using the current working directory of the + * process. + * + * This is useful if the commandline argument was given in a context + * other than the invocation of the current process. + * + * See also g_application_command_line_create_file_for_arg(). + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 */ /** * g_file_new_for_path: - * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. + * @path: a string containing a relative or absolute path. + * The string must be encoded in the glib filename encoding. * * Constructs a #GFile for a given path. This operation never * fails, but the returned object might not support any I/O * operation if @path is malformed. * - * Returns: (transfer full): a new #GFile for the given @path. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile for the given @path. + * Free the returned object with g_object_unref(). */ @@ -19527,13 +21829,15 @@ * operation if @uri is malformed or if the uri type is * not supported. * - * Returns: (transfer full): a new #GFile for the given @uri. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile for the given @uri. + * Free the returned object with g_object_unref(). */ /** * g_file_new_tmp: - * @tmpl: (type filename) (allow-none): Template for the file name, as in g_file_open_tmp(), or %NULL for a default template + * @tmpl: (type filename) (allow-none): Template for the file + * name, as in g_file_open_tmp(), or %NULL for a default template * @iostream: (out): on return, a #GFileIOStream for the created file * @error: a #GError, or %NULL * @@ -19548,7 +21852,8 @@ * Unlike the other #GFile constructors, this will return %NULL if * a temporary file could not be created. * - * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). * Since: 2.32 */ @@ -19576,7 +21881,8 @@ * really need to do read and write streaming, rather than just opening * for reading or writing. * - * Returns: (transfer full): #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -19584,9 +21890,11 @@ /** * g_file_open_readwrite_async: * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for reading and writing. @@ -19611,7 +21919,8 @@ * Finishes an asynchronous file read operation started with * g_file_open_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -19661,7 +21970,7 @@ * g_file_output_stream_query_info_async: * @stream: a #GFileOutputStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -19705,7 +22014,8 @@ * g_file_poll_mountable: * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Polls a file of type #G_FILE_TYPE_MOUNTABLE. @@ -19733,7 +22043,8 @@ * Finish an asynchronous poll operation that was polled * with g_file_poll_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. * Since: 2.22 */ @@ -19751,14 +22062,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() + * Returns: (transfer full): a #GAppInfo if the handle was found, + * %NULL if there were errors. + * When you are done with it, release it with g_object_unref() */ /** * g_file_query_exists: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * * Utility function to check if a particular file exists. This is * implemented using g_file_query_info() and as such does blocking I/O. @@ -19783,7 +22097,8 @@ * dialog. If you do this, you should make sure to also handle the errors * that can happen due to races when you execute the operation. * - * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). + * Returns: %TRUE if the file exists (and can be detected without error), + * %FALSE otherwise (or if cancelled). */ @@ -19791,7 +22106,8 @@ * g_file_query_file_type: * @file: input #GFile * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info() - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * * Utility function to inspect the #GFileType of a file. This is * implemented using g_file_query_info() and as such does blocking I/O. @@ -19799,7 +22115,8 @@ * The primary use case of this method is to check if a file is * a regular file, directory, or symlink. * - * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file does not exist + * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN + * if the file does not exist * Since: 2.18 */ @@ -19808,7 +22125,8 @@ * g_file_query_filesystem_info: * @file: input #GFile * @attributes: an attribute query string - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Similar to g_file_query_info(), but obtains information @@ -19837,7 +22155,8 @@ * be returned. Other errors are possible too, and depend on what * kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. + * Free the returned object with g_object_unref(). */ @@ -19845,9 +22164,11 @@ * g_file_query_filesystem_info_async: * @file: input #GFile * @attributes: an attribute query string - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about the filesystem @@ -19873,7 +22194,9 @@ * Finishes an asynchronous filesystem info query. * See g_file_query_filesystem_info_async(). * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19882,7 +22205,8 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Gets the requested information about specified @file. @@ -19916,7 +22240,8 @@ * returned. Other errors are possible too, and depend on what kind of * filesystem the file is on. * - * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL + * on error. Free the returned object with g_object_unref(). */ @@ -19925,9 +22250,11 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about specified @file. @@ -19951,14 +22278,17 @@ * Finishes an asynchronous file info query. * See g_file_query_info_async(). * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. Free the returned object with + * g_object_unref(). */ /** * g_file_query_settable_attributes: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtain the list of settable attributes for the file. @@ -19972,14 +22302,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() + * Returns: a #GFileAttributeInfoList describing the settable attributes. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** * g_file_query_writable_namespaces: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtain the list of attribute namespaces where new attributes @@ -19990,12 +22323,14 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() + * Returns: a #GFileAttributeInfoList describing the writable namespaces. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** - * g_file_read: + * g_file_read: (virtual read_fn) * @file: #GFile to read * @cancellable: (allow-none): a #GCancellable * @error: a #GError, or %NULL @@ -20012,17 +22347,19 @@ * error will be returned. Other errors are possible too, and depend * on what kind of filesystem the file is on. * - * Virtual: read_fn - * Returns: (transfer full): #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_read_async: * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for reading. @@ -20045,17 +22382,20 @@ * Finishes an asynchronous file read operation started with * g_file_read_async(). * - * Returns: (transfer full): a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace: * @file: input #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @etag: (allow-none): an optional [entity tag][gfile-etag] + * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Returns an output stream for overwriting the file, possibly @@ -20100,19 +22440,23 @@ * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are * possible too, and depend on what kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace_async: * @file: input #GFile - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously overwrites the file, replacing the contents, @@ -20132,10 +22476,13 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL + * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document, + * or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when no longer needed, or %NULL + * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag] + * for the document. This should be freed with g_free() when no longer + * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore * @error: a #GError, or %NULL * @@ -20154,7 +22501,8 @@ * The returned @new_etag can be used to verify that the file hasn't * changed the next time it is saved over. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. */ @@ -20163,7 +22511,7 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @length: the length of @contents in bytes - * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -20184,6 +22532,35 @@ * * If @make_backup is %TRUE, this function will attempt to * make a backup of @file. + * + * Note that no copy of @content will be made, so it must stay valid + * until @callback is called. See g_file_replace_contents_bytes_async() + * for a #GBytes version that will automatically hold a reference to the + * contents (without copying) for the duration of the call. + */ + + +/** + * g_file_replace_contents_bytes_async: + * @file: input #GFile + * @contents: a #GBytes + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL + * @make_backup: %TRUE if a backup should be created + * @flags: a set of #GFileCreateFlags + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Same as g_file_replace_contents_async() but takes a #GBytes input instead. + * This function will keep a ref on @contents until the operation is done. + * Unlike g_file_replace_contents_async() this allows forgetting about the + * content without waiting for the callback. + * + * When this operation has completed, @callback will be called with + * @user_user data, and the operation can be finalized with + * g_file_replace_contents_finish(). + * + * Since: 2.40 */ @@ -20191,7 +22568,9 @@ * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when it is no longer needed, or %NULL + * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag] + * for the document. This should be freed with g_free() when it is no + * longer needed, or %NULL * @error: a #GError, or %NULL * * Finishes an asynchronous replace of the given @file. See @@ -20211,17 +22590,20 @@ * Finishes an asynchronous file replace operation started with * g_file_replace_async(). * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @etag: (allow-none): an optional [entity tag][gfile-etag] + * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: return location for a #GError, or %NULL * * Returns an output stream for overwriting the file in readwrite mode, @@ -20235,7 +22617,8 @@ * supported, so make sure you really need to do read and write streaming, * rather than just opening for reading or writing. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -20243,12 +22626,15 @@ /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously overwrites the file in read-write mode, @@ -20275,7 +22661,8 @@ * Finishes an asynchronous file replace operation started with * g_file_replace_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -20289,7 +22676,9 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path is %NULL or if @file is invalid. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFile to the resolved path. + * %NULL if @relative_path is %NULL or if @file is invalid. + * Free the returned object with g_object_unref(). */ @@ -20298,9 +22687,11 @@ * @file: input #GFile * @attribute: a string containing the attribute's name * @type: The type of the attribute - * @value_p: (allow-none): a pointer to the value (or the pointer itself if the type is a pointer type) + * @value_p: (allow-none): a pointer to the value (or the pointer + * itself if the type is a pointer type) * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets an attribute in the file with attribute name @attribute to @value. @@ -20322,7 +22713,8 @@ * @attribute: a string containing the attribute's name * @value: a string containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. @@ -20333,7 +22725,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20343,7 +22736,8 @@ * @attribute: a string containing the attribute's name * @value: a #gint32 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. @@ -20353,7 +22747,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20363,7 +22758,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint64 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. @@ -20383,7 +22779,8 @@ * @attribute: a string containing the attribute's name * @value: a string containing the attribute's value * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. @@ -20403,7 +22800,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint32 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. @@ -20413,7 +22811,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20423,7 +22822,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint64 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. @@ -20433,7 +22833,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20442,8 +22843,9 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: a #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer * @@ -20476,7 +22878,8 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Tries to set all attributes in the #GFileInfo on the target @@ -20492,7 +22895,7 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if there was any error, %FALSE otherwise. + * Returns: %FALSE if there was any error, %TRUE otherwise. */ @@ -20500,7 +22903,8 @@ * g_file_set_display_name: * @file: input #GFile * @display_name: a string - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Renames @file to the specified display name. @@ -20519,7 +22923,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile specifying what @file was renamed to, + * or %NULL if there was an error. + * Free the returned object with g_object_unref(). */ @@ -20527,9 +22933,11 @@ * g_file_set_display_name_async: * @file: input #GFile * @display_name: a string - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously sets the display name for a given #GFile. @@ -20552,7 +22960,8 @@ * Finishes setting a display name started with * g_file_set_display_name_async(). * - * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -20592,7 +23001,8 @@ * Finish an asynchronous start operation that was started * with g_file_start_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. * Since: 2.22 */ @@ -20601,9 +23011,12 @@ * g_file_stop_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Stops a file of type #G_FILE_TYPE_MOUNTABLE. @@ -20631,7 +23044,8 @@ * Finish an asynchronous stop operation that was started * with g_file_stop_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -20640,11 +23054,10 @@ * g_file_supports_thread_contexts: * @file: a #GFile * - * Checks if @file supports <link - * linkend="g-main-context-push-thread-default-context">thread-default - * contexts</link>. If this returns %FALSE, you cannot perform - * asynchronous operations on @file in a thread that has a - * thread-default context. + * Checks if @file supports + * [thread-default contexts][g-main-context-push-thread-default-context]. + * If this returns %FALSE, you cannot perform asynchronous operations on + * @file in a thread that has a thread-default context. * * Returns: Whether or not @file supports thread-default contexts. * Since: 2.22 @@ -20652,9 +23065,10 @@ /** - * g_file_trash: + * g_file_trash: (virtual trash) * @file: #GFile to send to trash - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sends @file to the "Trashcan", if possible. This is similar to @@ -20671,11 +23085,43 @@ /** + * g_file_trash_async: (virtual trash_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously sends @file to the Trash location, if possible. + * + * Since: 2.38 + */ + + +/** + * g_file_trash_finish: (virtual trash_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous file trashing operation, started with + * g_file_trash_async(). + * + * Returns: %TRUE on successful trash, %FALSE otherwise. + * Since: 2.38 + */ + + +/** * g_file_unmount_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. @@ -20703,8 +23149,10 @@ * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. + * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() + * instead. */ @@ -20712,9 +23160,12 @@ * g_file_unmount_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. @@ -20743,7 +23194,8 @@ * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable_with_operation(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -20755,7 +23207,9 @@ * * Obtains a completion for @initial_text from @completer. * - * Returns: a completed string, or %NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished. + * Returns: a completed string, or %NULL if no completion exists. + * This string is not owned by GIO, so remember to g_free() it + * when finished. */ @@ -20766,7 +23220,8 @@ * * Gets an array of completion strings for a given initial text. * - * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished. + * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. + * This array must be freed by g_strfreev() when finished. */ @@ -20850,6 +23305,17 @@ /** + * g_icon_deserialize: + * @value: a #GVariant created with g_icon_serialize() + * + * Deserializes a #GIcon previously serialized using g_icon_serialize(). + * + * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails. + * Since: 2.38 + */ + + +/** * g_icon_equal: * @icon1: (allow-none): pointer to the first #GIcon. * @icon2: (allow-none): pointer to the second #GIcon. @@ -20861,13 +23327,13 @@ /** - * g_icon_hash: + * g_icon_hash: (virtual hash) * @icon: #gconstpointer to an icon object. * * Gets a hash for an icon. * - * Virtual: hash - * Returns: a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. + * Returns: a #guint containing a hash for the @icon, suitable for + * use in a #GHashTable or similar data structure. */ @@ -20883,13 +23349,29 @@ * implementations you need to ensure that each #GType is registered * with the type system prior to calling g_icon_new_for_string(). * - * Returns: (transfer full): An object implementing the #GIcon interface or %NULL if @error is set. + * Returns: (transfer full): An object implementing the #GIcon + * interface or %NULL if @error is set. * Since: 2.20 */ /** - * g_icon_to_string: + * g_icon_serialize: + * @icon: a #GIcon + * + * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved + * back by calling g_icon_deserialize() on the returned value. + * As serialization will avoid using raw icon data when possible, it only + * makes sense to transfer the #GVariant between processes on the same machine, + * (as opposed to over the network), and within the same file system namespace. + * + * Returns: (transfer full): a #GVariant, or %NULL when serialization fails. + * Since: 2.38 + */ + + +/** + * g_icon_to_string: (virtual to_tokens) * @icon: a #GIcon. * * Generates a textual representation of @icon that can be used for @@ -20900,22 +23382,17 @@ * The encoding of the returned string is proprietary to #GIcon except * in the following two cases * - * <itemizedlist> - * <listitem><para> - * If @icon is a #GFileIcon, the returned string is a native path - * (such as <literal>/path/to/my icon.png</literal>) without escaping - * if the #GFile for @icon is a native file. If the file is not - * native, the returned string is the result of g_file_get_uri() - * (such as <literal>sftp://path/to/my%20icon.png</literal>). - * </para></listitem> - * <listitem><para> - * If @icon is a #GThemedIcon with exactly one name, the encoding is - * simply the name (such as <literal>network-server</literal>). - * </para></listitem> - * </itemizedlist> - * - * Virtual: to_tokens - * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free. + * - If @icon is a #GFileIcon, the returned string is a native path + * (such as `/path/to/my icon.png`) without escaping + * if the #GFile for @icon is a native file. If the file is not + * native, the returned string is the result of g_file_get_uri() + * (such as `sftp://path/to/my\%20icon.png`). + * + * - If @icon is a #GThemedIcon with exactly one name, the encoding is + * simply the name (such as `network-server`). + * + * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't + * be serialized. Use g_free() to free. * Since: 2.20 */ @@ -21122,7 +23599,8 @@ * * Tests if @address falls within the range described by @mask. * - * Returns: whether @address falls within the range described by @mask. + * Returns: whether @address falls within the range described by + * @mask. * Since: 2.32 */ @@ -21151,7 +23629,8 @@ * delimited by a "/". If it is not present, then the length is * assumed to be the full length of the address. * - * Returns: a new #GInetAddressMask corresponding to @string, or %NULL on error. + * Returns: a new #GInetAddressMask corresponding to @string, or %NULL + * on error. * Since: 2.32 */ @@ -21174,7 +23653,8 @@ * Creates a #GInetAddress for the "any" address (unassigned/"don't * care") for @family. * - * Returns: a new #GInetAddress corresponding to the "any" address for @family. + * Returns: a new #GInetAddress corresponding to the "any" address + * for @family. * Since: 2.22 */ @@ -21199,7 +23679,8 @@ * * Parses @string as an IP address and creates a new #GInetAddress. * - * Returns: a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed. + * Returns: a new #GInetAddress corresponding to @string, or %NULL if + * @string could not be parsed. * Since: 2.22 */ @@ -21210,7 +23691,8 @@ * * Creates a #GInetAddress for the loopback address for @family. * - * Returns: a new #GInetAddress corresponding to the loopback address for @family. + * Returns: a new #GInetAddress corresponding to the loopback address + * for @family. * Since: 2.22 */ @@ -21221,7 +23703,9 @@ * * Gets the raw binary address data from @address. * - * Returns: a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). + * Returns: a pointer to an internal array of the bytes in @address, + * which should not be modified, stored, or freed. The size of this + * array can be gotten with g_inet_address_get_native_size(). * Since: 2.22 */ @@ -21232,7 +23716,8 @@ * * Converts @address to string form. * - * Returns: a representation of @address as a string, which should be freed after use. + * Returns: a representation of @address as a string, which should be + * freed after use. * Since: 2.22 */ @@ -21243,7 +23728,8 @@ * * Gets @address's #GInetAddress. * - * Returns: (transfer none): the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored + * Returns: (transfer none): the #GInetAddress for @address, which must be + * g_object_ref()'d if it will be stored * Since: 2.22 */ @@ -21252,7 +23738,7 @@ * g_inet_socket_address_get_flowinfo: * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress * - * Gets the <literal>sin6_flowinfo</literal> field from @address, + * Gets the `sin6_flowinfo` field from @address, * which must be an IPv6 address. * * Returns: the flowinfo field @@ -21275,7 +23761,7 @@ * g_inet_socket_address_get_scope_id: * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress * - * Gets the <literal>sin6_scope_id</literal> field from @address, + * Gets the `sin6_scope_id` field from @address, * which must be an IPv6 address. * * Returns: the scope id field @@ -21296,10 +23782,27 @@ /** + * g_inet_socket_address_new_from_string: + * @address: the string form of an IP address + * @port: a port number + * + * Creates a new #GInetSocketAddress for @address and @port. + * + * If @address is an IPv6 address, it can also contain a scope ID + * (separated from the address by a "<literal>%</literal>"). + * + * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be + * parsed. + * Since: 2.40 + */ + + +/** * g_initable_init: * @initable: a #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Initializes the object implementing the interface. * @@ -21316,8 +23819,7 @@ * If the object is not initialized, or initialization returns with an * error, then all operations on the object except g_object_ref() and * g_object_unref() are considered to be invalid, and have undefined - * behaviour. See the <xref linkend="ginitable"/> section introduction - * for more details. + * behaviour. See the [introduction][ginitable] for more details. * * Implementations of this method must be idempotent, i.e. multiple calls * to this function with the same argument should return the same results. @@ -21325,7 +23827,8 @@ * of the first call. This is so that it's safe to implement the singleton * pattern in the GObject constructor function. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function will + * return %FALSE and set @error appropriately if present. * Since: 2.22 */ @@ -21334,15 +23837,19 @@ * g_initable_new: * @object_type: a #GType supporting #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. - * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties - * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. + * @first_property_name: (allow-none): the name of the first property, or %NULL if no + * properties + * @...: the value if the first property, followed by and other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GInitable object. This is * similar to g_object_new() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -21350,16 +23857,19 @@ /** * g_initable_new_valist: * @object_type: a #GType supporting #GInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, followed by + * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Helper function for constructing #GInitable object. This is * similar to g_object_new_valist() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -21370,18 +23880,30 @@ * @n_parameters: the number of parameters in @parameters * @parameters: (array length=n_parameters): the parameters to use to construct the object * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Helper function for constructing #GInitable object. This is * similar to g_object_newv() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ /** + * g_input_stream_async_read_is_via_threads: + * @stream: input stream + * + * Checks if an input stream's read_async function uses threads. + * + * Returns: %TRUE if @stream's read_async function uses threads. + */ + + +/** * g_input_stream_clear_pending: * @stream: input stream * @@ -21426,7 +23948,7 @@ /** * g_input_stream_close_async: * @stream: A #GInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional cancellable object * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21448,7 +23970,8 @@ * g_input_stream_close_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). * @@ -21479,7 +24002,8 @@ /** * g_input_stream_read: * @stream: a #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore @@ -21510,7 +24034,8 @@ /** * g_input_stream_read_all: * @stream: a #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @bytes_read: (out): location to store the number of bytes that was read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -21537,9 +24062,11 @@ /** * g_input_stream_read_async: * @stream: A #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21573,7 +24100,8 @@ /** * g_input_stream_read_bytes: * @stream: a #GInputStream. - * @count: maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. + * @count: maximum number of bytes that will be read from the stream. Common + * values include 4096 and 8192. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -21609,7 +24137,7 @@ * g_input_stream_read_bytes_async: * @stream: A #GInputStream. * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21641,7 +24169,8 @@ * g_input_stream_read_bytes_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream read-into-#GBytes operation. * @@ -21653,7 +24182,8 @@ * g_input_stream_read_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream read operation. * @@ -21664,7 +24194,8 @@ /** * g_input_stream_set_pending: * @stream: input stream - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -21704,7 +24235,7 @@ * g_input_stream_skip_async: * @stream: A #GInputStream. * @count: the number of bytes that will be skipped from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21739,7 +24270,8 @@ * g_input_stream_skip_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream skip operation. * @@ -21819,7 +24351,8 @@ * * Finds a #GIOExtension for an extension point by name. * - * Returns: (transfer none): the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name + * Returns: (transfer none): the #GIOExtension for @extension_point that has the + * given name, or %NULL if there is no extension with that name */ @@ -21830,7 +24363,9 @@ * Gets a list of all extensions that implement this extension point. * The list is sorted by priority, beginning with the highest priority. * - * Returns: (element-type GIOExtension) (transfer none): a #GList of #GIOExtension<!-- -->s. The list is owned by GIO and should not be modified. + * Returns: (element-type GIOExtension) (transfer none): a #GList of + * #GIOExtensions. The list is owned by GIO and should not be + * modified. */ @@ -21840,7 +24375,8 @@ * * Gets the required type for @extension_point. * - * Returns: the #GType that all implementations must have, or #G_TYPE_INVALID if the extension point has no required type + * Returns: the #GType that all implementations must have, + * or #G_TYPE_INVALID if the extension point has no required type */ @@ -21867,7 +24403,8 @@ * * Looks up an existing extension point. * - * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. + * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there + * is no registered extension point with the given name. */ @@ -21877,7 +24414,8 @@ * * Registers an extension point. * - * Returns: (transfer none): the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. + * Returns: (transfer none): the new #GIOExtensionPoint. This object is + * owned by GIO and should not be freed. */ @@ -21909,7 +24447,8 @@ * Creates a new GIOModule that will load the specific * shared library when in use. * - * Returns: a #GIOModule from given @filename, or %NULL on error. + * Returns: a #GIOModule from given @filename, + * or %NULL on error. */ @@ -21962,7 +24501,12 @@ * all gtypes) then you can use g_io_modules_scan_all_in_directory() * which allows delayed/lazy loading of modules. * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free(). + * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded + * from the directory, + * All the modules are loaded into memory, if you want to + * unload them (enabling on-demand loading) you must call + * g_type_module_unuse() on all the modules. Free the list + * with g_list_free(). */ @@ -21977,7 +24521,12 @@ * all gtypes) then you can use g_io_modules_scan_all_in_directory() * which allows delayed/lazy loading of modules. * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free(). + * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded + * from the directory, + * All the modules are loaded into memory, if you want to + * unload them (enabling on-demand loading) you must call + * g_type_module_unuse() on all the modules. Free the list + * with g_list_free(). * Since: 2.30 */ @@ -22030,6 +24579,10 @@ * * A job is cancellable if a #GCancellable was passed into * g_io_scheduler_push_job(). + * + * Deprecated: You should never call this function, since you don't + * know how other libraries in your program might be making use of + * gioscheduler. */ @@ -22045,6 +24598,7 @@ * blocking the I/O job). * * Returns: The return value of @func + * Deprecated: Use g_main_context_invoke(). */ @@ -22064,6 +24618,8 @@ * on to this function you have to ensure that it is not freed before * @func is called, either by passing %NULL as @notify to * g_io_scheduler_push_job() or by using refcounting for @user_data. + * + * Deprecated: Use g_main_context_invoke(). */ @@ -22072,7 +24628,8 @@ * @job_func: a #GIOSchedulerJobFunc. * @user_data: data to pass to @job_func * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] + * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * * Schedules the I/O job to run in another thread. @@ -22083,6 +24640,8 @@ * If @cancellable is not %NULL, it can be used to cancel the I/O job * by calling g_cancellable_cancel() or by calling * g_io_scheduler_cancel_all_jobs(). + * + * Deprecated: use #GThreadPool or g_task_run_in_thread() */ @@ -22168,7 +24727,8 @@ * g_io_stream_close_finish: * @stream: a #GIOStream * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Closes a stream. * @@ -22184,7 +24744,8 @@ * Gets the input stream for this object. This is used * for reading. * - * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. Do not free. + * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. + * Do not free. * Since: 2.22 */ @@ -22196,7 +24757,8 @@ * Gets the output stream for this object. This is used for * writing. * - * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. Do not free. + * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. + * Do not free. * Since: 2.22 */ @@ -22226,7 +24788,8 @@ /** * g_io_stream_set_pending: * @stream: a #GIOStream - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -22262,7 +24825,8 @@ /** * g_io_stream_splice_finish: * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous io stream splice operation. * @@ -22275,7 +24839,8 @@ * g_keyfile_settings_backend_new: * @filename: the filename of the keyfile * @root_path: the path under which all settings keys appear - * @root_group: (allow-none): the group name corresponding to @root_path, or %NULL + * @root_group: (allow-none): the group name corresponding to + * @root_path, or %NULL * * Creates a keyfile-backed #GSettingsBackend. * @@ -22330,9 +24895,11 @@ * g_loadable_icon_load: * @icon: a #GLoadableIcon. * @size: an integer. - * @type: (out) (allow-none): a location to store the type of the loaded icon, %NULL to ignore. + * @type: (out) (allow-none): a location to store the type of the + * loaded icon, %NULL to ignore. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Loads a loadable icon. For the asynchronous version of this function, * see g_loadable_icon_load_async(). @@ -22346,7 +24913,8 @@ * @icon: a #GLoadableIcon. * @size: an integer. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Loads an icon asynchronously. To finish this function, see @@ -22359,8 +24927,10 @@ * g_loadable_icon_load_finish: * @icon: a #GLoadableIcon. * @res: a #GAsyncResult. - * @type: a location to store the type of the loaded icon, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @type: (out) (allow-none): a location to store the type of the + * loaded icon, %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). * @@ -22448,9 +25018,8 @@ * g_memory_output_stream_get_data_size: * @ostream: a #GMemoryOutputStream * - * Returns the number of bytes from the start up - * to including the last byte written in the stream - * that has not been truncated away. + * Returns the number of bytes from the start up to including the last + * byte written in the stream that has not been truncated away. * * Returns: the number of bytes written to the stream * Since: 2.18 @@ -22462,16 +25031,20 @@ * @ostream: a #GMemoryOutputStream * * Gets the size of the currently allocated data area (available from - * g_memory_output_stream_get_data()). If the stream isn't - * growable (no realloc was passed to g_memory_output_stream_new()) then - * this is the maximum size of the stream and further writes - * will return %G_IO_ERROR_NO_SPACE. + * g_memory_output_stream_get_data()). + * + * You probably don't want to use this function on resizable streams. + * See g_memory_output_stream_get_data_size() instead. For resizable + * streams the size returned by this function is an implementation + * detail and may be change at any time in response to operations on the + * stream. * - * Note that for growable streams the returned size may become invalid on - * the next write or truncate operation on the stream. + * If the stream is fixed-sized (ie: no realloc was passed to + * g_memory_output_stream_new()) then this is the maximum size of the + * stream and further writes will return %G_IO_ERROR_NO_SPACE. * - * If you want the number of bytes currently written to the stream, use - * g_memory_output_stream_get_data_size(). + * In any case, if you want the number of bytes currently written to the + * stream, use g_memory_output_stream_get_data_size(). * * Returns: the number of bytes allocated for the data buffer */ @@ -22481,24 +25054,49 @@ * g_memory_output_stream_new: (skip) * @data: (allow-none): pointer to a chunk of memory to use, or %NULL * @size: the size of @data - * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL - * @destroy_function: (allow-none): a function to be called on @data when the stream is finalized, or %NULL + * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) + * to be called when @data needs to be grown, or %NULL + * @destroy_function: (allow-none): a function to be called on @data when the stream is + * finalized, or %NULL * * Creates a new #GMemoryOutputStream. * - * If @data is non-%NULL, the stream will use that for its internal storage. - * If @realloc_fn is non-%NULL, it will be used for resizing the internal - * storage when necessary. To construct a fixed-size output stream, - * pass %NULL as @realloc_fn. + * In most cases this is not the function you want. See + * g_memory_output_stream_new_resizable() instead. * - * |[ - * /* a stream that can grow */ + * If @data is non-%NULL, the stream will use that for its internal storage. + * + * If @realloc_fn is non-%NULL, it will be used for resizing the internal + * storage when necessary and the stream will be considered resizable. + * In that case, the stream will start out being (conceptually) empty. + * @size is used only as a hint for how big @data is. Specifically, + * seeking to the end of a newly-created stream will seek to zero, not + * @size. Seeking past the end of the stream and then writing will + * introduce a zero-filled gap. + * + * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to + * the end will seek to @size exactly. Writing past the end will give + * an 'out of space' error. Attempting to seek past the end will fail. + * Unlike the resizable case, seeking to an offset within the stream and + * writing will preserve the bytes passed in as @data before that point + * and will return them as part of g_memory_output_stream_steal_data(). + * If you intend to seek you should probably therefore ensure that @data + * is properly initialised. + * + * It is probably only meaningful to provide @data and @size in the case + * that you want a fixed-sized stream. Put another way: if @realloc_fn + * is non-%NULL then it makes most sense to give @data as %NULL and + * @size as 0 (allowing #GMemoryOutputStream to do the initial + * allocation for itself). + * + * |[<!-- language="C" --> + * // a stream that can grow * stream = g_memory_output_stream_new (NULL, 0, realloc, free); * - * /* another stream that can grow */ + * // another stream that can grow * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); * - * /* a fixed-size stream */ + * // a fixed-size stream * data = malloc (200); * stream3 = g_memory_output_stream_new (data, 200, NULL, free); * ]| @@ -22508,6 +25106,16 @@ /** + * g_memory_output_stream_new_resizable: + * + * Creates a new #GMemoryOutputStream, using g_realloc() and g_free() + * for memory allocation. + * + * Since: 2.36 + */ + + +/** * g_memory_output_stream_steal_as_bytes: * @ostream: a #GMemoryOutputStream * @@ -22640,7 +25248,8 @@ * remains at the current position. The value returned in @value must * be unreffed using g_variant_unref() when it is no longer in use. * - * Returns: %TRUE on success, or %FALSE if there is no additional attribute + * Returns: %TRUE on success, or %FALSE if there is no additional + * attribute * Since: 2.32 */ @@ -22784,7 +25393,8 @@ * type, then the positional parameters are ignored and %FALSE is * returned. * - * Returns: %TRUE if the named attribute was found with the expected type + * Returns: %TRUE if the named attribute was found with the expected + * type * Since: 2.34 */ @@ -22881,8 +25491,7 @@ * second with the "Cut", "Copy" and "Paste" items. The first and * second menus would then be added as submenus of the third. In XML * format, this would look something like the following: - * - * <informalexample><programlisting><![CDATA[ + * |[ * <menu id='edit-menu'> * <section> * <item label='Undo'/> @@ -22894,7 +25503,7 @@ * <item label='Paste'/> * </section> * </menu> - * ]]></programlisting></informalexample> + * ]| * * The following example is exactly equivalent. It is more illustrative * of the exact relationship between the menus and items (keeping in @@ -22902,8 +25511,7 @@ * containing one). The style of the second example is more verbose and * difficult to read (and therefore not recommended except for the * purpose of understanding what is really going on). - * - * <informalexample><programlisting><![CDATA[ + * |[ * <menu id='edit-menu'> * <item> * <link name='section'> @@ -22919,7 +25527,7 @@ * </link> * </item> * </menu> - * ]]></programlisting></informalexample> + * ]| * * Returns: a new #GMenuItem * Since: 2.32 @@ -23085,14 +25693,8 @@ * * Sets the "action" and possibly the "target" attribute of @menu_item. * - * If @detailed_action contains a double colon ("::") then it is used as - * a separator between an action name and a target string. In this - * case, this call is equivalent to calling - * g_menu_item_set_action_and_target() with the part before the "::" and - * with a string-type #GVariant containing the part following the "::". - * - * If @detailed_action doesn't contain "::" then the action is set to - * the given string (verbatim) and the target value is unset. + * The format of @detailed_action is the same format parsed by + * g_action_parse_detailed_name(). * * See g_menu_item_set_action_and_target() or * g_menu_item_set_action_and_target_value() for more flexible (but @@ -23106,6 +25708,28 @@ /** + * g_menu_item_set_icon: + * @menu_item: a #GMenuItem + * @icon: a #GIcon, or %NULL + * + * Sets (or unsets) the icon on @menu_item. + * + * This call is the same as calling g_icon_serialize() and using the + * result as the value to g_menu_item_set_attribute_value() for + * %G_MENU_ATTRIBUTE_ICON. + * + * This API is only intended for use with "noun" menu items; things like + * bookmarks or applications in an "Open With" menu. Don't use it on + * menu items corresponding to verbs (eg: stock icons for 'Save' or + * 'Quit'). + * + * If @icon is %NULL then the icon is unset. + * + * Since: 2.38 + */ + + +/** * g_menu_item_set_label: * @menu_item: a #GMenuItem * @label: (allow-none): the label to set, or %NULL to unset @@ -23267,9 +25891,10 @@ * g_variant_get(), followed by a g_variant_unref(). As such, * @format_string must make a complete copy of the data (since the * #GVariant may go away after the call to g_variant_unref()). In - * particular, no '&' characters are allowed in @format_string. + * particular, no '&' characters are allowed in @format_string. * - * Returns: %TRUE if the named attribute was found with the expected type + * Returns: %TRUE if the named attribute was found with the expected + * type * Since: 2.32 */ @@ -23279,7 +25904,8 @@ * @model: a #GMenuModel * @item_index: the index of the item * @attribute: the attribute to query - * @expected_type: (allow-none): the expected type of the attribute, or %NULL + * @expected_type: (allow-none): the expected type of the attribute, or + * %NULL * * Queries the item at position @item_index in @model for the attribute * specified by @attribute. @@ -23335,7 +25961,8 @@ * An immutable #GMenuModel will never emit the #GMenuModel::items-changed * signal. Consumers of the model may make optimisations accordingly. * - * Returns: %TRUE if the model is mutable (ie: "items-changed" may be emitted). + * Returns: %TRUE if the model is mutable (ie: "items-changed" may be + * emitted). * Since: 2.32 */ @@ -23485,6 +26112,16 @@ /** + * g_menu_remove_all: + * @menu: a #GMenu + * + * Removes all items in the menu. + * + * Since: 2.38 + */ + + +/** * g_mount_can_eject: * @mount: a #GMount. * @@ -23524,7 +26161,8 @@ * g_mount_eject_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23538,7 +26176,8 @@ * g_mount_eject_with_operation: * @mount: a #GMount. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -23555,7 +26194,8 @@ * g_mount_eject_with_operation_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23573,7 +26213,9 @@ * @mount is a path that reflects the main entry point for the user (e.g. * the home directory, or the root of the volume). * - * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23586,7 +26228,9 @@ * This is a convenience method for getting the #GVolume and then * using that object to get the #GDrive. * - * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23596,7 +26240,9 @@ * * Gets the icon for @mount. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23606,7 +26252,9 @@ * * Gets the name of @mount. * - * Returns: the name for the given @mount. The returned string should be freed with g_free() when no longer needed. + * Returns: the name for the given @mount. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -23616,7 +26264,9 @@ * * Gets the root directory on @mount. * - * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23637,7 +26287,9 @@ * * Gets the symbolic icon for @mount. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * Since: 2.34 */ @@ -23651,7 +26303,9 @@ * considered an opaque string. Returns %NULL if there is no UUID * available. * - * Returns: the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. + * Returns: the UUID for @mount or %NULL if no UUID can be computed. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -23661,14 +26315,17 @@ * * Gets the volume for the @mount. * - * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ /** * g_mount_guess_content_type: * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @force_rescan: Whether to force a rescan of the content. + * Otherwise a cached result will be used if available * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: a #GAsyncReadyCallback * @user_data: user data passed to @callback @@ -23676,7 +26333,8 @@ * Tries to guess the type of content stored on @mount. Returns one or * more textual identifiers of well-known content types (typically * prefixed with "x-content/"), e.g. x-content/image-dcf for camera - * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * memory cards. See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) * specification for more on x-content types. * * This is an asynchronous operation (see @@ -23692,7 +26350,8 @@ * g_mount_guess_content_type_finish: * @mount: a #GMount * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Finishes guessing content types of @mount. If any errors occurred * during the operation, @error will be set to contain the errors and @@ -23700,7 +26359,8 @@ * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content * guessing. * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. + * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. + * Caller should free this array with g_strfreev() when done with it. * Since: 2.18 */ @@ -23708,20 +26368,24 @@ /** * g_mount_guess_content_type_sync: * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @force_rescan: Whether to force a rescan of the content. + * Otherwise a cached result will be used if available * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Tries to guess the type of content stored on @mount. Returns one or * more textual identifiers of well-known content types (typically * prefixed with "x-content/"), e.g. x-content/image-dcf for camera - * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * memory cards. See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) * specification for more on x-content types. * * This is an synchronous operation and as such may block doing IO; * see g_mount_guess_content_type() for the asynchronous version. * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. + * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. + * Caller should free this array with g_strfreev() when done with it. * Since: 2.18 */ @@ -23742,10 +26406,10 @@ * situation, a #GVolumeMonitor implementation would create two * #GVolume objects (for example, one for the camera functionality of * the device and one for a SD card reader on the device) with - * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal> - * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the + * activation URIs `gphoto2://[usb:001,002]/store1/` + * and `gphoto2://[usb:001,002]/store2/`. When the * underlying mount (with root - * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said + * `gphoto2://[usb:001,002]/`) is mounted, said * #GVolumeMonitor implementation would create two #GMount objects * (each with their root matching the corresponding volume activation * root) that would shadow the original mount. @@ -23776,7 +26440,8 @@ * * Gets a choice from the mount operation. * - * Returns: an integer containing an index of the user's choice from the choice's list, or %0. + * Returns: an integer containing an index of the user's choice from + * the choice's list, or %0. */ @@ -23896,7 +26561,8 @@ * g_mount_remount: * @mount: a #GMount. * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -23917,7 +26583,8 @@ * g_mount_remount_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes remounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23959,7 +26626,8 @@ * g_mount_unmount_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes unmounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23973,7 +26641,8 @@ * g_mount_unmount_with_operation: * @mount: a #GMount. * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -23990,7 +26659,8 @@ * g_mount_unmount_with_operation_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes unmounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -24179,7 +26849,8 @@ * @monitor: a #GNetworkMonitor * @connectable: a #GSocketConnectable * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously attempts to determine whether or not the host @@ -24305,6 +26976,202 @@ /** + * g_networking_init: + * + * Initializes the platform networking libraries (eg, on Windows, this + * calls WSAStartup()). GLib will call this itself if it is needed, so + * you only need to call it if you directly call system networking + * functions (without calling any GLib networking functions first). + * + * Since: 2.36 + */ + + +/** + * g_notification_add_button: + * @notification: a #GNotification + * @label: label of the button + * @detailed_action: a detailed action name + * + * Adds a button to @notification that activates the action in + * @detailed_action when clicked. That action must be an + * application-wide action (starting with "app."). If @detailed_action + * contains a target, the action will be activated with that target as + * its parameter. + * + * See g_action_parse_detailed_name() for a description of the format + * for @detailed_action. + * + * Since: 2.40 + */ + + +/** + * g_notification_add_button_with_target: (skip) + * @notification: a #GNotification + * @label: label of the button + * @action: an action name + * @target_format: (allow-none): a GVariant format string, or %NULL + * @...: positional parameters, as determined by @format_string + * + * Adds a button to @notification that activates @action when clicked. + * @action must be an application-wide action (it must start with "app."). + * + * If @target_format is given, it is used to collect remaining + * positional parameters into a GVariant instance, similar to + * g_variant_new(). @action will be activated with that GVariant as its + * parameter. + * + * Since: 2.40 + */ + + +/** + * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target) + * @notification: a #GNotification + * @label: label of the button + * @action: an action name + * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL + * + * Adds a button to @notification that activates @action when clicked. + * @action must be an application-wide action (it must start with "app."). + * + * If @target is non-%NULL, @action will be activated with @target as + * its parameter. + * + * Since: 2.40 + */ + + +/** + * g_notification_new: + * @title: the title of the notification + * + * Creates a new #GNotification with @title as its title. + * + * After populating @notification with more details, it can be sent to + * the desktop shell with g_application_send_notification(). Changing + * any properties after this call will not have any effect until + * resending @notification. + * + * Returns: a new #GNotification instance + * Since: 2.40 + */ + + +/** + * g_notification_set_body: + * @notification: a #GNotification + * @body: (allow-none): the new body for @notification, or %NULL + * + * Sets the body of @notification to @body. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_default_action: + * @notification: a #GNotification + * @detailed_action: a detailed action name + * + * Sets the default action of @notification to @detailed_action. This + * action is activated when the notification is clicked on. + * + * The action in @detailed_action must be an application-wide action (it + * must start with "app."). If @detailed_action contains a target, the + * given action will be activated with that target as its parameter. + * See g_action_parse_detailed_name() for a description of the format + * for @detailed_action. + * + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_default_action_and_target: (skip) + * @notification: a #GNotification + * @action: an action name + * @target_format: (allow-none): a GVariant format string, or %NULL + * @...: positional parameters, as determined by @format_string + * + * Sets the default action of @notification to @action. This action is + * activated when the notification is clicked on. It must be an + * application-wide action (it must start with "app."). + * + * If @target_format is given, it is used to collect remaining + * positional parameters into a GVariant instance, similar to + * g_variant_new(). @action will be activated with that GVariant as its + * parameter. + * + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target) + * @notification: a #GNotification + * @action: an action name + * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL + * + * Sets the default action of @notification to @action. This action is + * activated when the notification is clicked on. It must be an + * application-wide action (start with "app."). + * + * If @target_format is given, it is used to collect remaining + * positional parameters into a GVariant instance, similar to + * g_variant_new(). + * + * If @target is non-%NULL, @action will be activated with @target as + * its parameter. + * + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_icon: + * @notification: a #GNotification + * @icon: the icon to be shown in @notification, as a #GIcon + * + * Sets the icon of @notification to @icon. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_title: + * @notification: a #GNotification + * @title: the new title for @notification + * + * Sets the title of @notification to @title. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_urgent: + * @notification: a #GNotification + * @urgent: %TRUE if @notification is urgent + * + * Sets or unsets whether @notification is marked as urgent. + * + * Since: 2.40 + */ + + +/** * g_null_settings_backend_new: * * Creates a readonly #GSettingsBackend. @@ -24318,6 +27185,16 @@ /** + * g_output_stream_async_write_is_via_threads: + * @stream: a #GOutputStream. + * + * Checks if an ouput stream's write_async function uses threads. + * + * Returns: %TRUE if @stream's write_async function uses threads. + */ + + +/** * g_output_stream_clear_pending: * @stream: output stream * @@ -24390,7 +27267,8 @@ * g_output_stream_close_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Closes an output stream. * @@ -24440,7 +27318,8 @@ * g_output_stream_flush_finish: * @stream: a #GOutputStream. * @result: a GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes flushing an output stream. * @@ -24483,9 +27362,38 @@ /** + * g_output_stream_printf: + * @stream: a #GOutputStream. + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore + * @format: the format string. See the printf() documentation + * @...: the parameters to insert into the format string + * + * This is a utility function around g_output_stream_write_all(). It + * uses g_strdup_vprintf() to turn @format and @... into a string that + * is then written to @stream. + * + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. + * + * Note that partial writes cannot be properly checked with this + * function due to the variable length of the written string, if you + * need precise control over partial write failures, you need to + * create you own printf()-like wrapper around g_output_stream_write() + * or g_output_stream_write_all(). + * + * Since: 2.40 + * Returns: %TRUE on success, %FALSE if there was an error + */ + + +/** * g_output_stream_set_pending: * @stream: a #GOutputStream. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -24501,11 +27409,16 @@ * @source: a #GInputStream. * @flags: a set of #GOutputStreamSpliceFlags. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Splices an input stream into an output stream. * - * Returns: a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. + * Returns: a #gssize containing the size of the data spliced, or + * -1 if an error occurred. Note that if the number of bytes + * spliced is greater than %G_MAXSSIZE, then that will be + * returned, and there is no way to determine the actual number + * of bytes spliced. */ @@ -24533,16 +27446,48 @@ * g_output_stream_splice_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream splice operation. * - * Returns: a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. + * Returns: a #gssize of the number of bytes spliced. Note that if the + * number of bytes spliced is greater than %G_MAXSSIZE, then that + * will be returned, and there is no way to determine the actual + * number of bytes spliced. + */ + + +/** + * g_output_stream_vprintf: + * @stream: a #GOutputStream. + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore + * @format: the format string. See the printf() documentation + * @args: the parameters to insert into the format string + * + * This is a utility function around g_output_stream_write_all(). It + * uses g_strdup_vprintf() to turn @format and @args into a string that + * is then written to @stream. + * + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. + * + * Note that partial writes cannot be properly checked with this + * function due to the variable length of the written string, if you + * need precise control over partial write failures, you need to + * create you own printf()-like wrapper around g_output_stream_write() + * or g_output_stream_write_all(). + * + * Since: 2.40 + * Returns: %TRUE on success, %FALSE if there was an error */ /** - * g_output_stream_write: + * g_output_stream_write: (virtual write_fn) * @stream: a #GOutputStream. * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. * @count: the number of bytes to write @@ -24570,7 +27515,6 @@ * * On error -1 is returned and @error is set accordingly. * - * Virtual: write_fn * Returns: Number of bytes written, or -1 on error */ @@ -24580,7 +27524,8 @@ * @stream: a #GOutputStream. * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. * @count: the number of bytes to write - * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -24641,6 +27586,11 @@ * * For the synchronous, blocking version of this function, see * g_output_stream_write(). + * + * Note that no copy of @buffer will be made, so it must stay valid + * until @callback is called. See g_output_stream_write_bytes_async() + * for a #GBytes version that will automatically hold a reference to + * the contents (without copying) for the duration of the call. */ @@ -24651,26 +27601,17 @@ * @cancellable: (allow-none): optional cancellable object * @error: location to store the error occurring, or %NULL to ignore * - * Tries to write the data from @bytes into the stream. Will block - * during the operation. + * A wrapper function for g_output_stream_write() which takes a + * #GBytes as input. This can be more convenient for use by language + * bindings or in other cases where the refcounted nature of #GBytes + * is helpful over a bare pointer interface. * - * If @bytes is 0-length, returns 0 and does nothing. A #GBytes larger - * than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written to the stream is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. on a partial I/O error, or if there is not enough - * storage in the stream. All writes block until at least one byte - * is written or an error occurs; 0 is never returned (unless - * the size of @bytes is 0). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. + * However, note that this function may still perform partial writes, + * just like g_output_stream_write(). If that occurs, to continue + * writing, you will need to create a new #GBytes containing just the + * remaining bytes, using g_bytes_new_from_bytes(). Passing the same + * #GBytes instance multiple times potentially can result in duplicated + * data in the output stream. * * Returns: Number of bytes written, or -1 on error */ @@ -24685,29 +27626,16 @@ * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * - * Request an asynchronous write of the data in @bytes to the stream. - * When the operation is finished @callback will be called. You can - * then call g_output_stream_write_bytes_finish() to get the result of - * the operation. - * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * - * A #GBytes larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written will be passed to the - * @callback. It is not an error if this is not the same as the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the - * method will just wait until this changes. + * This function is similar to g_output_stream_write_async(), but + * takes a #GBytes as input. Due to the refcounted nature of #GBytes, + * this allows the stream to avoid taking a copy of the data. * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. + * However, note that this function may still perform partial writes, + * just like g_output_stream_write_async(). If that occurs, to continue + * writing, you will need to create a new #GBytes containing just the + * remaining bytes, using g_bytes_new_from_bytes(). Passing the same + * #GBytes instance multiple times potentially can result in duplicated + * data in the output stream. * * For the synchronous, blocking version of this function, see * g_output_stream_write_bytes(). @@ -24718,7 +27646,8 @@ * g_output_stream_write_bytes_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream write-from-#GBytes operation. * @@ -24730,7 +27659,8 @@ * g_output_stream_write_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream write operation. * @@ -24973,15 +27903,19 @@ * g_pollable_input_stream_read_nonblocking(), which will return a * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. * - * Returns: %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. + * Returns: %TRUE if @stream is readable, %FALSE if not. If an error + * has occurred on @stream, this will result in + * g_pollable_input_stream_is_readable() returning %TRUE, and the + * next attempt to read will return the error. * Since: 2.28 */ /** - * g_pollable_input_stream_read_nonblocking: + * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking) * @stream: a #GPollableInputStream - * @buffer: a buffer to read data into (which should be at least @count bytes long). + * @buffer: a buffer to read data into (which should be at least @count + * bytes long). * @count: the number of bytes you want to read * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -24998,8 +27932,8 @@ * may happen if you call this method after a source triggers due * to having been cancelled. * - * Virtual: read_nonblocking - * Returns: the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). + * Returns: the number of bytes read, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ @@ -25052,15 +27986,19 @@ * g_pollable_output_stream_write_nonblocking(), which will return a * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. * - * Returns: %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. + * Returns: %TRUE if @stream is writable, %FALSE if not. If an error + * has occurred on @stream, this will result in + * g_pollable_output_stream_is_writable() returning %TRUE, and the + * next attempt to write will return the error. * Since: 2.28 */ /** - * g_pollable_output_stream_write_nonblocking: + * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking) * @stream: a #GPollableOutputStream - * @buffer: (array length=count) (element-type guint8): a buffer to write data from + * @buffer: (array length=count) (element-type guint8): a buffer to write + * data from * @count: the number of bytes you want to write * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -25077,8 +28015,8 @@ * may happen if you call this method after a source triggers due * to having been cancelled. * - * Virtual: write_nonblocking - * Returns: the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). + * Returns: the number of bytes written, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ @@ -25099,7 +28037,8 @@ /** * g_pollable_source_new_full: - * @pollable_stream: (type GObject): the stream associated with the new source + * @pollable_stream: (type GObject): the stream associated with the + * new source * @child_source: (allow-none): optional child source to attach * @cancellable: (allow-none): optional #GCancellable to attach * @@ -25140,7 +28079,8 @@ /** * g_pollable_stream_write: * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @buffer: (array length=count) (element-type guint8): the buffer + * containing the data to write. * @count: the number of bytes to write * @blocking: whether to do blocking I/O * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -25165,10 +28105,12 @@ /** * g_pollable_stream_write_all: * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @buffer: (array length=count) (element-type guint8): the buffer + * containing the data to write. * @count: the number of bytes to write * @blocking: whether to do blocking I/O - * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -25197,6 +28139,26 @@ /** + * g_property_action_new: + * @name: the name of the action to create + * @object: the object that has the property to wrap + * @property_name: the name of the property + * + * Creates a #GAction corresponding to the value of property + * @property_name on @object. + * + * The property must be existent and readable and writable (and not + * construct-only). + * + * This function takes a reference on @object and doesn't release it + * until the action is destroyed. + * + * Returns: a new #GPropertyAction + * Since: 2.38 + */ + + +/** * g_proxy_address_get_destination_hostname: * @proxy: a #GProxyAddress * @@ -25285,8 +28247,10 @@ * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). * @dest_hostname: The destination hostname the proxy should tunnel to. * @dest_port: The destination port to tunnel to. - * @username: (allow-none): The username to authenticate to the proxy server (or %NULL). - * @password: (allow-none): The password to authenticate to the proxy server (or %NULL). + * @username: (allow-none): The username to authenticate to the proxy server + * (or %NULL). + * @password: (allow-none): The password to authenticate to the proxy server + * (or %NULL). * * Creates a new #GProxyAddress for @inetaddr with @protocol that should * tunnel through @dest_hostname and @dest_port. @@ -25313,7 +28277,9 @@ * does the necessary handshake to connect to @proxy_address, and if * required, wraps the #GIOStream to handle proxy payload. * - * Returns: (transfer full): a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. + * Returns: (transfer full): a #GIOStream that will replace @connection. This might + * be the same as @connection, in which case a reference + * will be added. * Since: 2.26 */ @@ -25353,7 +28319,8 @@ * Lookup "gio-proxy" extension point for a proxy implementation that supports * specified protocol. * - * Returns: (transfer full): return a #GProxy or NULL if protocol is not supported. + * Returns: (transfer full): return a #GProxy or NULL if protocol + * is not supported. * Since: 2.26 */ @@ -25389,22 +28356,24 @@ * @error: return location for a #GError, or %NULL * * Looks into the system proxy configuration to determine what proxy, - * if any, to use to connect to @uri. The returned proxy URIs are of the - * form <literal><protocol>://[user[:password]@]host:port</literal> - * or <literal>direct://</literal>, where <protocol> could be - * http, rtsp, socks or other proxying protocol. + * if any, to use to connect to @uri. The returned proxy URIs are of + * the form `<protocol>://[user[:password]@]host:port` or + * `direct://`, where <protocol> could be http, rtsp, socks + * or other proxying protocol. * * If you don't know what network protocol is being used on the - * socket, you should use <literal>none</literal> as the URI protocol. + * socket, you should use `none` as the URI protocol. * In this case, the resolver might still return a generic proxy type * (such as SOCKS), but would not return protocol-specific proxy types * (such as http). * - * <literal>direct://</literal> is used when no proxy is needed. + * `direct://` is used when no proxy is needed. * Direct connection should not be attempted unless it is part of the * returned array of proxies. * - * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ @@ -25434,7 +28403,9 @@ * g_proxy_resolver_lookup_async() is complete. See * g_proxy_resolver_lookup() for more details. * - * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ @@ -25563,7 +28534,8 @@ * operation, in which case @error (if non-%NULL) will be set to * %G_IO_ERROR_CANCELLED. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. * Since: 2.22 */ @@ -25597,7 +28569,8 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. * Since: 2.22 */ @@ -25633,7 +28606,10 @@ * address, it may be easier to create a #GNetworkAddress and use its * #GSocketConnectable interface. * - * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) + * Returns: (element-type GInetAddress) (transfer full): a #GList + * of #GInetAddress, or %NULL on error. You + * must unref each of the addresses and free the list when you are + * done with it. (You can use g_resolver_free_addresses() to do this.) * Since: 2.22 */ @@ -25668,7 +28644,9 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. + * Returns: (element-type GInetAddress) (transfer full): a #GList + * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() + * for more details. * Since: 2.22 */ @@ -25692,7 +28670,9 @@ * operation, in which case @error (if non-%NULL) will be set to * %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) + * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, + * or %NULL on error. You must free each of the records and the list when you are + * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) * Since: 2.34 */ @@ -25729,7 +28709,9 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) + * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, + * or %NULL on error. You must free each of the records and the list when you are + * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) * Since: 2.34 */ @@ -25746,9 +28728,8 @@ * Synchronously performs a DNS SRV lookup for the given @service and * @protocol in the given @domain and returns an array of #GSrvTarget. * @domain may be an ASCII-only or UTF-8 hostname. Note also that the - * @service and @protocol arguments <emphasis>do not</emphasis> - * include the leading underscore that appears in the actual DNS - * entry. + * @service and @protocol arguments do not include the leading underscore + * that appears in the actual DNS entry. * * On success, g_resolver_lookup_service() will return a #GList of * #GSrvTarget, sorted in order of preference. (That is, you should @@ -25766,7 +28747,9 @@ * to create a #GNetworkService and use its #GSocketConnectable * interface. * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.) + * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, + * or %NULL on error. You must free each of the targets and the list when you are + * done with it. (You can use g_resolver_free_targets() to do this.) * Since: 2.22 */ @@ -25804,7 +28787,8 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. + * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, + * or %NULL on error. See g_resolver_lookup_service() for more details. * Since: 2.22 */ @@ -25860,8 +28844,10 @@ * @resource: A #GResource * @path: A pathname inside the resource * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed + * @size: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (allow-none): a location to place the flags about the file, + * or %NULL if the length is not needed * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the resource and @@ -25912,7 +28898,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref() + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() * Since: 2.32 */ @@ -25946,7 +28933,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref() + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() * Since: 2.32 */ @@ -25998,8 +28986,10 @@ * g_resources_get_info: * @path: A pathname inside the resource * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed + * @size: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (allow-none): a location to place the flags about the file, + * or %NULL if the length is not needed * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the set of @@ -26033,7 +29023,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref() + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() * Since: 2.32 */ @@ -26050,7 +29041,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref() + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() * Since: 2.32 */ @@ -26103,15 +29095,27 @@ * @offset: a #goffset. * @type: a #GSeekType. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Seeks in the stream by the given @offset, modified by @type. * + * Attempting to seek past the end of the stream will have different + * results depending on if the stream is fixed-sized or resizable. If + * the stream is resizable then seeking past the end and then writing + * will result in zeros filling the empty space. Seeking past the end + * of a resizable stream and reading will result in EOF. Seeking past + * the end of a fixed-sized stream will fail. + * + * Any operation that would result in a negative offset will fail. + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ @@ -26126,11 +29130,12 @@ /** - * g_seekable_truncate: + * g_seekable_truncate: (virtual truncate_fn) * @seekable: a #GSeekable. * @offset: a #goffset. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Truncates a stream with a given #offset. * @@ -26140,8 +29145,9 @@ * operation was partially finished when the operation was cancelled the * partial result will be returned, without an error. * - * Virtual: truncate_fn - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ @@ -26207,8 +29213,10 @@ * g_settings_backend_flatten_tree: * @tree: a #GTree containing the changes * @path: (out): the location to save the path - * @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys - * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL + * @keys: (out) (transfer container) (array zero-terminated=1): the + * location to save the relative keys + * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): + * the location to save the values, or %NULL * * Calculate the longest common prefix of all keys in a tree and write * out an array of the key names relative to that prefix and, @@ -26226,8 +29234,8 @@ * g_settings_backend_get_default: * * Returns the default #GSettingsBackend. It is possible to override - * the default by setting the <envar>GSETTINGS_BACKEND</envar> - * environment variable to the name of a settings backend. + * the default by setting the `GSETTINGS_BACKEND` environment variable + * to the name of a settings backend. * * The user gets a reference to the backend. * @@ -26370,8 +29378,10 @@ * @object: (type GObject.Object): a #GObject * @property: the name of the property to bind * @flags: flags for the binding - * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping - * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping + * @get_mapping: a function that gets called to convert values + * from @settings to @object, or %NULL to use the default GIO mapping + * @set_mapping: a function that gets called to convert values + * from @object to @settings, or %NULL to use the default GIO mapping * @user_data: data that gets passed to @get_mapping and @set_mapping * @destroy: #GDestroyNotify function for @user_data * @@ -26409,8 +29419,7 @@ * * When the @inverted argument is %TRUE, the binding inverts the * value as it passes from the setting to the object, i.e. @property - * will be set to %TRUE if the key is <emphasis>not</emphasis> - * writable. + * will be set to %TRUE if the key is not writable. * * Note that the lifecycle of the binding is tied to the object, * and that you can have only one binding per object property. @@ -26498,14 +29507,14 @@ /** * g_settings_get_child: * @settings: a #GSettings object - * @name: the name of the 'child' schema + * @name: the name of the child schema * - * Creates a 'child' settings object which has a base path of - * <replaceable>base-path</replaceable>/@name, where - * <replaceable>base-path</replaceable> is the base path of @settings. + * Creates a child settings object which has a base path of + * `base-path/@name`, where `base-path` is the base path of + * @settings. * * The schema for the child settings object must have been declared - * in the schema of @settings using a <tag class="starttag">child</tag> element. + * in the schema of @settings using a <child> element. * * Returns: (transfer full): a 'child' settings object * Since: 2.26 @@ -26513,6 +29522,38 @@ /** + * g_settings_get_default_value: + * @settings: a #GSettings object + * @key: the key to get the default value for + * + * Gets the "default value" of a key. + * + * This is the value that would be read if g_settings_reset() were to be + * called on the key. + * + * Note that this may be a different value than returned by + * g_settings_schema_key_get_default_value() if the system administrator + * has provided a default value. + * + * Comparing the return values of g_settings_get_default_value() and + * g_settings_get_value() is not sufficient for determining if a value + * has been set because the user may have explicitly set the value to + * something that happens to be equal to the default. The difference + * here is that if the default changes in the future, the user's key + * will still be set. + * + * This function may be useful for adding an indication to a UI of what + * the default value was before the user set it. + * + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. + * + * Returns: (allow-none) (transfer full): the default value + * Since: 2.40 + */ + + +/** * g_settings_get_double: * @settings: a #GSettings object * @key: the key to get the value for @@ -26608,7 +29649,8 @@ * g_settings_get_mapped: * @settings: a #GSettings object * @key: the key to get the value for - * @mapping: (scope call): the function to map the value in the settings database to the value used by the application + * @mapping: (scope call): the function to map the value in the + * settings database to the value used by the application * @user_data: user data for @mapping * * Gets the value that is stored at @key in @settings, subject to @@ -26650,49 +29692,8 @@ * * Queries the range of a key. * - * This function will return a #GVariant that fully describes the range - * of values that are valid for @key. - * - * The type of #GVariant returned is <literal>(sv)</literal>. The - * string describes the type of range restriction in effect. The type - * and meaning of the value contained in the variant depends on the - * string. - * - * If the string is <literal>'type'</literal> then the variant contains - * an empty array. The element type of that empty array is the expected - * type of value and all values of that type are valid. - * - * If the string is <literal>'enum'</literal> then the variant contains - * an array enumerating the possible values. Each item in the array is - * a possible valid value and no other values are valid. - * - * If the string is <literal>'flags'</literal> then the variant contains - * an array. Each item in the array is a value that may appear zero or - * one times in an array to be used as the value for this key. For - * example, if the variant contained the array <literal>['x', - * 'y']</literal> then the valid values for the key would be - * <literal>[]</literal>, <literal>['x']</literal>, - * <literal>['y']</literal>, <literal>['x', 'y']</literal> and - * <literal>['y', 'x']</literal>. - * - * Finally, if the string is <literal>'range'</literal> then the variant - * contains a pair of like-typed values -- the minimum and maximum - * permissible values for this key. - * - * This information should not be used by normal programs. It is - * considered to be a hint for introspection purposes. Normal programs - * should already know what is permitted by their own schema. The - * format may change in any way in the future -- but particularly, new - * forms may be added to the possibilities described above. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * - * You should free the returned value with g_variant_unref() when it is - * no longer needed. - * - * Returns: a #GVariant describing the range * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead. */ @@ -26723,7 +29724,9 @@ * It is a programmer error to give a @key that isn't specified as * having an array of strings type in the schema for @settings. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. + * Returns: (array zero-terminated=1) (transfer full): a + * newly-allocated, %NULL-terminated array of strings, the value that + * is stored at @key in @settings. * Since: 2.26 */ @@ -26747,6 +29750,35 @@ /** + * g_settings_get_user_value: + * @settings: a #GSettings object + * @key: the key to get the user value for + * + * Checks the "user value" of a key, if there is one. + * + * The user value of a key is the last value that was set by the user. + * + * After calling g_settings_reset() this function should always return + * %NULL (assuming something is not wrong with the system + * configuration). + * + * It is possible that g_settings_get_value() will return a different + * value than this function. This can happen in the case that the user + * set a value for a key that was subsequently locked down by the system + * administrator -- this function will return the user's old value. + * + * This function may be useful for adding a "reset" option to a UI or + * for providing indication that a particular value has been changed. + * + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. + * + * Returns: (allow-none) (transfer full): the user's value, if set + * Since: 2.40 + */ + + +/** * g_settings_get_value: * @settings: a #GSettings object * @key: the key to get the value for @@ -26821,34 +29853,25 @@ /** * g_settings_list_relocatable_schemas: * - * Gets a list of the relocatable #GSettings schemas installed on the - * system. These are schemas that do not provide their own path. It is - * usual to instantiate these schemas directly, but if you want to you - * can use g_settings_new_with_path() to specify the path. - * - * The output of this function, taken together with the output of - * g_settings_list_schemas() represents the complete list of all - * installed schemas. - * - * Returns: (element-type utf8) (transfer none): a list of relocatable #GSettings schemas that are available. The list must not be modified or freed. + * Returns: (element-type utf8) (transfer none): a list of relocatable + * #GSettings schemas that are available. The list must not be + * modified or freed. * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead */ /** * g_settings_list_schemas: * - * Gets a list of the #GSettings schemas installed on the system. The - * returned list is exactly the list of schemas for which you may call - * g_settings_new() without adverse effects. - * - * This function does not list the schemas that do not provide their own - * paths (ie: schemas for which you must use - * g_settings_new_with_path()). See - * g_settings_list_relocatable_schemas() for that. - * - * Returns: (element-type utf8) (transfer none): a list of #GSettings schemas that are available. The list must not be modified or freed. + * Returns: (element-type utf8) (transfer none): a list of #GSettings + * schemas that are available. The list must not be modified or + * freed. * Since: 2.26 + * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead. + * If you used g_settings_list_schemas() to check for the presence of + * a particular schema, use g_settings_schema_source_lookup() instead + * of your whole loop. */ @@ -26955,6 +29978,10 @@ * It is a programmer error to call this function for a schema that * has an explicitly specified path. * + * It is a programmer error if @path is not a valid path. A valid path + * begins and ends with '/' and does not contain two consecutive '/' + * characters. + * * Returns: a new #GSettings object * Since: 2.26 */ @@ -26969,15 +29996,9 @@ * Checks if the given @value is of the correct type and within the * permitted range for @key. * - * This API is not intended to be used by normal programs -- they should - * already know what is permitted by their own schemas. This API is - * meant to be used by programs such as editors or commandline tools. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * * Returns: %TRUE if @value is valid for @key * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead. */ @@ -27018,6 +30039,21 @@ /** + * g_settings_schema_get_key: + * @schema: a #GSettingsSchema + * @name: the name of a key + * + * Gets the key named @name from @schema. + * + * It is a programmer error to request a key that does not exist. See + * g_settings_schema_list_keys(). + * + * Returns: (transfer full): the #GSettingsSchemaKey for @name + * Since: 2.40 + */ + + +/** * g_settings_schema_get_path: * @schema: a #GSettingsSchema * @@ -27037,6 +30073,173 @@ /** + * g_settings_schema_has_key: + * @schema: a #GSettingsSchema + * @name: the name of a key + * + * Checks if @schema has a key named @name. + * + * Returns: %TRUE if such a key exists + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_get_default_value: + * @key: a #GSettingsSchemaKey + * + * Gets the default value for @key. + * + * Note that this is the default value according to the schema. System + * administrator defaults and lockdown are not visible via this API. + * + * Returns: (transfer full): the default value for the key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_get_description: + * @key: a #GSettingsSchemaKey + * + * Gets the description for @key. + * + * If no description has been provided in the schema for @key, returns + * %NULL. + * + * The description can be one sentence to several paragraphs in length. + * Paragraphs are delimited with a double newline. Descriptions can be + * translated and the value returned from this function is is the + * current locale. + * + * This function is slow. The summary and description information for + * the schemas is not stored in the compiled schema database so this + * function has to parse all of the source XML files in the schema + * directory. + * + * Returns: the description for @key, or %NULL + * Since: 2.34 + */ + + +/** + * g_settings_schema_key_get_range: + * @key: a #GSettingsSchemaKey + * + * Queries the range of a key. + * + * This function will return a #GVariant that fully describes the range + * of values that are valid for @key. + * + * The type of #GVariant returned is `(sv)`. The string describes + * the type of range restriction in effect. The type and meaning of + * the value contained in the variant depends on the string. + * + * If the string is `'type'` then the variant contains an empty array. + * The element type of that empty array is the expected type of value + * and all values of that type are valid. + * + * If the string is `'enum'` then the variant contains an array + * enumerating the possible values. Each item in the array is + * a possible valid value and no other values are valid. + * + * If the string is `'flags'` then the variant contains an array. Each + * item in the array is a value that may appear zero or one times in an + * array to be used as the value for this key. For example, if the + * variant contained the array `['x', 'y']` then the valid values for + * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and + * `['y', 'x']`. + * + * Finally, if the string is `'range'` then the variant contains a pair + * of like-typed values -- the minimum and maximum permissible values + * for this key. + * + * This information should not be used by normal programs. It is + * considered to be a hint for introspection purposes. Normal programs + * should already know what is permitted by their own schema. The + * format may change in any way in the future -- but particularly, new + * forms may be added to the possibilities described above. + * + * You should free the returned value with g_variant_unref() when it is + * no longer needed. + * + * Returns: (transfer full): a #GVariant describing the range + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_get_summary: + * @key: a #GSettingsSchemaKey + * + * Gets the summary for @key. + * + * If no summary has been provided in the schema for @key, returns + * %NULL. + * + * The summary is a short description of the purpose of the key; usually + * one short sentence. Summaries can be translated and the value + * returned from this function is is the current locale. + * + * This function is slow. The summary and description information for + * the schemas is not stored in the compiled schema database so this + * function has to parse all of the source XML files in the schema + * directory. + * + * Returns: the summary for @key, or %NULL + * Since: 2.34 + */ + + +/** + * g_settings_schema_key_get_value_type: + * @key: a #GSettingsSchemaKey + * + * Gets the #GVariantType of @key. + * + * Returns: (transfer none): the type of @key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_range_check: + * @key: a #GSettingsSchemaKey + * @value: the value to check + * + * Checks if the given @value is of the correct type and within the + * permitted range for @key. + * + * It is a programmer error if @value is not of the correct type -- you + * must check for this first. + * + * Returns: %TRUE if @value is valid for @key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_ref: + * @key: a #GSettingsSchemaKey + * + * Increase the reference count of @key, returning a new reference. + * + * Returns: a new reference to @key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_unref: + * @key: a #GSettingsSchemaKey + * + * Decrease the reference count of @key, possibly freeing it. + * + * Since: 2.40 + */ + + +/** * g_settings_schema_ref: * @schema: a #GSettingsSchema * @@ -27060,9 +30263,8 @@ * * The returned source may actually consist of multiple schema sources * from different directories, depending on which directories were given - * in <envar>XDG_DATA_DIRS</envar> and - * <envar>GSETTINGS_SCHEMA_DIR</envar>. For this reason, all lookups - * performed against the default source should probably be done + * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all + * lookups performed against the default source should probably be done * recursively. * * Returns: (transfer none): the default schema source @@ -27071,6 +30273,31 @@ /** + * g_settings_schema_source_list_schemas: + * @source: a #GSettingsSchemaSource + * @recursive: if we should recurse + * @non_relocatable: (out) (transfer full): the list of non-relocatable + * schemas + * @relocatable: (out) (transfer full): the list of relocatable schemas + * + * Lists the schemas in a given source. + * + * If @recursive is %TRUE then include parent sources. If %FALSE then + * only include the schemas from one source (ie: one directory). You + * probably want %TRUE. + * + * Non-relocatable schemas are those for which you can call + * g_settings_new(). Relocatable schemas are those for which you must + * use g_settings_new_with_path(). + * + * Do not call this function from normal programs. This is designed for + * use by database editors, commandline tools, etc. + * + * Since: 2.40 + */ + + +/** * g_settings_schema_source_lookup: * @source: a #GSettingsSchemaSource * @schema_id: a schema ID @@ -27105,16 +30332,14 @@ * This function is not required for normal uses of #GSettings but it * may be useful to authors of plugin management systems. * - * The directory should contain a file called - * <filename>gschemas.compiled</filename> as produced by - * <command>glib-compile-schemas</command>. + * The directory should contain a file called `gschemas.compiled` as + * produced by the [glib-compile-schemas][glib-compile-schemas] tool. * - * If @trusted is %TRUE then <filename>gschemas.compiled</filename> is - * trusted not to be corrupted. This assumption has a performance - * advantage, but can result in crashes or inconsistent behaviour in the - * case of a corrupted file. Generally, you should set @trusted to - * %TRUE for files installed by the system and to %FALSE for files in - * the home directory. + * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be + * corrupted. This assumption has a performance advantage, but can result + * in crashes or inconsistent behaviour in the case of a corrupted file. + * Generally, you should set @trusted to %TRUE for files installed by the + * system and to %FALSE for files in the home directory. * * If @parent is non-%NULL then there are two effects. * @@ -27123,8 +30348,8 @@ * source, the lookup will recurse to the parent. * * Second, any references to other schemas specified within this - * source (ie: <literal>child</literal> or <literal>extends</literal>) - * references may be resolved from the @parent. + * source (ie: `child` or `extends`) references may be resolved + * from the @parent. * * For this second reason, except in very unusual situations, the * @parent should probably be given as the default schema source, as @@ -27181,7 +30406,8 @@ * schema for @settings or for the #GVariantType of @format to mismatch * the type given in the schema. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27199,7 +30425,8 @@ * It is a programmer error to give a @key that isn't specified as * having a boolean type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27217,7 +30444,8 @@ * It is a programmer error to give a @key that isn't specified as * having a 'double' type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27278,7 +30506,8 @@ * It is a programmer error to give a @key that isn't specified as * having a int32 type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27296,7 +30525,8 @@ * It is a programmer error to give a @key that isn't specified as * having a string type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27315,7 +30545,8 @@ * It is a programmer error to give a @key that isn't specified as * having an array of strings type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27334,7 +30565,8 @@ * It is a programmer error to give a @key that isn't specified as * having a uint32 type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.30 */ @@ -27353,7 +30585,8 @@ * * If @value is floating then this function consumes the reference. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27393,7 +30626,8 @@ /** * g_simple_action_group_add_entries: * @simple: a #GSimpleActionGroup - * @entries: (array length=n_entries): a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries): a pointer to the first item in + * an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 * @user_data: the user data for signal connections * @@ -27401,6 +30635,7 @@ * and adding them to the action group. * * Since: 2.30 + * Deprecated: 2.38: Use g_action_map_add_action_entries() */ @@ -27417,6 +30652,7 @@ * The action group takes its own reference on @action. * * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_add_action() */ @@ -27431,6 +30667,7 @@ * * Returns: (transfer none): a #GAction, or %NULL * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_lookup_action() */ @@ -27454,6 +30691,7 @@ * If no action of this name is in the group then nothing happens. * * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_remove_action() */ @@ -27520,6 +30758,8 @@ * property. Instead, they should call g_action_change_state() to * request the change. * + * If the @value GVariant is floating, it is consumed. + * * Since: 2.30 */ @@ -27586,9 +30826,9 @@ * g_simple_async_result_complete_in_idle: * @simple: a #GSimpleAsyncResult. * - * Completes an asynchronous function in an idle handler in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread that @simple was initially created in + * Completes an asynchronous function in an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @simple was initially created in * (and re-pushes that context around the invocation of the callback). * * Calling this function takes a reference to @simple for as long as @@ -27602,7 +30842,8 @@ * * Gets the operation result boolean from within the asynchronous result. * - * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE. + * Returns: %TRUE if the operation's result was %TRUE, %FALSE + * if the operation's result was %FALSE. */ @@ -27639,8 +30880,8 @@ /** * g_simple_async_result_is_valid: * @result: the #GAsyncResult passed to the _finish function. - * @source: the #GObject passed to the _finish function. - * @source_tag: the asynchronous function. + * @source: (allow-none): the #GObject passed to the _finish function. + * @source_tag: (allow-none): the asynchronous function. * * Ensures that the data passed to the _finish function of an async * operation is consistent. Three checks are performed. @@ -27648,12 +30889,12 @@ * First, @result is checked to ensure that it is really a * #GSimpleAsyncResult. Second, @source is checked to ensure that it * matches the source object of @result. Third, @source_tag is - * checked to ensure that it is either %NULL (as it is when the result was - * created by g_simple_async_report_error_in_idle() or - * g_simple_async_report_gerror_in_idle()) or equal to the - * @source_tag argument given to g_simple_async_result_new() (which, by - * convention, is a pointer to the _async function corresponding to the - * _finish function from which this function is called). + * checked to ensure that it is equal to the @source_tag argument given + * to g_simple_async_result_new() (which, by convention, is a pointer + * to the _async function corresponding to the _finish function from + * which this function is called). (Alternatively, if either + * @source_tag or @result's source tag is %NULL, then the source tag + * check is skipped.) * * Returns: #TRUE if all checks passed or #FALSE if any failed. * Since: 2.20 @@ -27884,6 +31125,74 @@ /** + * g_simple_proxy_resolver_new: + * @default_proxy: (allow-none): the default proxy to use, eg + * "socks://192.168.1.1" + * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses + * to not use a proxy for. + * + * Creates a new #GSimpleProxyResolver. See + * #GSimpleProxyResolver:default-proxy and + * #GSimpleProxyResolver:ignore-hosts for more details on how the + * arguments are interpreted. + * + * Returns: (transfer full): a new #GSimpleProxyResolver + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_default_proxy: + * @resolver: a #GSimpleProxyResolver + * @default_proxy: the default proxy to use + * + * Sets the default proxy on @resolver, to be used for any URIs that + * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set + * via g_simple_proxy_resolver_set_uri_proxy(). + * + * If @default_proxy starts with "socks://", + * #GSimpleProxyResolver will treat it as referring to all three of + * the socks5, socks4a, and socks4 proxy types. + * + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_ignore_hosts: + * @resolver: a #GSimpleProxyResolver + * @ignore_hosts: %NULL-terminated list of hosts/IP addresses + * to not use a proxy for + * + * Sets the list of ignored hosts. + * + * See #GSimpleProxyResolver:ignore-hosts for more details on how the + * @ignore_hosts argument is interpreted. + * + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_uri_proxy: + * @resolver: a #GSimpleProxyResolver + * @uri_scheme: the URI scheme to add a proxy for + * @proxy: the proxy to use for @uri_scheme + * + * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme + * matches @uri_scheme (and which don't match + * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy. + * + * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with + * "socks://", #GSimpleProxyResolver will treat it + * as referring to all three of the socks5, socks4a, and socks4 proxy + * types. + * + * Since: 2.36 + */ + + +/** * g_socket_accept: * @socket: a #GSocket. * @cancellable: (allow-none): a %GCancellable or %NULL @@ -27900,7 +31209,8 @@ * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. * To be notified of an incoming connection, wait for the %G_IO_IN condition. * - * Returns: (transfer full): a new #GSocket, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GSocket, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -27925,7 +31235,9 @@ * internal errors (other than @cancellable being triggered) will be * ignored. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses. + * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * error (in which case *@error will be set) or if there are no + * more addresses. */ @@ -27933,7 +31245,8 @@ * g_socket_address_enumerator_next_async: * @enumerator: a #GSocketAddressEnumerator * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the request + * is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously retrieves the next #GSocketAddress from @enumerator @@ -27953,7 +31266,9 @@ * g_socket_address_enumerator_next() for more information about * error handling. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses. + * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * error (in which case *@error will be set) or if there are no + * more addresses. */ @@ -27963,7 +31278,7 @@ * * Gets the socket family type of @address. * - * Returns: the socket family type of @address. + * Returns: the socket family type of @address * Since: 2.22 */ @@ -27972,24 +31287,26 @@ * g_socket_address_get_native_size: * @address: a #GSocketAddress * - * Gets the size of @address's native <type>struct sockaddr</type>. + * Gets the size of @address's native struct sockaddr. * You can use this to allocate memory to pass to * g_socket_address_to_native(). * - * Returns: the size of the native <type>struct sockaddr</type> that @address represents + * Returns: the size of the native struct sockaddr that + * @address represents * Since: 2.22 */ /** * g_socket_address_new_from_native: - * @native: a pointer to a <type>struct sockaddr</type> + * @native: a pointer to a struct sockaddr * @len: the size of the memory location pointed to by @native * * Creates a #GSocketAddress subclass corresponding to the native - * <type>struct sockaddr</type> @native. + * struct sockaddr @native. * - * Returns: a new #GSocketAddress if @native could successfully be converted, otherwise %NULL. + * Returns: a new #GSocketAddress if @native could successfully + * be converted, otherwise %NULL * Since: 2.22 */ @@ -27997,16 +31314,17 @@ /** * g_socket_address_to_native: * @address: a #GSocketAddress - * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>. - * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size(). - * @error: #GError for error reporting, or %NULL to ignore. + * @dest: a pointer to a memory location that will contain the native + * struct sockaddr + * @destlen: the size of @dest. Must be at least as large as + * g_socket_address_get_native_size() + * @error: #GError for error reporting, or %NULL to ignore * - * Converts a #GSocketAddress to a native <type>struct - * sockaddr</type>, which can be passed to low-level functions like - * connect() or bind(). + * Converts a #GSocketAddress to a native struct sockaddr, which can + * be passed to low-level functions like connect() or bind(). * - * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is - * returned. If the address type is not known on the system + * If not enough space is available, a %G_IO_ERROR_NO_SPACE error + * is returned. If the address type is not known on the system * then a %G_IO_ERROR_NOT_SUPPORTED error is returned. * * Returns: %TRUE if @dest was filled in, %FALSE on error @@ -28030,14 +31348,20 @@ * In certain situations, you may also want to bind a socket that will be * used to initiate connections, though this is not normally required. * - * @allow_reuse should be %TRUE for server sockets (sockets that you will - * eventually call g_socket_accept() on), and %FALSE for client sockets. - * (Specifically, if it is %TRUE, then g_socket_bind() will set the - * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if - * that address was previously used by another socket that has not yet been - * fully cleaned-up by the kernel. Failing to set this flag on a server - * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if - * the server program is stopped and then immediately restarted.) + * If @socket is a TCP socket, then @allow_reuse controls the setting + * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for + * server sockets (sockets that you will eventually call + * g_socket_accept() on), and %FALSE for client sockets. (Failing to + * set this flag on a server socket may cause g_socket_bind() to return + * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then + * immediately restarted.) + * + * If @socket is a UDP socket, then @allow_reuse determines whether or + * not other UDP sockets can be bound to the same address at the same + * time. In particular, you can have several UDP sockets bound to the + * same address, and they will all receive all of the multicast and + * broadcast packets sent to that address. (The behavior of unicast + * UDP packets to an address with multiple listeners is not defined.) * * Returns: %TRUE on success, %FALSE on error. * Since: 2.22 @@ -28138,7 +31462,8 @@ * g_socket_client_connect_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_async() * @@ -28214,7 +31539,8 @@ * g_socket_client_connect_to_host_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_host_async() * @@ -28270,7 +31596,8 @@ * g_socket_client_connect_to_service_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_service_async() * @@ -28337,7 +31664,8 @@ * g_socket_client_connect_to_uri_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() * @@ -28397,6 +31725,20 @@ /** + * g_socket_client_get_proxy_resolver: + * @client: a #GSocketClient. + * + * Gets the #GProxyResolver being used by @client. Normally, this will + * be the resolver returned by g_proxy_resolver_get_default(), but you + * can override it with g_socket_client_set_proxy_resolver(). + * + * Returns: (transfer none): The #GProxyResolver being used by + * @client. + * Since: 2.36 + */ + + +/** * g_socket_client_get_socket_type: * @client: a #GSocketClient. * @@ -28451,7 +31793,8 @@ * * Creates a new #GSocketClient with the default options. * - * Returns: a #GSocketClient. Free the returned object with g_object_unref(). + * Returns: a #GSocketClient. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -28466,6 +31809,8 @@ * #GProxyResolver to determine if a proxy protocol such as SOCKS is * needed, and automatically do the necessary proxy negotiation. * + * See also g_socket_client_set_proxy_resolver(). + * * Since: 2.26 */ @@ -28522,6 +31867,24 @@ /** + * g_socket_client_set_proxy_resolver: + * @client: a #GSocketClient. + * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the + * default. + * + * Overrides the #GProxyResolver used by @client. You can call this if + * you want to use specific proxies, rather than using the system + * default proxy settings. + * + * Note that whether or not the proxy resolver is actually used + * depends on the setting of #GSocketClient:enable-proxy, which is not + * changed by this function (but which is %TRUE by default) + * + * Since: 2.36 + */ + + +/** * g_socket_client_set_socket_type: * @client: a #GSocketClient. * @type: a #GSocketType @@ -28759,7 +32122,7 @@ * @connectable: a #GSocketConnectable * * Creates a #GSocketAddressEnumerator for @connectable that will - * return #GProxyAddress<!-- -->es for addresses that you must connect + * return #GProxyAddresses for addresses that you must connect * to via a proxy. * * If @connectable does not implement @@ -28868,7 +32231,8 @@ * * Try to get the local address of a socket connection. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -28880,7 +32244,15 @@ * * Try to get the remote address of a socket connection. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Since GLib 2.40, when used with g_socket_client_connect() or + * g_socket_client_connect_async(), during emission of + * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote + * address that will be used for the connection. This allows + * applications to print e.g. "Connecting to example.com + * (10.42.77.3)...". + * + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29019,7 +32391,19 @@ * * Get the amount of data pending in the OS input buffer. * - * Returns: the number of bytes that can be read from the socket without blocking or -1 on error. + * If @socket is a UDP or SCTP socket, this will return the size of + * just the next packet, even if additional packets are buffered after + * that one. + * + * Note that on Windows, this function is rather inefficient in the + * UDP case, and so if you know any plausible upper bound on the size + * of the incoming packet, it is better to just do a + * g_socket_receive() with a buffer of that size, rather than calling + * g_socket_get_available_bytes() first and then doing a receive of + * exactly the right size. + * + * Returns: the number of bytes that can be read from the socket + * without blocking or truncating, or -1 on error. * Since: 2.32 */ @@ -29042,7 +32426,7 @@ * * Gets the broadcast setting on @socket; if %TRUE, * it is possible to send packets to broadcast - * addresses or receive from broadcast addresses. + * addresses. * * Returns: the broadcast setting on @socket * Since: 2.32 @@ -29067,7 +32451,8 @@ * g_unix_connection_send_credentials() / * g_unix_connection_receive_credentials() functions. * - * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref(). + * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object + * that must be freed with g_object_unref(). * Since: 2.26 */ @@ -29131,7 +32516,8 @@ * useful if the socket has been bound to a local address, * either explicitly or implicitly when connecting. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29162,6 +32548,35 @@ /** + * g_socket_get_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, `SOL_SOCKET`) + * @optname: the "name" of the option (eg, `SO_BROADCAST`) + * @value: (out): return location for the option value + * @error: #GError for error reporting, or %NULL to ignore. + * + * Gets the value of an integer-valued option on @socket, as with + * getsockopt(). (If you need to fetch a non-integer-valued option, + * you will need to call getsockopt() directly.) + * + * The [<gio/gnetworking.h>][gio-gnetworking.h] + * header pulls in system headers that will define most of the + * standard/portable socket options. For unusual socket protocols or + * platform-dependent options, you may need to include additional + * headers. + * + * Note that even for socket options that are a single byte in size, + * @value is still a pointer to a #gint variable, not a #guchar; + * g_socket_get_option() will handle the conversion internally. + * + * Returns: success or failure. On failure, @error will be set, and + * the system error value (`errno` or WSAGetLastError()) will still + * be set to the result of the getsockopt() call. + * Since: 2.36 + */ + + +/** * g_socket_get_protocol: * @socket: a #GSocket. * @@ -29181,7 +32596,8 @@ * Try to get the remove address of a connected socket. This is only * useful for connection oriented sockets that have been connected. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29354,7 +32770,8 @@ * @listener: a #GSocketListener * @result: a #GAsyncResult. * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async accept operation. See g_socket_listener_accept_async() * @@ -29412,7 +32829,8 @@ * @listener: a #GSocketListener * @result: a #GAsyncResult. * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async accept operation. See g_socket_listener_accept_socket_async() * @@ -29460,7 +32878,8 @@ * g_socket_listener_add_any_inet_port: * @listener: a #GSocketListener * @source_object: (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Listens for TCP connections on any available port number for both * IPv6 and IPv4 (if each is available). @@ -29576,7 +32995,8 @@ * system, so you can use protocols not listed in #GSocketProtocol if you * know the protocol number used for it. * - * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref(). + * Returns: a #GSocket or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29594,7 +33014,8 @@ * will be set to non-blocking mode, independent on the blocking * mode of the #GSocket. * - * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref(). + * Returns: a #GSocket or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29602,7 +33023,8 @@ /** * g_socket_receive: * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29631,7 +33053,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -29639,8 +33062,10 @@ /** * g_socket_receive_from: * @socket: a #GSocket - * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL - * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). + * @address: (out) (allow-none): a pointer to a #GSocketAddress + * pointer, or %NULL + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29653,7 +33078,8 @@ * * See g_socket_receive() for additional information. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -29661,11 +33087,14 @@ /** * g_socket_receive_message: * @socket: a #GSocket - * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL + * @address: (out) (allow-none): a pointer to a #GSocketAddress + * pointer, or %NULL * @vectors: (array length=num_vectors): an array of #GInputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL - * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL + * @messages: (array length=num_messages) (allow-none): a pointer which + * may be filled with an array of #GSocketControlMessages, or %NULL + * @num_messages: a pointer which will be filled with the number of + * elements in @messages, or %NULL * @flags: a pointer to an int containing #GSocketMsgFlags flags * @cancellable: (allow-none): a %GCancellable or %NULL * @error: a #GError pointer, or %NULL @@ -29728,7 +33157,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -29736,7 +33166,8 @@ /** * g_socket_receive_with_blocking: * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29746,7 +33177,8 @@ * the choice of blocking or non-blocking behavior is determined by * the @blocking argument rather than by @socket's properties. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.26 */ @@ -29754,7 +33186,8 @@ /** * g_socket_send: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29774,7 +33207,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -29785,7 +33219,8 @@ * @address: (allow-none): a #GSocketAddress, or %NULL * @vectors: (array length=num_vectors): an array of #GOutputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL. + * @messages: (array length=num_messages) (allow-none): a pointer to an + * array of #GSocketControlMessages, or %NULL. * @num_messages: number of elements in @messages, or -1. * @flags: an int containing #GSocketMsgFlags flags * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29803,7 +33238,7 @@ * then @vectors is assumed to be terminated by a #GOutputVector with a * %NULL buffer pointer.) The #GOutputVector structs describe the buffers * that the sent data will be gathered from. Using multiple - * #GOutputVector<!-- -->s is more memory-efficient than manually copying + * #GOutputVectors is more memory-efficient than manually copying * data from multiple sources into a single buffer, and more * network-efficient than making multiple calls to g_socket_send(). * @@ -29829,7 +33264,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -29838,7 +33274,8 @@ * g_socket_send_to: * @socket: a #GSocket * @address: (allow-none): a #GSocketAddress, or %NULL - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29849,7 +33286,8 @@ * * See g_socket_send() for additional information. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -29857,7 +33295,8 @@ /** * g_socket_send_with_blocking: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29867,7 +33306,8 @@ * the choice of blocking or non-blocking behavior is determined by * the @blocking argument rather than by @socket's properties. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.26 */ @@ -29922,6 +33362,12 @@ * This call is thread-safe, so it may be called from a thread * handling an incoming client request. * + * Note that this only stops accepting new connections; it does not + * close the listening sockets, and you can call + * g_socket_service_start() again later to begin listening again. To + * close the listening sockets, call g_socket_listener_close(). (This + * will happen automatically when the #GSocketService is finalized.) + * * Since: 2.22 */ @@ -29947,10 +33393,11 @@ /** * g_socket_set_broadcast: * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses + * @broadcast: whether @socket should allow sending to broadcast + * addresses * - * Sets whether @socket should allow sending to and receiving from - * broadcast addresses. This is %FALSE by default. + * Sets whether @socket should allow sending to broadcast addresses. + * This is %FALSE by default. * * Since: 2.32 */ @@ -30001,7 +33448,8 @@ /** * g_socket_set_multicast_loopback: * @socket: a #GSocket. - * @loopback: whether @socket should receive messages sent to its multicast groups from the local host + * @loopback: whether @socket should receive messages sent to its + * multicast groups from the local host * * Sets whether outgoing multicast packets will be received by sockets * listening on that multicast address on the same host. This is %TRUE @@ -30025,6 +33473,31 @@ /** + * g_socket_set_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, `SOL_SOCKET`) + * @optname: the "name" of the option (eg, `SO_BROADCAST`) + * @value: the value to set the option to + * @error: #GError for error reporting, or %NULL to ignore. + * + * Sets the value of an integer-valued option on @socket, as with + * setsockopt(). (If you need to set a non-integer-valued option, + * you will need to call setsockopt() directly.) + * + * The [<gio/gnetworking.h>][gio-gnetworking.h] + * header pulls in system headers that will define most of the + * standard/portable socket options. For unusual socket protocols or + * platform-dependent options, you may need to include additional + * headers. + * + * Returns: success or failure. On failure, @error will be set, and + * the system error value (`errno` or WSAGetLastError()) will still + * be set to the result of the setsockopt() call. + * Since: 2.36 + */ + + +/** * g_socket_set_timeout: * @socket: a #GSocket. * @timeout: the timeout for @socket, in seconds, or 0 for none @@ -30203,7 +33676,7 @@ * * Creates a new #GSrvTarget with the given parameters. * - * You should not need to use this; normally #GSrvTarget<!-- -->s are + * You should not need to use this; normally #GSrvTargets are * created by #GResolver. * * Returns: a new #GSrvTarget. @@ -30218,7 +33691,7 @@ * Finalized a GResource initialized by g_static_resource_init(). * * This is normally used by code generated by - * <link linkend="glib-compile-resources">glib-compile-resources</link> + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Since: 2.32 @@ -30232,7 +33705,7 @@ * Gets the GResource that was registered by a call to g_static_resource_init(). * * This is normally used by code generated by - * <link linkend="glib-compile-resources">glib-compile-resources</link> + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Returns: (transfer none): a #GResource @@ -30248,7 +33721,7 @@ * GStaticResource. * * This is normally used by code generated by - * <link linkend="glib-compile-resources">glib-compile-resources</link> + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Since: 2.32 @@ -30256,6 +33729,1322 @@ /** + * g_subprocess_communicate: + * @subprocess: a #GSubprocess + * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL + * @cancellable: a #GCancellable + * @stdout_buf: (out): data read from the subprocess stdout + * @stderr_buf: (out): data read from the subprocess stderr + * @error: a pointer to a %NULL #GError pointer, or %NULL + * + * Communicate with the subprocess until it terminates, and all input + * and output has been completed. + * + * If @stdin_buf is given, the subprocess must have been created with + * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the + * stdin of the subprocess and the pipe is closed (ie: EOF). + * + * At the same time (as not to cause blocking when dealing with large + * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or + * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those + * streams. The data that was read is returned in @stdout and/or + * the @stderr. + * + * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, + * @stdout_buf will contain the data read from stdout. Otherwise, for + * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, + * @stdout_buf will be set to %NULL. Similar provisions apply to + * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. + * + * As usual, any output variable may be given as %NULL to ignore it. + * + * If you desire the stdout and stderr data to be interleaved, create + * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and + * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned + * in @stdout_buf and @stderr_buf will be set to %NULL. + * + * In case of any error (including cancellation), %FALSE will be + * returned with @error set. Some or all of the stdin data may have + * been written. Any stdout or stderr data that has been read will be + * discarded. None of the out variables (aside from @error) will have + * been set to anything in particular and should not be inspected. + * + * In the case that %TRUE is returned, the subprocess has exited and the + * exit status inspection APIs (eg: g_subprocess_get_if_exited(), + * g_subprocess_get_exit_status()) may be used. + * + * You should not attempt to use any of the subprocess pipes after + * starting this function, since they may be left in strange states, + * even if the operation was cancelled. You should especially not + * attempt to interact with the pipes while the operation is in progress + * (either from another thread or if using the asynchronous version). + * + * Returns: %TRUE if successful + * Since: 2.40 + */ + + +/** + * g_subprocess_communicate_async: + * @subprocess: Self + * @stdin_buf: (allow-none): Input data, or %NULL + * @cancellable: (allow-none): Cancellable + * @callback: Callback + * @user_data: User data + * + * Asynchronous version of g_subprocess_communicate(). Complete + * invocation with g_subprocess_communicate_finish(). + */ + + +/** + * g_subprocess_communicate_finish: + * @subprocess: Self + * @result: Result + * @stdout_buf: (out): Return location for stdout data + * @stderr_buf: (out): Return location for stderr data + * @error: Error + * + * Complete an invocation of g_subprocess_communicate_async(). + */ + + +/** + * g_subprocess_communicate_utf8: + * @subprocess: a #GSubprocess + * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL + * @cancellable: a #GCancellable + * @stdout_buf: (out): data read from the subprocess stdout + * @stderr_buf: (out): data read from the subprocess stderr + * @error: a pointer to a %NULL #GError pointer, or %NULL + * + * Like g_subprocess_communicate(), but validates the output of the + * process as UTF-8, and returns it as a regular NUL terminated string. + */ + + +/** + * g_subprocess_communicate_utf8_async: + * @subprocess: Self + * @stdin_buf: (allow-none): Input data, or %NULL + * @cancellable: Cancellable + * @callback: Callback + * @user_data: User data + * + * Asynchronous version of g_subprocess_communicate_utf(). Complete + * invocation with g_subprocess_communicate_utf8_finish(). + */ + + +/** + * g_subprocess_communicate_utf8_finish: + * @subprocess: Self + * @result: Result + * @stdout_buf: (out): Return location for stdout data + * @stderr_buf: (out): Return location for stderr data + * @error: Error + * + * Complete an invocation of g_subprocess_communicate_utf8_async(). + */ + + +/** + * g_subprocess_force_exit: + * @subprocess: a #GSubprocess + * + * Use an operating-system specific method to attempt an immediate, + * forceful termination of the process. There is no mechanism to + * determine whether or not the request itself was successful; + * however, you can use g_subprocess_wait() to monitor the status of + * the process after calling this function. + * + * On Unix, this function sends %SIGKILL. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_get_exit_status: + * @subprocess: a #GSubprocess + * + * Check the exit status of the subprocess, given that it exited + * normally. This is the value passed to the exit() system call or the + * return value from main. + * + * This is equivalent to the system WEXITSTATUS macro. + * + * It is an error to call this function before g_subprocess_wait() and + * unless g_subprocess_get_if_exited() returned %TRUE. + * + * Returns: the exit status + * Since: 2.40 + */ + + +/** + * g_subprocess_get_identifier: + * @subprocess: a #GSubprocess + * + * On UNIX, returns the process ID as a decimal string. On Windows, + * returns the result of GetProcessId() also as a string. + */ + + +/** + * g_subprocess_get_if_exited: + * @subprocess: a #GSubprocess + * + * Check if the given subprocess exited normally (ie: by way of exit() + * or return from main()). + * + * This is equivalent to the system WIFEXITED macro. + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the case of a normal exit + * Since: 2.40 + */ + + +/** + * g_subprocess_get_if_signaled: + * @subprocess: a #GSubprocess + * + * Check if the given subprocess terminated in response to a signal. + * + * This is equivalent to the system WIFSIGNALED macro. + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the case of termination due to a signal + * Since: 2.40 + */ + + +/** + * g_subprocess_get_status: + * @subprocess: a #GSubprocess + * + * Gets the raw status code of the process, as from waitpid(). + * + * This value has no particular meaning, but it can be used with the + * macros defined by the system headers such as WIFEXITED. It can also + * be used with g_spawn_check_exit_status(). + * + * It is more likely that you want to use g_subprocess_get_if_exited() + * followed by g_subprocess_get_exit_status(). + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: the (meaningless) waitpid() exit status from the kernel + * Since: 2.40 + */ + + +/** + * g_subprocess_get_stderr_pipe: + * @subprocess: a #GSubprocess + * + * Gets the #GInputStream from which to read the stderr output of + * @subprocess. + * + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDERR_PIPE. + * + * Returns: (transfer none): the stderr pipe + * Since: 2.40 + */ + + +/** + * g_subprocess_get_stdin_pipe: + * @subprocess: a #GSubprocess + * + * Gets the #GOutputStream that you can write to in order to give data + * to the stdin of @subprocess. + * + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDIN_PIPE. + * + * Returns: (transfer none): the stdout pipe + * Since: 2.40 + */ + + +/** + * g_subprocess_get_stdout_pipe: + * @subprocess: a #GSubprocess + * + * Gets the #GInputStream from which to read the stdout output of + * @subprocess. + * + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDOUT_PIPE. + * + * Returns: (transfer none): the stdout pipe + * Since: 2.40 + */ + + +/** + * g_subprocess_get_successful: + * @subprocess: a #GSubprocess + * + * Checks if the process was "successful". A process is considered + * successful if it exited cleanly with an exit status of 0, either by + * way of the exit() system call or return from main(). + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the process exited cleanly with a exit status of 0 + * Since: 2.40 + */ + + +/** + * g_subprocess_get_term_sig: + * @subprocess: a #GSubprocess + * + * Get the signal number that caused the subprocess to terminate, given + * that it terminated due to a signal. + * + * This is equivalent to the system WTERMSIG macro. + * + * It is an error to call this function before g_subprocess_wait() and + * unless g_subprocess_get_if_signaled() returned %TRUE. + * + * Returns: the signal causing termination + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_getenv: + * @self: a #GSubprocess + * @variable: the environment variable to get + * + * Returns the value of the environment variable @variable in the + * environment of processes launched from this launcher. + * + * The returned string is in the GLib file name encoding. On UNIX, this + * means that it can be an arbitrary byte string. On Windows, it will + * be UTF-8. + * + * Returns: the value of the environment variable, %NULL if unset + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_new: + * @flags: #GSubprocessFlags + * + * Creates a new #GSubprocessLauncher. + * + * The launcher is created with the default options. A copy of the + * environment of the calling process is made at the time of this call + * and will be used as the environment that the process is launched in. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_child_setup: + * @self: a #GSubprocessLauncher + * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function + * @user_data: user data for @child_setup + * @destroy_notify: a #GDestroyNotify for @user_data + * + * Sets up a child setup function. + * + * The child setup function will be called after fork() but before + * exec() on the child's side. + * + * @destroy_notify will not be automatically called on the child's side + * of the fork(). It will only be called when the last reference on the + * #GSubprocessLauncher is dropped or when a new child setup function is + * given. + * + * %NULL can be given as @child_setup to disable the functionality. + * + * Child setup functions are only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_cwd: + * @self: a #GSubprocess + * @cwd: the cwd for launched processes + * + * Sets the current working directory that processes will be launched + * with. + * + * By default processes are launched with the current working directory + * of the launching process at the time of launch. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_environ: + * @self: a #GSubprocess + * @env: the replacement environment + * + * Replace the entire environment of processes launched from this + * launcher with the given 'environ' variable. + * + * Typically you will build this variable by using g_listenv() to copy + * the process 'environ' and using the functions g_environ_setenv(), + * g_environ_unsetenv(), etc. + * + * As an alternative, you can use g_subprocess_launcher_setenv(), + * g_subprocess_launcher_unsetenv(), etc. + * + * All strings in this array are expected to be in the GLib file name + * encoding. On UNIX, this means that they can be arbitrary byte + * strings. On Windows, they should be in UTF-8. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_flags: + * @self: a #GSubprocessLauncher + * @flags: #GSubprocessFlags + * + * Sets the flags on the launcher. + * + * The default flags are %G_SUBPROCESS_FLAGS_NONE. + * + * You may not set flags that specify conflicting options for how to + * handle a particular stdio stream (eg: specifying both + * %G_SUBPROCESS_FLAGS_STDIN_PIPE and + * %G_SUBPROCESS_FLAGS_STDIN_INHERIT). + * + * You may also not set a flag that conflicts with a previous call to a + * function like g_subprocess_launcher_set_stdin_file_path() or + * g_subprocess_launcher_take_stdout_fd(). + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_stderr_file_path: + * @self: a #GSubprocessLauncher + * @path: a filename or %NULL + * + * Sets the file path to use as the stderr for spawned processes. + * + * If @path is %NULL then any previously given path is unset. + * + * The file will be created or truncated when the process is spawned, as + * would be the case if using '2>' at the shell. + * + * If you want to send both stdout and stderr to the same file then use + * %G_SUBPROCESS_FLAGS_STDERR_MERGE. + * + * You may not set a stderr file path if a stderr fd is already set or + * if the launcher flags contain any flags directing stderr elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_stdin_file_path: + * @self: a #GSubprocessLauncher + * @path: a filename or %NULL + * + * Sets the file path to use as the stdin for spawned processes. + * + * If @path is %NULL then any previously given path is unset. + * + * The file must exist or spawning the process will fail. + * + * You may not set a stdin file path if a stdin fd is already set or if + * the launcher flags contain any flags directing stdin elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_stdout_file_path: + * @self: a #GSubprocessLauncher + * @path: a filename or %NULL + * + * Sets the file path to use as the stdout for spawned processes. + * + * If @path is %NULL then any previously given path is unset. + * + * The file will be created or truncated when the process is spawned, as + * would be the case if using '>' at the shell. + * + * You may not set a stdout file path if a stdout fd is already set or + * if the launcher flags contain any flags directing stdout elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_setenv: + * @self: a #GSubprocess + * @variable: the environment variable to set, must not contain '=' + * @value: the new value for the variable + * @overwrite: whether to change the variable if it already exists + * + * Sets the environment variable @variable in the environment of + * processes launched from this launcher. + * + * Both the variable's name and value should be in the GLib file name + * encoding. On UNIX, this means that they can be arbitrary byte + * strings. On Windows, they should be in UTF-8. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_spawn: + * @self: a #GSubprocessLauncher + * @error: Error + * @argv0: Command line arguments + * @...: Continued arguments, %NULL terminated + * + * A convenience helper for creating a #GSubprocess given a provided + * varargs list of arguments. + * + * Since: 2.40 + * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + */ + + +/** + * g_subprocess_launcher_spawnv: + * @self: a #GSubprocessLauncher + * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments + * @error: Error + * + * A convenience helper for creating a #GSubprocess given a provided + * array of arguments. + * + * Since: 2.40 + * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + */ + + +/** + * g_subprocess_launcher_take_fd: + * @self: a #GSubprocessLauncher + * @source_fd: File descriptor in parent process + * @target_fd: Target descriptor for child process + * + * Transfer an arbitrary file descriptor from parent process to the + * child. This function takes "ownership" of the fd; it will be closed + * in the parent when @self is freed. + * + * By default, all file descriptors from the parent will be closed. + * This function allows you to create (for example) a custom pipe() or + * socketpair() before launching the process, and choose the target + * descriptor in the child. + * + * An example use case is GNUPG, which has a command line argument + * --passphrase-fd providing a file descriptor number where it expects + * the passphrase to be written. + */ + + +/** + * g_subprocess_launcher_take_stderr_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 + * + * Sets the file descriptor to use as the stderr for spawned processes. + * + * If @fd is -1 then any previously given fd is unset. + * + * Note that the default behaviour is to pass stderr through to the + * stderr of the parent process. + * + * The passed @fd belongs to the #GSubprocessLauncher. It will be + * automatically closed when the launcher is finalized. The file + * descriptor will also be closed on the child side when executing the + * spawned process. + * + * You may not set a stderr fd if a stderr file path is already set or + * if the launcher flags contain any flags directing stderr elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_take_stdin_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 + * + * Sets the file descriptor to use as the stdin for spawned processes. + * + * If @fd is -1 then any previously given fd is unset. + * + * Note that if your intention is to have the stdin of the calling + * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT + * is a better way to go about doing that. + * + * The passed @fd is noted but will not be touched in the current + * process. It is therefore necessary that it be kept open by the + * caller until the subprocess is spawned. The file descriptor will + * also not be explicitly closed on the child side, so it must be marked + * O_CLOEXEC if that's what you want. + * + * You may not set a stdin fd if a stdin file path is already set or if + * the launcher flags contain any flags directing stdin elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_take_stdout_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 + * + * Sets the file descriptor to use as the stdout for spawned processes. + * + * If @fd is -1 then any previously given fd is unset. + * + * Note that the default behaviour is to pass stdout through to the + * stdout of the parent process. + * + * The passed @fd is noted but will not be touched in the current + * process. It is therefore necessary that it be kept open by the + * caller until the subprocess is spawned. The file descriptor will + * also not be explicitly closed on the child side, so it must be marked + * O_CLOEXEC if that's what you want. + * + * You may not set a stdout fd if a stdout file path is already set or + * if the launcher flags contain any flags directing stdout elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_unsetenv: + * @self: a #GSubprocess + * @variable: the environment variable to unset, must not contain '=' + * + * Removes the environment variable @variable from the environment of + * processes launched from this launcher. + * + * The variable name should be in the GLib file name encoding. On UNIX, + * this means that they can be arbitrary byte strings. On Windows, they + * should be in UTF-8. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_new: (skip) + * @flags: flags that define the behaviour of the subprocess + * @error: (allow-none): return location for an error, or %NULL + * @argv0: first commandline argument to pass to the subprocess, + * followed by more arguments, followed by %NULL + * + * Create a new process with the given flags and varargs argument + * list. By default, matching the g_spawn_async() defaults, the + * child's stdin will be set to the system null device, and + * stdout/stderr will be inherited from the parent. You can use + * @flags to control this behavior. + * + * The argument list must be terminated with %NULL. + * + * Returns: A newly created #GSubprocess, or %NULL on error (and @error + * will be set) + * Since: 2.40 + */ + + +/** + * g_subprocess_newv: (rename-to g_subprocess_new) + * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess + * @flags: flags that define the behaviour of the subprocess + * @error: (allow-none): return location for an error, or %NULL + * + * Create a new process with the given flags and argument list. + * + * The argument list is expected to be %NULL-terminated. + * + * Returns: A newly created #GSubprocess, or %NULL on error (and @error + * will be set) + * Since: 2.40 + */ + + +/** + * g_subprocess_send_signal: + * @subprocess: a #GSubprocess + * @signal_num: the signal number to send + * + * Sends the UNIX signal @signal_num to the subprocess, if it is still + * running. + * + * This API is race-free. If the subprocess has terminated, it will not + * be signalled. + * + * This API is not available on Windows. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_wait: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable + * @error: a #GError + * + * Synchronously wait for the subprocess to terminate. + * + * After the process terminates you can query its exit status with + * functions such as g_subprocess_get_if_exited() and + * g_subprocess_get_exit_status(). + * + * This function does not fail in the case of the subprocess having + * abnormal termination. See g_subprocess_wait_check() for that. + * + * Returns: %TRUE on success, %FALSE if @cancellable was cancelled + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_async: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable, or %NULL + * @callback: a #GAsyncReadyCallback to call when the operation is complete + * @user_data: user_data for @callback + * + * Wait for the subprocess to terminate. + * + * This is the asynchronous version of g_subprocess_wait(). + * + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_check: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable + * @error: a #GError + * + * Combines g_subprocess_wait() with g_spawn_check_exit_status(). + * + * Returns: %TRUE on success, %FALSE if process exited abnormally, or + * @cancellable was cancelled + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_check_async: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable, or %NULL + * @callback: a #GAsyncReadyCallback to call when the operation is complete + * @user_data: user_data for @callback + * + * Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). + * + * This is the asynchronous version of g_subprocess_wait_check(). + * + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_check_finish: + * @subprocess: a #GSubprocess + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL + * + * Collects the result of a previous call to + * g_subprocess_wait_check_async(). + * + * Returns: %TRUE if successful, or %FALSE with @error set + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_finish: + * @subprocess: a #GSubprocess + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL + * + * Collects the result of a previous call to + * g_subprocess_wait_async(). + * + * Returns: %TRUE if successful, or %FALSE with @error set + * Since: 2.40 + */ + + +/** + * g_task_attach_source: + * @task: a #GTask + * @source: the source to attach + * @callback: the callback to invoke when @source triggers + * + * A utility function for dealing with async operations where you need + * to wait for a #GSource to trigger. Attaches @source to @task's + * #GMainContext with @task's [priority][io-priority], and sets @source's + * callback to @callback, with @task as the callback's `user_data`. + * + * This takes a reference on @task until @source is destroyed. + * + * Since: 2.36 + */ + + +/** + * g_task_get_cancellable: + * @task: a #GTask + * + * Gets @task's #GCancellable + * + * Returns: (transfer none): @task's #GCancellable + * Since: 2.36 + */ + + +/** + * g_task_get_check_cancellable: + * @task: the #GTask + * + * Gets @task's check-cancellable flag. See + * g_task_set_check_cancellable() for more details. + * + * Since: 2.36 + */ + + +/** + * g_task_get_context: + * @task: a #GTask + * + * Gets the #GMainContext that @task will return its result in (that + * is, the context that was the + * [thread-default main context][g-main-context-push-thread-default] + * at the point when @task was created). + * + * This will always return a non-%NULL value, even if the task's + * context is the default #GMainContext. + * + * Returns: (transfer none): @task's #GMainContext + * Since: 2.36 + */ + + +/** + * g_task_get_priority: + * @task: a #GTask + * + * Gets @task's priority + * + * Returns: @task's priority + * Since: 2.36 + */ + + +/** + * g_task_get_return_on_cancel: + * @task: the #GTask + * + * Gets @task's return-on-cancel flag. See + * g_task_set_return_on_cancel() for more details. + * + * Since: 2.36 + */ + + +/** + * g_task_get_source_object: + * @task: a #GTask + * + * Gets the source object from @task. Like + * g_async_result_get_source_object(), but does not ref the object. + * + * Returns: (transfer none) (type GObject): @task's source object, or %NULL + * Since: 2.36 + */ + + +/** + * g_task_get_source_tag: + * @task: a #GTask + * + * Gets @task's source tag. See g_task_set_source_tag(). + * + * Returns: (transfer none): @task's source tag + * Since: 2.36 + */ + + +/** + * g_task_get_task_data: + * @task: a #GTask + * + * Gets @task's `task_data`. + * + * Returns: (transfer none): @task's `task_data`. + * Since: 2.36 + */ + + +/** + * g_task_had_error: + * @task: a #GTask. + * + * Tests if @task resulted in an error. + * + * Returns: %TRUE if the task resulted in an error, %FALSE otherwise. + * Since: 2.36 + */ + + +/** + * g_task_is_valid: + * @result: (type Gio.AsyncResult): A #GAsyncResult + * @source_object: (allow-none) (type GObject): the source object + * expected to be associated with the task + * + * Checks that @result is a #GTask, and that @source_object is its + * source object (or that @source_object is %NULL and @result has no + * source object). This can be used in g_return_if_fail() checks. + * + * Returns: %TRUE if @result and @source_object are valid, %FALSE + * if not + * Since: 2.36 + */ + + +/** + * g_task_new: + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * + * Creates a #GTask acting on @source_object, which will eventually be + * used to invoke @callback in the current + * [thread-default main context][g-main-context-push-thread-default]. + * + * Call this in the "start" method of your asynchronous method, and + * pass the #GTask around throughout the asynchronous operation. You + * can use g_task_set_task_data() to attach task-specific data to the + * object, which you can retrieve later via g_task_get_task_data(). + * + * By default, if @cancellable is cancelled, then the return value of + * the task will always be %G_IO_ERROR_CANCELLED, even if the task had + * already completed before the cancellation. This allows for + * simplified handling in cases where cancellation may imply that + * other objects that the task depends on have been destroyed. If you + * do not want this behavior, you can use + * g_task_set_check_cancellable() to change it. + * + * Returns: a #GTask. + * Since: 2.36 + */ + + +/** + * g_task_propagate_boolean: + * @task: a #GTask. + * @error: return location for a #GError + * + * Gets the result of @task as a #gboolean. + * + * If the task resulted in an error, or was cancelled, then this will + * instead return %FALSE and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: the task result, or %FALSE on error + * Since: 2.36 + */ + + +/** + * g_task_propagate_int: + * @task: a #GTask. + * @error: return location for a #GError + * + * Gets the result of @task as an integer (#gssize). + * + * If the task resulted in an error, or was cancelled, then this will + * instead return -1 and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: the task result, or -1 on error + * Since: 2.36 + */ + + +/** + * g_task_propagate_pointer: + * @task: a #GTask + * @error: return location for a #GError + * + * Gets the result of @task as a pointer, and transfers ownership + * of that value to the caller. + * + * If the task resulted in an error, or was cancelled, then this will + * instead return %NULL and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: (transfer full): the task result, or %NULL on error + * Since: 2.36 + */ + + +/** + * g_task_report_error: + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * @source_tag: an opaque pointer indicating the source of this task + * @error: (transfer full): error to report + * + * Creates a #GTask and then immediately calls g_task_return_error() + * on it. Use this in the wrapper function of an asynchronous method + * when you want to avoid even calling the virtual method. You can + * then use g_async_result_is_tagged() in the finish method wrapper to + * check if the result there is tagged as having been created by the + * wrapper method, and deal with it appropriately if so. + * + * See also g_task_report_new_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_report_new_error: + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * @source_tag: an opaque pointer indicating the source of this task + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. + * + * Creates a #GTask and then immediately calls + * g_task_return_new_error() on it. Use this in the wrapper function + * of an asynchronous method when you want to avoid even calling the + * virtual method. You can then use g_async_result_is_tagged() in the + * finish method wrapper to check if the result there is tagged as + * having been created by the wrapper method, and deal with it + * appropriately if so. + * + * See also g_task_report_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_boolean: + * @task: a #GTask. + * @result: the #gboolean result of a task function. + * + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Since: 2.36 + */ + + +/** + * g_task_return_error: + * @task: a #GTask. + * @error: (transfer full): the #GError result of a task function. + * + * Sets @task's result to @error (which @task assumes ownership of) + * and completes the task (see g_task_return_pointer() for more + * discussion of exactly what this means). + * + * Note that since the task takes ownership of @error, and since the + * task may be completed before returning from g_task_return_error(), + * you cannot assume that @error is still valid after calling this. + * Call g_error_copy() on the error if you need to keep a local copy + * as well. + * + * See also g_task_return_new_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_error_if_cancelled: + * @task: a #GTask + * + * Checks if @task's #GCancellable has been cancelled, and if so, sets + * @task's error accordingly and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Returns: %TRUE if @task has been cancelled, %FALSE if not + * Since: 2.36 + */ + + +/** + * g_task_return_int: + * @task: a #GTask. + * @result: the integer (#gssize) result of a task function. + * + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Since: 2.36 + */ + + +/** + * g_task_return_new_error: + * @task: a #GTask. + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. + * + * Sets @task's result to a new #GError created from @domain, @code, + * @format, and the remaining arguments, and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * See also g_task_return_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_pointer: + * @task: a #GTask + * @result: (allow-none) (transfer full): the pointer result of a task + * function + * @result_destroy: (allow-none): a #GDestroyNotify function. + * + * Sets @task's result to @result and completes the task. If @result + * is not %NULL, then @result_destroy will be used to free @result if + * the caller does not take ownership of it with + * g_task_propagate_pointer(). + * + * "Completes the task" means that for an ordinary asynchronous task + * it will either invoke the task's callback, or else queue that + * callback to be invoked in the proper #GMainContext, or in the next + * iteration of the current #GMainContext. For a task run via + * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this + * method will save @result to be returned to the caller later, but + * the task will not actually be completed until the #GTaskThreadFunc + * exits. + * + * Note that since the task may be completed before returning from + * g_task_return_pointer(), you cannot assume that @result is still + * valid after calling this, unless you are still holding another + * reference on it. + * + * Since: 2.36 + */ + + +/** + * g_task_run_in_thread: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc + * + * Runs @task_func in another thread. When @task_func returns, @task's + * #GAsyncReadyCallback will be invoked in @task's #GMainContext. + * + * This takes a ref on @task until the task completes. + * + * See #GTaskThreadFunc for more details about how @task_func is handled. + * + * Since: 2.36 + */ + + +/** + * g_task_run_in_thread_sync: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc + * + * Runs @task_func in another thread, and waits for it to return or be + * cancelled. You can use g_task_propagate_pointer(), etc, afterward + * to get the result of @task_func. + * + * See #GTaskThreadFunc for more details about how @task_func is handled. + * + * Normally this is used with tasks created with a %NULL + * `callback`, but note that even if the task does + * have a callback, it will not be invoked when @task_func returns. + * + * Since: 2.36 + */ + + +/** + * g_task_set_check_cancellable: + * @task: the #GTask + * @check_cancellable: whether #GTask will check the state of + * its #GCancellable for you. + * + * Sets or clears @task's check-cancellable flag. If this is %TRUE + * (the default), then g_task_propagate_pointer(), etc, and + * g_task_had_error() will check the task's #GCancellable first, and + * if it has been cancelled, then they will consider the task to have + * returned an "Operation was cancelled" error + * (%G_IO_ERROR_CANCELLED), regardless of any other error or return + * value the task may have had. + * + * If @check_cancellable is %FALSE, then the #GTask will not check the + * cancellable itself, and it is up to @task's owner to do this (eg, + * via g_task_return_error_if_cancelled()). + * + * If you are using g_task_set_return_on_cancel() as well, then + * you must leave check-cancellable set %TRUE. + * + * Since: 2.36 + */ + + +/** + * g_task_set_priority: + * @task: the #GTask + * @priority: the [priority][io-priority] of the request + * + * Sets @task's priority. If you do not call this, it will default to + * %G_PRIORITY_DEFAULT. + * + * This will affect the priority of #GSources created with + * g_task_attach_source() and the scheduling of tasks run in threads, + * and can also be explicitly retrieved later via + * g_task_get_priority(). + * + * Since: 2.36 + */ + + +/** + * g_task_set_return_on_cancel: + * @task: the #GTask + * @return_on_cancel: whether the task returns automatically when + * it is cancelled. + * + * Sets or clears @task's return-on-cancel flag. This is only + * meaningful for tasks run via g_task_run_in_thread() or + * g_task_run_in_thread_sync(). + * + * If @return_on_cancel is %TRUE, then cancelling @task's + * #GCancellable will immediately cause it to return, as though the + * task's #GTaskThreadFunc had called + * g_task_return_error_if_cancelled() and then returned. + * + * This allows you to create a cancellable wrapper around an + * uninterruptable function. The #GTaskThreadFunc just needs to be + * careful that it does not modify any externally-visible state after + * it has been cancelled. To do that, the thread should call + * g_task_set_return_on_cancel() again to (atomically) set + * return-on-cancel %FALSE before making externally-visible changes; + * if the task gets cancelled before the return-on-cancel flag could + * be changed, g_task_set_return_on_cancel() will indicate this by + * returning %FALSE. + * + * You can disable and re-enable this flag multiple times if you wish. + * If the task's #GCancellable is cancelled while return-on-cancel is + * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE + * again will cause the task to be cancelled at that point. + * + * If the task's #GCancellable is already cancelled before you call + * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the + * #GTaskThreadFunc will still be run (for consistency), but the task + * will also be completed right away. + * + * Returns: %TRUE if @task's return-on-cancel flag was changed to + * match @return_on_cancel. %FALSE if @task has already been + * cancelled. + * Since: 2.36 + */ + + +/** + * g_task_set_source_tag: + * @task: the #GTask + * @source_tag: an opaque pointer indicating the source of this task + * + * Sets @task's source tag. You can use this to tag a task return + * value with a particular pointer (usually a pointer to the function + * doing the tagging) and then later check it using + * g_task_get_source_tag() (or g_async_result_is_tagged()) in the + * task's "finish" function, to figure out if the response came from a + * particular place. + * + * Since: 2.36 + */ + + +/** + * g_task_set_task_data: + * @task: the #GTask + * @task_data: (allow-none): task-specific data + * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data + * + * Sets @task's task data (freeing the existing task data, if any). + * + * Since: 2.36 + */ + + +/** * g_tcp_connection_get_graceful_disconnect: * @connection: a #GTcpConnection * @@ -30313,7 +35102,7 @@ * @self: a #GTestDBus * @path: path to a directory containing .service files * - * Add a path where dbus-daemon will lookup for .services files. This can't be + * Add a path where dbus-daemon will look up .service files. This can't be * called after g_test_dbus_up(). */ @@ -30334,11 +35123,11 @@ * g_test_dbus_get_bus_address: * @self: a #GTestDBus * - * Get the address on which dbus-daemon is running. if g_test_dbus_up() has not + * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not * been called yet, %NULL is returned. This can be used with - * g_dbus_connection_new_for_address() + * g_dbus_connection_new_for_address(). * - * Returns: the address of the bus, or %NULL. + * Returns: (allow-none): the address of the bus, or %NULL. */ @@ -30346,7 +35135,7 @@ * g_test_dbus_get_flags: * @self: a #GTestDBus * - * Gets the flags of the #GTestDBus object. + * Get the flags of the #GTestDBus object. * * Returns: the value of #GTestDBus:flags property */ @@ -30392,7 +35181,7 @@ * @self: a #GTestDBus * * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this - * call, it is safe for unit tests to start sending messages on the session bug. + * call, it is safe for unit tests to start sending messages on the session bus. * * If this function is called from setup callback of g_test_add(), * g_test_dbus_down() must be called in its teardown callback. @@ -30409,10 +35198,8 @@ * * Append a name to the list of icons from within @icon. * - * <note><para> * Note that doing so invalidates the hash computed by prior calls * to g_icon_hash(). - * </para></note> */ @@ -30439,7 +35226,8 @@ /** * g_themed_icon_new_from_names: * @iconnames: (array length=len): an array of strings containing icon names. - * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated + * @len: the length of the @iconnames array, or -1 if @iconnames is + * %NULL-terminated * * Creates a new themed icon for @iconnames. * @@ -30455,7 +35243,7 @@ * that can be created by shortening @iconname at '-' characters. * * In the following example, @icon1 and @icon2 are equivalent: - * |[ + * |[<!-- language="C" --> * const char *names[] = { * "gnome-dev-cdrom-audio", * "gnome-dev-cdrom", @@ -30478,10 +35266,8 @@ * * Prepend a name to the list of icons from within @icon. * - * <note><para> * Note that doing so invalidates the hash computed by prior calls * to g_icon_hash(). - * </para></note> * * Since: 2.18 */ @@ -30489,7 +35275,8 @@ /** * g_threaded_socket_service_new: - * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit + * @max_threads: the maximal number of threads to execute concurrently + * handling incoming clients, -1 means no limit * * Creates a new #GThreadedSocketService with no listeners. Listeners * must be added with one of the #GSocketListener "add" methods. @@ -30505,7 +35292,8 @@ * * Gets the #GType of @backend's #GTlsCertificate implementation. * - * Returns: the #GType of @backend's #GTlsCertificate implementation. + * Returns: the #GType of @backend's #GTlsCertificate + * implementation. * Since: 2.28 */ @@ -30516,7 +35304,8 @@ * * Gets the #GType of @backend's #GTlsClientConnection implementation. * - * Returns: the #GType of @backend's #GTlsClientConnection implementation. + * Returns: the #GType of @backend's #GTlsClientConnection + * implementation. * Since: 2.28 */ @@ -30537,7 +35326,8 @@ * * Gets the default #GTlsDatabase used to verify TLS connections. * - * Returns: (transfer full): the default database, which should be unreffed when done. + * Returns: (transfer full): the default database, which should be + * unreffed when done. * Since: 2.30 */ @@ -30559,7 +35349,8 @@ * * Gets the #GType of @backend's #GTlsServerConnection implementation. * - * Returns: the #GType of @backend's #GTlsServerConnection implementation. + * Returns: the #GType of @backend's #GTlsServerConnection + * implementation. * Since: 2.28 */ @@ -30582,7 +35373,9 @@ * * Gets the #GTlsCertificate representing @cert's issuer, if known * - * Returns: (transfer none): The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. + * Returns: (transfer none): The certificate of @cert's issuer, + * or %NULL if @cert is self-signed or signed with an unknown + * certificate. * Since: 2.28 */ @@ -30608,13 +35401,15 @@ * @file: file containing PEM-encoded certificates to import * @error: #GError for error reporting, or %NULL to ignore. * - * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded + * Creates one or more #GTlsCertificates from the PEM-encoded * data in @file. If @file cannot be read or parsed, the function will * return %NULL and set @error. If @file does not contain any * PEM-encoded certificates, this will return an empty list and not * set @error. * - * Returns: (element-type Gio.TlsCertificate) (transfer full): a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it. + * Returns: (element-type Gio.TlsCertificate) (transfer full): a + * #GList containing #GTlsCertificate objects. You must free the list + * and its contents when you are done with it. * Since: 2.28 */ @@ -30713,7 +35508,9 @@ * Each item in the list is a #GByteArray which contains the complete * subject DN of the certificate authority. * - * Returns: (element-type GByteArray) (transfer full): the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free(). + * Returns: (element-type GByteArray) (transfer full): the list of + * CA DNs. You should unref each element with g_byte_array_unref() and then + * the free the list with g_list_free(). * Since: 2.28 */ @@ -30724,7 +35521,9 @@ * * Gets @conn's expected server identity * - * Returns: (transfer none): a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. + * Returns: (transfer none): a #GSocketConnectable describing the + * expected server identity, or %NULL if the expected identity is not + * known. * Since: 2.28 */ @@ -30763,7 +35562,8 @@ * must have pollable input and output streams) which is assumed to * communicate with the server identified by @server_identity. * - * Returns: (transfer full) (type GTlsClientConnection): the new #GTlsClientConnection, or %NULL on error + * Returns: (transfer full) (type GTlsClientConnection): the new + * #GTlsClientConnection, or %NULL on error * Since: 2.28 */ @@ -30819,7 +35619,8 @@ * Used by #GTlsConnection implementations to emit the * #GTlsConnection::accept-certificate signal. * - * Returns: %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert + * Returns: %TRUE if one of the signal handlers has returned + * %TRUE to accept @peer_cert * Since: 2.28 */ @@ -30907,7 +35708,8 @@ * when the connection is closed. See * g_tls_connection_set_require_close_notify() for details. * - * Returns: %TRUE if @conn requires a proper TLS close notification. + * Returns: %TRUE if @conn requires a proper TLS close + * notification. * Since: 2.28 */ @@ -30961,7 +35763,7 @@ /** * g_tls_connection_handshake_async: * @conn: a #GTlsConnection - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): a #GCancellable, or %NULL * @callback: callback to call when the handshake is complete * @user_data: the data to pass to the callback function @@ -30982,7 +35784,8 @@ * Finish an asynchronous TLS handshake operation. See * g_tls_connection_handshake() for more information. * - * Returns: %TRUE on success, %FALSE on failure, in which case @error will be set. + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set. * Since: 2.28 */ @@ -31064,16 +35867,16 @@ * * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a * rehandshake only if the other end of the connection supports the - * TLS <literal>renegotiation_info</literal> extension. This is the - * default behavior, but means that rehandshaking will not work - * against older implementations that do not support that extension. + * TLS `renegotiation_info` extension. This is the default behavior, + * but means that rehandshaking will not work against older + * implementations that do not support that extension. * * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow - * rehandshaking even without the - * <literal>renegotiation_info</literal> extension. On the server side - * in particular, this is not recommended, since it leaves the server - * open to certain attacks. However, this mode is necessary if you - * need to allow renegotiation with older client software. + * rehandshaking even without the `renegotiation_info` extension. On + * the server side in particular, this is not recommended, since it + * leaves the server open to certain attacks. However, this mode is + * necessary if you need to allow renegotiation with older client + * software. * * Since: 2.28 */ @@ -31173,7 +35976,8 @@ * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full) (allow-none): a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full) (allow-none): a newly allocated + * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31207,7 +36011,8 @@ * If the handle is no longer valid, or does not point to a certificate in * this database, then %NULL will be returned. * - * Returns: (transfer full): a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated #GTlsCertificate object. + * Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31230,7 +36035,8 @@ * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31261,7 +36067,8 @@ * Finish an asynchronous lookup issuer operation. See * g_tls_database_lookup_certificate_issuer() for more information. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31280,7 +36087,8 @@ * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. + * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate + * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. * Since: 2.30 */ @@ -31315,7 +36123,8 @@ * Finish an asynchronous lookup of certificates. See * g_tls_database_lookup_certificates_issued_by() for more information. * - * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. + * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate + * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. * Since: 2.30 */ @@ -31356,7 +36165,8 @@ * This function can block, use g_tls_database_verify_chain_async() to perform * the verification operation asynchronously. * - * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification. + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. * Since: 2.30 */ @@ -31390,7 +36200,8 @@ * Finish an asynchronous verify chain operation. See * g_tls_database_verify_chain() for more information. * * - * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification. + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. * Since: 2.30 */ @@ -31415,7 +36226,8 @@ * * The certificates in @anchors must be PEM encoded. * - * Returns: (transfer full) (type GTlsFileDatabase): the new #GTlsFileDatabase, or %NULL on error + * Returns: (transfer full) (type GTlsFileDatabase): the new + * #GTlsFileDatabase, or %NULL on error * Since: 2.30 */ @@ -31528,6 +36340,114 @@ /** + * g_tls_interaction_invoke_request_certificate: + * @interaction: a #GTlsInteraction object + * @connection: a #GTlsConnection object + * @flags: flags providing more information about the request + * @cancellable: an optional #GCancellable cancellation object + * @error: an optional location to place an error on failure + * + * Invoke the interaction to ask the user to choose a certificate to + * use with the connection. It invokes this interaction in the main + * loop, specifically the #GMainContext returned by + * g_main_context_get_thread_default() when the interaction is + * created. This is called by called by #GTlsConnection when the peer + * requests a certificate during the handshake. + * + * Derived subclasses usually implement a certificate selector, + * although they may also choose to provide a certificate from + * elsewhere. Alternatively the user may abort this certificate + * request, which may or may not abort the TLS connection. + * + * The implementation can either be a synchronous (eg: modal dialog) or an + * asynchronous one (eg: modeless dialog). This function will take care of + * calling which ever one correctly. + * + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may + * not support immediate cancellation. + * + * Returns: The status of the certificate request interaction. + * Since: 2.40 + */ + + +/** + * g_tls_interaction_request_certificate: + * @interaction: a #GTlsInteraction object + * @connection: a #GTlsConnection object + * @flags: flags providing more information about the request + * @cancellable: an optional #GCancellable cancellation object + * @error: an optional location to place an error on failure + * + * Run synchronous interaction to ask the user to choose a certificate to use + * with the connection. In general, g_tls_interaction_invoke_request_certificate() + * should be used instead of this function. + * + * Derived subclasses usually implement a certificate selector, although they may + * also choose to provide a certificate from elsewhere. Alternatively the user may + * abort this certificate request, which will usually abort the TLS connection. + * + * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection + * passed to g_tls_interaction_request_certificate() will have had its + * #GTlsConnection:certificate filled in. + * + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may + * not support immediate cancellation. + * + * Returns: The status of the request certificate interaction. + * Since: 2.40 + */ + + +/** + * g_tls_interaction_request_certificate_async: + * @interaction: a #GTlsInteraction object + * @connection: a #GTlsConnection object + * @flags: flags providing more information about the request + * @cancellable: an optional #GCancellable cancellation object + * @callback: (allow-none): will be called when the interaction completes + * @user_data: (allow-none): data to pass to the @callback + * + * Run asynchronous interaction to ask the user for a certificate to use with + * the connection. In general, g_tls_interaction_invoke_request_certificate() should + * be used instead of this function. + * + * Derived subclasses usually implement a certificate selector, although they may + * also choose to provide a certificate from elsewhere. @callback will be called + * when the operation completes. Alternatively the user may abort this certificate + * request, which will usually abort the TLS connection. + * + * Since: 2.40 + */ + + +/** + * g_tls_interaction_request_certificate_finish: + * @interaction: a #GTlsInteraction object + * @result: the result passed to the callback + * @error: an optional location to place an error on failure + * + * Complete an request certificate user interaction request. This should be once + * the g_tls_interaction_request_certificate_async() completion callback is called. + * + * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection + * passed to g_tls_interaction_request_certificate_async() will have had its + * #GTlsConnection:certificate filled in. + * + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. + * + * Returns: The status of the request certificate interaction. + * Since: 2.40 + */ + + +/** * g_tls_password_get_description: * @password: a #GTlsPassword object * @@ -31630,7 +36550,7 @@ /** - * g_tls_password_set_value_full: + * g_tls_password_set_value_full: (virtual set_value) * @password: a #GTlsPassword object * @value: the value for the password * @length: the length of the password, or -1 @@ -31646,7 +36566,6 @@ * calculated automatically. (Note that the terminating nul is not * considered part of the password in this case.) * - * Virtual: set_value * Since: 2.30 */ @@ -31673,7 +36592,8 @@ * Creates a new #GTlsServerConnection wrapping @base_io_stream (which * must have pollable input and output streams). * - * Returns: (transfer full) (type GTlsServerConnection): the new #GTlsServerConnection, or %NULL on error + * Returns: (transfer full) (type GTlsServerConnection): the new + * #GTlsServerConnection, or %NULL on error * Since: 2.28 */ @@ -31695,7 +36615,8 @@ * Other ways to exchange credentials with a foreign peer includes the * #GUnixCredentialsMessage type and g_socket_get_credentials() function. * - * Returns: (transfer full): Received credentials on success (free with g_object_unref()), %NULL if @error is set. + * Returns: (transfer full): Received credentials on success (free with + * g_object_unref()), %NULL if @error is set. * Since: 2.26 */ @@ -31728,7 +36649,8 @@ * Finishes an asynchronous receive credentials operation started with * g_unix_connection_receive_credentials_async(). * - * Returns: (transfer full): a #GCredentials, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GCredentials, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.32 */ @@ -31889,7 +36811,8 @@ * this index with g_unix_fd_list_get() then you will receive back a * duplicated copy of the same file descriptor. * - * Returns: the index of the appended fd in case of success, else -1 (and @error is set) + * Returns: the index of the appended fd in case of success, else -1 + * (and @error is set) * Since: 2.24 */ @@ -31962,7 +36885,8 @@ /** * g_unix_fd_list_peek_fds: * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -31978,7 +36902,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: (array length=length) (transfer none): an array of file descriptors + * Returns: (array length=length) (transfer none): an array of file + * descriptors * Since: 2.24 */ @@ -31986,7 +36911,8 @@ /** * g_unix_fd_list_steal_fds: * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -32007,7 +36933,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: (array length=length) (transfer full): an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * Since: 2.24 */ @@ -32070,7 +36997,8 @@ /** * g_unix_fd_message_steal_fds: * @message: a #GUnixFDMessage - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -32090,7 +37018,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @message, an empty array is returned. * - * Returns: (array length=length) (transfer full): an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * Since: 2.22 */ @@ -32146,14 +37075,15 @@ /** * g_unix_is_mount_path_system_internal: - * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename> + * @mount_path: a mount path, e.g. `/media/disk` or `/usr` * * Determines if @mount_path is considered an implementation of the * OS. This is primarily used for hiding mountable and mounted volumes * that only are used in the OS and has little to no relevance to the * casual user. * - * Returns: %TRUE if @mount_path is considered an implementation detail of the OS. + * Returns: %TRUE if @mount_path is considered an implementation detail + * of the OS. */ @@ -32177,7 +37107,8 @@ * * Compares two unix mounts. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ @@ -32246,7 +37177,8 @@ * Guesses the name of a Unix mount. * The result is a translated string. * - * Returns: A newly allocated string that must be freed with g_free() + * Returns: A newly allocated string that must + * be freed with g_free() */ @@ -32306,7 +37238,8 @@ /** * g_unix_mount_monitor_set_rate_limit: * @mount_monitor: a #GUnixMountMonitor - * @limit_msec: a integer with the limit in milliseconds to poll for changes. + * @limit_msec: a integer with the limit in milliseconds to + * poll for changes. * * Sets the rate limit to which the @mount_monitor will report * consecutive change events to the mount and mount point entry files. @@ -32322,7 +37255,8 @@ * * Compares two unix mount points. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ @@ -32402,7 +37336,8 @@ * Guesses the name of a Unix mount point. * The result is a translated string. * - * Returns: A newly allocated string that must be freed with g_free() + * Returns: A newly allocated string that must + * be freed with g_free() */ @@ -32466,7 +37401,8 @@ * allowing for checking if the mounts have changed with * g_unix_mount_points_changed_since(). * - * Returns: (element-type GUnixMountPoint) (transfer full): a #GList of the UNIX mountpoints. + * Returns: (element-type GUnixMountPoint) (transfer full): + * a #GList of the UNIX mountpoints. */ @@ -32489,7 +37425,8 @@ * timestamp, allowing for checking if the mounts have changed * with g_unix_mounts_changed_since(). * - * Returns: (element-type GUnixMountEntry) (transfer full): a #GList of the UNIX mounts. + * Returns: (element-type GUnixMountEntry) (transfer full): + * a #GList of the UNIX mounts. */ @@ -32656,7 +37593,7 @@ * zero-padded buffer will be considered the name. (As above, if * @path_len is -1, then @path is assumed to be NUL-terminated.) In * this case, g_socket_address_get_native_size() will always return - * the full size of a <literal>struct sockaddr_un</literal>, although + * the full size of a `struct sockaddr_un`, although * g_unix_socket_address_get_path_len() will still return just the * length of @path. * @@ -32687,7 +37624,8 @@ * * Gets a #GFile for @path. * - * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ @@ -32702,7 +37640,8 @@ * might not support any I/O operation if the URI * is malformed or if the URI scheme is not supported. * - * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ @@ -32721,7 +37660,9 @@ * * Gets a list of URI schemes supported by @vfs. * - * Returns: (transfer none): a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. + * Returns: (transfer none): a %NULL-terminated array of strings. + * The returned array belongs to GIO and must + * not be freed or modified. */ @@ -32731,7 +37672,8 @@ * * Checks if the VFS is active. * - * Returns: %TRUE if construction of the @vfs was successful and it is now active. + * Returns: %TRUE if construction of the @vfs was successful + * and it is now active. */ @@ -32744,36 +37686,37 @@ * not support any I/O operations if the @parse_name cannot * be parsed by the #GVfs module. * - * Returns: (transfer full): a #GFile for the given @parse_name. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile for the given @parse_name. + * Free the returned object with g_object_unref(). */ /** * g_volume_can_eject: - * @volume: a #GVolume. + * @volume: a #GVolume * * Checks if a volume can be ejected. * - * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise. + * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise */ /** * g_volume_can_mount: - * @volume: a #GVolume. + * @volume: a #GVolume * * Checks if a volume can be mounted. * - * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise. + * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise */ /** * g_volume_eject: - * @volume: a #GVolume. + * @volume: a #GVolume * @flags: flags affecting the unmount if required for eject - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL * @user_data: user data that gets passed to @callback * * Ejects a volume. This is an asynchronous operation, and is @@ -32786,26 +37729,27 @@ /** * g_volume_eject_finish: - * @volume: pointer to a #GVolume. - * @result: a #GAsyncResult. + * @volume: pointer to a #GVolume + * @result: a #GAsyncResult * @error: a #GError location to store an error, or %NULL to ignore * * Finishes ejecting a volume. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. * - * Returns: %TRUE, %FALSE if operation failed. + * Returns: %TRUE, %FALSE if operation failed * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. */ /** * g_volume_eject_with_operation: - * @volume: a #GVolume. + * @volume: a #GVolume * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to + * avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL + * @user_data: user data passed to @callback * * Ejects a volume. This is an asynchronous operation, and is * finished by calling g_volume_eject_with_operation_finish() with the @volume @@ -32817,14 +37761,14 @@ /** * g_volume_eject_with_operation_finish: - * @volume: a #GVolume. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @volume: a #GVolume + * @result: a #GAsyncResult + * @error: a #GError location to store the error occurring, or %NULL * * Finishes ejecting a volume. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. * - * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise. + * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise * Since: 2.22 */ @@ -32833,11 +37777,11 @@ * g_volume_enumerate_identifiers: * @volume: a #GVolume * - * Gets the kinds of <link linkend="volume-identifier">identifiers</link> - * that @volume has. Use g_volume_get_identifier() to obtain - * the identifiers themselves. + * Gets the kinds of [identifiers][volume-identifier] that @volume has. + * Use g_volume_get_identifier() to obtain the identifiers themselves. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array + * of strings containing kinds of identifiers. Use g_strfreev() to free. */ @@ -32852,51 +37796,53 @@ * either be equal or a prefix of what this function returns. In * other words, in code * - * <programlisting> + * |[<!-- language="C" --> * GMount *mount; * GFile *mount_root * GFile *volume_activation_root; * - * mount = g_volume_get_mount (volume); /* mounted, so never NULL */ + * mount = g_volume_get_mount (volume); // mounted, so never NULL * mount_root = g_mount_get_root (mount); - * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */ - * </programlisting> - * + * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL + * ]| * then the expression - * - * <programlisting> + * |[<!-- language="C" --> * (g_file_has_prefix (volume_activation_root, mount_root) || * g_file_equal (volume_activation_root, mount_root)) - * </programlisting> - * + * ]| * will always be %TRUE. * * Activation roots are typically used in #GVolumeMonitor * implementations to find the underlying mount to shadow, see * g_mount_is_shadowed() for more details. * - * Returns: (transfer full): the activation root of @volume or %NULL. Use g_object_unref() to free. + * Returns: (transfer full): the activation root of @volume or %NULL. Use + * g_object_unref() to free. * Since: 2.18 */ /** * g_volume_get_drive: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the drive for the @volume. * - * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GDrive or %NULL if @volume is not + * associated with a drive. The returned object should be unreffed + * with g_object_unref() when no longer needed. */ /** * g_volume_get_icon: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the icon for @volume. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ @@ -32906,65 +37852,74 @@ * @kind: the kind of identifier to return * * Gets the identifier of the given kind for @volume. - * See the <link linkend="volume-identifier">introduction</link> - * for more information about volume identifiers. + * See the [introduction][volume-identifier] for more + * information about volume identifiers. * - * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GVolume doesn't have this kind of identifier + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GVolume + * doesn't have this kind of identifier */ /** * g_volume_get_mount: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the mount for the @volume. * - * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ /** * g_volume_get_name: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the name of @volume. * - * Returns: the name for the given @volume. The returned string should be freed with g_free() when no longer needed. + * Returns: the name for the given @volume. The returned string should + * be freed with g_free() when no longer needed. */ /** * g_volume_get_sort_key: - * @volume: A #GVolume. + * @volume: a #GVolume * * Gets the sort key for @volume, if any. * - * Returns: Sorting key for @volume or %NULL if no such key is available. + * Returns: Sorting key for @volume or %NULL if no such key is available * Since: 2.32 */ /** * g_volume_get_symbolic_icon: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the symbolic icon for @volume. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. * Since: 2.34 */ /** * g_volume_get_uuid: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the UUID for the @volume. The reference is typically based on * the file system UUID for the volume in question and should be * considered an opaque string. Returns %NULL if there is no UUID * available. * - * Returns: the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. + * Returns: the UUID for @volume or %NULL if no UUID can be computed. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -33001,8 +37956,13 @@ * is to return #GVolume objects representing entries in the users * "favorite servers" list or similar. * - * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount. - * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions. + * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL + * if no wants to adopt the #GMount. + * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor + * implementations should instead create shadow mounts with the URI of + * the mount they intend to adopt. See the proxy volume monitor in + * gvfs for an example of this. Also see g_mount_is_shadowed(), + * g_mount_shadow() and g_mount_unshadow() functions. */ @@ -33011,7 +37971,8 @@ * * Gets the volume monitor used by gio. * - * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it. + * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call + * g_object_unref() when done with it. */ @@ -33035,7 +37996,8 @@ * * Finds a #GMount object by its UUID (see g_mount_get_uuid()) * - * Returns: (transfer full): a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GMount or %NULL if no such mount is available. + * Free the returned object with g_object_unref(). */ @@ -33059,7 +38021,8 @@ * * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) * - * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. + * Free the returned object with g_object_unref(). */ @@ -33077,19 +38040,17 @@ /** - * g_volume_mount: - * @volume: a #GVolume. + * g_volume_mount: (virtual mount_fn) + * @volume: a #GVolume * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL * @user_data: user data that gets passed to @callback * * Mounts a volume. This is an asynchronous operation, and is * finished by calling g_volume_mount_finish() with the @volume * and #GAsyncResult returned in the @callback. - * - * Virtual: mount_fn */ @@ -33107,7 +38068,7 @@ * function; there's no need to listen for the 'mount-added' signal on * #GVolumeMonitor. * - * Returns: %TRUE, %FALSE if operation failed. + * Returns: %TRUE, %FALSE if operation failed */ @@ -33117,7 +38078,7 @@ * * Returns whether the volume should be automatically mounted. * - * Returns: %TRUE if the volume should be automatically mounted. + * Returns: %TRUE if the volume should be automatically mounted */ @@ -33302,7 +38263,8 @@ * * Optionally doesn't list the desktop ids given in the @except * - * Returns: a #GList containing the desktop ids which claim to handle @mime_type. + * Returns: a #GList containing the desktop ids which claim + * to handle @mime_type. */ |