/************************************************************/
/**
+ * GAction:
+ *
+ * #GAction is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GAction:enabled:
*
* If @action is currently enabled.
* GAction:name:
*
* The name of the action. This is mostly meaningful for identifying
- * the action once it has been added to a #GActionGroup.
+ * the action once it has been added to a #GActionGroup. It is immutable.
*
* Since: 2.28
*/
* GAction:parameter-type:
*
* The type of the parameter that must be given when activating the
- * action.
+ * action. This is immutable, and may be %NULL if no parameter is needed when
+ * activating the action.
*
* Since: 2.28
*/
* GAction:state-type:
*
* The #GVariantType of the state that the action has, or %NULL if the
- * action is stateless.
+ * action is stateless. This is immutable.
*
* Since: 2.28
*/
/**
* 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. Since GLib 2.40, this can be %NULL for stateful
+ * actions, in which case the default handler is used. For
+ * boolean-stated actions with no parameter, this is a
+ * toggle. For other state types (and parameter type equal
+ * to the state type) this will be a function that
+ * just calls @change_state (which you should provide).
+ * @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][gvariant-text]. The state is parsed
+ * with no extra type information, so type tags must be added to
+ * the string if they are necessary. Stateless actions should
+ * give %NULL here.
+ * @change_state: the callback to connect to the "change-state" signal
+ * of the action. All stateful actions should provide a
+ * handler here; stateless actions should not.
*
* This struct defines a single action. It is for use with
* g_action_map_add_action_entries().
/**
+ * GActionGroup:
+ *
+ * #GActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GActionGroup::action-added:
* @action_group: the #GActionGroup that changed
* @action_name: the name of the action in @action_group
* @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.
*
/**
+ * GActionMap:
+ *
+ * #GActionMap is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GActionMapInterface:
* @lookup_action: the virtual function pointer for g_action_map_lookup_action()
* @add_action: the virtual function pointer for g_action_map_add_action()
/**
+ * 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
+ */
+
+
+/**
+ * GAppInfoMonitor::changed:
+ *
+ * Signal emitted when the app info database for changes (ie: newly installed
+ * or removed applications).
+ */
+
+
+/**
+ * GAppLaunchContext::launch-failed:
+ * @context: the object emitting the signal
+ * @startup_notify_id: the startup notification id for the failed launch
+ *
+ * The ::launch-failed signal is emitted when a #GAppInfo launch
+ * fails. The startup notification id is provided, so that the launcher
+ * can cancel the startup notification.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * GAppLaunchContext::launched:
+ * @context: the object emitting the signal
+ * @info: the #GAppInfo that was just launched
+ * @platform_data: additional platform-specific data for this launch
+ *
+ * The ::launched signal is emitted when a #GAppInfo is successfully
+ * launched. The @platform_data is an GVariant dictionary mapping
+ * strings to variants (ie a{sv}), which contains additional,
+ * platform-specific data about this launch. On UNIX, at least the
+ * "pid" and "startup-notification-id" keys will be present.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * GApplication:
+ *
+ * #GApplication is an opaque data structure and can only be accessed
+ * using the following functions.
+ *
+ * Since: 2.28
+ */
+
+
+/**
* GApplication::activate:
* @application: the application
*
/**
* 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).
+ *
+ * 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.
+ *
+ * Returns: an exit code. If you have handled your options and want
+ * to exit the process, return a non-negative option, 0 for success,
+ * and a positive value for failure. To continue, return -1 to let
+ * the default option processing continue.
+ * Since: 2.40
*/
/**
+ * GApplication:is-busy:
+ *
+ * Whether the application is currently marked as busy through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+
+
+/**
* 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
+ * @handle_local_options: invoked locally after the parsing of the commandline
+ * options has occurred.
*
* Virtual function table for #GApplication.
*
/**
+ * GApplicationCommandLine:
+ *
+ * #GApplicationCommandLine is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* 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.
*
*
* 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
* 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;
* 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);
* ]|
*
/**
+ * GDBusActionGroup:
+ *
+ * #GDBusActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusAuthMechanism:credentials:
*
* If authenticating as a server, this property contains the
/**
* 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.
*
/**
* 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
* 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
*/
*
* 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
/**
+ * GDBusMenuModel:
+ *
+ * #GDBusMenuModel is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusMessage:
*
* The #GDBusMessage structure contains only private data and should
/**
+ * GDBusObject:
+ *
+ * #GDBusObject is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusObject::interface-added:
* @object: The #GDBusObject emitting the signal.
* @interface: The #GDBusInterface that was added.
/**
+ * GDBusObjectManager:
+ *
+ * #GDBusObjectManager is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusObjectManager::interface-added:
* @manager: The #GDBusObjectManager emitting the signal.
* @object: The #GDBusObject on which an interface was added.
* 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
* 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
* 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.
*
* @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
*/
* 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
*
* 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
*/
/**
+ * GDesktopAppInfoLookup:
+ *
+ * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDrive::changed:
* @drive: a #GDrive.
*
/**
+ * GIOExtension:
+ *
+ * #GIOExtension is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GIOExtensionPoint:
+ *
+ * #GIOExtensionPoint is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GIOModuleScope:
*
* Represents a scope for loading IO modules. A scope can be used for blocking
/**
* 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
*/
/**
* GInetSocketAddress:scope_id:
*
- * The <literal>sin6_scope_id</literal> field, for IPv6 addresses.
+ * The `sin6_scope_id` field, for IPv6 addresses.
*
* Since: 2.32
*/
/**
+ * GListModel:
+ *
+ * #GListModel is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GListModel::items-changed:
+ * @list: the #GListModel that changed
+ * @position: the position at which @list changed
+ * @removed: the number of items removed
+ * @added: the number of items added
+ *
+ * This signal is emitted whenever items were added or removed to
+ * @list. At @position, @removed items were removed and @added items
+ * were added in their place.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GListModelInterface:
+ * @g_iface: parent #GTypeInterface
+ * @get_item_type: the virtual function pointer for g_list_model_get_item_type()
+ * @get_n_items: the virtual function pointer for g_list_model_get_n_items()
+ * @get_item: the virtual function pointer for g_list_model_get_item()
+ *
+ * The virtual function table for #GListModel.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GListStore:
+ *
+ * #GListStore is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GListStore:item-type:
+ *
+ * The type of items contained in this list store. Items must be
+ * subclasses of #GObject.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GMemoryOutputStream:data:
*
* Pointer to buffer where data will be written.
* 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
/**
+ * 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
+ *
+ * Emitted when an unmount operation has been busy for more than some time
+ * (typically 1.5 seconds).
+ *
+ * When unmounting or ejecting a volume, the kernel might need to flush
+ * pending data in its buffers to the volume stable storage, and this operation
+ * can take a considerable amount of time. This signal may be emitted several
+ * times as long as the unmount operation is outstanding, and then one
+ * last time when the operation is completed, with @bytes_left set to zero.
+ *
+ * Implementations of GMountOperation should handle this signal by
+ * showing an UI notification, and then dismiss it, or show another notification
+ * of completion, when @bytes_left reaches zero.
+ *
+ * If the message contains a line break, the first line should be
+ * presented as a heading. For example, it may be used as the
+ * primary text in a #GtkMessageDialog.
+ *
+ * Since: 2.34
+ */
+
+
+/**
* GMountOperation:anonymous:
*
* Whether to use an anonymous user when authenticating.
/**
+ * GNetworkMonitor:connectivity:
+ *
+ * More detailed information about the host's network connectivity.
+ * See g_network_monitor_get_connectivity() and
+ * #GNetworkConnectivity for more details.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GNetworkMonitor:network-available:
*
* Whether the network is considered available. That is, whether the
* 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.)
/**
+ * GNetworkMonitorInterface:
+ * @g_iface: The parent interface.
+ * @network_changed: the virtual function pointer for the
+ * GNetworkMonitor::network-changed signal.
+ * @can_reach: the virtual function pointer for g_network_monitor_can_reach()
+ * @can_reach_async: the virtual function pointer for
+ * g_network_monitor_can_reach_async()
+ * @can_reach_finish: the virtual function pointer for
+ * g_network_monitor_can_reach_finish()
+ *
+ * The virtual function table for #GNetworkMonitor.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* GNetworkService:
*
* A #GSocketConnectable for resolving a SRV record and connecting to
/**
+ * 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
/**
- * GProxyAddress:
+ * GPropertyAction:
*
- * A #GInetSocketAddress representing a connection via a proxy server
+ * This type is opaque.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GProxyAddress:destination-protocol:
+ * GPropertyAction:enabled:
*
- * The protocol being spoke to the destination host, or %NULL if
- * the #GProxyAddress doesn't know.
+ * If @action is currently enabled.
*
- * Since: 2.34
+ * If the action is disabled then calls to g_action_activate() and
+ * g_action_change_state() have no effect.
+ *
+ * Since: 2.38
*/
/**
- * GProxyAddress:uri:
+ * GPropertyAction:name:
*
- * The URI string that the proxy was constructed from (or %NULL
- * if the creator didn't specify this).
+ * The name of the action. This is mostly meaningful for identifying
+ * the action once it has been added to a #GActionMap.
*
- * Since: 2.34
+ * Since: 2.38
*/
/**
- * 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()
+ * GPropertyAction:object:
*
- * The virtual function table for #GRemoteActionGroup.
+ * The object to wrap a property on.
*
- * Since: 2.32
+ * The object must be a non-%NULL #GObject with properties.
+ *
+ * Since: 2.38
*/
/**
- * GResolver:
+ * GPropertyAction:parameter-type:
*
- * The object that handles DNS resolution. Use g_resolver_get_default()
- * to get the default resolver.
+ * The type of the parameter that must be given when activating the
+ * action.
+ *
+ * Since: 2.38
*/
/**
- * GResolver::reload:
- * @resolver: a #GResolver
+ * GPropertyAction:property-name:
*
- * Emitted when the resolver notices that the system resolver
- * configuration has changed.
+ * 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
*/
/**
- * 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
- * @n_keys: the length of the @keys array, or 0
+ * GPropertyAction:state:
*
- * The "change-event" signal is emitted once per change event that
- * affects this settings object. You should connect to this signal
- * only if you are interested in viewing groups of changes before they
- * are split out into multiple emissions of the "changed" signal.
- * For most use cases it is more appropriate to use the "changed" signal.
+ * The state of the action, or %NULL if the action is stateless.
*
- * In the event that the change event applies to one or more specified
- * keys, @keys will be an array of #GQuark of length @n_keys. In the
- * event that the change event applies to the #GSettings object as a
- * whole (ie: potentially every key has been changed) then @keys will
- * be %NULL and @n_keys will be 0.
+ * Since: 2.38
+ */
+
+
+/**
+ * GPropertyAction:state-type:
*
- * The default handler for this signal invokes the "changed" signal
- * for each affected key. If any other connected handler returns
- * %TRUE then this default functionality will be suppressed.
+ * The #GVariantType of the state that the action has, or %NULL if the
+ * action is stateless.
*
- * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
+ * Since: 2.38
*/
/**
- * GSettings::changed:
- * @settings: the object on which the signal was emitted
- * @key: the name of the key that changed
+ * GProxyAddress:
+ *
+ * A #GInetSocketAddress representing a connection via a proxy server
+ *
+ * Since: 2.26
+ */
+
+
+/**
+ * GProxyAddress:destination-protocol:
+ *
+ * The protocol being spoke to the destination host, or %NULL if
+ * the #GProxyAddress doesn't know.
+ *
+ * Since: 2.34
+ */
+
+
+/**
+ * GProxyAddress:uri:
+ *
+ * The URI string that the proxy was constructed from (or %NULL
+ * if the creator didn't specify this).
+ *
+ * Since: 2.34
+ */
+
+
+/**
+ * GProxyAddressClass:
+ *
+ * Class structure for #GProxyAddress.
+ *
+ * Since: 2.26
+ */
+
+
+/**
+ * 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
+ */
+
+
+/**
+ * GProxyResolverInterface:
+ * @g_iface: The parent interface.
+ * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported()
+ * @lookup: the virtual function pointer for g_proxy_resolver_lookup()
+ * @lookup_async: the virtual function pointer for
+ * g_proxy_resolver_lookup_async()
+ * @lookup_finish: the virtual function pointer for
+ * g_proxy_resolver_lookup_finish()
+ *
+ * The virtual function table for #GProxyResolver.
+ */
+
+
+/**
+ * GRemoteActionGroup:
+ *
+ * #GRemoteActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * 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()
+ *
+ * The virtual function table for #GRemoteActionGroup.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * GResolver:
+ *
+ * The object that handles DNS resolution. Use g_resolver_get_default()
+ * to get the default resolver.
+ */
+
+
+/**
+ * GResolver::reload:
+ * @resolver: a #GResolver
+ *
+ * Emitted when the resolver notices that the system resolver
+ * configuration has changed.
+ */
+
+
+/**
+ * GSettings:
+ *
+ * #GSettings is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * 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 #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
+ * affects this settings object. You should connect to this signal
+ * only if you are interested in viewing groups of changes before they
+ * are split out into multiple emissions of the "changed" signal.
+ * For most use cases it is more appropriate to use the "changed" signal.
+ *
+ * In the event that the change event applies to one or more specified
+ * keys, @keys will be an array of #GQuark of length @n_keys. In the
+ * event that the change event applies to the #GSettings object as a
+ * whole (ie: potentially every key has been changed) then @keys will
+ * be %NULL and @n_keys will be 0.
+ *
+ * The default handler for this signal invokes the "changed" signal
+ * 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.
+ */
+
+
+/**
+ * GSettings::changed:
+ * @settings: the object on which the signal was emitted
+ * @key: the name of the key that changed
*
* The "changed" signal is emitted when a key has potentially changed.
* You should call one of the g_settings_get() calls to check the new
* 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.
*/
* '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.
*/
/**
+ * GSettingsSchemaKey:
+ *
+ * #GSettingsSchemaKey is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GSettingsSchemaSource:
*
* This is an opaque structure type. You may not access it directly.
/**
+ * GSimpleAction:
+ *
+ * #GSimpleAction is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GSimpleAction::activate:
* @simple: the #GSimpleAction
* @parameter: (allow-none): the parameter to the activation
* @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
*/
*
* 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,
* 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
*/
/**
* 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
/**
+ * GSimpleIOStream:
+ *
+ * A wrapper around a #GInputStream and a #GOutputStream.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GSimpleIOStream:input-stream:
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GSimpleIOStream:output-stream:
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GSimplePermission:
*
* #GSimplePermission is an opaque data structure. There are no methods
/**
+ * 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
*/
/**
* GSocketAddress:
*
- * A socket endpoint address, corresponding to <type>struct sockaddr</type>
+ * A socket endpoint address, corresponding to struct sockaddr
* or one of its subtypes.
*/
* 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
/**
+ * 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
/**
+ * GStaticResource:
+ *
+ * #GStaticResource is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GTask:
+ *
+ * The opaque object representing a synchronous or asynchronous task
+ * and its result.
+ */
+
+
+/**
+ * GTask:completed:
+ *
+ * Whether the task has completed, meaning its callback (if set) has been
+ * invoked. This can only happen after g_task_return_pointer(),
+ * g_task_return_error() or one of the other return functions have been called
+ * on the task.
+ *
+ * This property is guaranteed to change from %FALSE to %TRUE exactly once.
+ *
+ * The #GObject::notify signal for this change is emitted in the same main
+ * context as the task’s callback, immediately after that callback is invoked.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * 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
+ */
+
+
+/**
+ * GTcpWrapperConnection:
+ *
+ * #GTcpWrapperConnection is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GTestDBus:
*
* The #GTestDBus structure contains only private data and
/**
* GTestDBus:flags:
*
- * #GTestDBusFlags specifying the behaviour of the dbus session
+ * #GTestDBusFlags specifying the behaviour of the D-Bus session.
*
* Since: 2.34
*/
*
* For example, if the icon name was "gnome-dev-cdrom-audio", the array
* would become
- * |[
+ * |[<!-- language="C" -->
* {
* "gnome-dev-cdrom-audio",
* "gnome-dev-cdrom",
/**
* GTlsCertificate:certificate:
*
- * The DER (binary) encoded representation of the certificate's
- * public key. This property and the
- * #GTlsCertificate:certificate-pem property represent the same
- * data, just in different forms.
+ * The DER (binary) encoded representation of the certificate.
+ * This property and the #GTlsCertificate:certificate-pem property
+ * represent the same data, just in different forms.
*
* Since: 2.28
*/
/**
* GTlsCertificate:certificate-pem:
*
- * The PEM (ASCII) encoded representation of the certificate's
- * public key. This property and the #GTlsCertificate:certificate
+ * The PEM (ASCII) encoded representation of the certificate.
+ * This property and the #GTlsCertificate:certificate
* property represent the same data, just in different forms.
*
* Since: 2.28
* 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
* 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
/**
- * GTlsClientConnection:accepted-cas:
+ * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
*
* A list of the distinguished names of the Certificate Authorities
* that the server will accept client certificates signed by. If the
/**
* GTlsClientConnection:use-ssl3:
*
- * If %TRUE, tells the connection to use SSL 3.0 rather than trying
- * to negotiate the best version of TLS or SSL to use. This can be
- * used when talking to servers that don't implement version
- * negotiation correctly and therefore refuse to handshake at all with
- * a "modern" TLS handshake.
+ * If %TRUE, tells the connection to use a fallback version of TLS
+ * or SSL, rather than trying to negotiate the best version of TLS
+ * to use. This can be used when talking to servers that don't
+ * implement version negotiation correctly and therefore refuse to
+ * handshake at all with a "modern" TLS handshake.
+ *
+ * Despite the property name, the fallback version is not
+ * necessarily SSL 3.0; if SSL 3.0 has been disabled, the
+ * #GTlsClientConnection will use the next highest available version
+ * (normally TLS 1.0) as the fallback version.
*
* Since: 2.28
*/
* 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
*/
/**
* 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.
/**
+ * GUnixConnection:
+ *
+ * #GUnixConnection is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GUnixCredentialsMessage:credentials:
*
* The credentials stored in the message.
/**
+ * GUnixFDList:
+ *
+ * #GUnixFDList is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GUnixFDMessage:
+ *
+ * #GUnixFDMessage is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GUnixInputStream:close-fd:
*
* Whether to close the file descriptor when the stream is closed.
/**
+ * GUnixMountType:
+ * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type.
+ *
+ * Types of UNIX mounts.
+ */
+
+
+/**
* GUnixOutputStream:close-fd:
*
* Whether to close the file descriptor when the stream is closed.
* GUnixSocketAddress:
*
* A UNIX-domain (local) socket address, corresponding to a
- * <type>struct sockaddr_un</type>.
+ * struct sockaddr_un.
*/
*
* 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.
*/
*
* If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
* %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
- * and modification time from the file info to the the GZIP header.
+ * and modification time from the file info to the GZIP header.
*
* Since: 2.26
*/
* 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.
* 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 (),
*
* 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.
* SECTION:gaction
* @title: GAction
* @short_description: An action interface
+ * @include: gio/gio.h
*
* #GAction represents a single named action.
*
*
* #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
* 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
* 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.
/**
* SECTION:gactiongroupexporter
* @title: GActionGroup exporter
+ * @include: gio/gio.h
* @short_description: Export GActionGroups on D-Bus
* @see_also: #GActionGroup, #GDBusActionGroup
*
/**
* SECTION:gactionmap
* @title: GActionMap
+ * @include: gio/gio.h
* @short_description: Interface for action containers
*
* The GActionMap interface is implemented by #GActionGroup
* 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.
* 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.
*
* 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"))
* // do something special with uri
* }
* g_object_unref (file);
- * </programlisting>
+ * ]|
*
- * 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.
+ * 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:gapplication
- * @title: GApplication
- * @short_description: Core application class
+ * SECTION:gappinfomonitor
+ * @short_description: Monitor application information for changes
*
- * A #GApplication is the foundation of an application. It wraps some
- * low-level platform-specific services and is intended to act as the
- * foundation for higher-level application classes such as
+ * #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
+ */
+
+
+/**
+ * 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
+ * foundation for higher-level application classes such as
* #GtkApplication or #MxApplication. In general, you should not use
* 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 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().
*
* 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().
*
* 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).
*/
* 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
* 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
*
* 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)
*/
*
* A typical implementation might look something like this:
*
- * |[
+ * |[<!-- language="C" -->
* enum {
* NOT_INITIALIZED,
* INITIALIZING,
*
* 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);
* 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;
* }
* }
* GAsyncResult *result,
* GError **error)
* {
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (initable), foo_init_async), FALSE);
+ * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
*
- * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
- * error))
- * return FALSE;
- *
- * return TRUE;
+ * return g_task_propagate_boolean (G_TASK (result), error);
* }
*
* static void
* 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.
*
* 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,
* 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.
*/
/**
+ * 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
* @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.
* #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 NetBSD, the native credential type is a struct unpcbid.
+ * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
+ *
+ * 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.
*/
* 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
*
* 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).
*/
* 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>
+ *
+ * |[<!-- language="C" -->
* static gboolean
* on_authorize_authenticated_peer (GDBusAuthObserver *observer,
* GIOStream *stream,
*
* return authorized;
* }
- * </programlisting></example>
+ * ]|
*/
* over any transport that can by represented as an #GIOStream.
*
* This class is rarely used directly in D-Bus clients. If you are writing
- * an D-Bus client, it is often easier to use the g_bus_own_name(),
+ * a 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
* #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}
*
- * <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>
+ * 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-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>
+ * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
*
- * <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>
+ * 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)
+ *
+ * ## 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)
*/
* 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);
* FOO_BAR_ERROR_FAILED,
* FOO_BAR_ERROR_ANOTHER_ERROR,
* FOO_BAR_ERROR_SOME_THIRD_ERROR,
+ * FOO_BAR_N_ERRORS / *< skip >* /
* } FooBarError;
*
- * /<!-- -->* foo-bar-error.c: *<!-- -->/
+ * // foo-bar-error.c:
*
* static const GDBusErrorEntry foo_bar_error_entries[] =
* {
* {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
* };
*
+ * // 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
* foo_bar_error_quark (void)
* {
* &quark_volatile,
* foo_bar_error_entries,
* G_N_ELEMENTS (foo_bar_error_entries));
- * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR);
* 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
* 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)
*/
* 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
*
* 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)
*/
*
* 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)
*/
* @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
*
* #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
* 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
* #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
* @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
* %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)
*/
* 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.
* #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.
*/
* #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
* @see_also: #GFileInfo, #GFileEnumerator
*
* #GFile is a high level abstraction for manipulating files on a
- * virtual file system. #GFile<!-- -->s are lightweight, immutable
- * objects that do no I/O upon creation. It is necessary to understand that
- * #GFile objects do not represent files, merely an identifier for a file. All
- * file content I/O is implemented as streaming operations (see #GInputStream and
- * #GOutputStream).
+ * virtual file system. #GFiles are lightweight, immutable objects
+ * that do no I/O upon creation. It is necessary to understand that
+ * #GFile objects do not represent files, merely an identifier for a
+ * file. All file content I/O is implemented as streaming operations
+ * (see #GInputStream and #GOutputStream).
*
* To construct a #GFile, you can use:
- * 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 utf8 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 #GFile<!-- -->s
- * are extensible it could also be something else that corresponds to a pathname
- * in a userspace implementation of a filesystem.
- *
- * #GFile<!-- -->s make up hierarchies of directories and files that correspond to the
- * files on a filesystem. You can move through the file system with #GFile using
- * g_file_get_parent() to get an identifier for the parent directory, g_file_get_child()
- * to get a child within a directory, g_file_resolve_relative_path() to resolve a relative
- * path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not
- * end up at the same root if you repeatedly call g_file_get_parent() on two different
+ * - 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
+ * #GFiles are extensible it could also be something else that corresponds
+ * to a pathname in a userspace implementation of a filesystem.
+ *
+ * #GFiles make up hierarchies of directories and files that correspond to
+ * the files on a filesystem. You can move through the file system with
+ * #GFile using g_file_get_parent() to get an identifier for the parent
+ * directory, g_file_get_child() to get a child within a directory,
+ * g_file_resolve_relative_path() to resolve a relative path between two
+ * #GFiles. There can be multiple hierarchies, so you may not end up at
+ * the same root if you repeatedly call g_file_get_parent() on two different
* files.
*
- * All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names
- * are byte strings that are used to identify the file on the filesystem (relative to
- * its parent directory) and there is no guarantees that they have any particular charset
- * encoding or even make any sense at all. If you want to use filenames in a user
- * interface you should use the display name that you can get by requesting the
+ * All #GFiles have a basename (get with g_file_get_basename()). These names
+ * are byte strings that are used to identify the file on the filesystem
+ * (relative to its parent directory) and there is no guarantees that they
+ * have any particular charset encoding or even make any sense at all. If
+ * you want to use filenames in a user interface you should use the display
+ * name that you can get by requesting the
* %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
- * This is guaranteed to be in utf8 and can be used in a user interface. But always
- * store the real basename or the #GFile to use to actually access the file, because
- * there is no way to go from a display name to the actual name.
- *
- * Using #GFile as an identifier has the same weaknesses as using a path in that
- * there may be multiple aliases for the same file. For instance, hard or
- * soft links may cause two different #GFile<!-- -->s to refer to the same file.
- * Other possible causes for aliases are: case insensitive filesystems, short
- * and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if
- * two #GFile<!-- -->s point to the same file you can query for the
+ * This is guaranteed to be in UTF-8 and can be used in a user interface.
+ * But always store the real basename or the #GFile to use to actually
+ * access the file, because there is no way to go from a display name to
+ * the actual name.
+ *
+ * Using #GFile as an identifier has the same weaknesses as using a path
+ * in that there may be multiple aliases for the same file. For instance,
+ * hard or soft links may cause two different #GFiles to refer to the same
+ * file. Other possible causes for aliases are: case insensitive filesystems,
+ * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to
+ * check if two #GFiles point to the same file you can query for the
* %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
- * canonicalization of pathnames passed in, so that trivial differences in the
- * path string used at creation (duplicated slashes, slash at end of path, "."
- * or ".." path segments, etc) does not create different #GFile<!-- -->s.
+ * canonicalization of pathnames passed in, so that trivial differences in
+ * the path string used at creation (duplicated slashes, slash at end of
+ * path, "." or ".." path segments, etc) does not create different #GFiles.
*
* Many #GFile operations have both synchronous and asynchronous versions
* to suit your application. Asynchronous versions of synchronous functions
* the operation, producing a GAsyncResult which is then passed to the
* function's matching _finish() operation.
*
- * 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:
- * 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.
+ * It is highly recommended to use asynchronous calls when running within a
+ * shared main loop, such as in the main thread of an application. This avoids
+ * I/O operations blocking other sources on the main loop from being dispatched.
+ * Synchronous I/O operations should be performed from worker threads. See the
+ * [introduction to asynchronous programming section][async-programming] for
+ * more.
+ *
+ * Some #GFile operations almost always take a noticeable amount of time, and
+ * so do not have synchronous analogs. Notable cases include:
+ * - 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 #GFile<!-- -->s are entity tags, or "etags" for
+ * 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>
*/
* 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.
* 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.
* <!-- 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
* "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.
*/
* #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
*/
* @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).
* 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
* 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
*
* 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).
*
* 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
/**
* 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
/**
* 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.
* @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>
*/
* 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
*/
/**
+ * SECTION:glistmodel
+ * @title: GListModel
+ * @short_description: An interface describing a dynamic list of objects
+ * @include: gio/gio.h
+ * @see_also: #GListStore
+ *
+ * #GListModel is an interface that represents a mutable list of
+ * #GObjects. Its main intention is as a model for various widgets in
+ * user interfaces, such as list views, but it can also be used as a
+ * convenient method of returning lists of data, with support for
+ * updates.
+ *
+ * Each object in the list may also report changes in itself via some
+ * mechanism (normally the #GObject::notify signal). Taken together
+ * with the #GListModel::items-changed signal, this provides for a list
+ * that can change its membership, and in which the members can change
+ * their individual properties.
+ *
+ * A good example would be the list of visible wireless network access
+ * points, where each access point can report dynamic properties such as
+ * signal strength.
+ *
+ * It is important to note that the #GListModel itself does not report
+ * changes to the individual items. It only reports changes to the list
+ * membership. If you want to observe changes to the objects themselves
+ * then you need to connect signals to the objects that you are
+ * interested in.
+ *
+ * All items in a #GListModel are of (or derived from) the same type.
+ * g_list_model_get_item_type() returns that type. The type may be an
+ * interface, in which case all objects in the list must implement it.
+ *
+ * The semantics are close to that of an array:
+ * g_list_model_get_length() returns the number of items in the list and
+ * g_list_model_get_item() returns an item at a (0-based) position. In
+ * order to allow implementations to calculate the list length lazily,
+ * you can also iterate over items: starting from 0, repeatedly call
+ * g_list_model_get_item() until it returns %NULL.
+ *
+ * An implementation may create objects lazily, but must take care to
+ * return the same object for a given position until all references to
+ * it are gone.
+ *
+ * On the other side, a consumer is expected only to hold references on
+ * objects that are currently "user visible", in order to faciliate the
+ * maximum level of laziness in the implementation of the list and to
+ * reduce the required number of signal connections at a given time.
+ *
+ * This interface is intended only to be used from a single thread. The
+ * thread in which it is appropriate to use it depends on the particular
+ * implementation, but typically it will be from the thread that owns
+ * the [thread-default main context][g-main-context-push-thread-default]
+ * in effect at the time that the model was created.
+ */
+
+
+/**
+ * SECTION:gliststore
+ * @title: GListStore
+ * @short_description: A simple implementation of #GListModel
+ * @include: gio/gio.h
+ *
+ * #GListStore is a simple implementation of #GListModel that stores all
+ * items in memory.
+ *
+ * It provides insertions, deletions, and lookups in logarithmic time
+ * with a fast path for the common case of iterating the list linearly.
+ */
+
+
+/**
* SECTION:gloadableicon
* @short_description: Loadable Icons
* @include: gio/gio.h
* #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.
*/
* 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.
* 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.
* 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
* 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,
* 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
* 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>
*/
*
* 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
/**
+ * 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
*
* #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.
*/
/**
+ * 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
/**
* 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.
* @include: gio/gio.h
* @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
*
- * #GPollableInputStream is implemented by #GInputStream<!-- -->s that
+ * #GPollableInputStream is implemented by #GInputStreams that
* can be polled for readiness to read. This can be used when
* interfacing with a non-GIO API that expects
* UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
* @include: gio/gio.h
* @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
*
- * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
+ * #GPollableOutputStream is implemented by #GOutputStreams that
* can be polled for readiness to write. This can be used when
* interfacing with a non-GIO API that expects
* UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
/**
* SECTION:gpollableutils
- * @short_description: #GPollableInputStream / #GPollableOutputStream utilities
+ * @short_description: Utilities for pollable streams
* @include: gio/gio.h
*
* Utility functions for #GPollableInputStream and
/**
+ * 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.
/**
* SECTION:gproxyaddress
* @short_description: An internet address with proxy information
+ * @include: gio/gio.h
*
* Support for proxied #GInetSocketAddress.
*/
/**
* 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).
*
* 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.
*
* @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
* 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">
* <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.
*
*
* #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.
* the names must begin with a lowercase character, must not end
* with a '-', and must not contain consecutive dashes.
*
+ * GSettings supports change notification. The primary mechanism to
+ * watch for changes is to connect to the "changed" signal. You can
+ * optionally watch for changes on only a single key by using a signal
+ * detail. Signals are only guaranteed to be emitted for a given key
+ * after you have read the value of that key while a signal handler was
+ * connected for that key. Signals may or may not be emitted in the
+ * case that the key "changed" to the value that you had previously
+ * read. Signals may be reported in additional cases as well and the
+ * "changed" signal should really be treated as "may have changed".
+ *
* 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">
*
*
* </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">
* </key>
*
* <key name='flags-key' flags='org.gtk.Test.myflags'>
- * <default>["flag1",flag2"]</default>
+ * <default>["flag1","flag2"]</default>
* </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.
*/
* 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
*
* Consider the following example:
*
- * |[
+ * |[<!-- language="C" -->
* typedef struct
* {
* ...
* ships a gschemas.compiled file as part of itself, and then simply do
* the following:
*
- * |[
+ * |[<!-- language="C" -->
* {
* GSettings *settings;
* gint some_value;
* 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
* 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.
* 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
* 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.
*
* #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)
* 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);
* }
* 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;
* }
/**
+ * SECTION:gsimpleiostream
+ * @short_description: A wrapper around an input and an output stream.
+ * @include: gio/gio.h
+ * @see_also: #GIOStream
+ *
+ * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and
+ * #GOutputStream. This allows any pair of input and output streams to be used
+ * with #GIOStream methods.
+ *
+ * This is useful when you obtained a #GInputStream and a #GOutputStream
+ * by other means, for instance creating them with platform specific methods as
+ * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want
+ * to take advantage of the methods provided by #GIOStream.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* 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
/**
+ * 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.
* 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
* account the fact that your program will not automatically be killed
* if it tries to write to %stdout after it has been closed.
*
+ * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
+ * a #GSocket concurrently from multiple threads, you must implement your own
+ * locking.
+ *
* Since: 2.22
*/
/**
* 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.
*/
/**
* 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
* 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,
* 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);
* {
* 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;
* 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
*/
* 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
*
* 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
* 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
* 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
* 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.
* 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
/**
- * SECTION:gtcpconnection
- * @title: GTcpConnection
- * @short_description: A TCP GSocketConnection
- * @see_also: #GSocketConnection.
+ * SECTION:gsubprocess
+ * @title: GSubprocess
+ * @short_description: Child processes
+ * @include: gio/gio.h
+ * @see_also: #GSubprocessLauncher
*
- * This is the subclass of #GSocketConnection that is created
- * for TCP/IP sockets.
+ * #GSubprocess allows the creation of and interaction with child
+ * processes.
*
- * Since: 2.22
+ * 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:gtcpwrapperconnection
- * @title: GTcpWrapperConnection
- * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
- * @see_also: #GSocketConnection.
- *
+ * 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);
+ * g_object_unref (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);
+ * }
+ * ]|
+ *
+ * ## 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
+ * for TCP/IP sockets.
+ *
+ * Since: 2.22
+ */
+
+
+/**
+ * SECTION:gtcpwrapperconnection
+ * @title: GTcpWrapperConnection
+ * @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
* based on a #GSocket, but which is not actually a
* #GSocketConnection. This is used by #GSocketClient so that it can
* @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
+ * ]|
*/
* SECTION:gthreadedsocketservice
* @title: GThreadedSocketService
* @short_description: A threaded GSocketService
+ * @include: gio/gio.h
* @see_also: #GSocketService.
*
* A #GThreadedSocketService is a simple subclass of #GSocketService
* @short_description: TLS backend implementation
* @include: gio/gio.h
*
+ * TLS (Transport Layer Security, aka SSL) backend
*
+ * Since: 2.28
*/
* SECTION:gtlscertificate
* @title: GTlsCertificate
* @short_description: TLS certificate
+ * @include: gio/gio.h
* @see_also: #GTlsConnection
*
* A certificate used for TLS authentication and encryption.
- * This can represent either a public key only (eg, the certificate
+ * This can represent either a certificate only (eg, the certificate
* received by a client from a server), or the combination of
- * a public key and a private key (which is needed when acting as a
+ * a certificate and a private key (which is needed when acting as a
* #GTlsServerConnection).
*
* Since: 2.28
* @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
* 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
*/
* 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.
*/
* 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.
*/
* 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.
*/
*
* 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.
*/
* 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.
*/
* 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.
*/
*
* 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
* 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
* 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.
*/
* #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.
*/
* #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.
*/
/**
- * _g_freedesktop_dbus_call_add_match:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_rule: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
- * @user_data: User data to pass to @callback.
+ * _g_dbus_initialize:
*
- * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
- * 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 then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
+ * Does various one-time init things such as
*
- * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
+ * - registering the G_DBUS_ERROR error domain
+ * - parses the G_DBUS_DEBUG environment variable
*/
/**
- * _g_freedesktop_dbus_call_add_match_finish:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
- * @error: Return location for error or %NULL.
+ * _g_file_attribute_value_as_string:
+ * @attr: a #GFileAttributeValue.
*
- * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
+ * Converts a #GFileAttributeValue to a string for display.
+ * The returned string should be freed when no longer needed.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: a string from the @attr, %NULL on error, or "<invalid>"
+ * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
*/
/**
- * _g_freedesktop_dbus_call_add_match_sync:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_rule: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
- *
- * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ * _g_file_attribute_value_clear:
+ * @attr: a #GFileAttributeValue.
*
- * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
+ * Clears the value of @attr and sets its type to
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ */
+
+
+/**
+ * _g_file_attribute_value_free:
+ * @attr: a #GFileAttributeValue.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Frees the memory used by @attr.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
- * @user_data: User data to pass to @callback.
+ * _g_file_attribute_value_get_boolean:
+ * @attr: a #GFileAttributeValue.
*
- * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
- * 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 then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
+ * Gets the boolean value from a file attribute value. If the value is not the
+ * right type then %FALSE will be returned.
*
- * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
+ * Returns: the boolean value contained within the attribute, or %FALSE.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
- * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
- * @error: Return location for error or %NULL.
+ * _g_file_attribute_value_get_byte_string:
+ * @attr: a #GFileAttributeValue.
*
- * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
+ * Gets the byte string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: the byte string contained within the attribute or %NULL.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_name: Argument to pass with the method invocation.
- * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * _g_file_attribute_value_get_int32:
+ * @attr: a #GFileAttributeValue.
*
- * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
- *
- * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
+ * Gets the signed 32-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: the signed 32-bit integer from the attribute, or 0.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_unix_process_id:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
- * @user_data: User data to pass to @callback.
+ * _g_file_attribute_value_get_int64:
+ * @attr: a #GFileAttributeValue.
*
- * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
- * 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 then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
+ * Gets the signed 64-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
+ * Returns: the signed 64-bit integer from the attribute, or 0.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @out_pid: (out): Return location for return parameter or %NULL to ignore.
- * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
- * @error: Return location for error or %NULL.
+ * _g_file_attribute_value_get_object:
+ * @attr: a #GFileAttributeValue.
*
- * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
+ * Gets the GObject from a file attribute value. If the value
+ * is not the right type then %NULL will be returned.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: the GObject from the attribute, or %NULL.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_name: Argument to pass with the method invocation.
- * @out_pid: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
- *
- * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ * _g_file_attribute_value_get_string:
+ * @attr: a #GFileAttributeValue.
*
- * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
+ * Gets the string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: the UTF-8 string value contained within the attribute, or %NULL.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_unix_user:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
- * @user_data: User data to pass to @callback.
+ * _g_file_attribute_value_get_uint32:
+ * @attr: a #GFileAttributeValue.
*
- * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
- * 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 then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
+ * Gets the unsigned 32-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
+ * Returns: the unsigned 32-bit integer from the attribute, or 0.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @out_uid: (out): Return location for return parameter or %NULL to ignore.
- * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
- * @error: Return location for error or %NULL.
+ * _g_file_attribute_value_get_uint64:
+ * @attr: a #GFileAttributeValue.
*
- * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
+ * Gets the unsigned 64-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: the unsigned 64-bit integer from the attribute, or 0.
*/
/**
- * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
- * @proxy: A #_GFreedesktopDBusProxy.
- * @arg_name: Argument to pass with the method invocation.
- * @out_uid: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
- *
- * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ * _g_file_attribute_value_new:
*
- * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
+ * Creates a new file attribute.
*
- * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ * Returns: a #GFileAttributeValue.
*/
/**
- * _g_freedesktop_dbus_call_get_id:
- * @proxy: A #_GFreedesktopDBusProxy.
+ * _g_file_attribute_value_set_boolean:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gboolean to set within the type.
+ *
+ * Sets the attribute value to the given boolean value.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_byte_string:
+ * @attr: a #GFileAttributeValue.
+ * @string: a byte string to set within the type.
+ *
+ * Sets the attribute value to a given byte string.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_int32:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gint32 to set within the type.
+ *
+ * Sets the attribute value to the given signed 32-bit integer.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_int64:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gint64 to set within the type.
+ *
+ * Sets the attribute value to a given signed 64-bit integer.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_object:
+ * @attr: a #GFileAttributeValue.
+ * @obj: a #GObject.
+ *
+ * Sets the attribute to contain the value @obj.
+ * The @attr references the GObject internally.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_string:
+ * @attr: a #GFileAttributeValue.
+ * @string: a UTF-8 string to set within the type.
+ *
+ * Sets the attribute value to a given UTF-8 string.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_uint32:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #guint32 to set within the type.
+ *
+ * Sets the attribute value to the given unsigned 32-bit integer.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_uint64:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #guint64 to set within the type.
+ *
+ * Sets the attribute value to a given unsigned 64-bit integer.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_add_match:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_rule: Argument to pass with the method invocation.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy.
+ * 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 then call _g_freedesktop_dbus_call_add_match_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_add_match_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_add_match().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_add_match_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_rule: Argument to pass with the method invocation.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ *
+ * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy.
+ * 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 then call _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ *
+ * See _g_freedesktop_dbus_call_get_connection_selinux_security_context() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_unix_process_id:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy.
+ * 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 then call _g_freedesktop_dbus_call_get_connection_unix_process_id_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_pid: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_unix_process_id_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_pid: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ *
+ * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_unix_user:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
+ * @user_data: User data to pass to @callback.
+ *
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy.
+ * 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 then call _g_freedesktop_dbus_call_get_connection_unix_user_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_unix_user_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_uid: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_user().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_connection_unix_user_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_uid: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ *
+ * See _g_freedesktop_dbus_call_get_connection_unix_user() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_call_get_id:
+ * @proxy: A #_GFreedesktopDBusProxy.
* @cancellable: (allow-none): A #GCancellable or %NULL.
* @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
* @user_data: User data to pass to @callback.
/**
* _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.
*
* 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.
*/
* 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
*/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
* Since: 2.28
*/
* possible for an action to be removed and for a new action to be added
* with the same name but a different parameter type.
*
- * Returns: the parameter type
+ * Returns: (nullable): the parameter type
* Since: 2.28
*/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (allow-none): the current state of the action
+ * Returns: (nullable): the current state of the action
* Since: 2.28
*/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
* Since: 2.28
*/
* possible for an action to be removed and for a new action to be added
* with the same name but a different state type.
*
- * Returns: (transfer full): the state type, if the action is stateful
+ * Returns: (nullable) (transfer full): the state type, if the action
+ * is stateful
* Since: 2.28
*/
* 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
*/
/**
* 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
*
*
* 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,
*
* return G_ACTION_GROUP (group);
* }
- * </programlisting>
- * </example>
+ * ]|
*
* Since: 2.32
*/
/**
- * g_app_info_add_supports_type:
- * @appinfo: a #GAppInfo.
- * @content_type: a string.
- * @error: a #GError.
+ * g_action_name_is_valid:
+ * @action_name: an potential action name
*
- * Adds a content type to the application information to indicate the
- * application is capable of opening files with the given content type.
+ * Checks if @action_name is valid.
*
- * Returns: %TRUE on success, %FALSE on error.
- */
-
-
-/**
- * g_app_info_can_delete:
- * @appinfo: a #GAppInfo
+ * @action_name is valid if it consists only of alphanumeric characters,
+ * plus '-' and '.'. The empty string is not a valid action name.
*
- * Obtains the information whether the #GAppInfo can be deleted.
- * See g_app_info_delete().
+ * It is an error to call this function with a non-utf8 @action_name.
+ * @action_name must not be %NULL.
*
- * Returns: %TRUE if @appinfo can be deleted
- * Since: 2.20
+ * Returns: %TRUE if @action_name is valid
+ * Since: 2.38
*/
/**
- * g_app_info_can_remove_supports_type:
+ * 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.
+ * @error: a #GError.
+ *
+ * Adds a content type to the application information to indicate the
+ * application is capable of opening files with the given content type.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ */
+
+
+/**
+ * g_app_info_can_delete:
+ * @appinfo: a #GAppInfo
+ *
+ * Obtains the information whether the #GAppInfo can be deleted.
+ * See g_app_info_delete().
+ *
+ * Returns: %TRUE if @appinfo can be deleted
+ * Since: 2.20
+ */
+
+
+/**
+ * g_app_info_can_remove_supports_type:
* @appinfo: a #GAppInfo.
*
* 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.
*/
* 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.
*
/**
- * 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
*/
* @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.
*/
* 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.
*/
* 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.
*/
* 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
*/
/**
* 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.
*/
*
* 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.
*/
* 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
*/
*
* 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
*/
* 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
*/
*
* 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.
*/
* 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
*/
/**
* g_app_info_get_supported_types:
- * @info: a #GAppInfo that can handle files
+ * @appinfo: a #GAppInfo that can handle files
*
* Retrieves the list of content types that @app_info claims to support.
* If this information is not provided by the environment, this function
* 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
*/
/**
* g_app_info_launch:
* @appinfo: a #GAppInfo
- * @files: (element-type GFile): a #GList of #GFile objects
+ * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
* @launch_context: (allow-none): a #GAppLaunchContext or %NULL
* @error: a #GError
*
* 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.
*/
/**
* g_app_info_launch_uris:
* @appinfo: a #GAppInfo
- * @uris: (element-type utf8): a #GList containing URIs to launch.
+ * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
* @launch_context: (allow-none): a #GAppLaunchContext or %NULL
* @error: a #GError
*
/**
+ * 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.
*
* 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.
*/
* 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
*/
* @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.
*/
/**
+ * g_application_add_main_option:
+ * @application: the #GApplication
+ * @long_name: the long name of an option used to specify it in a commandline
+ * @short_name: the short name of an option
+ * @flags: flags from #GOptionFlags
+ * @arg: the type of the option, as a #GOptionArg
+ * @description: the description for the option in `--help` output
+ * @arg_description: (nullable): the placeholder to use for the extra argument
+ * parsed by the option in `--help` output
+ *
+ * Add an option to be handled by @application.
+ *
+ * Calling this function is the equivalent of calling
+ * g_application_add_main_option_entries() with a single #GOptionEntry
+ * that has its arg_data member set to %NULL.
+ *
+ * The parsed arguments will be packed into a #GVariantDict which
+ * is passed to #GApplication::handle-local-options. If
+ * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
+ * be sent to the primary instance. See
+ * g_application_add_main_option_entries() for more details.
+ *
+ * See #GOptionEntry for more documentation of the arguments.
+ *
+ * Since: 2.42
+ */
+
+
+/**
+ * g_application_add_main_option_entries:
+ * @application: a #GApplication
+ * @entries: (array zero-terminated=1) (element-type GOptionEntry): 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_bind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Marks @application as busy (see g_application_mark_busy()) while
+ * @property on @object is %TRUE.
+ *
+ * The binding holds a reference to @application while it is active, but
+ * not to @object. Instead, the binding is destroyed when @object is
+ * finalized.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * 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
*/
* 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
*/
/**
+ * 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
*
*
* For local invocation, it will be %NULL.
*
- * Returns: (allow-none): the platform data, or %NULL
+ * Returns: (nullable): the platform data, or %NULL
* Since: 2.28
*/
/**
+ * 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
/**
+ * g_application_get_is_busy:
+ * @application: a #GApplication
+ *
+ * Gets the application's current busy state, as set through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Returns: %TRUE if @application is currenty marked as busy
+ * Since: 2.44
+ */
+
+
+/**
* g_application_get_is_registered:
* @application: a #GApplication
*
/**
+ * g_application_get_resource_base_path:
+ * @application: a #GApplication
+ *
+ * Gets the resource base path of @application.
+ *
+ * See g_application_set_resource_base_path() for more information.
+ *
+ * Returns: (nullable): the base resource path, if one is set
+ * Since: 2.42
+ */
+
+
+/**
* g_application_hold:
* @application: a #GApplication
*
*
* 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().
*
* 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.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
/**
+ * 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
* 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.
*/
/**
+ * g_application_set_resource_base_path:
+ * @application: a #GApplication
+ * @resource_path: (nullable): the resource path to use
+ *
+ * Sets (or unsets) the base resource path of @application.
+ *
+ * The path is used to automatically load various [application
+ * resources][gresource] such as menu layouts and action descriptions.
+ * The various types of resources will be found at fixed names relative
+ * to the given base path.
+ *
+ * By default, the resource base path is determined from the application
+ * ID by prefixing '/' and replacing each '.' with '/'. This is done at
+ * the time that the #GApplication object is constructed. Changes to
+ * the application ID after that point will not have an impact on the
+ * resource base path.
+ *
+ * As an example, if the application has an ID of "org.example.app" then
+ * the default resource base path will be "/org/example/app". If this
+ * is a #GtkApplication (and you have not manually changed the path)
+ * then Gtk will then search for the menus of the application at
+ * "/org/example/app/gtk/menus.ui".
+ *
+ * See #GResource for more information about adding resources to your
+ * application.
+ *
+ * You can disable automatic resource loading functionality by setting
+ * the path to %NULL.
+ *
+ * Changing the resource base path once the application is running is
+ * not recommended. The point at which the resource path is consulted
+ * for forming paths for various purposes is unspecified.
+ *
+ * Since: 2.42
+ */
+
+
+/**
+ * g_application_unbind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Destroys a binding between @property and the busy state of
+ * @application that was previously created with
+ * g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * 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
* 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
*/
/**
* 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.
* 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
*/
/**
* 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
* @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
*
* 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.
*/
/**
* g_async_result_is_tagged:
- * @result: a #GAsyncResult
+ * @res: a #GAsyncResult
* @source_tag: an application-defined tag
*
- * Checks if @result has the given @source_tag (generally a function
- * pointer indicating the function @result was created by).
+ * Checks if @res has the given @source_tag (generally a function
+ * pointer indicating the function @res was created by).
*
- * Returns: %TRUE if @result has the indicated @source_tag, %FALSE if not.
+ * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
+ * not.
* Since: 2.34
*/
/**
* g_async_result_legacy_propagate_error:
- * @result: a #GAsyncResult
- * @dest: (out): a location to propagate the error to.
+ * @res: a #GAsyncResult
+ * @error: (out): a location to propagate the error to.
*
- * If @result is a #GSimpleAsyncResult, this is equivalent to
+ * If @res is a #GSimpleAsyncResult, this is equivalent to
* 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
*/
* 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.
*/
* 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
/**
* 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
*
* 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
*/
*
* 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.
*/
/**
* 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.
*
/**
* 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().
*
* 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,
* 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
* 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.
*
* 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
* 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
*/
* 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_cancellable_cancel:
- * @cancellable: a #GCancellable object.
+ * g_bytes_icon_get_bytes:
+ * @icon: a #GIcon.
*
- * Will set @cancellable to cancelled, and will emit the
- * #GCancellable::cancelled signal. (However, see the warning about
- * race conditions in the documentation for that signal if you are
- * planning to connect to it.)
+ * Gets the #GBytes associated with the given @icon.
*
- * This function is thread-safe. In other words, you can safely call
- * it from a thread other than the one running the operation that was
+ * 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: (nullable): a #GCancellable object.
+ *
+ * Will set @cancellable to cancelled, and will emit the
+ * #GCancellable::cancelled signal. (However, see the warning about
+ * race conditions in the documentation for that signal if you are
+ * planning to connect to it.)
+ *
+ * This function is thread-safe. In other words, you can safely call
+ * it from a thread other than the one running the operation that was
* passed the @cancellable.
*
- * The convention within gio is that cancelling an asynchronous
+ * If @cancellable is %NULL, this function returns immediately for convenience.
+ *
+ * The convention within GIO is that cancelling an asynchronous
* operation causes it to complete asynchronously. That is, if you
* cancel the operation from the same thread in which it is running,
* then the operation's #GAsyncReadyCallback will not be invoked until
*
* 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
*/
*
* 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: (nullable) (transfer none): a #GCancellable from the top
+ * of the stack, or %NULL if the stack is empty.
*/
*
* 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.
*/
*
* 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.
*/
* 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
*/
*
* If cancellable is currently in use by any cancellable operation
* then the behavior of this function is undefined.
+ *
+ * Note that it is generally not a good idea to reuse an existing
+ * cancellable for more operations after it has been cancelled once,
+ * as this function might tempt you to do. The recommended practice
+ * is to drop the reference to a cancellable after cancelling it,
+ * and let it die with the outstanding async operations. You should
+ * create a fresh cancellable for further async operations.
*/
* For convenience, you can call this with a %NULL #GCancellable,
* in which case the source will never trigger.
*
+ * The new #GSource will hold a reference to the #GCancellable.
+ *
* Returns: (transfer full): the new #GSource.
* Since: 2.28
*/
* 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.
*/
*
* 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.
*/
*
* 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: (nullable): Newly allocated string with content type or
+ * %NULL. Free with g_free()
* Since: 2.18
*/
*
* 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()
+ */
+
+
+/**
+ * g_content_type_get_generic_icon_name:
+ * @type: a content type string
+ *
+ * Gets the generic icon name for a content type.
+ *
+ * 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()
+ * Since: 2.34
*/
*
* 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()
*/
*
* 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: (nullable): the registered mime type for the given @type,
+ * or %NULL if unknown.
+ */
+
+
+/**
+ * g_content_type_get_symbolic_icon:
+ * @type: a content type string
+ *
+ * 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()
+ * Since: 2.34
*/
* @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()
*/
*
* 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
*/
*
* 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.
*/
*
* 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
* 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.
* 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
*/
*
* 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
*
* 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.
*/
* 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.
*/
* 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.
*/
* 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.
*/
* 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: (nullable) (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.
* 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: (nullable) (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
*/
* 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: (nullable) (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
*/
* 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: (nullable) (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
*/
* 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.
*/
* 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.
*/
* 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.
*/
* 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.
*/
* 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.
* 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.
*/
* 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
* 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
*/
* 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
* 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
* 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
*/
/**
+ * 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
*/
*
* 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
/**
* 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.
*
/**
* 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
* 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
*
* 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",
* 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
/**
* 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: A unique or well-known bus name.
- * @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
*
* 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",
* 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.
/**
* 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: A unique or well-known bus name.
- * @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
* %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
/**
* 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.
*
*
* 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
*/
* 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).
*
/**
* 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
/**
* 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
* 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
* 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
*/
/**
* 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.
/**
* 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
/**
* 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
* 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.
* 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
*
* 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
* #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.
* 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
*/
/**
* 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.
*
* %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.
*
* 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.
* 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
*/
/**
* 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().
*
* 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
* 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
/**
* 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.
* 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.
*
/**
* 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
/**
* 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
*/
* 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().
*
/**
* 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
*/
* 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
*/
* @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
*/
/**
* 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
*/
/**
- * 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
*/
/**
* 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
*/
*
* 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
*
* 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.
*
* 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.
*
* 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.
*
* 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
*/
*
* 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.
*
*
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
* @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
* 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
*/
* (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
*/
* 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
*/
* 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
*/
*
* 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
*/
*
* Gets the body of a message.
*
- * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
+ * Returns: (transfer none): A #GVariant or %NULL if the body is
+ * empty. Do not free, it is owned by @message.
* Since: 2.26
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
* 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
*/
/**
* 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.
/**
* 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.
*
/**
* 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.
/**
* 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.
*
/**
- * g_dbus_message_print:
+ * g_dbus_message_print: (type method-return)
* @message: A #GDBusMessage.
* @indent: Indentation level.
*
* 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
/**
* 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.
*
* 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
*/
*
* 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
*/
* 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
*
* 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
*/
/**
+ * 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.
*
* 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.
* 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
*/
*
* 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
*
* Parses @xml_data and returns a #GDBusNodeInfo representing the data.
*
+ * The introspection XML must contain exactly one top-level
+ * <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
*/
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
* 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
*/
* #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: (nullable): The name owner or %NULL if no name owner
+ * exists. Free with g_free().
* Since: 2.30
*/
*
* 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.
*
* 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
*/
*
* 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.
*
* 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
*/
* 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
*/
* 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.
* 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
*/
* 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
*/
*
* 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
*/
*
* 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
*/
* @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
*/
*
* 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
*/
*
* 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
*/
* @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.
*
* 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)",
* -1,
* NULL,
* (GAsyncReadyCallback) two_strings_done,
- * &data);
+ * &data);
* ]|
*
* If @proxy has an expected interface (see
*
* 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
*
* 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
*/
* 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.
*
*
* 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)",
* G_DBUS_CALL_FLAGS_NONE,
* -1,
* NULL,
- * &error);
+ * &error);
* ]|
*
* The calling thread is blocked until a reply is received. See
* #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
*/
* @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.
*
* 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
*/
* 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.
*
* 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
*/
* #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
*/
*
* 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
*/
* 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
*/
* 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
*
* 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
*/
*
* 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
*/
* 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.
*
* 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
* 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
*
* 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)",
* 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
*/
* 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
*/
* 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
*/
/**
- * g_desktop_app_info_get_categories:
+ * 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 categories from the desktop file.
+ * 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: The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it.
+ * 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.
*/
/**
+ * g_desktop_app_info_get_implementations:
+ * @interface: the name of the interface
+ *
+ * Gets all applications that implement @interface.
+ *
+ * An application implements an interface if that interface is listed in
+ * the Implements= line of the desktop file of the application.
+ *
+ * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo
+ * objects.
+ * Since: 2.42
+ */
+
+
+/**
* g_desktop_app_info_get_is_hidden:
* @info: a #GDesktopAppInfo.
*
/**
* g_desktop_app_info_get_show_in:
* @info: a #GDesktopAppInfo
- * @desktop_env: a string specifying a desktop name
+ * @desktop_env: (nullable): a string specifying a desktop name
*
* 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.
+ * @desktop_env should typically be given as %NULL, in which case the
+ * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
+ * to override the default mechanism then you may specify @desktop_env,
+ * but this is not recommended.
*
* 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
*/
/**
* g_desktop_app_info_get_startup_wm_class:
- * @app_info: a #GDesktopAppInfo that supports startup notify
+ * @info: a #GDesktopAppInfo that supports startup notify
*
- * Retrieves the StartupWMClass field from @app_info. This represents the
- * WM_CLASS property of the main window of the application, if launched through
- * @app_info.
+ * Retrieves the StartupWMClass field from @info. This represents the
+ * 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(),
* 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.
*
* 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
*/
/**
+ * 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>
- *
* Should be called only once; subsequent calls are ignored.
+ *
+ * Deprecated: 2.42: do not use this API. Since 2.42 the value of the
+ * `XDG_CURRENT_DESKTOP` environment variable will be used.
*/
*
* 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.
*/
*
* 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.
*/
* 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.
* 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.
* 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.
*/
*
* 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().
*/
*
* 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.
*/
*
* 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.
*/
/**
+ * g_drive_get_symbolic_icon:
+ * @drive: a #GDrive.
+ *
+ * Gets the icon for @drive.
+ *
+ * Returns: (transfer full): symbolic #GIcon for the @drive.
+ * Free the returned object with g_object_unref().
+ * Since: 2.34
+ */
+
+
+/**
* g_drive_get_volumes:
* @drive: a #GDrive.
*
*
* 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.
*/
*
* 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.
*/
* 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
*
* 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
*/
* 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
*
* 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
*/
*
* 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
*/
* @emblemed: a #GEmblemedIcon
* @emblem: a #GEmblem
*
- * Adds @emblem to the #GList of #GEmblem <!-- -->s.
+ * Adds @emblem to the #GList of #GEmblems.
*
* Since: 2.18
*/
*
* 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
*/
/**
* g_file_append_to:
- * @file: input #GFile.
- * @flags: a set of #GFileCreateFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @file: input #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
* @error: a #GError, or %NULL
*
- * Gets an output stream for appending data to the file. If
- * the file doesn't already exist it is created.
+ * Gets an output stream for appending data to the file.
+ * If the file doesn't already exist it is created.
*
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
* will be made readable only to the current user, to the level that
* is supported on the target filesystem.
*
- * 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 @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.
*
- * Some file systems don't allow all file names, and may
- * return an %G_IO_ERROR_INVALID_FILENAME error.
- * If the file is a directory the %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.
+ * Some file systems don't allow all file names, and may return an
+ * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the
+ * %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().
*/
/**
* 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
+ * @file: input #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @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.
* For more details, see g_file_append_to() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_append_to_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_append_to_finish() to get the result
+ * of the operation.
*/
/**
* g_file_append_to_finish:
- * @file: input #GFile.
+ * @file: input #GFile
* @res: #GAsyncResult
* @error: a #GError, or %NULL
*
* 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().
*/
*
* 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.
*/
*
* 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.
*/
*
* 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.
*/
* @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.
* 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
*/
* 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
*/
* 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
*/
/**
+ * g_file_attribute_value_dup:
+ * @other: a #GFileAttributeValue to duplicate.
+ *
+ * Duplicates a file attribute.
+ *
+ * Returns: a duplicate of the @other.
+ */
+
+
+/**
+ * g_file_attribute_value_set:
+ * @attr: a #GFileAttributeValue to set the value in.
+ * @new_value: a #GFileAttributeValue to get the value from.
+ *
+ * Sets an attribute's value from another attribute.
+ */
+
+
+/**
* g_file_copy:
- * @source: input #GFile.
+ * @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
*
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * If @progress_callback is not %NULL, then the operation can be monitored by
- * setting this to a #GFileProgressCallback function. @progress_callback_data
- * will be passed to this function. It is guaranteed that this callback will
- * be called after all data has been transferred with the total number of bytes
- * copied during the operation.
+ * If @progress_callback is not %NULL, then the operation can be monitored
+ * by setting this to a #GFileProgressCallback function.
+ * @progress_callback_data will be passed to this function. It is guaranteed
+ * that this callback will be called after all data has been transferred with
+ * the total number of bytes copied during the operation.
*
- * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND
- * error is returned, independent on the status of the @destination.
+ * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error
+ * is returned, independent on the status of the @destination.
*
- * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the
- * error G_IO_ERROR_EXISTS is returned.
+ * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
+ * the error %G_IO_ERROR_EXISTS is returned.
*
- * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY
+ * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
* error is returned. If trying to overwrite a directory with a directory the
- * G_IO_ERROR_WOULD_MERGE error is returned.
+ * %G_IO_ERROR_WOULD_MERGE error is returned.
*
* If the source is a directory and the target does not exist, or
* #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
- * G_IO_ERROR_WOULD_RECURSE error is returned.
+ * %G_IO_ERROR_WOULD_RECURSE error is returned.
*
* If you are interested in copying the #GFile object itself (not the on-disk
* file), see g_file_dup().
/**
* g_file_copy_async: (skip)
- * @source: input #GFile.
+ * @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
* asynchronously. For details of the behaviour, see g_file_copy().
*
* If @progress_callback is not %NULL, then that function that will be called
- * just like in g_file_copy(), however the callback will run in the main loop,
- * not in the thread that is doing the I/O operation.
+ * just like in g_file_copy(). The callback will run in the default main context
+ * of the thread calling g_file_copy_async() — the same context as @callback is
+ * run in.
*
* When the operation is finished, @callback will be called. You can then call
* g_file_copy_finish() to get the result of the operation.
/**
* g_file_copy_attributes:
- * @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.
- * @error: a #GError, %NULL to ignore.
+ * @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
+ * @error: a #GError, %NULL to ignore
*
* Copies the file attributes from @source to @destination.
*
* 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.
*/
/**
* g_file_copy_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
- * Finishes copying the file started with
- * g_file_copy_async().
+ * Finishes copying the file started with g_file_copy_async().
*
* Returns: a %TRUE on success, %FALSE on error.
*/
/**
* g_file_create:
- * @file: input #GFile.
- * @flags: a set of #GFileCreateFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @file: input #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @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.
*
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
- * will be made readable only to the current user, to the level that
- * is supported on the target filesystem.
+ * will be made readable only to the current user, to the level
+ * that is supported on the target filesystem.
*
- * 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 @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 a file or directory with this name already exists the G_IO_ERROR_EXISTS
- * error will be returned.
- * Some file systems don't allow all file names, and may
- * return an G_IO_ERROR_INVALID_FILENAME error, and if the name
- * is to long 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.
+ * If a file or directory with this name already exists the
+ * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
+ * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
+ * error, and if the name is to long %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 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().
*/
/**
* 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
+ * @file: input #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @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 for writing to it.
- * The file must not already exist.
+ * Asynchronously creates a new file and returns an output stream
+ * for writing to it. The file must not already exist.
*
* For more details, see g_file_create() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_create_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_create_finish() to get the result
+ * of the operation.
*/
/**
* g_file_create_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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().
*/
* 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 writing to it.
- * The file must not already exist.
+ * Creates a new file and returns a stream for reading and
+ * writing to it. The file must not already exist.
*
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
- * will be made readable only to the current user, to the level that
- * is supported on the target filesystem.
+ * will be made readable only to the current user, to the level
+ * that is supported on the target filesystem.
*
- * 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 @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 a file or directory with this name already exists the %G_IO_ERROR_EXISTS
- * error will be returned. Some file systems don't allow all file names,
- * and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name
- * is too long, %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.
+ * If a file or directory with this name already exists, the
+ * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't
+ * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME
+ * error, and if the name is too long, %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.
*
- * Note that in many non-local file cases read and write streams are not
- * supported, so make sure you really need to do read and write streaming,
- * rather than just opening for reading or writing.
+ * Note that in many non-local file cases read and write streams are
+ * 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
*/
* 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 for reading and
- * writing to it. The file must not already exist.
+ * Asynchronously creates a new file and returns a stream
+ * for reading and writing to it. The file must not already exist.
*
* For more details, see g_file_create_readwrite() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then
- * call g_file_create_readwrite_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_create_readwrite_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
* 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:
- * @file: input #GFile.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * g_file_delete: (virtual delete_file)
+ * @file: input #GFile
+ * @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 deleted if it
- * is empty.
+ * Deletes 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().
*
* 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.
*
- * Virtual: delete_file
* Returns: %TRUE if the file was deleted. %FALSE otherwise.
*/
/**
+ * g_file_delete_async: (virtual delete_file_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 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().
+ *
+ * Since: 2.34
+ */
+
+
+/**
+ * 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().
+ *
+ * Returns: %TRUE if the file was deleted. %FALSE otherwise.
+ * Since: 2.34
+ */
+
+
+/**
* g_file_descriptor_based_get_fd:
* @fd_based: a #GFileDescriptorBased.
*
/**
* g_file_dup:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Duplicates a #GFile handle. This operation does not duplicate
* the actual file or directory represented by the #GFile; see
* g_file_copy() if attempting to copy a file.
*
- * This call does no blocking i/o.
+ * 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.
*/
/**
* g_file_eject_mountable:
- * @file: input #GFile.
+ * @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.
/**
* g_file_eject_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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.
*/
/**
* g_file_eject_mountable_with_operation:
- * @file: input #GFile.
+ * @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.
/**
* g_file_eject_mountable_with_operation_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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
*/
/**
* g_file_enumerate_children:
- * @file: input #GFile.
- * @attributes: an attribute query string.
- * @flags: a set of #GFileQueryInfoFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Gets the requested information about the files in a directory. The result
- * is a #GFileEnumerator object that will give out #GFileInfo objects for
- * all the files in the directory.
- *
- * The @attributes value is a string that specifies the file attributes that
- * should be gathered. It is not an error if it's not possible to read a particular
- * requested attribute from a file - it just won't be set. @attributes should
- * be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
- * means all attributes, and a wildcard like "standard::*" means all attributes in the standard
- * namespace. An example attribute query be "standard::*,owner::user".
- * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME.
+ * @file: input #GFile
+ * @attributes: an attribute query string
+ * @flags: a set of #GFileQueryInfoFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: #GError for error reporting
*
- * 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.
+ * Gets the requested information about the files in a directory.
+ * The result is a #GFileEnumerator object that will give out
+ * #GFileInfo objects for all the files in the directory.
+ *
+ * The @attributes value is a string that specifies the file
+ * attributes that should be gathered. It is not an error if
+ * it's not possible to read a particular requested attribute
+ * from a file - it just won't be set. @attributes should
+ * be a comma-separated list of attributes or attribute wildcards.
+ * The wildcard "*" means all attributes, and a wildcard like
+ * "standard::*" means all attributes in the standard namespace.
+ * An example attribute query be "standard::*,owner::user".
+ * The standard attributes are available as defines, like
+ * #G_FILE_ATTRIBUTE_STANDARD_NAME.
+ *
+ * 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 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 error will be returned.
- * Other errors are possible too.
+ * 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_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().
*/
/**
* g_file_enumerate_children_async:
- * @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
+ * @file: input #GFile
+ * @attributes: an attribute query string
+ * @flags: a set of #GFileQueryInfoFlags
+ * @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 in a directory. The result
- * is a #GFileEnumerator object that will give out #GFileInfo objects for
- * all the files in the directory.
+ * Asynchronously gets the requested information about the files
+ * in a directory. The result is a #GFileEnumerator object that will
+ * give out #GFileInfo objects for all the files in the directory.
*
* For more details, see g_file_enumerate_children() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_enumerate_children_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called. You can
+ * then call g_file_enumerate_children_finish() to get the result of
+ * the operation.
*/
/**
* g_file_enumerate_children_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
* 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().
*/
/**
* 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
* 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().
*
/**
+ * 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
*
/**
+ * g_file_enumerator_iterate:
+ * @direnum: an open #GFileEnumerator
+ * @out_info: (out) (transfer none) (allow-none): Output location for the next #GFileInfo, or %NULL
+ * @out_child: (out) (transfer none) (allow-none): Output location for the next #GFile, or %NULL
+ * @cancellable: a #GCancellable
+ * @error: a #GError
+ *
+ * This is a version of g_file_enumerator_next_file() that's easier to
+ * use correctly from C programs. With g_file_enumerator_next_file(),
+ * the gboolean return value signifies "end of iteration or error", which
+ * requires allocation of a temporary #GError.
+ *
+ * In contrast, with this function, a %FALSE return from
+ * gs_file_enumerator_iterate() *always* means
+ * "error". End of iteration is signaled by @out_info or @out_child being %NULL.
+ *
+ * Another crucial difference is that the references for @out_info and
+ * @out_child are owned by @direnum (they are cached as hidden
+ * properties). You must not unref them in your own code. This makes
+ * memory management significantly easier for C code in combination
+ * with loops.
+ *
+ * Finally, this function optionally allows retrieving a #GFile as
+ * well.
+ *
+ * You must specify at least one of @out_info or @out_child.
+ *
+ * The code pattern for correctly using g_file_enumerator_iterate() from C
+ * is:
+ *
+ * |[
+ * direnum = g_file_enumerate_children (file, ...);
+ * while (TRUE)
+ * {
+ * GFileInfo *info;
+ * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
+ * goto out;
+ * if (!info)
+ * break;
+ * ... do stuff with "info"; do not unref it! ...
+ * }
+ *
+ * out:
+ * g_object_unref (direnum); // Note: frees the last @info
+ * ]|
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_file_enumerator_next_file:
* @enumerator: a #GFileEnumerator.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* 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: (nullable) (transfer full): A #GFileInfo or %NULL on error
+ * or end of enumerator. Free the returned object with
+ * g_object_unref() when no longer needed.
*/
* 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
* 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
* 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 #GFileInfos. You must free the list with
+ * g_list_free() and unref the infos with g_object_unref() when you're
+ * done with them.
*/
/**
* g_file_equal:
- * @file1: the first #GFile.
- * @file2: the second #GFile.
+ * @file1: the first #GFile
+ * @file2: the second #GFile
*
- * Checks equality of two given #GFile<!-- -->s. Note that two
- * #GFile<!-- -->s that differ can still refer to the same
+ * Checks if the two given #GFiles refer to the same file.
+ *
+ * Note that two #GFiles that differ can still refer to the same
* file on the filesystem due to various forms of filename
* aliasing.
*
- * This call does no blocking i/o.
+ * 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.
*/
/**
* g_file_find_enclosing_mount:
- * @file: input #GFile.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError
*
* Gets a #GMount for the #GFile.
*
- * If the #GFileIface for @file does not have a mount (e.g. possibly a
- * remote share), @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL
- * will be returned.
+ * If the #GFileIface for @file does not have a mount (e.g.
+ * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND
+ * and %NULL will be returned.
*
* 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: (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.
* For more details, see g_file_find_enclosing_mount() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_find_enclosing_mount_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_find_enclosing_mount_finish() to
+ * get the result of the operation.
*/
* 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().
*/
/**
* g_file_get_basename:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Gets the base name (the last component of the path) for a given #GFile.
*
* or a uri like sftp://host/) it will return a single directory separator
* (and on Windows, possibly a drive letter).
*
- * The base name is a byte string (*not* UTF-8). It has no defined encoding
+ * The base name is a byte string (not UTF-8). It has no defined encoding
* or rules other than it may not contain zero bytes. If you want to use
* filenames in a user interface you should use the display name that you
* can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
* attribute with g_file_query_info().
*
- * This call does no blocking i/o.
+ * 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: (nullable): 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.
*/
/**
* g_file_get_child:
- * @file: input #GFile.
- * @name: string containing the child's basename.
+ * @file: input #GFile
+ * @name: string containing the child's basename
*
* Gets a child of @file with basename equal to @name.
*
* you can still have a #GFile that points to it. You can use this
* for instance to create that file.
*
- * This call does no blocking i/o.
+ * 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().
*/
/**
* g_file_get_child_for_display_name:
- * @file: input #GFile.
- * @display_name: string to a possible child.
- * @error: #GError.
+ * @file: input #GFile
+ * @display_name: string to a possible child
+ * @error: return location for an error
*
- * Gets the child of @file for a given @display_name (i.e. a UTF8
- * version of the name). If this function fails, it returns %NULL and @error will be
- * set. This is very useful when constructing a GFile for a new file
- * and the user entered the filename in the user interface, for instance
- * when you select a directory and type a filename in the file selector.
+ * Gets the child of @file for a given @display_name (i.e. a UTF-8
+ * version of the name). If this function fails, it returns %NULL
+ * and @error will be set. This is very useful when constructing a
+ * #GFile for a new file and the user entered the filename in the
+ * user interface, for instance when you select a directory and
+ * type a filename in the file selector.
*
- * This call does no blocking i/o.
+ * 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().
*/
/**
* g_file_get_parent:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Gets the parent directory for the @file.
* If the @file represents the root directory of the
* file system, then %NULL will be returned.
*
- * This call does no blocking i/o.
+ * 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: (nullable) (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().
*/
/**
* g_file_get_parse_name:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Gets the parse name of the @file.
* A parse name is a UTF-8 string that describes the
* like in a location entry.
*
* For local files with names that can safely be converted
- * to UTF8 the pathname is used, otherwise the IRI is used
- * (a form of URI that allows UTF8 characters unescaped).
+ * to UTF-8 the pathname is used, otherwise the IRI is used
+ * (a form of URI that allows UTF-8 characters unescaped).
*
- * This call does no blocking i/o.
+ * 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.
*/
/**
* g_file_get_path:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Gets the local pathname for #GFile, if one exists.
*
- * This call does no blocking i/o.
+ * 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: (nullable): 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.
*/
/**
* g_file_get_relative_path:
- * @parent: input #GFile.
- * @descendant: input #GFile.
+ * @parent: input #GFile
+ * @descendant: input #GFile
*
* Gets the path for @descendant relative to @parent.
*
- * This call does no blocking i/o.
+ * 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: (nullable): 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.
*/
/**
* g_file_get_uri:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Gets the URI for the @file.
*
- * This call does no blocking i/o.
+ * 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.
*/
/**
* g_file_get_uri_scheme:
- * @file: input #GFile.
+ * @file: input #GFile
*
* 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.
+ * 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.
*/
* 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:
- * @file: input #GFile.
- * @prefix: input #GFile.
+ * g_file_has_prefix: (virtual prefix_matches)
+ * @file: input #GFile
+ * @prefix: input #GFile
*
- * Checks whether @file has the prefix specified by @prefix. In other word,
- * if the names of initial elements of @file<!-- -->s pathname match @prefix.
- * Only full pathname elements are matched, so a path like /foo is not
- * considered a prefix of /foobar, only of /foo/bar.
+ * Checks whether @file has the prefix specified by @prefix.
*
- * This call does no i/o, as it works purely on names. As such it can
+ * In other words, if the names of initial elements of @file's
+ * pathname match @prefix. Only full pathname elements are matched,
+ * so a path like /foo is not considered a prefix of /foobar, only
+ * of /foo/bar.
+ *
+ * A #GFile is not a prefix of itself. If you want to check for
+ * equality, use g_file_equal().
+ *
+ * This call does no I/O, as it works purely on names. As such it can
* sometimes return %FALSE even if @file is inside a @prefix (from a
* 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.
*/
/**
* g_file_has_uri_scheme:
- * @file: input #GFile.
- * @uri_scheme: a string containing a URI scheme.
+ * @file: input #GFile
+ * @uri_scheme: a string containing a URI scheme
*
* Checks to see if a #GFile has a given URI scheme.
*
- * This call does no blocking i/o.
+ * 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:
- * @file: (type GFile): #gconstpointer to a #GFile.
+ * 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.
+ * 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.
*/
*
* 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.
*/
* @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.
*/
* 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().
*/
* 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.
*/
*
* 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.
*/
* 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.
*/
*
* 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.
*/
* 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.
*/
* 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
*/
*
* 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.
*/
/**
+ * 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.
*
* 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.
/**
+ * g_file_info_get_symbolic_icon:
+ * @info: a #GFileInfo.
+ *
+ * Gets the symbolic icon for a file.
+ *
+ * Returns: (transfer none): #GIcon for the given @info.
+ * Since: 2.34
+ */
+
+
+/**
* g_file_info_get_symlink_target:
* @info: a #GFileInfo.
*
*
* 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.
*/
* 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
*/
*
* 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: (nullable) (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.
*/
/**
* 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.
* @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.
*/
/**
+ * g_file_info_set_symbolic_icon:
+ * @info: a #GFileInfo.
+ * @icon: a #GIcon.
+ *
+ * Sets the symbolic icon for a given #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
+ *
+ * Since: 2.34
+ */
+
+
+/**
* g_file_info_set_symlink_target:
* @info: a #GFileInfo.
* @symlink_target: a static string containing a path to a symlink target.
* @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
* 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
* 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.
*
* 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
/**
* g_file_is_native:
- * @file: input #GFile.
+ * @file: input #GFile
*
* Checks to see if a file is native to the platform.
*
* e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
* as it might be on a locally mounted remote filesystem.
*
- * On some systems non-native files may be available using
- * the native filesystem via a userspace filesystem (FUSE), in
- * these cases this call will return %FALSE, but g_file_get_path()
- * will still return a native path.
+ * On some systems non-native files may be available using the native
+ * filesystem via a userspace filesystem (FUSE), in these cases this call
+ * will return %FALSE, but g_file_get_path() will still return a native path.
*
- * This call does no blocking i/o.
+ * This call does no blocking I/O.
*
- * Returns: %TRUE if file is native.
+ * Returns: %TRUE if @file is native
*/
/**
* g_file_load_contents:
- * @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
+ * @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
* @error: a #GError, or %NULL
*
* Loads the content of the file into memory. The data is always
* 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.
*/
/**
* g_file_load_contents_async:
- * @file: input #GFile.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @file: input #GFile
+ * @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
*
/**
* g_file_load_contents_finish:
- * @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
+ * @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
* @error: a #GError, or %NULL
*
* Finishes an asynchronous load of the @file's contents.
* 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.
*/
/**
* 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.
+ * @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
* @callback: a #GAsyncReadyCallback to call when the request is satisfied
- * @user_data: the data to pass to the callback functions.
+ * @user_data: the data to pass to the callback functions
*
- * Reads the partial contents of a file. A #GFileReadMoreCallback should be
- * used to stop reading from the file when appropriate, else this function
- * will behave exactly as g_file_load_contents_async(). This operation
- * can be finished by g_file_load_partial_contents_finish().
+ * Reads the partial contents of a file. A #GFileReadMoreCallback should
+ * be used to stop reading from the file when appropriate, else this
+ * function will behave exactly as g_file_load_contents_async(). This
+ * operation can be finished by g_file_load_partial_contents_finish().
*
* Users of this function should be aware that @user_data is passed to
* both the @read_more_callback and the @callback.
/**
* g_file_load_partial_contents_finish:
- * @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
+ * @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
* @error: a #GError, or %NULL
*
* Finishes an asynchronous partial load operation that was started
* 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.
+ * @file: input #GFile
+ * @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 of
- * the immediate parent directory of the path or URI given by the #GFile. To
- * recursively create directories, see g_file_make_directory_with_parents().
+ * Creates a directory. Note that this will only create a child directory
+ * of the immediate parent directory of the path or URI given by the #GFile.
+ * To recursively create directories, see g_file_make_directory_with_parents().
* This function will fail if the parent directory does not exist, setting
- * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support creating
- * directories, this function will fail, setting @error to
+ * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support
+ * creating directories, this function will fail, setting @error to
* %G_IO_ERROR_NOT_SUPPORTED.
*
* For a local #GFile the newly created directory will have the default
/**
+ * 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.
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
* @error: a #GError, or %NULL
*
- * Creates a directory and any parent directories that may not exist similar to
- * 'mkdir -p'. If the file system does not support creating directories, this
- * function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the
- * directory itself already exists, this function will fail setting @error
- * to %G_IO_ERROR_EXISTS, unlike the similar g_mkdir_with_parents().
+ * Creates a directory and any parent directories that may not
+ * exist similar to 'mkdir -p'. If the file system does not support
+ * creating directories, this function will fail, setting @error to
+ * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists,
+ * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike
+ * the similar g_mkdir_with_parents().
*
* For a local #GFile the newly created directories will have the default
* (current) ownership and permissions of the current process.
* 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
*/
* 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.
- * @error: a #GError.
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError
*
* Creates a symbolic link named @file which contains the string
* @symlink_value.
/**
+ * 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, depending
- * on the type of the file.
+ * Obtains a file or directory monitor for the given file,
+ * depending on the type of the file.
*
* 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: (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
*/
/**
- * g_file_monitor_directory:
- * @file: input #GFile.
- * @flags: a set of #GFileMonitorFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL.
+ * g_file_monitor_directory: (virtual monitor_dir)
+ * @file: input #GFile
+ * @flags: a set of #GFileMonitorFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
* Obtains a directory monitor for the given file.
* This may fail if directory monitoring is not supported.
* 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().
*/
* 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]).
*/
/**
* g_file_monitor_file:
- * @file: input #GFile.
- * @flags: a set of #GFileMonitorFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL.
+ * @file: input #GFile
+ * @flags: a set of #GFileMonitorFlags
+ * @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
* mechanism exists, then regular polling of the file is used.
* 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().
*/
/**
* 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.
/**
* g_file_mount_enclosing_volume:
- * @location: input #GFile.
+ * @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 the file @location.
+ * Starts a @mount_operation, mounting the volume that contains
+ * the file @location.
*
* When this operation has completed, @callback will be called with
* @user_user data, and the operation can be finalized with
/**
* g_file_mount_enclosing_volume_finish:
- * @location: input #GFile.
- * @result: a #GAsyncResult.
+ * @location: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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.
*/
/**
* g_file_mount_mountable:
- * @file: input #GFile.
+ * @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.
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_mount_mountable_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_mount_mountable_finish() to get
+ * the result of the operation.
*/
/**
* g_file_mount_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* Finishes a mount operation. See g_file_mount_mountable() for details.
* 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().
*/
/**
* g_file_move:
- * @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.
+ * @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
* @error: #GError for returning error conditions, or %NULL
*
- * Tries to move the file or directory @source to the location specified by @destination.
- * If native move operations are supported then this is used, otherwise a copy + delete
- * fallback is used. The native implementation may support moving directories (for instance
- * on moves inside the same filesystem), but the fallback code does not.
+ * Tries to move the file or directory @source to the location specified
+ * by @destination. If native move operations are supported then this is
+ * used, otherwise a copy + delete fallback is used. The native
+ * implementation may support moving directories (for instance on moves
+ * inside the same filesystem), but the fallback code does not.
*
* If the flag #G_FILE_COPY_OVERWRITE is specified an already
* existing @destination file is overwritten.
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * If @progress_callback is not %NULL, then the operation can be monitored by
- * setting this to a #GFileProgressCallback function. @progress_callback_data
- * will be passed to this function. It is guaranteed that this callback will
- * be called after all data has been transferred with the total number of bytes
- * copied during the operation.
+ * If @progress_callback is not %NULL, then the operation can be monitored
+ * by setting this to a #GFileProgressCallback function.
+ * @progress_callback_data will be passed to this function. It is
+ * guaranteed that this callback will be called after all data has been
+ * transferred with the total number of bytes copied during the operation.
*
- * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND
+ * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND
* error is returned, independent on the status of the @destination.
*
- * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the
- * error G_IO_ERROR_EXISTS is returned.
+ * If #G_FILE_COPY_OVERWRITE is not specified and the target exists,
+ * then the error %G_IO_ERROR_EXISTS is returned.
*
- * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY
+ * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY
* error is returned. If trying to overwrite a directory with a directory the
- * G_IO_ERROR_WOULD_MERGE error is returned.
+ * %G_IO_ERROR_WOULD_MERGE error is returned.
*
- * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is
- * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error
- * may be returned (if the native move operation isn't available).
+ * If the source is a directory and the target does not exist, or
+ * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then
+ * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native
+ * move operation isn't available).
*
* Returns: %TRUE on successful move, %FALSE otherwise.
*/
/**
* g_file_new_for_commandline_arg:
- * @arg: a command line string.
+ * @arg: a command line string
+ *
+ * Creates a #GFile with the given argument from the command line.
+ * The value of @arg can be either a URI, an absolute path or a
+ * relative path resolved relative to the current working directory.
+ * This operation never fails, but the returned object might not
+ * support any I/O operation if @arg points to a malformed path.
+ *
+ * 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.
*
- * Creates a #GFile with the given argument from the command line. The value of
- * @arg can be either a URI, an absolute path or a relative path resolved
- * relative to the current working directory.
- * This operation never fails, but the returned object might not support any
- * I/O operation if @arg points to a malformed path.
+ * 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.
*
- * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref().
+ * 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().
*/
/**
* g_file_new_for_uri:
- * @uri: a UTF8 string containing a URI.
+ * @uri: a UTF-8 string containing a URI
*
* Constructs a #GFile for a given URI. This operation never
* fails, but the returned object might not support any I/O
* 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.
- * @iostream: (out): on return, a #GFileIOStream for the created file.
+ * @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
*
* Opens a file in the preferred directory for temporary files (as
* 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
*/
* @error: a #GError, or %NULL
*
* Opens an existing file for reading and writing. The result is
- * a #GFileIOStream that can be used to read and write the contents of the file.
+ * a #GFileIOStream that can be used to read and write the contents
+ * of the file.
*
- * 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 @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 the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
- * If the file is a directory, the 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.
- * Note that in many non-local file cases read and write streams are not supported,
- * so make sure you really need to do read and write streaming, rather than
- * just opening for reading or writing.
+ * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+ * be returned. If the file is a directory, the %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. Note that in many non-local
+ * file cases read and write streams are 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): #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
*/
/**
* 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
+ * @file: input #GFile
+ * @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.
* For more details, see g_file_open_readwrite() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_open_readwrite_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_open_readwrite_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
* g_file_open_readwrite_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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
*/
* 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
/**
* g_file_parse_name:
- * @parse_name: a file name or path to be parsed.
+ * @parse_name: a file name or path to be parsed
*
- * Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()).
- * This operation never fails, but the returned object might not support any I/O
- * operation if the @parse_name cannot be parsed.
+ * Constructs a #GFile with the given @parse_name (i.e. something
+ * given by g_file_get_parse_name()). This operation never fails,
+ * but the returned object might not support any I/O operation if
+ * the @parse_name cannot be parsed.
*
* Returns: (transfer full): a new #GFile.
*/
/**
* 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.
+ * @file: input #GFile
+ * @cancellable: 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
*
- * Polls a file of type G_FILE_TYPE_MOUNTABLE.
+ * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
*
* 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.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_mount_mountable_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_mount_mountable_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
* g_file_poll_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* Finishes a poll operation. See g_file_poll_mountable() for details.
* 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
*/
/**
* g_file_query_default_handler:
- * @file: a #GFile to open.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @file: a #GFile to open
+ * @cancellable: optional #GCancellable object, %NULL to ignore
* @error: a #GError, or %NULL
*
* Returns the #GAppInfo that is registered as the default
* 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.
+ * @file: input #GFile
+ * @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.
* general approach to handling that is to not check, but just do the
* operation and handle the errors as they come.
*
- * As an example of race-free checking, take the case of reading a file, and
- * if it doesn't exist, creating it. There are two racy versions: read it, and
- * on error create it; and: check if it exists, if not create it. These
- * can both result in two processes creating the file (with perhaps a partially
- * written file as the result). The correct approach is to always try to create
- * the file with g_file_create() which will either atomically create the file
- * or fail with a G_IO_ERROR_EXISTS error.
+ * As an example of race-free checking, take the case of reading a file,
+ * and if it doesn't exist, creating it. There are two racy versions: read
+ * it, and on error create it; and: check if it exists, if not create it.
+ * These can both result in two processes creating the file (with perhaps
+ * a partially written file as the result). The correct approach is to
+ * always try to create the file with g_file_create() which will either
+ * atomically create the file or fail with a %G_IO_ERROR_EXISTS error.
*
- * However, in many cases an existence check is useful in a user
- * interface, for instance to make a menu item sensitive/insensitive, so that
- * you don't have to fool users that something is possible and then just show
- * and error 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.
+ * However, in many cases an existence check is useful in a user interface,
+ * for instance to make a menu item sensitive/insensitive, so that you don't
+ * have to fool users that something is possible and then just show an error
+ * 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).
*/
/**
* 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.
+ * @file: input #GFile
+ * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info()
+ * @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.
*
- * The primary use case of this method is to check if a file is a regular file,
- * directory, or symlink.
+ * 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
*/
/**
* g_file_query_filesystem_info:
- * @file: input #GFile.
- * @attributes: an attribute query string.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @file: input #GFile
+ * @attributes: an attribute query string
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError
*
* Similar to g_file_query_info(), but obtains information
* about the filesystem the @file is on, rather than the file itself.
* For instance the amount of space available and the type of
* the filesystem.
*
- * The @attributes value is a string that specifies the file attributes that
- * should be gathered. It is not an error if it's not possible to read a particular
- * requested attribute from a file - it just won't be set. @attributes should
- * be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
- * means all attributes, and a wildcard like "filesystem::*" means all attributes in the
- * filesystem namespace. The standard namespace for filesystem attributes is "filesystem".
- * Common attributes of interest are #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE
- * (the total size of the filesystem in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of
- * bytes available), and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
- *
- * 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.
+ * The @attributes value is a string that specifies the attributes
+ * that should be gathered. It is not an error if it's not possible
+ * to read a particular requested attribute from a file - it just
+ * won't be set. @attributes should be a comma-separated list of
+ * attributes or attribute wildcards. The wildcard "*" means all
+ * attributes, and a wildcard like "filesystem::*" means all attributes
+ * in the filesystem namespace. The standard namespace for filesystem
+ * attributes is "filesystem". Common attributes of interest are
+ * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem
+ * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available),
+ * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
+ *
+ * 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 the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
- * Other errors are possible too, and depend on what kind of filesystem the file is on.
+ * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will
+ * 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().
*/
/**
* 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
+ * @file: input #GFile
+ * @attributes: an attribute query string
+ * @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
/**
* g_file_query_filesystem_info_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
- * Finishes an asynchronous filesystem info query. See
- * g_file_query_filesystem_info_async().
+ * 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().
*/
/**
* g_file_query_info:
- * @file: input #GFile.
- * @attributes: an attribute query string.
- * @flags: a set of #GFileQueryInfoFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
- *
- * Gets the requested information about specified @file. The result
- * is a #GFileInfo object that contains key-value attributes (such as
- * the type or size of the file).
- *
- * The @attributes value is a string that specifies the file attributes that
- * should be gathered. It is not an error if it's not possible to read a particular
- * requested attribute from a file - it just won't be set. @attributes should
- * be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
- * means all attributes, and a wildcard like "standard::*" means all attributes in the standard
- * namespace. An example attribute query be "standard::*,owner::user".
- * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME.
+ * @file: input #GFile
+ * @attributes: an attribute query string
+ * @flags: a set of #GFileQueryInfoFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError
*
- * 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.
+ * Gets the requested information about specified @file.
+ * The result is a #GFileInfo object that contains key-value
+ * attributes (such as the type or size of the file).
+ *
+ * The @attributes value is a string that specifies the file
+ * attributes that should be gathered. It is not an error if
+ * it's not possible to read a particular requested attribute
+ * from a file - it just won't be set. @attributes should be a
+ * comma-separated list of attributes or attribute wildcards.
+ * The wildcard "*" means all attributes, and a wildcard like
+ * "standard::*" means all attributes in the standard namespace.
+ * An example attribute query be "standard::*,owner::user".
+ * The standard attributes are available as defines, like
+ * #G_FILE_ATTRIBUTE_STANDARD_NAME.
+ *
+ * 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.
*
* For symlinks, normally the information about the target of the
- * symlink is returned, rather than information about the symlink itself.
- * However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the
- * information about the symlink itself will be returned. Also, for symlinks
- * that point to non-existing files the information about the symlink itself
- * will be returned.
+ * symlink is returned, rather than information about the symlink
+ * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
+ * in @flags the information about the symlink itself will be returned.
+ * Also, for symlinks that point to non-existing files the information
+ * about the symlink itself will be returned.
*
- * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
- * Other errors are possible too, and depend on what kind of filesystem the file is on.
+ * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
+ * 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().
*/
/**
* g_file_query_info_async:
- * @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
+ * @file: input #GFile
+ * @attributes: an attribute query string
+ * @flags: a set of #GFileQueryInfoFlags
+ * @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. The result
- * is a #GFileInfo object that contains key-value attributes (such as type or size
- * for the file).
+ * Asynchronously gets the requested information about specified @file.
+ * The result is a #GFileInfo object that contains key-value attributes
+ * (such as type or size for the file).
*
- * For more details, see g_file_query_info() which is
- * the synchronous version of this call.
+ * For more details, see g_file_query_info() which is the synchronous
+ * version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_query_info_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called. You can
+ * then call g_file_query_info_finish() to get the result of the operation.
*/
/**
* g_file_query_info_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
* 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.
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
* @error: a #GError, or %NULL
*
* Obtain the list of settable attributes for the file.
*
* Returns the type and full attribute name of all the attributes
- * that can be set on this file. This doesn't mean setting it will always
- * succeed though, you might get an access failure, or some specific
- * file may not support a specific attribute.
+ * that can be set on this file. This doesn't mean setting it will
+ * always succeed though, you might get an access failure, or some
+ * specific file may not support a specific attribute.
*
* 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: 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.
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
* @error: a #GError, or %NULL
*
* Obtain the list of attribute namespaces where new attributes
* 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:
- * @file: #GFile to read.
+ * g_file_read: (virtual read_fn)
+ * @file: #GFile to read
* @cancellable: (allow-none): a #GCancellable
* @error: a #GError, or %NULL
*
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
- * If the file is a directory, the 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.
+ * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
+ * returned. If the file is a directory, the %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.
*
- * 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.
* For more details, see g_file_read() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_read_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_read_finish() to get the result
+ * of the operation.
*/
/**
* g_file_read_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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.
- * @make_backup: %TRUE if a backup should be created.
- * @flags: a set of #GFileCreateFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Returns an output stream for overwriting the file, possibly
* will be made readable only to the current user, to the level that
* is supported on the target filesystem.
*
- * 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 @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 you pass in a non-#NULL @etag value, then this value is
- * compared to the current entity tag of the file, and if they differ
- * an G_IO_ERROR_WRONG_ETAG error is returned. This generally means
- * that the file has been changed since you last read it. You can get
- * the new etag from g_file_output_stream_get_etag() after you've
- * finished writing and closed the #GFileOutputStream. When you load
- * a new file you can use g_file_input_stream_query_info() to get
- * the etag of the file.
+ * If you pass in a non-%NULL @etag value and @file already exists, then
+ * this value is compared to the current entity tag of the file, and if
+ * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This
+ * generally means that the file has been changed since you last read
+ * it. You can get the new etag from g_file_output_stream_get_etag()
+ * after you've finished writing and closed the #GFileOutputStream. When
+ * you load a new file you can use g_file_input_stream_query_info() to
+ * get the etag of the file.
*
- * If @make_backup is %TRUE, this function will attempt to make a backup
- * of the current file before overwriting it. If this fails a G_IO_ERROR_CANT_CREATE_BACKUP
- * error will be returned. If you want to replace anyway, try again with
- * @make_backup set to %FALSE.
- *
- * If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned,
- * and if the file is some other form of non-regular file then a
- * G_IO_ERROR_NOT_REGULAR_FILE error will be returned.
- * Some file systems don't allow all file names, and may
- * return an G_IO_ERROR_INVALID_FILENAME error, and if the name
- * is to long 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.
+ * If @make_backup is %TRUE, this function will attempt to make a
+ * backup of the current file before overwriting it. If this fails
+ * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you
+ * want to replace anyway, try again with @make_backup set to %FALSE.
+ *
+ * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will
+ * be returned, and if the file is some other form of non-regular file
+ * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some
+ * file systems don't allow all file names, and may return an
+ * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long
+ * %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.
- * @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
+ * @file: input #GFile
+ * @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 [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, possibly
- * creating a backup copy of the file first.
+ * Asynchronously overwrites the file, replacing the contents,
+ * possibly creating a backup copy of the file first.
*
* For more details, see g_file_replace() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_replace_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_replace_finish() to get the result
+ * of the operation.
*/
/**
* g_file_replace_contents:
- * @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
- * @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
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @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 [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 [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
*
* Replaces the contents of @file with @contents of @length bytes.
*
- * If @etag is specified (not %NULL) any existing file must have that etag, or
- * the error %G_IO_ERROR_WRONG_ETAG will be returned.
+ * If @etag is specified (not %NULL), any existing file must have that etag,
+ * or the error %G_IO_ERROR_WRONG_ETAG will be returned.
*
- * If @make_backup is %TRUE, this function will attempt to make a backup of @file.
+ * If @make_backup is %TRUE, this function will attempt to make a backup
+ * of @file.
*
* 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.
*
- * The returned @new_etag can be used to verify that the file hasn't changed the
- * next time it is saved over.
+ * 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.
*/
/**
* g_file_replace_contents_async:
- * @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
- * @make_backup: %TRUE if a backup should be created.
- * @flags: a set of #GFileCreateFlags.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @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 [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
*
*
* 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_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
- * @error: a #GError, or %NULL
+ * 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
*
- * Finishes an asynchronous replace of the given @file. See
- * g_file_replace_contents_async(). Sets @new_etag to the new entity
- * tag for the document, if present.
+ * 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.
*
- * Returns: %TRUE on success, %FALSE on failure.
+ * 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
+ */
+
+
+/**
+ * g_file_replace_contents_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @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
+ * g_file_replace_contents_async(). Sets @new_etag to the new entity
+ * tag for the document, if present.
+ *
+ * Returns: %TRUE on success, %FALSE on failure.
*/
/**
* g_file_replace_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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,
* possibly creating a backup copy of the file first. If the file doesn't
* exist, it will be created.
*
- * For details about the behaviour, see g_file_replace() which does the same
- * thing but returns an output stream only.
+ * For details about the behaviour, see g_file_replace() which does the
+ * same thing but returns an output stream only.
*
* Note that in many non-local file cases read and write streams are 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 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_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.
- * @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
+ * @file: input #GFile
+ * @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 [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, replacing the
- * contents, possibly creating a backup copy of the file first.
+ * Asynchronously overwrites the file in read-write mode,
+ * replacing the contents, possibly creating a backup copy
+ * of the file first.
*
* For more details, see g_file_replace_readwrite() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then
- * call g_file_replace_readwrite_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_replace_readwrite_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
* g_file_replace_readwrite_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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
*/
/**
* g_file_resolve_relative_path:
- * @file: input #GFile.
- * @relative_path: a given relative path string.
+ * @file: input #GFile
+ * @relative_path: a given relative path string
*
* Resolves a relative path for @file to an absolute path.
*
- * This call does no blocking i/o.
+ * 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().
*/
/**
* g_file_set_attribute:
- * @file: input #GFile.
- * @attribute: a string containing the attribute's name.
+ * @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)
- * @flags: a set of #GFileQueryInfoFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @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
* @error: a #GError, or %NULL
*
* Sets an attribute in the file with attribute name @attribute to @value.
/**
* g_file_set_attribute_byte_string:
- * @file: input #GFile.
- * @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.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
* 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.
*/
/**
* g_file_set_attribute_int32:
- * @file: input #GFile.
- * @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.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
* 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.
*/
/**
* g_file_set_attribute_int64:
- * @file: input #GFile.
- * @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.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
/**
* g_file_set_attribute_string:
- * @file: input #GFile.
- * @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.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
/**
* g_file_set_attribute_uint32:
- * @file: input #GFile.
- * @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.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
* 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.
*/
/**
* g_file_set_attribute_uint64:
- * @file: input #GFile.
- * @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.
+ * @file: input #GFile
+ * @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
* @error: a #GError, or %NULL
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
* 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.
*/
/**
* g_file_set_attributes_async:
- * @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.
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): a #gpointer.
+ * @file: input #GFile
+ * @info: a #GFileInfo
+ * @flags: a #GFileQueryInfoFlags
+ * @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
*
* Asynchronously sets the attributes of @file with @info.
*
- * For more details, see g_file_set_attributes_from_info() which is
- * the synchronous version of this call.
+ * For more details, see g_file_set_attributes_from_info(),
+ * which is the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_set_attributes_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_set_attributes_finish() to get
+ * the result of the operation.
*/
/**
* g_file_set_attributes_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @info: (out) (transfer full): a #GFileInfo.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @info: (out) (transfer full): a #GFileInfo
* @error: a #GError, or %NULL
*
* Finishes setting an attribute started in g_file_set_attributes_async().
/**
* g_file_set_attributes_from_info:
- * @file: input #GFile.
- * @info: a #GFileInfo.
+ * @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 values,
- * not stopping on the first error.
+ * Tries to set all attributes in the #GFileInfo on the target
+ * values, not stopping on the first error.
*
- * If there is any error during this operation then @error will be set to
- * the first error. Error on particular fields are flagged by setting
- * the "status" field in the attribute value to
- * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect
- * further errors.
+ * If there is any error during this operation then @error will
+ * be set to the first error. Error on particular fields are flagged
+ * by setting the "status" field in the attribute value to
+ * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can
+ * also detect further errors.
*
* 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 there was any error, %FALSE otherwise.
+ * Returns: %FALSE if there was any error, %TRUE otherwise.
*/
/**
* g_file_set_display_name:
- * @file: input #GFile.
- * @display_name: a string.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @file: input #GFile
+ * @display_name: a string
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
* @error: a #GError, or %NULL
*
* Renames @file to the specified display name.
*
- * The display name is converted from UTF8 to the correct encoding for the target
- * filesystem if possible and the @file is renamed to this.
+ * The display name is converted from UTF-8 to the correct encoding
+ * for the target filesystem if possible and the @file is renamed to this.
*
- * If you want to implement a rename operation in the user interface the edit name
- * (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename
- * widget, and then the result after editing should be passed to g_file_set_display_name().
+ * If you want to implement a rename operation in the user interface the
+ * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the
+ * initial value in the rename widget, and then the result after editing
+ * should be passed to g_file_set_display_name().
*
* On success the resulting converted filename is returned.
*
* 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().
*/
/**
* 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
+ * @file: input #GFile
+ * @display_name: a string
+ * @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.
* For more details, see g_file_set_display_name() which is
* the synchronous version of this call.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_set_display_name_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_set_display_name_finish() to get
+ * the result of the operation.
*/
/**
* g_file_set_display_name_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
* 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().
*/
/**
* g_file_start_mountable:
- * @file: input #GFile.
+ * @file: input #GFile
* @flags: flags affecting the operation
- * @start_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.
+ * @start_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 file of type G_FILE_TYPE_MOUNTABLE.
+ * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
* Using @start_operation, you can request callbacks when, for instance,
* passwords are needed during authentication.
*
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_mount_mountable_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_mount_mountable_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
* g_file_start_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* Finishes a start operation. See g_file_start_mountable() for details.
* 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
*/
/**
* g_file_stop_mountable:
- * @file: input #GFile.
+ * @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.
+ * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
*
* 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.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_stop_mountable_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_stop_mountable_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
* g_file_stop_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* Finishes an stop operation, see g_file_stop_mountable() for details.
* 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
*/
/**
* g_file_supports_thread_contexts:
- * @file: a #GFile.
+ * @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
/**
- * g_file_trash:
- * @file: #GFile to send to trash.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * g_file_trash: (virtual trash)
+ * @file: #GFile to send to trash
+ * @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
* Not all file systems support trashing, so this call can return the
* %G_IO_ERROR_NOT_SUPPORTED error.
*
- *
* 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.
/**
+ * 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.
+ * @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.
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_unmount_mountable_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_unmount_mountable_finish() to get
+ * the result of the operation.
*
* Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
*/
/**
* g_file_unmount_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* Finishes an unmount operation, see g_file_unmount_mountable() for details.
* 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.
*/
/**
* g_file_unmount_mountable_with_operation:
- * @file: input #GFile.
+ * @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.
+ * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
*
* 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.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_unmount_mountable_finish() to get the result of the operation.
+ * When the operation is finished, @callback will be called.
+ * You can then call g_file_unmount_mountable_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
* g_file_unmount_mountable_with_operation_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
+ * @file: input #GFile
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
- * Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details.
+ * Finishes an unmount operation,
+ * see g_file_unmount_mountable_with_operation() for details.
*
* 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
*/
*
* 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.
*/
*
* 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.
*/
/**
+ * 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.
/**
- * 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.
*/
* 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
* 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: (nullable): An allocated NUL-terminated UTF8 string or
+ * %NULL if @icon can't be serialized. Use g_free() to free.
* Since: 2.20
*/
*
* 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
*/
* 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
*/
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
* 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
* 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
/**
+ * 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.
*
* 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.
* 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
*/
* 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
*/
/**
* 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
*/
* @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_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
* 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().
*
/**
* 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
* can happen e.g. near the end of a file. Zero is returned on end of file
* (or if @count is zero), but never otherwise.
*
+ * The returned @buffer is not a nul-terminated string, it can contain nul bytes
+ * at any position, and this function doesn't nul-terminate the @buffer.
+ *
* 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
/**
* 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.
* read into @buffer.
*
* If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_read is updated to contain
- * the number of bytes read into @buffer before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered. This functionality is only
+ * available from C. If you need it from another language then you must
+ * write your own loop around g_input_stream_read().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ */
+
+
+/**
+ * g_input_stream_read_all_async:
+ * @stream: A #GInputStream
+ * @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 [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
+ *
+ * Request an asynchronous read of @count bytes from the stream into the
+ * buffer starting at @buffer.
+ *
+ * This is the asynchronous equivalent of g_input_stream_read_all().
+ *
+ * Call g_input_stream_read_all_finish() to collect the result.
+ *
+ * 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.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_input_stream_read_all_finish:
+ * @stream: a #GInputStream
+ * @result: a #GAsyncResult
+ * @bytes_read: (out): location to store the number of bytes that was read from the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an asynchronous stream read operation started with
+ * g_input_stream_read_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered. This functionality is only
+ * available from C. If you need it from another language then you must
+ * write your own loop around g_input_stream_read_async().
*
* Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
*/
/**
* 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
/**
* 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
*
* On error %NULL is returned and @error is set accordingly.
*
* Returns: a new #GBytes, or %NULL on error
+ * Since: 2.34
*/
* 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
* 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.
+ *
+ * Since: 2.34
*/
* 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.
*
* Returns: the newly-allocated #GBytes, or %NULL on error
+ * Since: 2.34
*/
* 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.
*
/**
* 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
* 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
* 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.
*
* g_io_error_from_errno:
* @err_no: Error number as defined in errno.h.
*
- * Converts errno.h error codes into GIO error codes.
+ * Converts errno.h error codes into GIO error codes. The fallback
+ * value %G_IO_ERROR_FAILED is returned for error codes not currently
+ * handled (but note that future GLib releases may return a more
+ * specific value instead).
*
* Returns: #GIOErrorEnum value for the given errno.h error number.
*/
* g_io_error_from_win32_error:
* @error_code: Windows error number.
*
- * Converts some common error codes into GIO error codes. The
- * fallback value G_IO_ERROR_FAILED is returned for error codes not
- * handled.
+ * Converts some common error codes (as returned from GetLastError()
+ * or WSAGetLastError()) into GIO error codes. The fallback value
+ * %G_IO_ERROR_FAILED is returned for error codes not currently
+ * handled (but note that future GLib releases may return a more
+ * specific value instead).
+ *
+ * You can use g_win32_error_message() to get a localized string
+ * corresponding to @error_code. (But note that unlike g_strerror(),
+ * g_win32_error_message() returns a string that must be freed.)
*
* Returns: #GIOErrorEnum value for the given error number.
* Since: 2.26
*
* 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
*/
* 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.
*/
*
* 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
*/
*
* 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.
*/
*
* 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.
*/
* 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.
*/
* 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().
*/
* 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
*/
*
* 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.
*/
* blocking the I/O job).
*
* Returns: The return value of @func
+ * Deprecated: Use g_main_context_invoke().
*/
* 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().
*/
* @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.
* 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()
*/
* 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.
*
* 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
*/
* 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
*/
/**
* 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
/**
* 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.
*
* 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.
*
/**
- * 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.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_list_model_get_item: (skip)
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
*
- * Loads a loadable icon. For the asynchronous version of this function,
- * see g_loadable_icon_load_async().
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
*
- * Returns: (transfer full): a #GInputStream to read the icon from.
+ * %NULL is never returned for an index that is smaller than the length
+ * of the list. See g_list_model_get_n_items().
+ *
+ * Returns: (transfer full) (nullable) (type GObject): the item at @position.
+ * Since: 2.44
*/
/**
- * g_loadable_icon_load_async:
- * @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
- * @user_data: (closure): the data to pass to callback function
+ * g_list_model_get_item_type:
+ * @list: a #GListModel
*
- * Loads an icon asynchronously. To finish this function, see
- * g_loadable_icon_load_finish(). For the synchronous, blocking
- * version of this function, see g_loadable_icon_load().
+ * Gets the type of the items in @list. All items returned from
+ * g_list_model_get_type() are of that type or a subtype, or are an
+ * implementation of that interface.
+ *
+ * The item type of a #GListModel can not change during the life of the
+ * model.
+ *
+ * Returns: the #GType of the items contained in @list.
+ * Since: 2.44
*/
/**
- * 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.
+ * g_list_model_get_n_items:
+ * @list: a #GListModel
*
- * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+ * Gets the number of items in @list.
*
- * Returns: (transfer full): a #GInputStream to read the icon from.
+ * Depending on the model implementation, calling this function may be
+ * less efficient than iterating the list with increasing values for
+ * @position until g_list_model_get_item() returns %NULL.
+ *
+ * Returns: the number of items in @list.
+ * Since: 2.44
*/
/**
- * g_local_vfs_new:
+ * g_list_model_get_object: (rename-to g_list_model_get_item)
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
*
- * Returns a new #GVfs handle for a local vfs.
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
*
- * Returns: a new #GVfs handle.
+ * %NULL is never returned for an index that is smaller than the length
+ * of the list. See g_list_model_get_n_items().
+ *
+ * Returns: (transfer full) (nullable): the object at @position.
+ * Since: 2.44
*/
/**
- * g_memory_input_stream_add_bytes:
- * @stream: a #GMemoryInputStream
- * @bytes: input data
+ * g_list_model_items_changed:
+ * @list: a #GListModel
+ * @position: the position at which @list changed
+ * @removed: the number of items removed
+ * @added: the number of items added
*
- * Appends @bytes to data that can be read from the input stream.
+ * Emits the #GListModel::items-changed signal on @list.
*
- * Since: 2.34
+ * This function should only be called by classes implementing
+ * #GListModel. It has to be called after the internal representation
+ * of @list has been updated, because handlers connected to this signal
+ * might query the new state of the list.
+ *
+ * Implementations must only make changes to the model (as visible to
+ * its consumer) in places that will not cause problems for that
+ * consumer. For models that are driven directly by a write API (such
+ * as #GListStore), changes can be reported in response to uses of that
+ * API. For models that represent remote data, changes should only be
+ * made from a fresh mainloop dispatch. It is particularly not
+ * permitted to make changes in response to a call to the #GListModel
+ * consumer API.
+ *
+ * Stated another way: in general, it is assumed that code making a
+ * series of accesses to the model via the API, without returning to the
+ * mainloop, and without calling other code, will continue to view the
+ * same contents of the model.
+ *
+ * Since: 2.44
*/
/**
- * g_memory_input_stream_add_data:
- * @stream: a #GMemoryInputStream
- * @data: (array length=len) (element-type guint8) (transfer full): input data
- * @len: length of the data, may be -1 if @data is a nul-terminated string
- * @destroy: (allow-none): function that is called to free @data, or %NULL
+ * g_list_store_append:
+ * @store: a #GListStore
+ * @item: the new item
+ *
+ * Appends @item to @store. @item must be of type #GListStore:item-type.
+ *
+ * This function takes a ref on @item.
+ *
+ * Use g_list_store_splice() to append multiple items at the same time
+ * efficiently.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_insert:
+ * @store: a #GListStore
+ * @position: the position at which to insert the new item
+ * @item: the new item
+ *
+ * Inserts @item into @store at @position. @item must be of type
+ * #GListStore:item-type or derived from it. @position must be smaller
+ * than the length of the list, or equal to it to append.
+ *
+ * This function takes a ref on @item.
+ *
+ * Use g_list_store_splice() to insert multiple items at the same time
+ * efficiently.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_insert_sorted:
+ * @store: a #GListStore
+ * @item: the new item
+ * @compare_func: pairwise comparison function for sorting
+ * @user_data: (closure): user data for @compare_func
+ *
+ * Inserts @item into @store at a position to be determined by the
+ * @compare_func.
+ *
+ * The list must already be sorted before calling this function or the
+ * result is undefined. Usually you would approach this by only ever
+ * inserting items by way of this function.
+ *
+ * This function takes a ref on @item.
+ *
+ * Returns: the position at which @item was inserted
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_new:
+ * @item_type: the #GType of items in the list
+ *
+ * Creates a new #GListStore with items of type @item_type. @item_type
+ * must be a subclass of #GObject.
+ *
+ * Returns: a new #GListStore
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_remove:
+ * @store: a #GListStore
+ * @position: the position of the item that is to be removed
+ *
+ * Removes the item from @store that is at @position. @position must be
+ * smaller than the current length of the list.
+ *
+ * Use g_list_store_splice() to remove multiple items at the same time
+ * efficiently.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_remove_all:
+ * @store: a #GListStore
+ *
+ * Removes all items from @store.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_splice:
+ * @store: a #GListStore
+ * @position: the position at which to make the change
+ * @n_removals: the number of items to remove
+ * @additions: (array length=n_additions): the items to add
+ * @n_additions: the number of items to add
+ *
+ * Changes @store by removing @n_removals items and adding @n_additions
+ * items to it. @additions must contain @n_additions items of type
+ * #GListStore:item-type. %NULL is not permitted.
+ *
+ * This function is more efficient than g_list_store_insert() and
+ * g_list_store_remove(), because it only emits
+ * #GListModel::items-changed once for the change.
+ *
+ * This function takes a ref on each item in @additions.
+ *
+ * The parameters @position and @n_removals must be correct (ie:
+ * @position + @n_removals must be less than or equal to the length of
+ * the list at the time this function is called).
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_loadable_icon_load:
+ * @icon: a #GLoadableIcon.
+ * @size: an integer.
+ * @type: (out) (optional): 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.
+ *
+ * Loads a loadable icon. For the asynchronous version of this function,
+ * see g_loadable_icon_load_async().
+ *
+ * Returns: (transfer full): a #GInputStream to read the icon from.
+ */
+
+
+/**
+ * g_loadable_icon_load_async:
+ * @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
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Loads an icon asynchronously. To finish this function, see
+ * g_loadable_icon_load_finish(). For the synchronous, blocking
+ * version of this function, see g_loadable_icon_load().
+ */
+
+
+/**
+ * g_loadable_icon_load_finish:
+ * @icon: a #GLoadableIcon.
+ * @res: a #GAsyncResult.
+ * @type: (out) (optional): 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().
+ *
+ * Returns: (transfer full): a #GInputStream to read the icon from.
+ */
+
+
+/**
+ * g_local_vfs_new:
+ *
+ * Returns a new #GVfs handle for a local vfs.
+ *
+ * Returns: a new #GVfs handle.
+ */
+
+
+/**
+ * g_memory_input_stream_add_bytes:
+ * @stream: a #GMemoryInputStream
+ * @bytes: input data
+ *
+ * Appends @bytes to data that can be read from the input stream.
+ *
+ * Since: 2.34
+ */
+
+
+/**
+ * g_memory_input_stream_add_data:
+ * @stream: a #GMemoryInputStream
+ * @data: (array length=len) (element-type guint8) (transfer full): input data
+ * @len: length of the data, may be -1 if @data is a nul-terminated string
+ * @destroy: (allow-none): function that is called to free @data, or %NULL
*
* Appends @data to data that can be read from the input stream
*/
* 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
* @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
*/
* 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);
* ]|
/**
+ * 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
*
* 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
*/
/**
+ * g_menu_item_get_attribute:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute name to query
+ * @format_string: a #GVariant format string
+ * @...: positional parameters, as per @format_string
+ *
+ * Queries the named @attribute on @menu_item.
+ *
+ * If the attribute exists and matches the #GVariantType corresponding
+ * to @format_string then @format_string is used to deconstruct the
+ * value into the positional parameters and %TRUE is returned.
+ *
+ * If the attribute does not exist, or it does exist but has the wrong
+ * type, then the positional parameters are ignored and %FALSE is
+ * returned.
+ *
+ * Returns: %TRUE if the named attribute was found with the expected
+ * type
+ * Since: 2.34
+ */
+
+
+/**
+ * g_menu_item_get_attribute_value:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute name to query
+ * @expected_type: (allow-none): the expected type of the attribute
+ *
+ * Queries the named @attribute on @menu_item.
+ *
+ * If @expected_type is specified and the attribute does not have this
+ * type, %NULL is returned. %NULL is also returned if the attribute
+ * simply does not exist.
+ *
+ * Returns: (transfer full): the attribute value, or %NULL
+ * Since: 2.34
+ */
+
+
+/**
+ * g_menu_item_get_link:
+ * @menu_item: a #GMenuItem
+ * @link: the link name to query
+ *
+ * Queries the named @link on @menu_item.
+ *
+ * Returns: (transfer full): the link, or %NULL
+ * Since: 2.34
+ */
+
+
+/**
* g_menu_item_new:
* @label: (allow-none): the section label, or %NULL
* @detailed_action: (allow-none): the detailed action string, or %NULL
/**
+ * g_menu_item_new_from_model:
+ * @model: a #GMenuModel
+ * @item_index: the index of an item in @model
+ *
+ * Creates a #GMenuItem as an exact copy of an existing menu item in a
+ * #GMenuModel.
+ *
+ * @item_index must be valid (ie: be sure to call
+ * g_menu_model_get_n_items() first).
+ *
+ * Returns: a new #GMenuItem.
+ * Since: 2.34
+ */
+
+
+/**
* g_menu_item_new_section:
* @label: (allow-none): the section label, or %NULL
* @section: a #GMenuModel with the items of the section
* 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'/>
* <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
* 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'>
* </link>
* </item>
* </menu>
- * ]]></programlisting></informalexample>
+ * ]|
*
* Returns: a new #GMenuItem
* Since: 2.32
*
* 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
/**
+ * 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
* type, then the positional parameters are ignored and %FALSE is
* returned.
*
- * Returns: %TRUE if the named attribute was found with the expected type
+ * This function is a mix of g_menu_model_get_item_attribute_value() and
+ * 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.
+ *
+ * Returns: %TRUE if the named attribute was found with the expected
+ * type
* Since: 2.32
*/
* @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.
* 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
*/
/**
+ * g_menu_remove_all:
+ * @menu: a #GMenu
+ *
+ * Removes all items in the menu.
+ *
+ * Since: 2.38
+ */
+
+
+/**
* g_mount_can_eject:
* @mount: a #GMount.
*
* 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.
* 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.
* 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.
* @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.
*/
* 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.
*/
*
* 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.
*/
*
* 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.
*/
*
* 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.
*/
/**
+ * g_mount_get_symbolic_icon:
+ * @mount: a #GMount.
+ *
+ * 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.
+ * Since: 2.34
+ */
+
+
+/**
* g_mount_get_uuid:
* @mount: a #GMount.
*
* 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.
*/
*
* 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
* 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
* 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
* %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
*/
/**
* 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
*/
* 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.
*
* 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.
*/
* 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.
* 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.
* 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.
* 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.
* 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.
* Creates a new #GSocketConnectable for connecting to the given
* @hostname and @port.
*
+ * Note that depending on the configuration of the machine, a
+ * @hostname of `localhost` may refer to the IPv4 loopback address
+ * only, or to both IPv4 and IPv6; use
+ * g_network_address_new_loopback() to create a #GNetworkAddress that
+ * is guaranteed to resolve to both addresses.
+ *
* Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
* Since: 2.22
*/
/**
+ * g_network_address_new_loopback:
+ * @port: the port
+ *
+ * Creates a new #GSocketConnectable for connecting to the local host
+ * over a loopback connection to the given @port. This is intended for
+ * use in connecting to local services which may be running on IPv4 or
+ * IPv6.
+ *
+ * The connectable will return IPv4 and IPv6 loopback addresses,
+ * regardless of how the host resolves `localhost`. By contrast,
+ * g_network_address_new() will often only return an IPv4 address when
+ * resolving `localhost`, and an IPv6 address for `localhost6`.
+ *
+ * g_network_address_get_hostname() will always return `localhost` for
+ * #GNetworkAddresses created with this constructor.
+ *
+ * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
+ * Since: 2.44
+ */
+
+
+/**
* g_network_address_parse:
* @host_and_port: the hostname and optionally a port
* @default_port: the default port if not in @host_and_port
* @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
/**
+ * g_network_monitor_get_connectivity:
+ * @monitor: the #GNetworkMonitor
+ *
+ * Gets a more detailed networking state than
+ * g_network_monitor_get_network_available().
+ *
+ * If #GNetworkMonitor:network-available is %FALSE, then the
+ * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
+ *
+ * If #GNetworkMonitor:network-available is %TRUE, then the
+ * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
+ * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
+ * the host has a default route, but appears to be unable to actually
+ * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
+ * host is trapped behind a "captive portal" that requires some sort
+ * of login or acknowledgement before allowing full Internet access).
+ *
+ * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
+ * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
+ * reachable but others are not. In this case, applications can
+ * attempt to connect to remote servers, but should gracefully fall
+ * back to their "offline" behavior if the connection attempt fails.
+ *
+ * Returns: the network connectivity state
+ * Since: 2.44
+ */
+
+
+/**
* g_network_monitor_get_default:
*
* Gets the default #GNetworkMonitor for the system.
/**
- * g_null_settings_backend_new:
+ * g_networking_init:
*
- * Creates a readonly #GSettingsBackend.
- *
- * This backend does not allow changes to settings, so all settings
- * will always have their default values.
+ * 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).
*
- * Returns: (transfer full): a newly created #GSettingsBackend
- * Since: 2.28
+ * Since: 2.36
*/
/**
- * g_output_stream_clear_pending:
- * @stream: output stream
+ * g_notification_add_button:
+ * @notification: a #GNotification
+ * @label: label of the button
+ * @detailed_action: a detailed action name
*
- * Clears the pending flag on @stream.
+ * 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_output_stream_close:
- * @stream: A #GOutputStream.
- * @cancellable: (allow-none): optional cancellable object
- * @error: location to store the error occurring, or %NULL to ignore
+ * 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 @target_format
*
- * Closes the stream, releasing resources related to it.
+ * Adds a button to @notification that activates @action when clicked.
+ * @action must be an application-wide action (it must start with "app.").
*
- * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
- * Closing a stream multiple times will not return an error.
+ * 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.
*
- * Closing a stream will automatically flush any outstanding buffers in the
- * stream.
+ * 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 @target_format
+ *
+ * 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 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_priority:
+ * @notification: a #GNotification
+ * @priority: a #GNotificationPriority
+ *
+ * Sets the priority of @notification to @priority. See
+ * #GNotificationPriority for possible values.
+ */
+
+
+/**
+ * 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
+ *
+ * Deprecated in favor of g_notification_set_priority().
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_null_settings_backend_new:
+ *
+ * Creates a readonly #GSettingsBackend.
+ *
+ * This backend does not allow changes to settings, so all settings
+ * will always have their default values.
+ *
+ * Returns: (transfer full): a newly created #GSettingsBackend
+ * Since: 2.28
+ */
+
+
+/**
+ * g_output_stream_clear_pending:
+ * @stream: output stream
+ *
+ * Clears the pending flag on @stream.
+ */
+
+
+/**
+ * g_output_stream_close:
+ * @stream: A #GOutputStream.
+ * @cancellable: (allow-none): optional cancellable object
+ * @error: location to store the error occurring, or %NULL to ignore
+ *
+ * Closes the stream, releasing resources related to it.
+ *
+ * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
+ * Closing a stream multiple times will not return an error.
+ *
+ * Closing a stream will automatically flush any outstanding buffers in the
+ * stream.
*
* Streams will be automatically closed when the last reference
* is dropped, but you might want to call this function to make sure
* 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.
*
* 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.
*
/**
+ * 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
* @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.
*/
* 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
*
* On error -1 is returned and @error is set accordingly.
*
- * Virtual: write_fn
* Returns: Number of bytes written, or -1 on error
*/
* @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
*
* is set to @count.
*
* If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_written is updated to contain
- * the number of bytes written into the stream before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered. This
+ * functionality is only available from C. If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ */
+
+
+/**
+ * g_output_stream_write_all_async:
+ * @stream: A #GOutputStream
+ * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write
+ * @count: the number of bytes to write
+ * @io_priority: the 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
+ *
+ * Request an asynchronous write of @count bytes from @buffer into
+ * the stream. When the operation is finished @callback will be called.
+ * You can then call g_output_stream_write_all_finish() to get the result of the
+ * operation.
+ *
+ * This is the asynchronous version of g_output_stream_write_all().
+ *
+ * Call g_output_stream_write_all_finish() to collect the result.
+ *
+ * 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.
+ *
+ * Note that no copy of @buffer will be made, so it must stay valid
+ * until @callback is called.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_output_stream_write_all_finish:
+ * @stream: a #GOutputStream
+ * @result: a #GAsyncResult
+ * @bytes_written: (out): location to store the number of bytes that was written to the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ *
+ * Finishes an asynchronous stream write operation started with
+ * g_output_stream_write_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered. This
+ * functionality is only available from C. If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write_async().
*
* Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
*/
*
* 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.
*/
* @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.
- *
- * 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.
+ * 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.
*
- * 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
*/
* @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().
* 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.
*
* 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.
*
* 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: (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 you want to read
* @cancellable: (allow-none): a #GCancellable, or %NULL
* @error: #GError for error reporting, or %NULL to ignore.
* 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).
*/
* 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.
* 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).
*/
/**
* 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
*
/**
* g_pollable_stream_read:
* @stream: a #GInputStream
- * @buffer: a buffer to read data into
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into
* @count: the number of bytes to read
* @blocking: whether to do blocking I/O
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
/**
* 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.
/**
* 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
*
/**
+ * g_property_action_new:
+ * @name: the name of the action to create
+ * @object: (type GObject.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
*
* @inetaddr: The proxy server #GInetAddress.
* @port: The proxy server port.
* @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
- * @dest_hostname: The destination hostname the the proxy should tunnel to.
+ * @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.
* 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
*/
* 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
*/
* @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
*/
* 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
*/
* 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
*/
* 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
*/
* the textual form of an IP address (in which case this just becomes
* a wrapper around g_inet_address_new_from_string()).
*
- * On success, g_resolver_lookup_by_name() will return a #GList of
+ * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
* #GInetAddress, sorted in order of preference and guaranteed to not
* contain duplicates. That is, if using the result to connect to
* @hostname, you should attempt to connect to the first address
* result using e.g. g_socket_listener_add_address().
*
* If the DNS resolution fails, @error (if non-%NULL) will be set to a
- * value from #GResolverError.
+ * value from #GResolverError and %NULL will be returned.
*
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* 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 non-empty #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
*/
* 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
*/
* information on what the records contain for each @record_type.
*
* If the DNS resolution fails, @error (if non-%NULL) will be set to
- * a value from #GResolverError.
+ * a value from #GResolverError and %NULL will be returned.
*
* If @cancellable is non-%NULL, it can be used to cancel the
* 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 non-empty #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
*/
* @error: return location for a #GError, or %NULL
*
* Retrieves the result of a previous call to
- * g_resolver_lookup_records_async(). Returns a list of records as #GVariant
- * tuples. See #GResolverRecordType for information on what the records contain.
+ * g_resolver_lookup_records_async(). Returns a non-empty list of records as
+ * #GVariant tuples. See #GResolverRecordType for information on what the
+ * records contain.
*
* If the DNS resolution failed, @error (if non-%NULL) will be set to
* 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 non-empty #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
*/
* 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
+ * On success, g_resolver_lookup_service() will return a non-empty #GList of
* #GSrvTarget, sorted in order of preference. (That is, you should
* attempt to connect to the first target first, then the second if
* the first fails, etc.)
*
* If the DNS resolution fails, @error (if non-%NULL) will be set to
- * a value from #GResolverError.
+ * a value from #GResolverError and %NULL will be returned.
*
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* 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 non-empty #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
*/
* 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 non-empty #GList of
+ * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
+ * details.
* Since: 2.22
*/
* @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
*
* @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
*/
*
* @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
*/
* @error: return location for a #GError, or %NULL
*
* Returns all the names of children at the specified @path in the set of
- * globally registred resources.
+ * globally registered resources.
* The return result is a %NULL terminated list of strings which should
* be released with g_strfreev().
*
* 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
- * globally registred resources and if found returns information about it.
+ * globally registered resources and if found returns information about it.
*
* @lookup_flags controls the behaviour of the lookup.
*
* @error: return location for a #GError, or %NULL
*
* Looks for a file at the specified @path in the set of
- * globally registred resources and returns a #GBytes that
+ * globally registered resources and returns a #GBytes that
* lets you directly access the data in memory.
*
* The data is always followed by a zero byte, so you
*
* @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
*/
* @error: return location for a #GError, or %NULL
*
* Looks for a file at the specified @path in the set of
- * globally registred resources and returns a #GInputStream
+ * globally registered resources and returns a #GInputStream
* that lets you read the data.
*
* @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
*/
* @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.
*/
/**
- * 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.
*
* 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.
*/
* 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,
* 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.
*
* @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
*
*
* 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.
/**
* 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
/**
+ * 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
* 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
*
* 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.
*/
* 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
*/
/**
- * g_settings_get_value:
+ * g_settings_get_user_value:
* @settings: a #GSettings object
- * @key: the key to get the value for
+ * @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
*
* Gets the value that is stored in @settings for @key.
*
/**
* 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.
*/
* backend, and a #GMainContext to which signals are dispatched.
*
* This constructor therefore gives you full control over constructing
- * #GSettings instances. The first 4 parameters are given directly as
+ * #GSettings instances. The first 3 parameters are given directly as
* @schema, @backend and @path, and the main context is taken from the
* thread-default (as per g_settings_new()).
*
* If @backend is %NULL then the default backend is used.
*
* If @path is %NULL then the path from the schema is used. It is an
- * error f @path is %NULL and the schema has no path of its own or if
+ * error if @path is %NULL and the schema has no path of its own or if
* @path is non-%NULL and not equal to the path that the schema does
* have.
*
* 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
*/
* 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.
*/
/**
+ * 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
*
/**
+ * 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_name:
+ * @key: a #GSettingsSchemaKey
+ *
+ * Gets the name of @key.
+ *
+ * Returns: the name of @key.
+ * Since: 2.44
+ */
+
+
+/**
+ * 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_list_children:
+ * @schema: a #GSettingsSchema
+ *
+ * Gets the list of children in @schema.
+ *
+ * You should free the return value with g_strfreev() when you are done
+ * with it.
+ *
+ * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Since: 2.44
+ */
+
+
+/**
* g_settings_schema_ref:
* @schema: a #GSettingsSchema
*
*
* 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
/**
+ * g_settings_schema_source_list_schemas:
+ * @source: a #GSettingsSchemaSource
+ * @recursive: if we should recurse
+ * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
+ * list of non-relocatable schemas
+ * @relocatable: (out) (transfer full) (array zero-terminated=1): 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
*
* If the schema isn't found, %NULL is returned.
*
- * Returns: (transfer full): a new #GSettingsSchema
+ * Returns: (nullable) (transfer full): a new #GSettingsSchema
* Since: 2.32
*/
* 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.
*
* source, the lookup will recurse to the parent.
*
* Second, any references to other schemas specified within this
- * source (ie: <literal>child</literal> or <literal>extents</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
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
*
* 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
*/
/**
* g_settings_unbind:
- * @object: the object
+ * @object: (type GObject.Object): the object
* @property: the property whose binding is removed
*
* Removes an existing binding for @property on @object.
/**
* 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
*
* and adding them to the action group.
*
* Since: 2.30
+ * Deprecated: 2.38: Use g_action_map_add_action_entries()
*/
* The action group takes its own reference on @action.
*
* Since: 2.28
+ * Deprecated: 2.38: Use g_action_map_add_action()
*/
*
* Returns: (transfer none): a #GAction, or %NULL
* Since: 2.28
+ * Deprecated: 2.38: Use g_action_map_lookup_action()
*/
* 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()
*/
* 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
*/
/**
+ * g_simple_action_set_state_hint:
+ * @simple: a #GSimpleAction
+ * @state_hint: (allow-none): a #GVariant representing the state hint
+ *
+ * Sets the state hint for the action.
+ *
+ * See g_action_get_state_hint() for more information about
+ * action state hints.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_simple_async_report_error_in_idle: (skip)
* @object: (allow-none): a #GObject, or %NULL.
* @callback: a #GAsyncReadyCallback.
* 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
*
* 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.
*/
/**
* 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.
* 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
/**
+ * g_simple_io_stream_new:
+ * @input_stream: a #GInputStream.
+ * @output_stream: a #GOutputStream.
+ *
+ * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
+ * See also #GIOStream.
+ *
+ * Returns: a new #GSimpleIOStream instance.
+ * Since: 2.44
+ */
+
+
+/**
* g_simple_permission_new:
* @allowed: %TRUE if the action is allowed
*
/**
+ * 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
* 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
*/
* 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.
*/
* 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
* 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.
*/
*
* Gets the socket family type of @address.
*
- * Returns: the socket family type of @address.
+ * Returns: the socket family type of @address
* Since: 2.22
*/
* 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
*/
/**
* 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
* 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
* 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()
*
* 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()
*
* 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()
*
* 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()
*
/**
+ * 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.
*
*
* 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
*/
* #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
*/
/**
+ * 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
* @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
*
* 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
*/
*
* 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
*/
* @condition: a #GIOCondition mask to monitor
* @cancellable: (allow-none): a %GCancellable or %NULL
*
- * Creates a %GSource that can be attached to a %GMainContext to monitor
- * for the availibility of the specified @condition on the socket.
+ * Creates a #GSource that can be attached to a %GMainContext to monitor
+ * for the availability of the specified @condition on the socket. The #GSource
+ * keeps a reference to the @socket.
*
* The callback on the source is of the #GSocketSourceFunc type.
*
*
* 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
*/
*
* 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
* 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
*/
* @socket: a #GSocket.
*
* Returns the underlying OS socket object. On unix this
- * is a socket file descriptor, and on windows this is
+ * is a socket file descriptor, and on Windows this is
* a Winsock2 SOCKET handle. This may be useful for
* doing platform specific or otherwise unusual operations
* on the socket.
* 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
*/
/**
+ * 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.
*
* 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
*/
* @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()
*
* @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()
*
* 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).
* useful if you're listening on multiple addresses and do
* different things depending on what address is connected to.
*
+ * The @socket will not be automatically closed when the @listener is finalized
+ * unless the listener held the final reference to the socket. Before GLib 2.42,
+ * the @socket was automatically closed on finalization of the @listener, even
+ * if references to it were held elsewhere.
+ *
* Returns: %TRUE on success, %FALSE on error.
* Since: 2.22
*/
* 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
*/
* 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
*/
/**
* 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.
*
* 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
*/
/**
* 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.
*
* 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
*/
/**
* 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
*
* 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
*/
/**
* 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
* 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
*/
/**
* 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.
*
* 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
*/
* @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
* 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().
*
*
* 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
*/
/**
+ * g_socket_send_messages:
+ * @socket: a #GSocket
+ * @messages: (array length=num_messages): an array of #GOutputMessage structs
+ * @num_messages: the number of elements in @messages
+ * @flags: an int containing #GSocketMsgFlags flags
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Send multiple data messages from @socket in one go. This is the most
+ * complicated and fully-featured version of this call. For easier use, see
+ * g_socket_send(), g_socket_send_to(), and g_socket_send_message().
+ *
+ * @messages must point to an array of #GOutputMessage structs and
+ * @num_messages must be the length of this array. Each #GOutputMessage
+ * contains an address to send the data to, and a pointer to an array of
+ * #GOutputVector structs to describe the buffers that the data to be sent
+ * for each message will be gathered from. Using multiple #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(). Sending multiple messages in one go avoids the
+ * overhead of making a lot of syscalls in scenarios where a lot of data
+ * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP),
+ * or where the same data needs to be sent to multiple recipients.
+ *
+ * @flags modify how the message is sent. The commonly available arguments
+ * for this are available in the #GSocketMsgFlags enum, but the
+ * values there are the same as the system values, and the flags
+ * are passed in as-is, so you can pass in system-specific flags too.
+ *
+ * If the socket is in blocking mode the call will block until there is
+ * space for all the data in the socket queue. If there is no space available
+ * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
+ * will be returned if no data was written at all, otherwise the number of
+ * messages sent will be returned. To be notified when space is available,
+ * wait for the %G_IO_OUT condition. Note though that you may still receive
+ * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
+ * notified of a %G_IO_OUT condition. (On Windows in particular, this is
+ * very common due to the way the underlying APIs work.)
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Returns: number of messages sent, or -1 on error. Note that the number of
+ * messages sent may be smaller than @num_messages if the socket is
+ * non-blocking or if @num_messages was larger than UIO_MAXIOV (1024),
+ * in which case the caller may re-try to send the remaining messages.
+ * Since: 2.44
+ */
+
+
+/**
* 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.
*
* 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
*/
/**
* 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
* 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
*/
* 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
*/
/**
* 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
*/
/**
* 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
/**
+ * 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
/**
- * g_srv_target_copy:
- * @target: a #GSrvTarget
+ * g_srv_target_copy:
+ * @target: a #GSrvTarget
+ *
+ * Copies @target
+ *
+ * Returns: a copy of @target
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_free:
+ * @target: a #GSrvTarget
+ *
+ * Frees @target
+ *
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_get_hostname:
+ * @target: a #GSrvTarget
+ *
+ * Gets @target's hostname (in ASCII form; if you are going to present
+ * this to the user, you should use g_hostname_is_ascii_encoded() to
+ * check if it contains encoded Unicode segments, and use
+ * g_hostname_to_unicode() to convert it if it does.)
+ *
+ * Returns: @target's hostname
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_get_port:
+ * @target: a #GSrvTarget
+ *
+ * Gets @target's port
+ *
+ * Returns: @target's port
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_get_priority:
+ * @target: a #GSrvTarget
+ *
+ * Gets @target's priority. You should not need to look at this;
+ * #GResolver already sorts the targets according to the algorithm in
+ * RFC 2782.
+ *
+ * Returns: @target's priority
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_get_weight:
+ * @target: a #GSrvTarget
+ *
+ * Gets @target's weight. You should not need to look at this;
+ * #GResolver already sorts the targets according to the algorithm in
+ * RFC 2782.
+ *
+ * Returns: @target's weight
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_list_sort: (skip)
+ * @targets: a #GList of #GSrvTarget
+ *
+ * Sorts @targets in place according to the algorithm in RFC 2782.
+ *
+ * Returns: (transfer full): the head of the sorted list.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_srv_target_new:
+ * @hostname: the host that the service is running on
+ * @port: the port that the service is running on
+ * @priority: the target's priority
+ * @weight: the target's weight
+ *
+ * Creates a new #GSrvTarget with the given parameters.
+ *
+ * You should not need to use this; normally #GSrvTargets are
+ * created by #GResolver.
+ *
+ * Returns: a new #GSrvTarget.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_static_resource_fini:
+ * @static_resource: pointer to a static #GStaticResource
+ *
+ * Finalized a GResource initialized by g_static_resource_init().
+ *
+ * This is normally used by code generated by
+ * [glib-compile-resources][glib-compile-resources]
+ * and is not typically used by other code.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_static_resource_get_resource:
+ * @static_resource: pointer to a static #GStaticResource
+ *
+ * Gets the GResource that was registered by a call to g_static_resource_init().
+ *
+ * This is normally used by code generated by
+ * [glib-compile-resources][glib-compile-resources]
+ * and is not typically used by other code.
+ *
+ * Returns: (transfer none): a #GResource
+ * Since: 2.32
+ */
+
+
+/**
+ * g_static_resource_init:
+ * @static_resource: pointer to a static #GStaticResource
+ *
+ * Initializes a GResource from static data using a
+ * GStaticResource.
+ *
+ * This is normally used by code generated by
+ * [glib-compile-resources][glib-compile-resources]
+ * and is not typically used by other code.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * 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_utf8(). 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
+ *
+ * Creates 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
+ *
+ * Creates 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
+ * @...: more commandline 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.
+ *
+ * Cancelling @cancellable doesn't kill the subprocess. Call
+ * g_subprocess_force_exit() if it is desirable.
+ *
+ * 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_completed:
+ * @task: a #GTask.
+ *
+ * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
+ * the task’s callback is invoked, and will return %FALSE if called from inside
+ * the callback.
+ *
+ * Returns: %TRUE if the task has completed, %FALSE otherwise.
+ * Since: 2.44
+ */
+
+
+/**
+ * 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.
*
- * Copies @target
+ * 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).
*
- * Returns: a copy of @target
- * Since: 2.22
+ * 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_srv_target_free:
- * @target: a #GSrvTarget
+ * g_task_return_error_if_cancelled:
+ * @task: a #GTask
*
- * Frees @target
+ * 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).
*
- * Since: 2.22
+ * Returns: %TRUE if @task has been cancelled, %FALSE if not
+ * Since: 2.36
*/
/**
- * g_srv_target_get_hostname:
- * @target: a #GSrvTarget
+ * g_task_return_int:
+ * @task: a #GTask.
+ * @result: the integer (#gssize) result of a task function.
*
- * Gets @target's hostname (in ASCII form; if you are going to present
- * this to the user, you should use g_hostname_is_ascii_encoded() to
- * check if it contains encoded Unicode segments, and use
- * g_hostname_to_unicode() to convert it if it does.)
+ * Sets @task's result to @result and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
*
- * Returns: @target's hostname
- * Since: 2.22
+ * Since: 2.36
*/
/**
- * g_srv_target_get_port:
- * @target: a #GSrvTarget
+ * 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.
*
- * Gets @target's port
+ * 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).
*
- * Returns: @target's port
- * Since: 2.22
+ * See also g_task_return_error().
+ *
+ * Since: 2.36
*/
/**
- * g_srv_target_get_priority:
- * @target: a #GSrvTarget
+ * 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.
*
- * Gets @target's priority. You should not need to look at this;
- * #GResolver already sorts the targets according to the algorithm in
- * RFC 2782.
+ * 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().
*
- * Returns: @target's priority
- * Since: 2.22
+ * "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_srv_target_get_weight:
- * @target: a #GSrvTarget
+ * g_task_run_in_thread:
+ * @task: a #GTask
+ * @task_func: a #GTaskThreadFunc
*
- * Gets @target's weight. You should not need to look at this;
- * #GResolver already sorts the targets according to the algorithm in
- * RFC 2782.
+ * Runs @task_func in another thread. When @task_func returns, @task's
+ * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
*
- * Returns: @target's weight
- * Since: 2.22
+ * 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_srv_target_list_sort: (skip)
- * @targets: a #GList of #GSrvTarget
+ * g_task_run_in_thread_sync:
+ * @task: a #GTask
+ * @task_func: a #GTaskThreadFunc
*
- * Sorts @targets in place according to the algorithm in RFC 2782.
+ * 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.
*
- * Returns: (transfer full): the head of the sorted list.
- * Since: 2.22
+ * 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.
+ * #GTask:completed will be set to %TRUE just before this function returns.
+ *
+ * Since: 2.36
*/
/**
- * g_srv_target_new:
- * @hostname: the host that the service is running on
- * @port: the port that the service is running on
- * @priority: the target's priority
- * @weight: the target's weight
+ * g_task_set_check_cancellable:
+ * @task: the #GTask
+ * @check_cancellable: whether #GTask will check the state of
+ * its #GCancellable for you.
*
- * Creates a new #GSrvTarget with the given parameters.
+ * 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.
*
- * You should not need to use this; normally #GSrvTarget<!-- -->s are
- * created by #GResolver.
+ * 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()).
*
- * Returns: a new #GSrvTarget.
- * Since: 2.22
+ * If you are using g_task_set_return_on_cancel() as well, then
+ * you must leave check-cancellable set %TRUE.
+ *
+ * Since: 2.36
*/
/**
- * g_static_resource_fini:
- * @static_resource: pointer to a static #GStaticResource
+ * g_task_set_priority:
+ * @task: the #GTask
+ * @priority: the [priority][io-priority] of the request
*
- * Finalized a GResource initialized by g_static_resource_init().
+ * Sets @task's priority. If you do not call this, it will default to
+ * %G_PRIORITY_DEFAULT.
*
- * This is normally used by code generated by
- * <link linkend="glib-compile-resources">glib-compile-resources</link>
- * and is not typically used by other code.
+ * 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.32
+ * Since: 2.36
*/
/**
- * g_static_resource_get_resource:
- * @static_resource: pointer to a static #GStaticResource
+ * g_task_set_return_on_cancel:
+ * @task: the #GTask
+ * @return_on_cancel: whether the task returns automatically when
+ * it is cancelled.
*
- * Gets the GResource that was registred by a call to g_static_resource_init().
+ * 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().
*
- * This is normally used by code generated by
- * <link linkend="glib-compile-resources">glib-compile-resources</link>
- * and is not typically used by other code.
+ * 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.
*
- * Returns: (transfer none): a #GResource
- * Since: 2.32
+ * 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_static_resource_init:
- * @static_resource: pointer to a static #GStaticResource
+ * g_task_set_source_tag:
+ * @task: the #GTask
+ * @source_tag: an opaque pointer indicating the source of this task
*
- * Initializes a GResource from static data using a
- * GStaticResource.
+ * 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.
*
- * This is normally used by code generated by
- * <link linkend="glib-compile-resources">glib-compile-resources</link>
- * and is not typically used by other code.
+ * 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
*
- * Since: 2.32
+ * Sets @task's task data (freeing the existing task data, if any).
+ *
+ * Since: 2.36
*/
* @connection: a #GTcpConnection
* @graceful_disconnect: Whether to do graceful disconnects or not
*
- * This enabled graceful disconnects on close. A graceful disconnect
+ * This enables graceful disconnects on close. A graceful disconnect
* means that we signal the receiving end that the connection is terminated
* and wait for it to close the connection before closing the connection.
*
* @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().
*/
* 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.
*/
* g_test_dbus_get_flags:
* @self: a #GTestDBus
*
- *
+ * Get the flags of the #GTestDBus object.
*
* Returns: the value of #GTestDBus:flags property
*/
* @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.
*
* 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>
*/
/**
* 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.
*
* 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",
*
* 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
*/
/**
* 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.
*
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
*
* 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
*/
/**
+ * g_tls_certificate_is_same:
+ * @cert_one: first certificate to compare
+ * @cert_two: second certificate to compare
+ *
+ * Check if two #GTlsCertificate objects represent the same certificate.
+ * The raw DER byte data of the two certificates are checked for equality.
+ * This has the effect that two certificates may compare equal even if
+ * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
+ * #GTlsCertificate:private-key-pem properties differ.
+ *
+ * Returns: whether the same or not
+ * Since: 2.34
+ */
+
+
+/**
* g_tls_certificate_list_new_from_file:
* @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
*/
* @file: file containing a PEM-encoded certificate to import
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
- * @file cannot be read or parsed, the function will return %NULL and
+ * Creates a #GTlsCertificate from the PEM-encoded data in @file. The
+ * returned certificate will be the first certificate found in @file. As
+ * of GLib 2.44, if @file contains more certificates it will try to load
+ * a certificate chain. All certificates will be verified in the order
+ * found (top-level certificate should be the last one in the file) and
+ * the #GTlsCertificate:issuer property of each certificate will be set
+ * accordingly if the verification succeeds. If any certificate in the
+ * chain cannot be verified, the first certificate in the file will
+ * still be returned.
+ *
+ * If @file cannot be read or parsed, the function will return %NULL and
* set @error. Otherwise, this behaves like
* g_tls_certificate_new_from_pem().
*
/**
* g_tls_certificate_new_from_files:
- * @cert_file: file containing a PEM-encoded certificate to import
+ * @cert_file: file containing one or more PEM-encoded certificates to
+ * import
* @key_file: file containing a PEM-encoded private key to import
* @error: #GError for error reporting, or %NULL to ignore.
*
* Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
- * and @key_file. If either file cannot be read or parsed, the
- * function will return %NULL and set @error. Otherwise, this behaves
- * like g_tls_certificate_new_from_pem().
+ * and @key_file. The returned certificate will be the first certificate
+ * found in @cert_file. As of GLib 2.44, if @cert_file contains more
+ * certificates it will try to load a certificate chain. All
+ * certificates will be verified in the order found (top-level
+ * certificate should be the last one in the file) and the
+ * #GTlsCertificate:issuer property of each certificate will be set
+ * accordingly if the verification succeeds. If any certificate in the
+ * chain cannot be verified, the first certificate in the file will
+ * still be returned.
+ *
+ * If either file cannot be read or parsed, the function will return
+ * %NULL and set @error. Otherwise, this behaves like
+ * g_tls_certificate_new_from_pem().
*
* Returns: the new certificate, or %NULL on error
* Since: 2.28
* @length: the length of @data, or -1 if it's 0-terminated.
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
- * If @data includes both a certificate and a private key, then the
+ * Creates a #GTlsCertificate from the PEM-encoded data in @data. If
+ * @data includes both a certificate and a private key, then the
* returned certificate will include the private key data as well. (See
* the #GTlsCertificate:private-key-pem property for information about
* supported formats.)
*
- * If @data includes multiple certificates, only the first one will be
- * parsed.
+ * The returned certificate will be the first certificate found in
+ * @data. As of GLib 2.44, if @data contains more certificates it will
+ * try to load a certificate chain. All certificates will be verified in
+ * the order found (top-level certificate should be the last one in the
+ * file) and the #GTlsCertificate:issuer property of each certificate
+ * will be set accordingly if the verification succeeds. If any
+ * certificate in the chain cannot be verified, the first certificate in
+ * the file will still be returned.
*
* Returns: the new certificate, or %NULL if @data is invalid
* Since: 2.28
* 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
*/
*
* 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
*/
* 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
*/
* 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
*/
* 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
*/
/**
* 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
* 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
*/
*
* %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
*/
* and between applications. If a certificate is modified in the database,
* then it is not guaranteed that this handle will continue to point to it.
*
- * Returns: (allow-none): a newly allocated string containing the handle.
+ * Returns: (nullable): a newly allocated string containing the
+ * handle.
* Since: 2.30
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
*
* 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
*/
/**
+ * 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
*
/**
- * 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
* calculated automatically. (Note that the terminating nul is not
* considered part of the password in this case.)
*
- * Virtual: set_value
* Since: 2.30
*/
* 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
*/
* 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
*/
* 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
*/
* 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
*/
/**
* 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.
* 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
*/
/**
* 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.
* 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
*/
/**
* 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.
* 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
*/
/**
* 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.
*/
*
* 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.
*/
* 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()
*/
/**
+ * g_unix_mount_guess_symbolic_icon:
+ * @mount_entry: a #GUnixMountEntry
+ *
+ * Guesses the symbolic icon of a Unix mount.
+ *
+ * Returns: (transfer full): a #GIcon
+ * Since: 2.34
+ */
+
+
+/**
+ * g_unix_mount_guess_type:
+ * @mount_entry: a #GUnixMount.
+ *
+ * Guesses the type of a unix mount. If the mount type cannot be
+ * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
+ *
+ * Returns: a #GUnixMountType.
+ */
+
+
+/**
* g_unix_mount_is_readonly:
* @mount_entry: a #GUnixMount.
*
/**
+ * g_unix_mount_monitor_get:
+ *
+ * Gets the #GUnixMountMonitor for the current thread-default main
+ * context.
+ *
+ * The mount monitor can be used to monitor for changes to the list of
+ * mounted filesystems as well as the list of mount points (ie: fstab
+ * entries).
+ *
+ * You must only call g_object_unref() on the return value from under
+ * the same main context as you called this function.
+ *
+ * Returns: (transfer full): the #GUnixMountMonitor.
+ * Since: 2.44
+ */
+
+
+/**
* g_unix_mount_monitor_new:
*
- * Gets a new #GUnixMountMonitor. The default rate limit for which the
- * monitor will report consecutive changes for the mount and mount
- * point entry files is the default for a #GFileMonitor. Use
- * g_unix_mount_monitor_set_rate_limit() to change this.
+ * Deprecated alias for g_unix_mount_monitor_get().
+ *
+ * This function was never a true constructor, which is why it was
+ * renamed.
*
* Returns: a #GUnixMountMonitor.
+ * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead.
*/
/**
* 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.
+ *
+ * This function does nothing.
*
- * Sets the rate limit to which the @mount_monitor will report
- * consecutive change events to the mount and mount point entry files.
+ * Before 2.44, this was a partially-effective way of controlling the
+ * rate at which events would be reported under some uncommon
+ * circumstances. Since @mount_monitor is a singleton, it also meant
+ * that calling this function would have side effects for other users of
+ * the monitor.
*
* Since: 2.18
+ * Deprecated: 2.44: This function does nothing. Don't call it.
*/
*
* 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.
*/
* 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()
+ */
+
+
+/**
+ * g_unix_mount_point_guess_symbolic_icon:
+ * @mount_point: a #GUnixMountPoint
+ *
+ * Guesses the symbolic icon of a Unix mount point.
+ *
+ * Returns: (transfer full): a #GIcon
+ * Since: 2.34
+ */
+
+
+/**
+ * g_unix_mount_point_guess_type:
+ * @mount_point: a #GUnixMountPoint.
+ *
+ * Guesses the type of a unix mount point.
+ * If the mount type cannot be determined,
+ * returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
+ *
+ * Returns: a #GUnixMountType.
*/
* 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.
*/
* 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.
*/
/**
* g_unix_socket_address_abstract_names_supported:
*
- * Checks if abstract unix domain socket names are supported.
+ * Checks if abstract UNIX domain socket names are supported.
*
* Returns: %TRUE if supported, %FALSE otherwise
* Since: 2.22
* 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.
*
*
* 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().
*/
* 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().
*/
*
* 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.
*/
*
* 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.
*/
* 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
/**
* 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
/**
* 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
*/
* 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.
*/
* 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: (nullable) (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.
*/
* @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
+ *
+ * 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.
+ * 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.
*/
* 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.
*/
*
* 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.
*/
*
* 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().
*/
*
* 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().
*/
/**
- * 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
*/
* 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
*/
*
* 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
*/
/**
- * get_all_desktop_entries_for_mime_type:
- * @mime_type: a mime type.
- * @except: NULL or a strv list
- *
- * Returns all the desktop ids for @mime_type. The desktop files
- * are listed in an order so that default applications are listed before
- * non-default ones, and handlers for inherited mimetypes are listed
- * after the base ones.
- *
- * Optionally doesn't list the desktop ids given in the @except
+ * get_viewable_logical_drives:
*
- * Returns: a #GList containing the desktop ids which claim to handle @mime_type.
- */
-
-
-/**
- * mime_info_cache_reload:
- * @dir: directory path which needs reloading.
+ * Returns the list of logical and viewable drives as defined by
+ * GetLogicalDrives() and the registry keys
+ * Software\Microsoft\Windows\CurrentVersion\Policies\Explorer under
+ * HKLM or HKCU. If neither key exists the result of
+ * GetLogicalDrives() is returned.
*
- * Reload the mime information for the @dir.
+ * Returns: bitmask with same meaning as returned by GetLogicalDrives()
*/
projects / platform / upstream / gobject-introspection.git / blobdiff