/************************************************************/
/**
+ * 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_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
* @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
* @get_action_state: the virtual function pointer for g_action_group_get_action_state()
- * @set_action_state: the virtual function pointer for g_action_group_set_action_state()
+ * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* @query_action: the virtual function pointer for g_action_group_query_action()
* @activate_action: the virtual function pointer for g_action_group_activate_action()
- * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* @action_added: the class closure for the #GActionGroup::action-added signal
* @action_removed: the class closure for the #GActionGroup::action-removed signal
* @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
* @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()
/**
- * GAppInfo:
+ * GAppInfoMonitor:
*
- * Information about an installed application and methods to launch
- * it (with file arguments).
+ * 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
*/
/**
- * GAppInfoCreateFlags:
- * @G_APP_INFO_CREATE_NONE: No flags.
- * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens in a terminal window.
- * @G_APP_INFO_CREATE_SUPPORTS_URIS: Application supports URI arguments.
- * @G_APP_INFO_CREATE_SUPPORTS_STARTUP_NOTIFICATION: Application supports startup notification. Since 2.26
+ * GAppInfoMonitor::changed:
*
- * Flags used when creating a #GAppInfo.
+ * Signal emitted when the app info database for changes (ie: newly installed
+ * or removed applications).
*/
/**
- * GAppInfoIface:
- * @g_iface: The parent interface.
- * @dup: Copies a #GAppInfo.
- * @equal: Checks two #GAppInfo<!-- -->s for equality.
- * @get_id: Gets a string identifier for a #GAppInfo.
- * @get_name: Gets the name of the application for a #GAppInfo.
- * @get_description: Gets a short description for the application described by the #GAppInfo.
- * @get_executable: Gets the executable name for the #GAppInfo.
- * @get_icon: Gets the #GIcon for the #GAppInfo.
- * @launch: Launches an application specified by the #GAppInfo.
- * @supports_uris: Indicates whether the application specified supports launching URIs.
- * @supports_files: Indicates whether the application specified accepts filename arguments.
- * @launch_uris: Launches an application with a list of URIs.
- * @should_show: Returns whether an application should be shown (e.g. when getting a list of installed applications). <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> <citetitle>FreeDesktop.Org Startup Notification Specification</citetitle></ulink>.
- * @set_as_default_for_type: Sets an application as default for a given content type.
- * @set_as_default_for_extension: Sets an application as default for a given file extension.
- * @add_supports_type: Adds to the #GAppInfo information about supported file types.
- * @can_remove_supports_type: Checks for support for removing supported file types from a #GAppInfo.
- * @remove_supports_type: Removes a supported application type from a #GAppInfo.
- * @can_delete: Checks if a #GAppInfo can be deleted. Since 2.20
- * @do_delete: Deletes a #GAppInfo. Since 2.20
- * @get_commandline: Gets the commandline for the #GAppInfo. Since 2.20
- * @get_display_name: Gets the display name for the #GAppInfo. Since 2.24
- * @set_as_last_used_for_type: Sets the application as the last used. See g_app_info_set_as_last_used_for_type().
+ * GAppLaunchContext::launch-failed:
+ * @context: the object emitting the signal
+ * @startup_notify_id: the startup notification id for the failed launch
*
- * Application Information interface, for operating system portability.
+ * 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:
+ * 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.
*
- * Integrating the launch with the launching application. This is used to
- * handle for instance startup notification and launching the new application
- * on the same screen as the launching window.
+ * Since: 2.36
*/
/**
* GApplication:
*
- *
+ * #GApplication is an opaque data structure and can only be accessed
+ * using the following functions.
*
* Since: 2.28
*/
/**
* 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.
- *
- * process. See g_application_command_line_set_exit_status().
+ * 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().
+ */
+
+
+/**
+ * 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
+ * @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.
*
/**
- * GApplicationCommandLineClass:
+ * GApplicationCommandLine:
*
- * The <structname>GApplicationCommandLineClass</structname> structure
- * contains private data only
- *
- * Since: 2.28
+ * #GApplicationCommandLine is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GApplicationFlags:
- * @G_APPLICATION_FLAGS_NONE: Default
- * @G_APPLICATION_IS_SERVICE: Run as a service. In this mode, registration fails if the service is already running, and the application will stay around for a while when the use count falls to zero.
- * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance.
- * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for details.
- * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details.
- * @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected to use the <envar>GIT_COMMITTER_NAME</envar> environment variable when editing a git commit message. The environment is available to the #GApplication::command-line signal handler, via g_application_command_line_getenv().
- * @G_APPLICATION_NON_UNIQUE: Make no attempts to do any of the typical single-instance application negotiation. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process. Since: 2.30.
+ * GApplicationCommandLineClass:
*
- * Flags used to define the behaviour of a #GApplication.
+ * The #GApplicationCommandLineClass-struct
+ * contains private data only.
*
* Since: 2.28
*/
/**
- * GAskPasswordFlags:
- * @G_ASK_PASSWORD_NEED_PASSWORD: operation requires a password.
- * @G_ASK_PASSWORD_NEED_USERNAME: operation requires a username.
- * @G_ASK_PASSWORD_NEED_DOMAIN: operation requires a domain.
- * @G_ASK_PASSWORD_SAVING_SUPPORTED: operation supports saving settings.
- * @G_ASK_PASSWORD_ANONYMOUS_SUPPORTED: operation supports anonymous users.
+ * GBytesIcon:bytes:
*
- * #GAskPasswordFlags are used to request specific information from the
- * user, or to notify the user of their choices in an authentication
- * situation.
+ * The bytes containing the icon.
*/
/**
- * GAsyncInitable:
+ * GCancellable::cancelled:
+ * @cancellable: a #GCancellable.
*
- * Interface for asynchronously initializable objects.
+ * Emitted when the operation has been cancelled.
*
- * Since: 2.22
+ * Can be used by implementations of cancellable operations. If the
+ * operation is cancelled from another thread, the signal will be
+ * emitted in the thread that cancelled the operation, not the
+ * thread that is running the operation.
+ *
+ * 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 after
+ * a call to g_signal_handler_disconnect() for that handler has
+ * already returned.
+ *
+ * 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
+ * g_cancellable_disconnect() which protect against problems
+ * like this.
+ *
+ * An example of how to us this:
+ * |[<!-- 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
+ * my_data = my_data_new (...);
+ *
+ * id = 0;
+ * if (cancellable)
+ * id = g_cancellable_connect (cancellable,
+ * G_CALLBACK (cancelled_handler)
+ * data, NULL);
+ *
+ * // cancellable operation here...
+ *
+ * g_cancellable_disconnect (cancellable, id);
+ *
+ * // cancelled_handler is never called after this, it is now safe
+ * // to free the data
+ * my_data_free (my_data);
+ * ]|
+ *
+ * Note that the cancelled signal is emitted in the thread that
+ * the user cancelled from, which may be the main thread. So, the
+ * cancellable signal should not do something that can block.
*/
/**
- * GAsyncInitableIface:
- * @g_iface: The parent interface.
- * @init_async: Starts initialization of the object.
- * @init_finish: Finishes initialization of the object.
- *
- * Provides an interface for asynchronous initializing object such that
- * initialization may fail.
+ * GCharsetConverter:
*
- * Since: 2.22
+ * Conversions between character sets.
*/
/**
- * GAsyncReadyCallback:
- * @source_object: the object the asynchronous operation was started with.
- * @res: a #GAsyncResult.
- * @user_data: user data passed to the callback.
+ * GCredentials:
+ *
+ * The #GCredentials structure contains only private data and
+ * should only be accessed using the provided API.
*
- * Type definition for a function that will be called back when an asynchronous
- * operation within GIO has been completed.
+ * Since: 2.26
*/
/**
- * GAsyncResult:
+ * GCredentialsClass:
+ *
+ * Class structure for #GCredentials.
*
- * Holds results information for an asynchronous operation,
- * usually passed directly to a asynchronous _finish() operation.
+ * Since: 2.26
*/
/**
- * GAsyncResultIface:
- * @g_iface: The parent interface.
- * @get_user_data: Gets the user data passed to the callback.
- * @get_source_object: Gets the source object that issued the asynchronous operation.
+ * GDBusActionGroup:
*
- * Interface definition for #GAsyncResult.
+ * #GDBusActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GBaseFinalizeFunc:
- * @g_class: The #GTypeClass structure to finalize.
+ * GDBusAuthMechanism:credentials:
+ *
+ * If authenticating as a server, this property contains the
+ * received credentials, if any.
*
- * A callback function used by the type system to finalize those portions
- * of a derived types class structure that were setup from the corresponding
- * GBaseInitFunc() function. Class finalization basically works the inverse
- * way in which class intialization is performed.
- * See GClassInitFunc() for a discussion of the class intialization process.
+ * If authenticating as a client, the property contains the
+ * credentials that were sent, if any.
*/
/**
- * GBaseInitFunc:
- * @g_class: The #GTypeClass structure to initialize.
+ * GDBusAuthObserver:
+ *
+ * The #GDBusAuthObserver structure contains only private data and
+ * should only be accessed using the provided API.
*
- * A callback function used by the type system to do base initialization
- * of the class structures of derived types. It is called as part of the
- * initialization process of all derived classes and should reallocate
- * or reset all dynamic class members copied over from the parent class.
- * For example, class members (such as strings) that are not sufficiently
- * handled by a plain memory copy of the parent class into the derived class
- * have to be altered. See GClassInitFunc() for a discussion of the class
- * intialization process.
+ * Since: 2.26
*/
/**
- * GBinding:
+ * GDBusAuthObserver::allow-mechanism:
+ * @observer: The #GDBusAuthObserver emitting the signal.
+ * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
*
- * <structname>GBinding</structname> is an opaque structure whose members
- * cannot be accessed directly.
+ * Emitted to check if @mechanism is allowed to be used.
*
- * Since: 2.26
+ * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
+ * Since: 2.34
*/
/**
- * GBindingFlags:
- * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value.
- * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated.
- * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target.
- * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full().
- *
- * Flags to be passed to g_object_bind_property() or
- * g_object_bind_property_full().
+ * GDBusAuthObserver::authorize-authenticated-peer:
+ * @observer: The #GDBusAuthObserver emitting the signal.
+ * @stream: A #GIOStream for the #GDBusConnection.
+ * @credentials: (allow-none): Credentials received from the peer or %NULL.
*
- * This enumeration can be extended at later date.
+ * Emitted to check if a peer that is successfully authenticated
+ * is authorized.
*
+ * Returns: %TRUE if the peer is authorized, %FALSE if not.
* Since: 2.26
*/
/**
- * GBindingTransformFunc:
- * @binding: a #GBinding
- * @source_value: the value of the source property
- * @target_value: the value of the target property
- * @user_data: data passed to the transform function
- *
- * A function to be called to transform the source property of @source
- * from @source_value into the target property of @target
- * using @target_value.
+ * GDBusAuthObserverClass:
+ * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
*
- * otherwise
+ * Class structure for #GDBusAuthObserverClass.
*
- * Returns: %TRUE if the transformation was successful, and %FALSE
* Since: 2.26
*/
/**
- * GBookmarkFile:
+ * GDBusConnection:
+ *
+ * The #GDBusConnection structure contains only private data and
+ * should only be accessed using the provided API.
*
- * The <structname>GBookmarkFile</structname> struct contains only
- * private data and should not be directly accessed.
+ * Since: 2.26
*/
/**
- * GBookmarkFileError:
- * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed
- * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found
- * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark
- * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found
- * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed
- * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding
- * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing
- * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found
+ * 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
+ *
+ * Emitted when the connection is closed.
+ *
+ * The cause of this event can be
+ *
+ * - 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.
*
- * Error codes returned by bookmark file parsing.
+ * - 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
+ * once.
+ *
+ * Since: 2.26
*/
/**
- * GBoxedCopyFunc:
- * @boxed: The boxed structure to be copied.
+ * GDBusConnection:address:
*
- * This function is provided by the user and should produce a copy
- * of the passed in boxed structure.
+ * A D-Bus address specifying potential endpoints that can be used
+ * when establishing the connection.
*
- * Returns: The newly created copy of the boxed structure.
+ * Since: 2.26
*/
/**
- * GBoxedFreeFunc:
- * @boxed: The boxed structure to be freed.
+ * GDBusConnection:authentication-observer:
+ *
+ * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
*
- * This function is provided by the user and should free the boxed
- * structure passed.
+ * Since: 2.26
*/
/**
- * GBufferedInputStream:
+ * GDBusConnection:capabilities:
+ *
+ * Flags from the #GDBusCapabilityFlags enumeration
+ * representing connection features negotiated with the other peer.
*
- * Implements #GFilterInputStream with a sized input buffer.
+ * Since: 2.26
*/
/**
- * GBufferedOutputStream:
+ * GDBusConnection:closed:
*
- * An implementation of #GFilterOutputStream with a sized buffer.
+ * A boolean specifying whether the connection has been closed.
+ *
+ * Since: 2.26
*/
/**
- * GBusAcquiredCallback:
- * @connection: The #GDBusConnection to a message bus.
- * @name: The name that is requested to be owned.
- * @user_data: User data passed to g_bus_own_name().
+ * GDBusConnection:exit-on-close:
*
- * Invoked when a connection to a message bus has been obtained.
+ * A boolean specifying whether the process will be terminated (by
+ * 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.
*
* Since: 2.26
*/
/**
- * GBusNameAcquiredCallback:
- * @connection: The #GDBusConnection on which to acquired the name.
- * @name: The name being owned.
- * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
+ * GDBusConnection:flags:
*
- * Invoked when the name is acquired.
+ * Flags from the #GDBusConnectionFlags enumeration.
*
* Since: 2.26
*/
/**
- * GBusNameAppearedCallback:
- * @connection: The #GDBusConnection the name is being watched on.
- * @name: The name being watched.
- * @name_owner: Unique name of the owner of the name being watched.
- * @user_data: User data passed to g_bus_watch_name().
+ * GDBusConnection:guid:
+ *
+ * The GUID of the peer performing the role of server when
+ * authenticating.
*
- * Invoked when the name being watched is known to have to have a owner.
+ * If you are constructing a #GDBusConnection and pass
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
+ * #GDBusConnection:flags property then you MUST also set this
+ * property to a valid guid.
+ *
+ * If you are constructing a #GDBusConnection and pass
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
+ * #GDBusConnection:flags property you will be able to read the GUID
+ * of the other peer here after the connection has been successfully
+ * initialized.
*
* Since: 2.26
*/
/**
- * GBusNameLostCallback:
- * @connection: The #GDBusConnection on which to acquire the name or %NULL if the connection was disconnected.
- * @name: The name being owned.
- * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
+ * GDBusConnection:locked:
*
- * Invoked when the name is lost or @connection has been closed.
+ * A boolean specifying whether the message is locked.
*
* Since: 2.26
*/
/**
- * GBusNameOwnerFlags:
- * @G_BUS_NAME_OWNER_FLAGS_NONE: No flags set.
- * @G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT: Allow another message bus connection to claim the the name.
- * @G_BUS_NAME_OWNER_FLAGS_REPLACE: If another message bus connection owns the name and have specified #G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection.
+ * GDBusConnection:stream:
+ *
+ * The underlying #GIOStream used for I/O.
+ *
+ * If this is passed on construction and is a #GSocketConnection,
+ * then the corresponding #GSocket will be put into non-blocking mode.
*
- * Flags used in g_bus_own_name().
+ * While the #GDBusConnection is active, it will interact with this
+ * stream from a worker thread, so it is not safe to interact with
+ * the stream directly.
*
* Since: 2.26
*/
/**
- * GBusNameVanishedCallback:
- * @connection: The #GDBusConnection the name is being watched on.
- * @name: The name being watched.
- * @user_data: User data passed to g_bus_watch_name().
+ * GDBusConnection:unique-name:
*
- * Invoked when the name being watched is known not to have to have a owner.
+ * The unique name as assigned by the message bus or %NULL if the
+ * connection is not open or not a message bus connection.
*
* Since: 2.26
*/
/**
- * GBusNameWatcherFlags:
- * @G_BUS_NAME_WATCHER_FLAGS_NONE: No flags set.
- * @G_BUS_NAME_WATCHER_FLAGS_AUTO_START: If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name.
+ * GDBusConnectionClass:
+ * @closed: Signal class handler for the #GDBusConnection::closed signal.
*
- * Flags used in g_bus_watch_name().
+ * Class structure for #GDBusConnection.
*
* Since: 2.26
*/
/**
- * GBusType:
- * @G_BUS_TYPE_STARTER: An alias for the message bus that activated the process, if any.
- * @G_BUS_TYPE_NONE: Not a message bus.
- * @G_BUS_TYPE_SYSTEM: The system-wide message bus.
- * @G_BUS_TYPE_SESSION: The login session message bus.
+ * GDBusInterfaceSkeleton::g-authorize-method:
+ * @interface: The #GDBusInterfaceSkeleton emitting the signal.
+ * @invocation: A #GDBusMethodInvocation.
+ *
+ * Emitted when a method is invoked by a remote caller and used to
+ * determine if the method call is authorized.
*
- * An enumeration for well-known message buses.
+ * 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.
+ * [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.
*
- * Since: 2.26
+ * If %FALSE is returned then no further handlers are run and the
+ * signal handler must take a reference to @invocation and finish
+ * handling the call (e.g. return an error via
+ * g_dbus_method_invocation_return_error()).
+ *
+ * Otherwise, if %TRUE is returned, signal emission continues. If no
+ * handlers return %FALSE, then the method is dispatched. If
+ * @interface has an enclosing #GDBusObjectSkeleton, then the
+ * #GDBusObjectSkeleton::authorize-method signal handlers run before
+ * the handlers for this signal.
+ *
+ * The default class handler just returns %TRUE.
+ *
+ * Please note that the common case is optimized: if no signals
+ * handlers are connected and the default class handler isn't
+ * overridden (for both @interface and the enclosing
+ * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
+ * not have the
+ * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
+ * flags set, no dedicated thread is ever used and the call will be
+ * handled in the same thread as the object that @interface belongs
+ * to was exported in.
+ *
+ * Returns: %TRUE if the call is authorized, %FALSE otherwise.
+ * Since: 2.30
*/
/**
- * GCClosure:
- * @closure: the #GClosure
- * @callback: the callback function
+ * GDBusInterfaceSkeleton:g-flags:
+ *
+ * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
*
- * A #GCClosure is a specialization of #GClosure for C function callbacks.
+ * Since: 2.30
*/
/**
- * GCallback:
+ * GDBusMenuModel:
*
- * The type used for callback functions in structure definitions and function
- * signatures. This doesn't mean that all callback functions must take no
- * parameters and return void. The required signature of a callback function
- * is determined by the context in which is used (e.g. the signal to which it
- * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback.
+ * #GDBusMenuModel is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GCancellable:
+ * GDBusMessage:
+ *
+ * The #GDBusMessage structure contains only private data and should
+ * only be accessed using the provided API.
*
- * Allows actions to be cancelled.
+ * Since: 2.26
*/
/**
- * GCancellable::cancelled:
- * @cancellable: a #GCancellable.
+ * GDBusMessageClass:
*
- * Emitted when the operation has been cancelled.
+ * Class structure for #GDBusMessage.
*
- * Can be used by implementations of cancellable operations. If the
- * operation is cancelled from another thread, the signal will be
- * emitted in the thread that cancelled the operation, not the
- * thread that is running the operation.
+ * Since: 2.26
+ */
+
+
+/**
+ * GDBusMethodInvocation:
*
- * 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.
- *
- * 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.
- *
- * In order to make it safe and easy to connect handlers there
- * are two helper functions: g_cancellable_connect() and
- * g_cancellable_disconnect() which protect against problems
- * 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))
- * return;
- *
- * /<!-- -->* Set up all the data needed to be able to
- * * handle cancellation of the operation *<!-- -->/
- * my_data = my_data_new (...);
- *
- * id = 0;
- * if (cancellable)
- * id = g_cancellable_connect (cancellable,
- * G_CALLBACK (cancelled_handler)
- * data, NULL);
- *
- * /<!-- -->* cancellable operation here... *<!-- -->/
- *
- * g_cancellable_disconnect (cancellable, id);
- *
- * /<!-- -->* cancelled_handler is never called after this, it
- * * is now safe to free the data *<!-- -->/
- * my_data_free (my_data);
- * ]|
+ * The #GDBusMethodInvocation structure contains only private data and
+ * should only be accessed using the provided API.
*
- * Note that the cancelled signal is emitted in the thread that
- * the user cancelled from, which may be the main thread. So, the
- * cancellable signal should not do something that can block.
+ * Since: 2.26
*/
/**
- * GCancellableSourceFunc:
- * @cancellable: the #GCancellable
- * @user_data: data passed in by the user.
+ * GDBusMethodInvocationClass:
*
- * This is the function type of the callback used for the #GSource
- * returned by g_cancellable_source_new().
+ * Class structure for #GDBusMethodInvocation.
*
- * Returns: it should return %FALSE if the source should be removed.
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * GCharsetConverter:
+ * GDBusObject:
*
- * Conversions between character sets.
+ * #GDBusObject is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GChecksum:
+ * GDBusObject::interface-added:
+ * @object: The #GDBusObject emitting the signal.
+ * @interface: The #GDBusInterface that was added.
*
- * An opaque structure representing a checksumming operation.
- * To create a new GChecksum, use g_checksum_new(). To free
- * a GChecksum, use g_checksum_free().
+ * Emitted when @interface is added to @object.
*
- * Since: 2.16
+ * Since: 2.30
*/
/**
- * GChecksumType:
- * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm
- * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm
- * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm
- *
- * The hashing algorithm to be used by #GChecksum when performing the
- * digest of some data.
+ * GDBusObject::interface-removed:
+ * @object: The #GDBusObject emitting the signal.
+ * @interface: The #GDBusInterface that was removed.
*
- * Note that the #GChecksumType enumeration may be extended at a later
- * date to include new hashing algorithm types.
+ * Emitted when @interface is removed from @object.
*
- * Since: 2.16
+ * Since: 2.30
*/
/**
- * GChildWatchFunc:
- * @pid: the process id of the child process
- * @status: Status information about the child process, see waitpid(2) for more information about this field
- * @user_data: user data passed to g_child_watch_add()
+ * GDBusObjectManager:
*
- * The type of functions to be called when a child exists.
+ * #GDBusObjectManager is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GClassFinalizeFunc:
- * @g_class: The #GTypeClass structure to finalize.
- * @class_data: The @class_data member supplied via the #GTypeInfo structure.
+ * GDBusObjectManager::interface-added:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject on which an interface was added.
+ * @interface: The #GDBusInterface that was added.
+ *
+ * Emitted when @interface is added to @object.
+ *
+ * This signal exists purely as a convenience to avoid having to
+ * connect signals to all objects managed by @manager.
*
- * A callback function used by the type system to finalize a class.
- * This function is rarely needed, as dynamically allocated class resources
- * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
- * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
- * structure of a static type is invalid, because classes of static types
- * will never be finalized (they are artificially kept alive when their
- * reference count drops to zero).
+ * Since: 2.30
*/
/**
- * GClassInitFunc:
- * @g_class: The #GTypeClass structure to initialize.
- * @class_data: The @class_data member supplied via the #GTypeInfo structure.
+ * GDBusObjectManager::interface-removed:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject on which an interface was removed.
+ * @interface: The #GDBusInterface that was removed.
*
- * A callback function used by the type system to initialize the class
- * of a specific type. This function should initialize all static class
- * members.
- * The initialization process of a class involves:
- * <itemizedlist>
- * <listitem><para>
- * 1 - Copying common members from the parent class over to the
- * derived class structure.
- * </para></listitem>
- * <listitem><para>
- * 2 - Zero initialization of the remaining members not copied
- * over from the parent class.
- * </para></listitem>
- * <listitem><para>
- * 3 - Invocation of the GBaseInitFunc() initializers of all parent
- * types and the class' type.
- * </para></listitem>
- * <listitem><para>
- * 4 - Invocation of the class' GClassInitFunc() initializer.
- * </para></listitem>
- * </itemizedlist>
- * Since derived classes are partially initialized through a memory copy
- * of the parent class, the general rule is that GBaseInitFunc() and
- * GBaseFinalizeFunc() should take care of necessary reinitialization
- * and release of those class members that were introduced by the type
- * that specified these GBaseInitFunc()/GBaseFinalizeFunc().
- * GClassInitFunc() should only care about initializing static
- * class members, while dynamic class members (such as allocated strings
- * or reference counted resources) are better handled by a GBaseInitFunc()
- * for this type, so proper initialization of the dynamic class members
- * is performed for class initialization of derived types as well.
- * An example may help to correspond the intend of the different class
- * initializers:
+ * Emitted when @interface has been removed from @object.
*
- * |[
- * typedef struct {
- * GObjectClass parent_class;
- * gint static_integer;
- * gchar *dynamic_string;
- * } TypeAClass;
- * static void
- * type_a_base_class_init (TypeAClass *class)
- * {
- * class->dynamic_string = g_strdup ("some string");
- * }
- * static void
- * type_a_base_class_finalize (TypeAClass *class)
- * {
- * g_free (class->dynamic_string);
- * }
- * static void
- * type_a_class_init (TypeAClass *class)
- * {
- * class->static_integer = 42;
- * }
+ * This signal exists purely as a convenience to avoid having to
+ * connect signals to all objects managed by @manager.
*
- * typedef struct {
- * TypeAClass parent_class;
- * gfloat static_float;
- * GString *dynamic_gstring;
- * } TypeBClass;
- * static void
- * type_b_base_class_init (TypeBClass *class)
- * {
- * class->dynamic_gstring = g_string_new ("some other string");
- * }
- * static void
- * type_b_base_class_finalize (TypeBClass *class)
- * {
- * g_string_free (class->dynamic_gstring);
- * }
- * static void
- * type_b_class_init (TypeBClass *class)
- * {
- * class->static_float = 3.14159265358979323846;
- * }
- * ]|
- * Initialization of TypeBClass will first cause initialization of
- * TypeAClass (derived classes reference their parent classes, see
- * g_type_class_ref() on this).
- * Initialization of TypeAClass roughly involves zero-initializing its fields,
- * then calling its GBaseInitFunc() type_a_base_class_init() to allocate
- * its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
- * type_a_class_init() to initialize its static members (static_integer).
- * The first step in the initialization process of TypeBClass is then
- * a plain memory copy of the contents of TypeAClass into TypeBClass and
- * zero-initialization of the remaining fields in TypeBClass.
- * The dynamic members of TypeAClass within TypeBClass now need
- * reinitialization which is performed by calling type_a_base_class_init()
- * with an argument of TypeBClass.
- * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
- * is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
- * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
- * is called to complete the initialization process with the static members
- * (static_float).
- * Corresponding finalization counter parts to the GBaseInitFunc() functions
- * have to be provided to release allocated resources at class finalization
- * time.
+ * Since: 2.30
*/
/**
- * GClosure:
- * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke()
- * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate()
+ * GDBusObjectManager::object-added:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject that was added.
*
- * A #GClosure represents a callback supplied by the programmer.
- */
-
-
-/**
- * GClosureMarshal:
- * @closure: the #GClosure to which the marshaller belongs
- * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value.
- * @n_param_values: the length of the @param_values array
- * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure
- * @invocation_hint: (allow-none): the invocation hint given as the last argument to g_closure_invoke()
- * @marshal_data: (allow-none): additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal()
+ * Emitted when @object is added to @manager.
*
- * The type used for marshaller functions.
+ * Since: 2.30
*/
/**
- * GClosureNotify:
- * @data: data specified when registering the notification callback
- * @closure: the #GClosure on which the notification is emitted
+ * GDBusObjectManager::object-removed:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject that was removed.
*
- * The type used for the various notification callbacks which can be registered
- * on closures.
+ * Emitted when @object is removed from @manager.
+ *
+ * Since: 2.30
*/
/**
- * GConnectFlags:
- * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal.
- * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler.
+ * GDBusObjectManagerClient::interface-proxy-properties-changed:
+ * @manager: The #GDBusObjectManagerClient emitting the signal.
+ * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
+ * @interface_proxy: The #GDBusProxy that has properties that are changing.
+ * @changed_properties: A #GVariant containing the properties that changed.
+ * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
*
- * The connection flags are used to specify the behaviour of a signal's
- * connection.
+ * Emitted when one or more D-Bus properties on proxy changes. The
+ * local cache has already been updated when this signal fires. Note
+ * that both @changed_properties and @invalidated_properties are
+ * guaranteed to never be %NULL (either may be empty though).
+ *
+ * This signal exists purely as a convenience to avoid having to
+ * connect signals to all interface proxies managed by @manager.
+ *
+ * This signal is emitted in the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * that @manager was constructed in.
+ *
+ * Since: 2.30
*/
/**
- * GConvertError:
- * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported.
- * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input.
- * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason.
- * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input.
- * @G_CONVERT_ERROR_BAD_URI: URI is invalid.
- * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path.
+ * GDBusObjectManagerClient::interface-proxy-signal:
+ * @manager: The #GDBusObjectManagerClient emitting the signal.
+ * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
+ * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
+ * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
+ * @signal_name: The signal name.
+ * @parameters: A #GVariant tuple with parameters for the signal.
+ *
+ * Emitted when a D-Bus signal is received on @interface_proxy.
+ *
+ * This signal exists purely as a convenience to avoid having to
+ * connect signals to all interface proxies managed by @manager.
+ *
+ * This signal is emitted in the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * that @manager was constructed in.
*
- * Error codes returned by character set conversion routines.
+ * Since: 2.30
*/
/**
- * GConverter:
+ * GDBusObjectManagerClient:bus-type:
*
- * Seek object for streaming operations.
+ * If this property is not %G_BUS_TYPE_NONE, then
+ * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
+ * #GDBusConnection obtained by calling g_bus_get() with the value
+ * of this property.
*
- * Since: 2.24
+ * Since: 2.30
*/
/**
- * GConverterFlags:
- * @G_CONVERTER_NO_FLAGS: No flags.
- * @G_CONVERTER_INPUT_AT_END: At end of input data
- * @G_CONVERTER_FLUSH: Flush data
+ * GDBusObjectManagerClient:connection:
*
- * Flags used when calling a g_converter_convert().
+ * The #GDBusConnection to use.
*
- * Since: 2.24
+ * Since: 2.30
*/
/**
- * GConverterIface:
- * @g_iface: The parent interface.
- * @convert: Converts data.
- * @reset: Reverts the internal state of the converter to its initial state.
+ * GDBusObjectManagerClient:flags:
*
- * Provides an interface for converting data from one type
- * to another type. The conversion can be stateful
- * and may fail at any place.
+ * Flags from the #GDBusObjectManagerClientFlags enumeration.
*
- * Since: 2.24
+ * Since: 2.30
*/
/**
- * GConverterInputStream:
+ * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
+ *
+ * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
*
- * An implementation of #GFilterInputStream that allows data
- * conversion.
+ * Since: 2.30
*/
/**
- * GConverterOutputStream:
+ * GDBusObjectManagerClient:get-proxy-type-func:
+ *
+ * The #GDBusProxyTypeFunc to use when determining what #GType to
+ * use for interface proxies or %NULL.
*
- * An implementation of #GFilterOutputStream that allows data
- * conversion.
+ * Since: 2.30
*/
/**
- * GConverterResult:
- * @G_CONVERTER_ERROR: There was an error during conversion.
- * @G_CONVERTER_CONVERTED: Some data was consumed or produced
- * @G_CONVERTER_FINISHED: The conversion is finished
- * @G_CONVERTER_FLUSHED: Flushing is finished
+ * GDBusObjectManagerClient:get-proxy-type-user-data:
*
- * Results returned from g_converter_convert().
+ * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
*
- * Since: 2.24
+ * Since: 2.30
*/
/**
- * GCopyFunc:
- * @src: A pointer to the data which should be copied
- * @data: Additional data
+ * GDBusObjectManagerClient:name:
*
- * A function of this signature is used to copy the node data
- * when doing a deep-copy of a tree.
+ * The well-known name or unique name that the manager is for.
*
- * Returns: A pointer to the copy
- * Since: 2.4
+ * Since: 2.30
*/
/**
- * GCredentials:
+ * GDBusObjectManagerClient:name-owner:
*
- * The #GCredentials structure contains only private data and
- * should only be accessed using the provided API.
+ * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
+ * no-one is currently owning the name. Connect to the
+ * #GObject::notify signal to track changes to this property.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GCredentialsClass:
+ * GDBusObjectManagerClient:object-path:
*
- * Class structure for #GCredentials.
+ * The object path the manager is for.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GCredentialsType:
- * @G_CREDENTIALS_TYPE_INVALID: Indicates an invalid native credential type.
- * @G_CREDENTIALS_TYPE_LINUX_UCRED: The native credentials type is a <type>struct ucred</type>.
- * @G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED: The native credentials type is a <type>struct cmsgcred</type>.
- * @G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED: The native credentials type is a <type>struct sockpeercred</type>. Added in 2.30.
+ * GDBusObjectManagerServer:connection:
*
- * Enumeration describing different kinds of native credential types.
+ * The #GDBusConnection to export objects on.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusAnnotationInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @key: The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".
- * @value: The value of the annotation.
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GDBusObjectManagerServer:object-path:
*
- * Information about an annotation.
+ * The object path to register the manager object at.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusArgInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: Name of the argument, e.g. @unix_user_id.
- * @signature: D-Bus signature of the argument (a single complete type).
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GDBusObjectProxy:g-connection:
*
- * Information about an argument for a method or a signal.
+ * The connection of the proxy.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusAuthMechanism:credentials:
+ * GDBusObjectProxy:g-object-path:
*
- * If authenticating as a server, this property contains the
- * received credentials, if any.
+ * The object path of the proxy.
*
- * If authenticating as a client, the property contains the
- * credentials that were sent, if any.
+ * Since: 2.30
*/
/**
- * GDBusAuthObserver:
+ * GDBusObjectSkeleton::authorize-method:
+ * @object: The #GDBusObjectSkeleton emitting the signal.
+ * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
+ * @invocation: A #GDBusMethodInvocation.
*
- * The #GDBusAuthObserver structure contains only private data and
- * should only be accessed using the provided API.
+ * Emitted when a method is invoked by a remote caller and used to
+ * determine if the method call is authorized.
*
- * Since: 2.26
+ * 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.
+ *
+ * Returns: %TRUE if the call is authorized, %FALSE otherwise.
+ * Since: 2.30
*/
/**
- * GDBusAuthObserver::authorize-authenticated-peer:
- * @observer: The #GDBusAuthObserver emitting the signal.
- * @stream: A #GIOStream for the #GDBusConnection.
- * @credentials: Credentials received from the peer or %NULL.
+ * GDBusObjectSkeleton:g-object-path:
*
- * Emitted to check if a peer that is successfully authenticated
- * is authorized.
+ * The object path where the object is exported.
*
- * Returns: %TRUE if the peer is authorized, %FALSE if not.
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusAuthObserverClass:
- * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
+ * GDBusProxy::g-properties-changed:
+ * @proxy: The #GDBusProxy emitting the signal.
+ * @changed_properties: A #GVariant containing the properties that changed
+ * @invalidated_properties: A %NULL terminated array of properties that was invalidated
*
- * Class structure for #GDBusAuthObserverClass.
+ * Emitted when one or more D-Bus properties on @proxy changes. The
+ * local cache has already been updated when this signal fires. Note
+ * that both @changed_properties and @invalidated_properties are
+ * guaranteed to never be %NULL (either may be empty though).
+ *
+ * If the proxy has the flag
+ * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
+ * @invalidated_properties will always be empty.
+ *
+ * This signal corresponds to the
+ * `PropertiesChanged` D-Bus signal on the
+ * `org.freedesktop.DBus.Properties` interface.
*
* Since: 2.26
*/
/**
- * GDBusCallFlags:
- * @G_DBUS_CALL_FLAGS_NONE: No flags set.
- * @G_DBUS_CALL_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this method invocation.
+ * GDBusProxy::g-signal:
+ * @proxy: The #GDBusProxy emitting the signal.
+ * @sender_name: (allow-none): The sender of the signal or %NULL if the connection is not a bus connection.
+ * @signal_name: The name of the signal.
+ * @parameters: A #GVariant tuple with parameters for the signal.
*
- * Flags used in g_dbus_connection_call() and similar APIs.
+ * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
*
* Since: 2.26
*/
/**
- * GDBusCapabilityFlags:
- * @G_DBUS_CAPABILITY_FLAGS_NONE: No flags set.
- * @G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING: The connection supports exchanging UNIX file descriptors with the remote peer.
+ * GDBusProxy:g-bus-type:
*
- * Capabilities negotiated with the remote peer.
+ * If this property is not %G_BUS_TYPE_NONE, then
+ * #GDBusProxy:g-connection must be %NULL and will be set to the
+ * #GDBusConnection obtained by calling g_bus_get() with the value
+ * of this property.
*
* Since: 2.26
*/
/**
- * GDBusConnection:
+ * GDBusProxy:g-connection:
*
- * The #GDBusConnection structure contains only private data and
- * should only be accessed using the provided API.
+ * The #GDBusConnection the proxy is for.
*
* Since: 2.26
*/
/**
- * 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: A #GError with more details about the event or %NULL.
- *
- * Emitted when the connection is closed.
+ * GDBusProxy:g-default-timeout:
*
- * 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>
+ * The timeout to use if -1 (specifying default timeout) is passed
+ * as @timeout_msec in the g_dbus_proxy_call() and
+ * g_dbus_proxy_call_sync() functions.
*
- * Upon receiving this signal, you should give up your reference to
- * @connection. You are guaranteed that this signal is emitted only
- * once.
+ * This allows applications to set a proxy-wide timeout for all
+ * remote method invocations on the proxy. If this property is -1,
+ * the default timeout (typically 25 seconds) is used. If set to
+ * %G_MAXINT, then no timeout is used.
*
* Since: 2.26
*/
/**
- * GDBusConnection:address:
+ * GDBusProxy:g-flags:
*
- * A D-Bus address specifying potential endpoints that can be used
- * when establishing the connection.
+ * Flags from the #GDBusProxyFlags enumeration.
*
* Since: 2.26
*/
/**
- * GDBusConnection:authentication-observer:
+ * GDBusProxy:g-interface-info:
*
- * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
+ * 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 "expected interface".
*
- * Since: 2.26
- */
-
-
-/**
- * GDBusConnection:capabilities:
+ * The checks performed are:
+ * - 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.
*
- * Flags from the #GDBusCapabilityFlags enumeration
- * representing connection features negotiated with the other peer.
+ * - 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
+ * service-side is not considered an ABI break.
*
* Since: 2.26
*/
/**
- * GDBusConnection:closed:
+ * GDBusProxy:g-interface-name:
*
- * A boolean specifying whether the connection has been closed.
+ * The D-Bus interface name the proxy is for.
*
* Since: 2.26
*/
/**
- * GDBusConnection:exit-on-close:
+ * GDBusProxy:g-name:
*
- * A boolean specifying whether the process will be terminated (by
- * calling <literal>raise(SIGTERM)</literal>) if the connection
- * is closed by the remote peer.
+ * The well-known or unique name that the proxy is for.
*
* Since: 2.26
*/
/**
- * GDBusConnection:flags:
+ * GDBusProxy:g-name-owner:
*
- * Flags from the #GDBusConnectionFlags enumeration.
+ * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
+ * currently owns that name. You may connect to #GObject::notify signal to
+ * track changes to this property.
*
* Since: 2.26
*/
/**
- * GDBusConnection:guid:
- *
- * The GUID of the peer performing the role of server when
- * authenticating.
- *
- * If you are constructing a #GDBusConnection and pass
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
- * #GDBusConnection:flags property then you MUST also set this
- * property to a valid guid.
+ * GDBusProxy:g-object-path:
*
- * If you are constructing a #GDBusConnection and pass
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
- * #GDBusConnection:flags property you will be able to read the GUID
- * of the other peer here after the connection has been successfully
- * initialized.
+ * The object path the proxy is for.
*
* Since: 2.26
*/
/**
- * GDBusConnection:locked:
+ * GDBusServer:
*
- * A boolean specifying whether the message is locked.
+ * The #GDBusServer structure contains only private data and
+ * should only be accessed using the provided API.
*
* Since: 2.26
*/
/**
- * GDBusConnection:stream:
+ * GDBusServer::new-connection:
+ * @server: The #GDBusServer emitting the signal.
+ * @connection: A #GDBusConnection for the new connection.
*
- * The underlying #GIOStream used for I/O.
+ * Emitted when a new authenticated connection has been made. Use
+ * g_dbus_connection_get_peer_credentials() to figure out what
+ * identity (if any), was authenticated.
*
- * If this is passed on construction and is a #GSocketConnection,
- * then the corresponding #GSocket will be put into non-blocking mode.
+ * If you want to accept the connection, take a reference to the
+ * @connection object and return %TRUE. When you are done with the
+ * connection call g_dbus_connection_close() and give up your
+ * reference. Note that the other peer may disconnect at any time -
+ * a typical thing to do when accepting a connection is to listen to
+ * the #GDBusConnection::closed signal.
*
- * While the #GDBusConnection is active, it will interact with this
- * stream from a worker thread, so it is not safe to interact with
- * the stream directly.
+ * 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
+ * [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.
* Since: 2.26
*/
/**
- * GDBusConnection:unique-name:
+ * GDBusServer:active:
*
- * The unique name as assigned by the message bus or %NULL if the
- * connection is not open or not a message bus connection.
+ * Whether the server is currently active.
*
* Since: 2.26
*/
/**
- * GDBusConnectionClass:
- * @closed: Signal class handler for the #GDBusConnection::closed signal.
+ * GDBusServer:address:
*
- * Class structure for #GDBusConnection.
+ * The D-Bus address to listen on.
*
* Since: 2.26
*/
/**
- * GDBusConnectionFlags:
- * @G_DBUS_CONNECTION_FLAGS_NONE: No flags set.
- * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT: Perform authentication against server.
- * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER: Perform authentication against client.
- * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: When authenticating as a server, allow the anonymous authentication method.
- * @G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION: Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup.
- * @G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING: If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called.
+ * GDBusServer:authentication-observer:
*
- * Flags used when creating a new #GDBusConnection.
+ * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
*
* Since: 2.26
*/
/**
- * GDBusError:
+ * GDBusServer:client-address:
*
- * Certain timeout errors, e.g. while starting a service. Warning: this is
- * Error codes for the %G_DBUS_ERROR error domain.
+ * The D-Bus address that clients can use.
*
* Since: 2.26
*/
/**
- * GDBusErrorEntry:
- * @error_code: An error code.
- * @dbus_error_name: The D-Bus error name to associate with @error_code.
+ * GDBusServer:flags:
*
- * Struct used in g_dbus_error_register_error_domain().
+ * Flags from the #GDBusServerFlags enumeration.
*
* Since: 2.26
*/
/**
- * GDBusInterface:
+ * GDBusServer:guid:
*
- * Base type for D-Bus interfaces.
+ * The guid of the server.
*
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * GDBusInterfaceGetPropertyFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that the method was invoked on.
- * @interface_name: The D-Bus interface name for the property.
- * @property_name: The name of the property to get the value of.
- * @error: Return location for error.
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
- *
- * The type of the @get_property function in #GDBusInterfaceVTable.
+ * GDBusServerClass:
+ * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
*
- * @error is set. If the returned #GVariant is floating, it is
- * consumed - otherwise its reference count is decreased by one.
+ * Class structure for #GDBusServer.
*
- * Returns: A #GVariant with the value for @property_name or %NULL if
* Since: 2.26
*/
/**
- * GDBusInterfaceIface:
- * @parent_iface: The parent interface.
- * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_get_info().
- * @get_object: Gets the enclosing #GDBusObject. See g_dbus_interface_get_object().
- * @set_object: Sets the enclosing #GDBusObject. See g_dbus_interface_set_object().
- *
- * Base type for D-Bus interfaces.
+ * GDataOutputStream:byte-order:
*
- * Since: 2.30
+ * Determines the byte ordering that is used when writing
+ * multi-byte entities (such as integers) to the stream.
*/
/**
- * GDBusInterfaceInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".
- * @methods: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods.
- * @signals: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals.
- * @properties: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties.
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
- *
- * Information about a D-Bus interface.
+ * GDataStream:byte-order:
*
- * Since: 2.26
+ * The ::byte-order property determines the byte ordering that
+ * is used when reading multi-byte entities (such as integers)
+ * from the stream.
*/
/**
- * GDBusInterfaceMethodCallFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that the method was invoked on.
- * @interface_name: The D-Bus interface name the method was invoked on.
- * @method_name: The name of the method that was invoked.
- * @parameters: A #GVariant tuple with parameters.
- * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
- *
- * The type of the @method_call function in #GDBusInterfaceVTable.
+ * GDataStream:newline-type:
*
- * Since: 2.26
+ * The :newline-type property determines what is considered
+ * as a line ending when reading complete lines from the stream.
*/
/**
- * GDBusInterfaceSetPropertyFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that the method was invoked on.
- * @interface_name: The D-Bus interface name for the property.
- * @property_name: The name of the property to get the value of.
- * @value: The value to set the property to.
- * @error: Return location for error.
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
- *
- * The type of the @set_property function in #GDBusInterfaceVTable.
+ * GDesktopAppInfo:
*
- * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
- * Since: 2.26
+ * Information about an installed application from a desktop file.
*/
/**
- * GDBusInterfaceSkeleton:
- *
- * The #GDBusInterfaceSkeleton structure contains private data and should
- * only be accessed using the provided API.
+ * GDesktopAppInfo:filename:
*
- * Since: 2.30
+ * The origin filename of this #GDesktopAppInfo
*/
/**
- * GDBusInterfaceSkeleton::g-authorize-method:
- * @interface: The #GDBusInterfaceSkeleton emitting the signal.
- * @invocation: A #GDBusMethodInvocation.
- *
- * Emitted when a method is invoked by a remote caller and used to
- * determine if the method call is authorized.
- *
- * 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.
- *
- * If %FALSE is returned then no further handlers are run and the
- * signal handler must take a reference to @invocation and finish
- * handling the call (e.g. return an error via
- * g_dbus_method_invocation_return_error()).
- *
- * Otherwise, if %TRUE is returned, signal emission continues. If no
- * handlers return %FALSE, then the method is dispatched. If
- * @interface has an enclosing #GDBusObjectSkeleton, then the
- * #GDBusObjectSkeleton::authorize-method signal handlers run before
- * the handlers for this signal.
- *
- * The default class handler just returns %TRUE.
+ * GDesktopAppInfoLookup:
*
- * Please note that the common case is optimized: if no signals
- * handlers are connected and the default class handler isn't
- * overridden (for both @interface and the enclosing
- * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
- * not have the
- * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
- * flags set, no dedicated thread is ever used and the call will be
- * handled in the same thread as the object that @interface belongs
- * to was exported in.
+ * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GDrive::changed:
+ * @drive: a #GDrive.
*
- * Returns: %TRUE if the call is authorized, %FALSE otherwise.
- * Since: 2.30
+ * Emitted when the drive's state has changed.
*/
/**
- * GDBusInterfaceSkeleton:g-flags:
+ * GDrive::disconnected:
+ * @drive: a #GDrive.
*
- * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
+ * This signal is emitted when the #GDrive have been
+ * disconnected. If the recipient is holding references to the
+ * object they should release them so the object can be
+ * finalized.
+ */
+
+
+/**
+ * GDrive::eject-button:
+ * @drive: a #GDrive.
*
- * Since: 2.30
+ * Emitted when the physical eject button (if any) of a drive has
+ * been pressed.
*/
/**
- * GDBusInterfaceSkeletonClass:
- * @parent_class: The parent class.
- * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_skeleton_get_info() for details.
- * @get_vtable: Returns a #GDBusInterfaceVTable. See g_dbus_interface_skeleton_get_vtable() for details.
- * @get_properties: Returns a #GVariant with all properties. See g_dbus_interface_skeleton_get_properties().
- * @flush: Emits outstanding changes, if any. See g_dbus_interface_skeleton_flush().
- * @g_authorize_method: Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal.
+ * GDrive::stop-button:
+ * @drive: a #GDrive.
*
- * Class structure for #GDBusInterfaceSkeleton.
+ * Emitted when the physical stop button (if any) of a drive has
+ * been pressed.
*
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusInterfaceSkeletonFlags:
- * @G_DBUS_INTERFACE_SKELETON_FLAGS_NONE: No flags set.
- * @G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD: Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must use locking to access data structures used by other threads.
- *
- * Flags describing the behavior of a #GDBusInterfaceSkeleton instance.
+ * GFileIcon:file:
*
- * Since: 2.30
+ * The file containing the icon.
*/
/**
- * GDBusInterfaceVTable:
- * @method_call: Function for handling incoming method calls.
- * @get_property: Function for getting a property.
- * @set_property: Function for setting a property.
+ * GFileMonitor::changed:
+ * @monitor: a #GFileMonitor.
+ * @file: a #GFile.
+ * @other_file: (allow-none): a #GFile or #NULL.
+ * @event_type: a #GFileMonitorEvent.
*
- * Virtual table for handling properties and method calls for a D-Bus
- * interface.
+ * Emitted when @file has been changed.
*
- * If you want to handle getting/setting D-Bus properties asynchronously, simply
- * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
- * D-Bus interface using g_dbus_connection_register_object().
+ * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
+ * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the
+ * old path, and @other_file will be set to a #GFile containing the new path.
*
- * Since: 2.26
+ * In all the other cases, @other_file will be set to #NULL.
*/
/**
- * GDBusMessage:
- *
- * The #GDBusMessage structure contains only private data and should
- * only be accessed using the provided API.
+ * GFilenameCompleter::got-completion-data:
*
- * Since: 2.26
+ * Emitted when the file name completion information comes available.
*/
/**
- * GDBusMessageByteOrder:
- * @G_DBUS_MESSAGE_BYTE_ORDER_BIG_ENDIAN: The byte order is big endian.
- * @G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN: The byte order is little endian.
+ * GIOExtension:
*
- * Enumeration used to describe the byte order of a D-Bus message.
- *
- * Since: 2.26
+ * #GIOExtension is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDBusMessageClass:
- *
- * Class structure for #GDBusMessage.
+ * GIOExtensionPoint:
*
- * Since: 2.26
+ * #GIOExtensionPoint is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDBusMessageFilterFunction:
- * @connection: (transfer none): A #GDBusConnection.
- * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
- * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is a message to be sent to the other peer.
- * @user_data: User data passed when adding the filter.
+ * GIOModuleScope:
*
- * Signature for function used in g_dbus_connection_add_filter().
+ * Represents a scope for loading IO modules. A scope can be used for blocking
+ * duplicate modules, or blocking a module you don't want to load.
*
- * A filter function is passed a #GDBusMessage and expected to return
- * a #GDBusMessage too. Passive filter functions that don't modify the
- * message can simply return the @message object:
- * |[
- * static GDBusMessage *
- * passive_filter (GDBusConnection *connection
- * GDBusMessage *message,
- * gboolean incoming,
- * gpointer user_data)
- * {
- * /<!-- -->* inspect @message *<!-- -->/
- * return message;
- * }
- * ]|
- * Filter functions that wants to drop a message can simply return %NULL:
- * |[
- * static GDBusMessage *
- * drop_filter (GDBusConnection *connection
- * GDBusMessage *message,
- * gboolean incoming,
- * gpointer user_data)
- * {
- * if (should_drop_message)
- * {
- * g_object_unref (message);
- * message = NULL;
- * }
- * return message;
- * }
- * ]|
- * Finally, a filter function may modify a message by copying it:
- * |[
- * static GDBusMessage *
- * modifying_filter (GDBusConnection *connection
- * GDBusMessage *message,
- * gboolean incoming,
- * gpointer user_data)
- * {
- * GDBusMessage *copy;
- * GError *error;
- *
- * error = NULL;
- * copy = g_dbus_message_copy (message, &error);
- * /<!-- -->* handle @error being is set *<!-- -->/
- * g_object_unref (message);
- *
- * /<!-- -->* modify @copy *<!-- -->/
- *
- * return copy;
- * }
- * ]|
- * If the returned #GDBusMessage is different from @message and cannot
- * be sent on @connection (it could use features, such as file
- * descriptors, not compatible with @connection), then a warning is
- * logged to <emphasis>standard error</emphasis>. Applications can
- * check this ahead of time using g_dbus_message_to_blob() passing a
- * #GDBusCapabilityFlags value obtained from @connection.
- *
- * g_object_unref() or %NULL to drop the message. Passive filter
- * functions can simply return the passed @message object.
+ * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
+ * or g_io_modules_scan_all_in_directory_with_scope().
*
- * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusMessageFlags:
- * @G_DBUS_MESSAGE_FLAGS_NONE: No flags set.
- * @G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED: A reply is not expected.
- * @G_DBUS_MESSAGE_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this message.
- *
- * Message flags used in #GDBusMessage.
+ * GInetAddress:
*
- * Since: 2.26
+ * An IPv4 or IPv6 internet address.
*/
/**
- * GDBusMessageHeaderField:
- * @G_DBUS_MESSAGE_HEADER_FIELD_INVALID: Not a valid header field.
- * @G_DBUS_MESSAGE_HEADER_FIELD_PATH: The object path.
- * @G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE: The interface name.
- * @G_DBUS_MESSAGE_HEADER_FIELD_MEMBER: The method or signal name.
- * @G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME: The name of the error that occurred.
- * @G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL: The serial number the message is a reply to.
- * @G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION: The name the message is intended for.
- * @G_DBUS_MESSAGE_HEADER_FIELD_SENDER: Unique name of the sender of the message (filled in by the bus).
- * @G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE: The signature of the message body.
- * @G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS: The number of UNIX file descriptors that accompany the message.
+ * GInetAddress:is-any:
*
- * Header fields used in #GDBusMessage.
+ * Whether this is the "any" address for its family.
+ * See g_inet_address_get_is_any().
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * GDBusMessageType:
- * @G_DBUS_MESSAGE_TYPE_INVALID: Message is of invalid type.
- * @G_DBUS_MESSAGE_TYPE_METHOD_CALL: Method call.
- * @G_DBUS_MESSAGE_TYPE_METHOD_RETURN: Method reply.
- * @G_DBUS_MESSAGE_TYPE_ERROR: Error reply.
- * @G_DBUS_MESSAGE_TYPE_SIGNAL: Signal emission.
+ * GInetAddress:is-link-local:
*
- * Message types used in #GDBusMessage.
+ * Whether this is a link-local address.
+ * See g_inet_address_get_is_link_local().
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * GDBusMethodInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: The name of the D-Bus method, e.g. @RequestName.
- * @in_args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments.
- * @out_args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments.
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GInetAddress:is-loopback:
*
- * Information about a method on an D-Bus interface.
+ * Whether this is the loopback address for its family.
+ * See g_inet_address_get_is_loopback().
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * GDBusMethodInvocation:
+ * GInetAddress:is-mc-global:
*
- * The #GDBusMethodInvocation structure contains only private data and
- * should only be accessed using the provided API.
+ * Whether this is a global multicast address.
+ * See g_inet_address_get_is_mc_global().
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * GDBusMethodInvocationClass:
+ * GInetAddress:is-mc-link-local:
*
- * Class structure for #GDBusMethodInvocation.
+ * Whether this is a link-local multicast address.
+ * See g_inet_address_get_is_mc_link_local().
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * GDBusNodeInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @path: The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details.
- * @interfaces: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
- * @nodes: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GInetAddress:is-mc-node-local:
*
- * Information about nodes in a remote object hierarchy.
+ * Whether this is a node-local multicast address.
+ * See g_inet_address_get_is_mc_node_local().
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * GDBusObject::interface-added:
- * @object: The #GDBusObject emitting the signal.
- * @interface: The #GDBusInterface that was added.
+ * GInetAddress:is-mc-org-local:
*
- * Emitted when @interface is added to @object.
+ * Whether this is an organization-local multicast address.
+ * See g_inet_address_get_is_mc_org_local().
*
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusObject::interface-removed:
- * @object: The #GDBusObject emitting the signal.
- * @interface: The #GDBusInterface that was removed.
+ * GInetAddress:is-mc-site-local:
*
- * Emitted when @interface is removed from @object.
+ * Whether this is a site-local multicast address.
+ * See g_inet_address_get_is_mc_site_local().
*
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusObjectIface:
- * @parent_iface: The parent interface.
- * @get_object_path: Returns the object path. See g_dbus_object_get_object_path().
- * @get_interfaces: Returns all interfaces. See g_dbus_object_get_interfaces().
- * @get_interface: Returns an interface by name. See g_dbus_object_get_interface().
- * @interface_added: Signal handler for the #GDBusObject::interface-added signal.
- * @interface_removed: Signal handler for the #GDBusObject::interface-removed signal.
+ * GInetAddress:is-multicast:
*
- * Base object type for D-Bus objects.
+ * Whether this is a multicast address.
+ * See g_inet_address_get_is_multicast().
*
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusObjectManager::interface-added:
- * @manager: The #GDBusObjectManager emitting the signal.
- * @object: The #GDBusObject on which an interface was added.
- * @interface: The #GDBusInterface that was added.
- *
- * Emitted when @interface is added to @object.
+ * GInetAddress:is-site-local:
*
- * This signal exists purely as a convenience to avoid having to
- * connect signals to all objects managed by @manager.
+ * Whether this is a site-local address.
+ * See g_inet_address_get_is_loopback().
*
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusObjectManager::interface-removed:
- * @manager: The #GDBusObjectManager emitting the signal.
- * @object: The #GDBusObject on which an interface was removed.
- * @interface: The #GDBusInterface that was removed.
- *
- * Emitted when @interface has been removed from @object.
+ * GInetAddressMask:
*
- * This signal exists purely as a convenience to avoid having to
- * connect signals to all objects managed by @manager.
+ * A combination of an IPv4 or IPv6 base address and a length,
+ * representing a range of IP addresses.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManager::object-added:
- * @manager: The #GDBusObjectManager emitting the signal.
- * @object: The #GDBusObject that was added.
- *
- * Emitted when @object is added to @manager.
+ * GInetSocketAddress:
*
- * Since: 2.30
+ * An IPv4 or IPv6 socket address, corresponding to a struct
+ * sockaddr_in or struct sockaddr_in6.
*/
/**
- * GDBusObjectManager::object-removed:
- * @manager: The #GDBusObjectManager emitting the signal.
- * @object: The #GDBusObject that was removed.
+ * GInetSocketAddress:flowinfo:
*
- * Emitted when @object is removed from @manager.
+ * The `sin6_flowinfo` field, for IPv6 addresses.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerClient:
+ * GInetSocketAddress:scope_id:
*
- * The #GDBusObjectManagerClient structure contains private data and should
- * only be accessed using the provided API.
+ * The `sin6_scope_id` field, for IPv6 addresses.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerClient::interface-proxy-properties-changed:
- * @manager: The #GDBusObjectManagerClient emitting the signal.
- * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
- * @interface_proxy: The #GDBusProxy that has properties that are changing.
- * @changed_properties: A #GVariant containing the properties that changed.
- * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
- *
- * Emitted when one or more D-Bus properties on proxy changes. The
- * local cache has already been updated when this signal fires. Note
- * that both @changed_properties and @invalidated_properties are
- * guaranteed to never be %NULL (either may be empty though).
- *
- * This signal exists purely as a convenience to avoid having to
- * 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>
- * that @manager was constructed in.
+ * GListModel:
*
- * Since: 2.30
+ * #GListModel is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDBusObjectManagerClient::interface-proxy-signal:
- * @manager: The #GDBusObjectManagerClient emitting the signal.
- * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
- * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
- * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
- * @signal_name: The signal name.
- * @parameters: A #GVariant tuple with parameters for the signal.
- *
- * Emitted when a D-Bus signal is received on @interface_proxy.
- *
- * This signal exists purely as a convenience to avoid having to
- * connect signals to all interface proxies managed by @manager.
+ * 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 in the
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
- * that @manager was constructed in.
+ * 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.30
+ * Since: 2.44
*/
/**
- * GDBusObjectManagerClient:bus-type:
+ * 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()
*
- * If this property is not %G_BUS_TYPE_NONE, then
- * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
- * #GDBusConnection obtained by calling g_bus_get() with the value
- * of this property.
+ * The virtual function table for #GListModel.
*
- * Since: 2.30
+ * Since: 2.44
*/
/**
- * GDBusObjectManagerClient:connection:
- *
- * The #GDBusConnection to use.
+ * GListStore:
*
- * Since: 2.30
+ * #GListStore is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDBusObjectManagerClient:flags:
+ * GListStore:item-type:
*
- * Flags from the #GDBusObjectManagerClientFlags enumeration.
+ * The type of items contained in this list store. Items must be
+ * subclasses of #GObject.
*
- * Since: 2.30
+ * Since: 2.44
*/
/**
- * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
+ * GMemoryOutputStream:data:
*
- * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
+ * Pointer to buffer where data will be written.
*
- * Since: 2.30
+ * Since: 2.24
*/
/**
- * GDBusObjectManagerClient:get-proxy-type-func:
+ * GMemoryOutputStream:data-size:
*
- * The #GDBusProxyTypeFunc to use when determining what #GType to
- * use for interface proxies or %NULL.
+ * Size of data written to the buffer.
*
- * Since: 2.30
+ * Since: 2.24
*/
/**
- * GDBusObjectManagerClient:get-proxy-type-user-data:
+ * GMemoryOutputStream:destroy-function: (skip)
*
- * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
+ * Function called with the buffer as argument when the stream is destroyed.
*
- * Since: 2.30
+ * Since: 2.24
*/
/**
- * GDBusObjectManagerClient:name:
+ * GMemoryOutputStream:realloc-function: (skip)
*
- * The well-known name or unique name that the manager is for.
+ * Function with realloc semantics called to enlarge the buffer.
*
- * Since: 2.30
+ * Since: 2.24
*/
/**
- * GDBusObjectManagerClient:name-owner:
+ * GMemoryOutputStream:size:
*
- * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
- * no-one is currently owning the name. Connect to the
- * #GObject::notify signal to track changes to this property.
+ * Current size of the data buffer.
*
- * Since: 2.30
+ * Since: 2.24
*/
/**
- * GDBusObjectManagerClient:object-path:
+ * GMenu:
*
- * The object path the manager is for.
+ * #GMenu is an opaque structure type. You must access it using the
+ * functions below.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerClientClass:
- * @parent_class: The parent class.
- * @interface_proxy_signal: Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal.
- * @interface_proxy_properties_changed: Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal.
+ * GMenuAttributeIter:
*
- * Class structure for #GDBusObjectManagerClient.
+ * #GMenuAttributeIter is an opaque structure type. You must access it
+ * using the functions below.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerClientFlags:
- * @G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE: No flags set.
- * @G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START: If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in managers for well-known names.
+ * GMenuItem:
*
- * Flags used when constructing a #GDBusObjectManagerClient.
+ * #GMenuItem is an opaque structure type. You must access it using the
+ * functions below.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerIface:
- * @parent_iface: The parent interface.
- * @get_object_path: Virtual function for g_dbus_object_manager_get_object_path().
- * @get_objects: Virtual function for g_dbus_object_manager_get_objects().
- * @get_object: Virtual function for g_dbus_object_manager_get_object().
- * @get_interface: Virtual function for g_dbus_object_manager_get_interface().
- * @object_added: Signal handler for the #GDBusObjectManager::object-added signal.
- * @object_removed: Signal handler for the #GDBusObjectManager::object-removed signal.
- * @interface_added: Signal handler for the #GDBusObjectManager::interface-added signal.
- * @interface_removed: Signal handler for the #GDBusObjectManager::interface-removed signal.
+ * GMenuLinkIter:
*
- * Base type for D-Bus object managers.
+ * #GMenuLinkIter is an opaque structure type. You must access it using
+ * the functions below.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerServer:
+ * GMenuModel:
*
- * The #GDBusObjectManagerServer structure contains private data and should
- * only be accessed using the provided API.
+ * #GMenuModel is an opaque structure type. You must access it using the
+ * functions below.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * GDBusObjectManagerServer:connection:
+ * GMenuModel::items-changed:
+ * @model: the #GMenuModel that is changing
+ * @position: the position of the change
+ * @removed: the number of items removed
+ * @added: the number of items added
*
- * The #GDBusConnection to export objects on.
+ * Emitted when a change has occured to the menu.
*
- * Since: 2.30
- */
-
-
-/**
- * GDBusObjectManagerServer:object-path:
+ * The only changes that can occur to a menu is that items are removed
+ * or added. Items may not change (except by being removed and added
+ * back in the same location). This signal is capable of describing
+ * both of those changes (at the same time).
*
- * The object path to register the manager object at.
+ * The signal means that starting at the index @position, @removed
+ * items were removed and @added items were added in their place. If
+ * @removed is zero then only items were added. If @added is zero
+ * then only items were removed.
*
- * Since: 2.30
+ * As an example, if the menu contains items a, b, c, d (in that
+ * order) and the signal (2, 1, 3) occurs then the new composition of
+ * the menu will be a, b, _, _, _, d (with each _ representing some
+ * new item).
+ *
+ * Signal handlers may query the model (particularly the added items)
+ * and expect to see the results of the modification that is being
+ * reported. The signal is emitted after the modification.
*/
/**
- * GDBusObjectManagerServerClass:
- * @parent_class: The parent class.
- *
- * Class structure for #GDBusObjectManagerServer.
+ * GMount::changed:
+ * @mount: the object on which the signal is emitted
*
- * Since: 2.30
+ * Emitted when the mount has been changed.
*/
/**
- * GDBusObjectProxy:
+ * GMount::pre-unmount:
+ * @mount: the object on which the signal is emitted
*
- * The #GDBusObjectProxy structure contains private data and should
- * only be accessed using the provided API.
+ * This signal is emitted when the #GMount is about to be
+ * unmounted.
*
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusObjectProxy:g-connection:
- *
- * The connection of the proxy.
+ * GMount::unmounted:
+ * @mount: the object on which the signal is emitted
*
- * Since: 2.30
+ * This signal is emitted when the #GMount have been
+ * unmounted. If the recipient is holding references to the
+ * object they should release them so the object can be
+ * finalized.
*/
/**
- * GDBusObjectProxy:g-object-path:
+ * GMountOperation::aborted:
*
- * The object path of the proxy.
+ * Emitted by the backend when e.g. a device becomes unavailable
+ * while a mount operation is in progress.
*
- * Since: 2.30
+ * Implementations of GMountOperation should handle this signal
+ * by dismissing open password dialogs.
+ *
+ * Since: 2.20
*/
/**
- * GDBusObjectProxyClass:
- * @parent_class: The parent class.
+ * GMountOperation::ask-password:
+ * @op: a #GMountOperation requesting a password.
+ * @message: string containing a message to display to the user.
+ * @default_user: string containing the default user name.
+ * @default_domain: string containing the default domain.
+ * @flags: a set of #GAskPasswordFlags.
*
- * Class structure for #GDBusObjectProxy.
+ * Emitted when a mount operation asks the user for a password.
*
- * Since: 2.30
+ * 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.
*/
/**
- * GDBusObjectSkeleton:
+ * GMountOperation::ask-question:
+ * @op: a #GMountOperation asking a question.
+ * @message: string containing a message to display to the user.
+ * @choices: an array of strings for each possible choice.
+ *
+ * Emitted when asking the user a question and gives a list of
+ * choices for the user to choose from.
*
- * The #GDBusObjectSkeleton structure contains private data and should only be
- * accessed using the provided API.
+ * 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.
+ */
+
+
+/**
+ * GMountOperation::reply:
+ * @op: a #GMountOperation.
+ * @result: a #GMountOperationResult indicating how the request was handled
*
- * Since: 2.30
+ * Emitted when the user has replied to the mount operation.
*/
/**
- * GDBusObjectSkeleton::authorize-method:
- * @object: The #GDBusObjectSkeleton emitting the signal.
- * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
- * @invocation: A #GDBusMethodInvocation.
+ * 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.
+ * @choices: an array of strings for each possible choice.
*
- * Emitted when a method is invoked by a remote caller and used to
- * determine if the method call is authorized.
+ * Emitted when one or more processes are blocking an operation
+ * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
*
- * This signal is like #GDBusInterfaceSkeleton<!-- -->'s
- * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
- * for the enclosing object.
+ * Note that this signal may be emitted several times to update the
+ * list of blocking processes as processes close files. The
+ * application should only respond with g_mount_operation_reply() to
+ * the latest signal (setting #GMountOperation:choice to the choice
+ * the user made).
*
- * The default class handler just returns %TRUE.
+ * 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.
*
- * Returns: %TRUE if the call is authorized, %FALSE otherwise.
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * GDBusObjectSkeleton:g-object-path:
+ * 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
*
- * The object path where the object is exported.
+ * Emitted when an unmount operation has been busy for more than some time
+ * (typically 1.5 seconds).
*
- * Since: 2.30
+ * 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
*/
/**
- * GDBusObjectSkeletonClass:
- * @parent_class: The parent class.
- * @authorize_method: Signal class handler for the #GDBusObjectSkeleton::authorize-method signal.
- *
- * Class structure for #GDBusObjectSkeleton.
+ * GMountOperation:anonymous:
*
- * Since: 2.30
+ * Whether to use an anonymous user when authenticating.
*/
/**
- * GDBusPropertyInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: The name of the D-Bus property, e.g. "SupportedFilesystems".
- * @signature: The D-Bus signature of the property (a single complete type).
- * @flags: Access control flags for the property.
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
- *
- * Information about a D-Bus property on a D-Bus interface.
+ * GMountOperation:choice:
*
- * Since: 2.26
+ * The index of the user's choice when a question is asked during the
+ * mount operation. See the #GMountOperation::ask-question signal.
*/
/**
- * GDBusPropertyInfoFlags:
- * @G_DBUS_PROPERTY_INFO_FLAGS_NONE: No flags set.
- * @G_DBUS_PROPERTY_INFO_FLAGS_READABLE: Property is readable.
- * @G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE: Property is writable.
- *
- * Flags describing the access control of a D-Bus property.
+ * GMountOperation:domain:
*
- * Since: 2.26
+ * The domain to use for the mount operation.
*/
/**
- * GDBusProxy:
- *
- * The #GDBusProxy structure contains only private data and
- * should only be accessed using the provided API.
+ * GMountOperation:password:
*
- * Since: 2.26
+ * The password that is used for authentication when carrying out
+ * the mount operation.
*/
/**
- * GDBusProxy::g-properties-changed:
- * @proxy: The #GDBusProxy emitting the signal.
- * @changed_properties: A #GVariant containing the properties that changed
- * @invalidated_properties: A %NULL terminated array of properties that was invalidated
- *
- * Emitted when one or more D-Bus properties on @proxy changes. The
- * local cache has already been updated when this signal fires. Note
- * that both @changed_properties and @invalidated_properties are
- * guaranteed to never be %NULL (either may be empty though).
- *
- * This signal corresponds to the
- * <literal>PropertiesChanged</literal> D-Bus signal on the
- * <literal>org.freedesktop.DBus.Properties</literal> interface.
+ * GMountOperation:password-save:
*
- * Since: 2.26
+ * Determines if and how the password information should be saved.
*/
/**
- * GDBusProxy::g-signal:
- * @proxy: The #GDBusProxy emitting the signal.
- * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection.
- * @signal_name: The name of the signal.
- * @parameters: A #GVariant tuple with parameters for the signal.
- *
- * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
+ * GMountOperation:username:
*
- * Since: 2.26
+ * The user name that is used for authentication when carrying out
+ * the mount operation.
*/
/**
- * GDBusProxy:g-bus-type:
- *
- * If this property is not %G_BUS_TYPE_NONE, then
- * #GDBusProxy:g-connection must be %NULL and will be set to the
- * #GDBusConnection obtained by calling g_bus_get() with the value
- * of this property.
+ * GNetworkAddress:
*
- * Since: 2.26
+ * A #GSocketConnectable for resolving a hostname and connecting to
+ * that host.
*/
/**
- * GDBusProxy:g-connection:
+ * GNetworkMonitor:
*
- * The #GDBusConnection the proxy is for.
+ * #GNetworkMonitor monitors the status of network connections and
+ * indicates when a possibly-user-visible change has occurred.
*
- * Since: 2.26
+ * Since: 2.32
*/
/**
- * GDBusProxy:g-default-timeout:
- *
- * The timeout to use if -1 (specifying default timeout) is passed
- * as @timeout_msec in the g_dbus_proxy_call() and
- * g_dbus_proxy_call_sync() functions.
+ * GNetworkMonitor::network-changed:
+ * @monitor: a #GNetworkMonitor
+ * @available: the current value of #GNetworkMonitor:network-available
*
- * This allows applications to set a proxy-wide timeout for all
- * remote method invocations on the proxy. If this property is -1,
- * the default timeout (typically 25 seconds) is used. If set to
- * %G_MAXINT, then no timeout is used.
+ * Emitted when the network configuration changes. If @available is
+ * %TRUE, then some hosts may be reachable that were not reachable
+ * before, while others that were reachable before may no longer be
+ * reachable. If @available is %FALSE, then no remote hosts are
+ * reachable.
*
- * Since: 2.26
+ * Since: 2.32
*/
/**
- * GDBusProxy:g-flags:
+ * GNetworkMonitor:connectivity:
*
- * Flags from the #GDBusProxyFlags enumeration.
+ * More detailed information about the host's network connectivity.
+ * See g_network_monitor_get_connectivity() and
+ * #GNetworkConnectivity for more details.
*
- * Since: 2.26
+ * Since: 2.44
*/
/**
- * GDBusProxy:g-interface-info:
+ * GNetworkMonitor:network-available:
*
- * 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>.
+ * Whether the network is considered available. That is, whether the
+ * system has a default route for at least one of IPv4 or IPv6.
*
- * 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>
- * 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
- * service-side is not considered an ABI break.
+ * Real-world networks are of course much more complicated than
+ * this; the machine may be connected to a wifi hotspot that
+ * requires payment before allowing traffic through, or may be
+ * 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
+ * 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.)
*
- * Since: 2.26
+ * See also #GNetworkMonitor::network-changed.
+ *
+ * Since: 2.32
*/
/**
- * GDBusProxy:g-interface-name:
+ * 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 D-Bus interface name the proxy is for.
+ * The virtual function table for #GNetworkMonitor.
*
- * Since: 2.26
+ * Since: 2.32
*/
/**
- * GDBusProxy:g-name:
- *
- * The well-known or unique name that the proxy is for.
+ * GNetworkService:
*
- * Since: 2.26
+ * A #GSocketConnectable for resolving a SRV record and connecting to
+ * that service.
*/
/**
- * GDBusProxy:g-name-owner:
+ * GNotification:
*
- * The unique name that owns #GDBusProxy:name or %NULL if no-one
- * currently owns that name. You may connect to #GObject::notify signal to
- * track changes to this property.
+ * This structure type is private and should only be accessed using the
+ * public APIs.
*
- * Since: 2.26
+ * Since: 2.40
*/
/**
- * GDBusProxy:g-object-path:
- *
- * The object path the proxy is for.
+ * GPermission:
*
- * Since: 2.26
+ * #GPermission is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDBusProxyClass:
- * @g_properties_changed: Signal class handler for the #GDBusProxy::g-properties-changed signal.
- * @g_signal: Signal class handler for the #GDBusProxy::g-signal signal.
- *
- * Class structure for #GDBusProxy.
+ * GPermission:allowed:
*
- * Since: 2.26
+ * %TRUE if the caller currently has permission to perform the action that
+ * @permission represents the permission to perform.
*/
/**
- * GDBusProxyFlags:
- * @G_DBUS_PROXY_FLAGS_NONE: No flags set.
- * @G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES: Don't load properties.
- * @G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS: Don't connect to signals on the remote object.
- * @G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START: If not set and the proxy if for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in proxies for well-known names.
- *
- * Flags used when constructing an instance of a #GDBusProxy derived class.
+ * GPermission:can-acquire:
*
- * Since: 2.26
+ * %TRUE if it is generally possible to acquire the permission by calling
+ * g_permission_acquire().
*/
/**
- * GDBusProxyTypeFunc:
- * @manager: A #GDBusObjectManagerClient.
- * @object_path: The object path of the remote object.
- * @interface_name: (allow-none): The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested.
- * @user_data: User data.
- *
- * Function signature for a function used to determine the #GType to
- * use for an interface proxy (if @interface_name is not %NULL) or
- * object proxy (if @interface_name is %NULL).
- *
- * This function is called in the
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
- * that @manager was constructed in.
+ * GPermission:can-release:
*
- * must be a #GDBusProxy<!-- -->- or #GDBusObjectProxy<!-- -->-derived
- * type.
- *
- * Returns: A #GType to use for the remote object. The returned type
- * Since: 2.30
- */
-
-
-/**
- * GDBusSendMessageFlags:
- * @G_DBUS_SEND_MESSAGE_FLAGS_NONE: No flags set.
- * @G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL: Do not automatically assign a serial number from the #GDBusConnection object when sending a message.
- *
- * Flags used when sending #GDBusMessage<!-- -->s on a #GDBusConnection.
- *
- * Since: 2.26
+ * %TRUE if it is generally possible to release the permission by calling
+ * g_permission_release().
*/
/**
- * GDBusServer:
+ * GPropertyAction:
*
- * The #GDBusServer structure contains only private data and
- * should only be accessed using the provided API.
+ * This type is opaque.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusServer::new-connection:
- * @server: The #GDBusServer emitting the signal.
- * @connection: A #GDBusConnection for the new connection.
- *
- * Emitted when a new authenticated connection has been made. Use
- * g_dbus_connection_get_peer_credentials() to figure out what
- * identity (if any), was authenticated.
- *
- * If you want to accept the connection, take a reference to the
- * @connection object and return %TRUE. When you are done with the
- * connection call g_dbus_connection_close() and give up your
- * reference. Note that the other peer may disconnect at any time -
- * a typical thing to do when accepting a connection is to listen to
- * the #GDBusConnection::closed signal.
- *
- * 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.
+ * GPropertyAction:enabled:
*
- * 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.
+ * If @action is currently enabled.
*
- * run.
+ * If the action is disabled then calls to g_action_activate() and
+ * g_action_change_state() have no effect.
*
- * Returns: %TRUE to claim @connection, %FALSE to let other handlers
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusServer:active:
+ * GPropertyAction:name:
*
- * Whether the server is currently active.
+ * The name of the action. This is mostly meaningful for identifying
+ * the action once it has been added to a #GActionMap.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusServer:address:
+ * GPropertyAction:object:
*
- * The D-Bus address to listen on.
+ * The object to wrap a property on.
*
- * Since: 2.26
+ * The object must be a non-%NULL #GObject with properties.
+ *
+ * Since: 2.38
*/
/**
- * GDBusServer:authentication-observer:
+ * GPropertyAction:parameter-type:
*
- * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
+ * The type of the parameter that must be given when activating the
+ * action.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusServer:client-address:
+ * GPropertyAction:property-name:
*
- * The D-Bus address that clients can use.
+ * The name of the property to wrap on the object.
*
- * Since: 2.26
+ * The property must exist on the passed-in object and it must be
+ * readable and writable (and not construct-only).
+ *
+ * Since: 2.38
*/
/**
- * GDBusServer:flags:
+ * GPropertyAction:state:
*
- * Flags from the #GDBusServerFlags enumeration.
+ * The state of the action, or %NULL if the action is stateless.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusServer:guid:
+ * GPropertyAction:state-type:
*
- * The guid of the server.
+ * The #GVariantType of the state that the action has, or %NULL if the
+ * action is stateless.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusServerClass:
- * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
+ * GProxyAddress:
*
- * Class structure for #GDBusServer.
+ * A #GInetSocketAddress representing a connection via a proxy server
*
* Since: 2.26
*/
/**
- * GDBusServerFlags:
- * @G_DBUS_SERVER_FLAGS_NONE: No flags set.
- * @G_DBUS_SERVER_FLAGS_RUN_IN_THREAD: All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details).
- * @G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: Allow the anonymous authentication method.
+ * GProxyAddress:destination-protocol:
*
- * Flags used when creating a #GDBusServer.
+ * The protocol being spoke to the destination host, or %NULL if
+ * the #GProxyAddress doesn't know.
*
- * Since: 2.26
+ * Since: 2.34
*/
/**
- * GDBusSignalCallback:
- * @connection: A #GDBusConnection.
- * @sender_name: The unique bus name of the sender of the signal.
- * @object_path: The object path that the signal was emitted on.
- * @interface_name: The name of the interface.
- * @signal_name: The name of the signal.
- * @parameters: A #GVariant tuple with parameters for the signal.
- * @user_data: User data passed when subscribing to the signal.
+ * GProxyAddress:uri:
*
- * Signature for callback function used in g_dbus_connection_signal_subscribe().
+ * The URI string that the proxy was constructed from (or %NULL
+ * if the creator didn't specify this).
*
- * Since: 2.26
+ * Since: 2.34
*/
/**
- * GDBusSignalFlags:
- * @G_DBUS_SIGNAL_FLAGS_NONE: No flags set.
- * @G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE: Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually).
+ * GProxyAddressClass:
*
- * Flags used when subscribing to signals via g_dbus_connection_signal_subscribe().
+ * Class structure for #GProxyAddress.
*
* Since: 2.26
*/
/**
- * GDBusSignalInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: The name of the D-Bus signal, e.g. "NameOwnerChanged".
- * @args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments.
- * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GProxyAddressEnumerator:default-port:
*
- * Information about a signal on a D-Bus interface.
+ * The default port to use if #GProxyAddressEnumerator:uri does not
+ * specify one.
*
- * Since: 2.26
+ * Since: 2.38
*/
/**
- * GDBusSubtreeDispatchFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
- * @interface_name: The D-Bus interface name that the method call or property access is for.
- * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
- * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
- *
- * The type of the @dispatch function in #GDBusSubtreeVTable.
+ * GProxyAddressEnumerator:proxy-resolver:
*
- * Subtrees are flat. @node, if non-%NULL, is always exactly one
- * segment of the object path (ie: it never contains a slash).
+ * The proxy resolver to use.
*
- * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
- * Since: 2.26
+ * Since: 2.36
*/
/**
- * GDBusSubtreeEnumerateFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
- *
- * The type of the @enumerate function in #GDBusSubtreeVTable.
- *
- * This function is called when generating introspection data and also
- * when preparing to dispatch incoming messages in the event that the
- * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
- * specified (ie: to verify that the object path is valid).
- *
- * Hierarchies are not supported; the items that you return should not
- * contain the '/' character.
- *
- * The return value will be freed with g_strfreev().
+ * 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()
*
- * Returns: A newly allocated array of strings for node names that are children of @object_path.
- * Since: 2.26
+ * The virtual function table for #GProxyResolver.
*/
/**
- * GDBusSubtreeFlags:
- * @G_DBUS_SUBTREE_FLAGS_NONE: No flags set.
- * @G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES: Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree.
+ * GRemoteActionGroup:
*
- * Flags passed to g_dbus_connection_register_subtree().
- *
- * Since: 2.26
+ * #GRemoteActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDBusSubtreeIntrospectFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
- * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
- *
- * The type of the @introspect function in #GDBusSubtreeVTable.
- *
- * Subtrees are flat. @node, if non-%NULL, is always exactly one
- * segment of the object path (ie: it never contains a slash).
- *
- * This function should return %NULL to indicate that there is no object
- * at this node.
- *
- * If this function returns non-%NULL, the return value is expected to
- * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
- * structures describing the interfaces implemented by @node. This
- * array will have g_dbus_interface_info_unref() called on each item
- * before being freed with g_free().
+ * 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 difference between returning %NULL and an array containing zero
- * items is that the standard DBus interfaces will returned to the
- * remote introspector in the empty array case, but not in the %NULL
- * case.
+ * The virtual function table for #GRemoteActionGroup.
*
- * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
- * Since: 2.26
+ * Since: 2.32
*/
/**
- * GDBusSubtreeVTable:
- * @enumerate: Function for enumerating child nodes.
- * @introspect: Function for introspecting a child node.
- * @dispatch: Function for dispatching a remote call on a child node.
- *
- * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
+ * GResolver:
*
- * Since: 2.26
+ * The object that handles DNS resolution. Use g_resolver_get_default()
+ * to get the default resolver.
*/
/**
- * GDataInputStream:
+ * GResolver::reload:
+ * @resolver: a #GResolver
*
- * An implementation of #GBufferedInputStream that allows for high-level
- * data manipulation of arbitrary data (including binary operations).
+ * Emitted when the resolver notices that the system resolver
+ * configuration has changed.
*/
/**
- * GDataOutputStream:
+ * GSettings:
*
- * An implementation of #GBufferedOutputStream that allows for high-level
- * data manipulation of arbitrary data (including binary operations).
+ * #GSettings is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDataOutputStream:byte-order:
+ * 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
*
- * Determines the byte ordering that is used when writing
- * multi-byte entities (such as integers) to the stream.
+ * 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.
*/
/**
- * GDataStream:byte-order:
+ * GSettings::changed:
+ * @settings: the object on which the signal was emitted
+ * @key: the name of the key that changed
*
- * The ::byte-order property determines the byte ordering that
- * is used when reading multi-byte entities (such as integers)
- * from the stream.
+ * 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
+ * value.
+ *
+ * This signal supports detailed connections. You can connect to the
+ * detailed signal "changed::x" in order to only receive callbacks
+ * when key "x" changes.
*/
/**
- * GDataStream:newline-type:
+ * GSettings::writable-change-event:
+ * @settings: the object on which the signal was emitted
+ * @key: the quark of the key, or 0
*
- * The :newline-type property determines what is considered
- * as a line ending when reading complete lines from the stream.
+ * The "writable-change-event" signal is emitted once per writability
+ * change event that affects this settings object. You should connect
+ * to this signal if you are interested in viewing groups of changes
+ * before they are split out into multiple emissions of the
+ * "writable-changed" signal. For most use cases it is more
+ * appropriate to use the "writable-changed" signal.
+ *
+ * In the event that the writability change applies only to a single
+ * key, @key will be set to the #GQuark for that key. In the event
+ * that the writability change affects the entire settings object,
+ * @key will be 0.
+ *
+ * The default handler for this signal invokes the "writable-changed"
+ * and "changed" signals for each affected key. This is done because
+ * changes in writability might also imply changes in value (if for
+ * example, a new mandatory setting is introduced). 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.
*/
/**
- * GDataStreamByteOrder:
- * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order.
- * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order.
- * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture.
+ * GSettings::writable-changed:
+ * @settings: the object on which the signal was emitted
+ * @key: the key
+ *
+ * The "writable-changed" signal is emitted when the writability of a
+ * key has potentially changed. You should call
+ * g_settings_is_writable() in order to determine the new status.
*
- * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources
- * across various machine architectures.
+ * This signal supports detailed connections. You can connect to the
+ * detailed signal "writable-changed::x" in order to only receive
+ * callbacks when the writability of "x" changes.
*/
/**
- * GDataStreamNewlineType:
- * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms.
- * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings.
- * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows.
- * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type.
+ * GSettings:context:
*
- * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
+ * The name of the context that the settings are stored in.
*/
/**
- * GDateTime:
+ * GSettings:delay-apply:
*
- * <structname>GDateTime</structname> is an opaque structure whose members
- * cannot be accessed directly.
+ * Whether the #GSettings object is in 'delay-apply' mode. See
+ * g_settings_delay() for details.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * GDebugKey:
- * @key: the string
- * @value: the flag
+ * GSettings:has-unapplied:
*
- * Associates a string with a bit flag.
- * Used in g_parse_debug_string().
+ * If this property is %TRUE, the #GSettings object has outstanding
+ * changes that will be applied when g_settings_apply() is called.
*/
/**
- * GDesktopAppInfo:
+ * GSettings:path:
*
- * Information about an installed application from a desktop file.
+ * The path within the backend where the settings are stored.
*/
/**
- * GDesktopAppInfo:filename:
+ * GSettings:schema:
*
- * The origin filename of this #GDesktopAppInfo
+ * The name of the schema that describes the types of keys
+ * for this #GSettings object.
+ *
+ * The type of this property is *not* #GSettingsSchema.
+ * #GSettingsSchema has only existed since version 2.32 and
+ * unfortunately this name was used in previous versions to refer to
+ * the schema ID rather than the schema itself. Take care to use the
+ * '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.
*/
/**
- * GDesktopAppInfoLookup:
+ * GSettings:schema-id:
*
- * Interface that is used by backends to associate default
- * handlers with URI schemes.
+ * The name of the schema that describes the types of keys
+ * for this #GSettings object.
*/
/**
- * GDesktopAppLaunchCallback:
- * @appinfo: a #GDesktopAppInfo
- * @pid: Process identifier
- * @user_data: User data
+ * GSettings:settings-schema:
+ *
+ * The #GSettingsSchema describing the types of keys for this
+ * #GSettings object.
*
- * During invocation, g_desktop_app_info_launch_uris_as_manager() may
- * create one or more child processes. This callback is invoked once
- * for each, providing the process ID.
+ * Ideally, this property would be called 'schema'. #GSettingsSchema
+ * has only existed since version 2.32, however, and before then the
+ * 'schema' property was used to refer to the ID of the schema rather
+ * than the schema itself. Take care.
*/
/**
- * GDrive:
+ * GSettingsSchema:
+ *
+ * This is an opaque structure type. You may not access it directly.
*
- * Opaque drive object.
+ * Since: 2.32
*/
/**
- * GDrive::changed:
- * @drive: a #GDrive.
+ * GSettingsSchemaKey:
*
- * Emitted when the drive's state has changed.
+ * #GSettingsSchemaKey is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDrive::disconnected:
- * @drive: a #GDrive.
+ * GSettingsSchemaSource:
*
- * This signal is emitted when the #GDrive have been
- * disconnected. If the recipient is holding references to the
- * object they should release them so the object can be
- * finalized.
+ * This is an opaque structure type. You may not access it directly.
+ *
+ * Since: 2.32
*/
/**
- * GDrive::eject-button:
- * @drive: a #GDrive.
+ * GSimpleAction:
*
- * Emitted when the physical eject button (if any) of a drive has
- * been pressed.
+ * #GSimpleAction is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GDrive::stop-button:
- * @drive: a #GDrive.
- *
- * Emitted when the physical stop button (if any) of a drive has
- * been pressed.
+ * GSimpleAction::activate:
+ * @simple: the #GSimpleAction
+ * @parameter: (allow-none): the parameter to the activation
*
- * Since: 2.22
+ * Indicates that the action was just activated.
+ *
+ * @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
*/
/**
- * GDriveIface:
- * @g_iface: The parent interface.
- * @changed: Signal emitted when the drive is changed.
- * @disconnected: The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.
- * @eject_button: Signal emitted when the physical eject button (if any) of a drive have been pressed.
- * @get_name: Returns the name for the given #GDrive.
- * @get_icon: Returns a #GIcon for the given #GDrive.
- * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes.
- * @get_volumes: Returns a list #GList of #GVolume for the #GDrive.
- * @is_media_removable: Returns %TRUE if the #GDrive supports removal and insertion of media.
- * @has_media: Returns %TRUE if the #GDrive has media inserted.
- * @is_media_check_automatic: Returns %TRUE if the #GDrive is capabable of automatically detecting media changes.
- * @can_poll_for_media: Returns %TRUE if the #GDrive is capable of manually polling for media change.
- * @can_eject: Returns %TRUE if the #GDrive can eject media.
- * @eject: Ejects a #GDrive.
- * @eject_finish: Finishes an eject operation.
- * @poll_for_media: Poll for media insertion/removal on a #GDrive.
- * @poll_for_media_finish: Finishes a media poll operation.
- * @get_identifier: Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one.
- * @enumerate_identifiers: Returns an array strings listing the kinds of identifiers which the #GDrive has.
- * @get_start_stop_type: Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22.
- * @can_stop: Returns %TRUE if a #GDrive can be stopped. Since 2.22.
- * @stop: Stops a #GDrive. Since 2.22.
- * @stop_finish: Finishes a stop operation. Since 2.22.
- * @can_start: Returns %TRUE if a #GDrive can be started. Since 2.22.
- * @can_start_degraded: Returns %TRUE if a #GDrive can be started degraded. Since 2.22.
- * @start: Starts a #GDrive. Since 2.22.
- * @start_finish: Finishes a start operation. Since 2.22.
- * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.
- * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22.
- * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
- * @get_sort_key: Gets a key used for sorting #GDrive instances or %NULL if no such key exists. Since 2.32.
- *
- * Interface for creating #GDrive implementations.
- */
-
-
-/**
- * GDriveStartFlags:
- * @G_DRIVE_START_NONE: No flags set.
- *
- * Flags used when starting a drive.
+ * GSimpleAction::change-state:
+ * @simple: the #GSimpleAction
+ * @value: (allow-none): the requested value for the state
*
- * Since: 2.22
+ * Indicates that the action just received a request to change its
+ * state.
+ *
+ * @value will always be of the correct state type. In the event that
+ * an incorrect type was given, no signal will be emitted.
+ *
+ * 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
+ * call g_simple_action_set_state() from the handler.
+ *
+ * An example of a 'change-state' handler:
+ * |[<!-- language="C" -->
+ * static void
+ * change_volume_state (GSimpleAction *action,
+ * GVariant *value,
+ * gpointer user_data)
+ * {
+ * gint requested;
+ *
+ * requested = g_variant_get_int32 (value);
+ *
+ * // Volume only goes from 0 to 10
+ * if (0 <= requested && requested <= 10)
+ * g_simple_action_set_state (action, value);
+ * }
+ * ]|
+ *
+ * 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
*/
/**
- * GDriveStartStopType:
- * @G_DRIVE_START_STOP_TYPE_UNKNOWN: Unknown or drive doesn't support start/stop.
- * @G_DRIVE_START_STOP_TYPE_SHUTDOWN: The stop method will physically shut down the drive and e.g. power down the port the drive is attached to.
- * @G_DRIVE_START_STOP_TYPE_NETWORK: The start/stop methods are used for connecting/disconnect to the drive over the network.
- * @G_DRIVE_START_STOP_TYPE_MULTIDISK: The start/stop methods will assemble/disassemble a virtual drive from several physical drives.
- * @G_DRIVE_START_STOP_TYPE_PASSWORD: The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command)
+ * GSimpleAction:enabled:
*
- * Enumeration describing how a drive can be started/stopped.
+ * If @action is currently enabled.
*
- * Since: 2.22
+ * If the action is disabled then calls to g_action_activate() and
+ * g_action_change_state() have no effect.
+ *
+ * Since: 2.28
*/
/**
- * GEmblem:
+ * GSimpleAction:name:
+ *
+ * The name of the action. This is mostly meaningful for identifying
+ * the action once it has been added to a #GSimpleActionGroup.
*
- * An object for Emblems
+ * Since: 2.28
*/
/**
- * GEmblemOrigin:
- * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin
- * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information
- * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly"
- * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)
+ * GSimpleAction:parameter-type:
*
- * GEmblemOrigin is used to add information about the origin of the emblem
- * to #GEmblem.
+ * The type of the parameter that must be given when activating the
+ * action.
*
- * Since: 2.18
+ * Since: 2.28
*/
/**
- * GEmblemedIcon:
+ * GSimpleAction:state:
+ *
+ * The state of the action, or %NULL if the action is stateless.
*
- * An implementation of #GIcon for icons with emblems.
+ * Since: 2.28
*/
/**
- * GEnumClass:
- * @g_type_class: the parent class
- * @minimum: the smallest possible value.
- * @maximum: the largest possible value.
- * @n_values: the number of possible values.
- * @values: an array of #GEnumValue structs describing the individual values.
+ * GSimpleAction:state-type:
+ *
+ * The #GVariantType of the state that the action has, or %NULL if the
+ * action is stateless.
*
- * The class of an enumeration type holds information about its
- * possible values.
+ * Since: 2.28
*/
/**
- * GEnumValue:
- * @value: the enum value
- * @value_name: the name of the value
- * @value_nick: the nickname of the value
+ * GSimpleIOStream:
*
- * A structure which contains a single enum value, its name, and its
- * nickname.
+ * A wrapper around a #GInputStream and a #GOutputStream.
+ *
+ * Since: 2.44
*/
/**
- * GError:
- * @domain: error domain, e.g. #G_FILE_ERROR
- * @code: error code, e.g. %G_FILE_ERROR_NOENT
- * @message: human-readable informative error message
+ * GSimpleIOStream:input-stream:
*
- * The <structname>GError</structname> structure contains
- * information about an error that has occurred.
+ * Since: 2.44
*/
/**
- * GFile:
+ * GSimpleIOStream:output-stream:
*
- * A handle to an object implementing the #GFileIface interface.
- * Generally stores a location within the file system. Handles do not
- * necessarily represent files or directories that currently exist.
+ * Since: 2.44
*/
/**
- * GFileAttributeInfo:
- * @name: the name of the attribute.
- * @type: the #GFileAttributeType type of the attribute.
- * @flags: a set of #GFileAttributeInfoFlags.
+ * GSimplePermission:
*
- * Information about a specific attribute.
+ * #GSimplePermission is an opaque data structure. There are no methods
+ * except for those defined by #GPermission.
*/
/**
- * GFileAttributeInfoFlags:
- * @G_FILE_ATTRIBUTE_INFO_NONE: no flags set.
- * @G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE: copy the attribute values when the file is copied.
- * @G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED: copy the attribute values when the file is moved.
+ * GSimpleProxyResolver:default-proxy:
*
- * Flags specifying the behaviour of an attribute.
+ * 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.
*/
/**
- * GFileAttributeInfoList:
- * @infos: an array of #GFileAttributeInfo<!-- -->s.
- * @n_infos: the number of values in the array.
+ * 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"
*
- * Acts as a lightweight registry for possible valid file attributes.
- * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s.
+ * - 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.
*/
/**
- * GFileAttributeMatcher:
+ * GSocket:broadcast:
+ *
+ * Whether the socket should allow sending to broadcast addresses.
*
- * Determines if a string matches a file attribute.
+ * Since: 2.32
*/
/**
- * GFileAttributeStatus:
- * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty).
- * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set.
- * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value.
+ * GSocket:multicast-loopback:
+ *
+ * Whether outgoing multicast packets loop back to the local host.
*
- * Used by g_file_set_attributes_from_info() when setting file attributes.
+ * Since: 2.32
*/
/**
- * GFileAttributeType:
- * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type.
- * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string.
- * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes.
- * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value.
- * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject.
- * @G_FILE_ATTRIBUTE_TYPE_STRINGV: a %NULL terminated char **. Since 2.22
+ * GSocket:multicast-ttl:
+ *
+ * Time-to-live out outgoing multicast packets
*
- * The data types for file attributes.
+ * Since: 2.32
*/
/**
- * GFileCopyFlags:
- * @G_FILE_COPY_NONE: No flags set.
- * @G_FILE_COPY_OVERWRITE: Overwrite any existing files
- * @G_FILE_COPY_BACKUP: Make a backup of any existing files.
- * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks.
- * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo).
- * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported.
- * @G_FILE_COPY_TARGET_DEFAULT_PERMS: Leaves target file with default perms, instead of setting the source file perms.
+ * GSocket:timeout:
+ *
+ * The timeout in seconds on socket I/O
*
- * Flags used when copying or moving files.
+ * Since: 2.26
*/
/**
- * GFileCreateFlags:
- * @G_FILE_CREATE_NONE: No flags set.
- * @G_FILE_CREATE_PRIVATE: Create a file that can only be accessed by the current user.
- * @G_FILE_CREATE_REPLACE_DESTINATION: Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. Since 2.20
+ * GSocket:ttl:
+ *
+ * Time-to-live for outgoing unicast packets
*
- * Flags used when an operation may create a file.
+ * Since: 2.32
*/
/**
- * GFileDescriptorBased:
+ * GSocketAddress:
*
- * An interface for file descriptor based io objects.
+ * A socket endpoint address, corresponding to struct sockaddr
+ * or one of its subtypes.
*/
/**
- * GFileDescriptorBasedIface:
- * @g_iface: The parent interface.
+ * GSocketClient::event:
+ * @client: the #GSocketClient
+ * @event: the event that is occurring
+ * @connectable: the #GSocketConnectable that @event is occurring on
+ * @connection: the current representation of the connection
+ *
+ * Emitted when @client's activity on @connectable changes state.
+ * Among other things, this can be used to provide progress
+ * information about a network connection in the UI. The meanings of
+ * the different @event values are as follows:
+ *
+ * - %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
+ * particular, if @client ends up attempting to connect to more than
+ * one address). However, if @client emits the #GSocketClient::event
+ * signal at all for a given connectable, that it will always emit
+ * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
+ *
+ * Note that there may be additional #GSocketClientEvent values in
+ * the future; unrecognized @event values should be ignored.
+ *
+ * Since: 2.32
*/
/**
- * GFileEnumerator:
+ * GSocketClient:proxy-resolver:
*
- * A per matched file iterator.
+ * The proxy resolver to use
+ *
+ * Since: 2.36
*/
/**
- * GFileIOStream:
+ * GSocketService::incoming:
+ * @service: the #GSocketService
+ * @connection: a new #GSocketConnection object
+ * @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
+ * handling of @connection, but may not block; in essence,
+ * asynchronous operations must be used.
*
- * A subclass of GIOStream for opened files. This adds
- * a few file-specific operations and seeking and truncating.
+ * @connection will be unreffed once the signal handler returns,
+ * so you need to ref it yourself if you are planning to use it.
*
- * #GFileIOStream implements GSeekable.
+ * Returns: %TRUE to stop other handlers from being called
+ * Since: 2.22
*/
/**
- * GFileIcon:
+ * GSrvTarget:
*
- * Gets an icon for a #GFile. Implements #GLoadableIcon.
+ * A single target host/port that a network service is running on.
*/
/**
- * GFileIcon:file:
+ * GStaticResource:
*
- * The file containing the icon.
+ * #GStaticResource is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GFileIface:
- * @g_iface: The parent interface.
- * @dup: Duplicates a #GFile.
- * @hash: Creates a hash of a #GFile.
- * @equal: Checks equality of two given #GFile<!-- -->s.
- * @is_native: Checks to see if a file is native to the system.
- * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme.
- * @get_uri_scheme: Gets the URI scheme for a #GFile.
- * @get_basename: Gets the basename for a given #GFile.
- * @get_path: Gets the current path within a #GFile.
- * @get_uri: Gets a URI for the path within a #GFile.
- * @get_parse_name: Gets the parsed name for the #GFile.
- * @get_parent: Gets the parent directory for the #GFile.
- * @prefix_matches: Checks whether a #GFile contains a specified file.
- * @get_relative_path: Gets the path for a #GFile relative to a given path.
- * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path.
- * @get_child_for_display_name: Gets the child #GFile for a given display name.
- * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile.
- * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile.
- * @enumerate_children_finish: Finishes asynchronously enumerating the children.
- * @query_info: Gets the #GFileInfo for a #GFile.
- * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile.
- * @query_info_finish: Finishes an asynchronous query info operation.
- * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on.
- * @query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on.
- * @query_filesystem_info_finish: Finishes asynchronously getting the file system info.
- * @find_enclosing_mount: Gets a #GMount for the #GFile.
- * @find_enclosing_mount_async: Asynchronously gets the #GMount for a #GFile.
- * @find_enclosing_mount_finish: Finishes asynchronously getting the volume.
- * @set_display_name: Sets the display name for a #GFile.
- * @set_display_name_async: Asynchronously sets a #GFile's display name.
- * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name.
- * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set.
- * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set.
- * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes.
- * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable.
- * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable.
- * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces.
- * @set_attribute: Sets a #GFileAttribute.
- * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo.
- * @set_attributes_async: Asynchronously sets a file's attributes.
- * @set_attributes_finish: Finishes setting a file's attributes asynchronously.
- * @read_fn: Reads a file asynchronously.
- * @read_async: Asynchronously reads a file.
- * @read_finish: Finishes asynchronously reading a file.
- * @append_to: Writes to the end of a file.
- * @append_to_async: Asynchronously writes to the end of a file.
- * @append_to_finish: Finishes an asynchronous file append operation.
- * @create: Creates a new file.
- * @create_async: Asynchronously creates a file.
- * @create_finish: Finishes asynchronously creating a file.
- * @replace: Replaces the contents of a file.
- * @replace_async: Asynchronously replaces the contents of a file.
- * @replace_finish: Finishes asynchronously replacing a file.
- * @delete_file: Deletes a file.
- * @_delete_file_async: Asynchronously deletes a file.
- * @_delete_file_finish: Finishes an asynchronous delete.
- * @trash: Sends a #GFile to the Trash location.
- * @_trash_async: Asynchronously sends a #GFile to the Trash location.
- * @_trash_finish: Finishes an asynchronous file trashing operation.
- * @make_directory: Makes a directory.
- * @_make_directory_async: Asynchronously makes a directory.
- * @_make_directory_finish: Finishes making a directory asynchronously.
- * @make_symbolic_link: Makes a symbolic link.
- * @_make_symbolic_link_async: Asynchronously makes a symbolic link
- * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously.
- * @copy: Copies a file.
- * @copy_async: Asynchronously copies a file.
- * @copy_finish: Finishes an asynchronous copy operation.
- * @move: Moves a file.
- * @_move_async: Asynchronously moves a file.
- * @_move_finish: Finishes an asynchronous move operation.
- * @mount_mountable: Mounts a mountable object.
- * @mount_mountable_finish: Finishes a mounting operation.
- * @unmount_mountable: Unmounts a mountable object.
- * @unmount_mountable_finish: Finishes an unmount operation.
- * @eject_mountable: Ejects a mountable.
- * @eject_mountable_finish: Finishes an eject operation.
- * @mount_enclosing_volume: Mounts a specified location.
- * @mount_enclosing_volume_finish: Finishes mounting a specified location.
- * @monitor_dir: Creates a #GFileMonitor for the location.
- * @monitor_file: Creates a #GFileMonitor for the location.
- * @open_readwrite: Open file read/write. Since 2.22.
- * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22.
- * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22.
- * @create_readwrite: Creates file read/write. Since 2.22.
- * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22.
- * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22.
- * @replace_readwrite: Replaces file read/write. Since 2.22.
- * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22.
- * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22.
- * @start_mountable: Starts a mountable object. Since 2.22.
- * @start_mountable_finish: Finishes an start operation. Since 2.22.
- * @stop_mountable: Stops a mountable. Since 2.22.
- * @stop_mountable_finish: Finishes an stop operation. Since 2.22.
- * @supports_thread_contexts: a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.
- * @unmount_mountable_with_operation: Unmounts a mountable object using a #GMountOperation. Since 2.22.
- * @unmount_mountable_with_operation_finish: Finishes an unmount operation using a #GMountOperation. Since 2.22.
- * @eject_mountable_with_operation: Ejects a mountable object using a #GMountOperation. Since 2.22.
- * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
- * @poll_mountable: Polls a mountable object for media changes. Since 2.22.
- * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22.
- *
- * An interface for writing VFS file handles.
- */
-
-
-/**
- * GFileInfo:
- *
- * Stores information about a file system object referenced by a #GFile.
- */
-
-
-/**
- * GFileInputStream:
- *
- * A subclass of GInputStream for opened files. This adds
- * a few file-specific operations and seeking.
- *
- * #GFileInputStream implements #GSeekable.
- */
-
-
-/**
- * GFileMonitor:
- *
- * Watches for changes to a file.
+ * GTask:
+ *
+ * The opaque object representing a synchronous or asynchronous task
+ * and its result.
*/
/**
- * GFileMonitor::changed:
- * @monitor: a #GFileMonitor.
- * @file: a #GFile.
- * @other_file: a #GFile or #NULL.
- * @event_type: a #GFileMonitorEvent.
+ * GTask:completed:
*
- * Emitted when @file has been changed.
+ * 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.
*
- * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
- * #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the
- * old path, and @other_file will be set to a #GFile containing the new path.
+ * This property is guaranteed to change from %FALSE to %TRUE exactly once.
*
- * In all the other cases, @other_file will be set to #NULL.
- */
-
-
-/**
- * GFileMonitorEvent:
- * @G_FILE_MONITOR_EVENT_CHANGED: a file changed.
- * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes.
- * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted.
- * @G_FILE_MONITOR_EVENT_CREATED: a file was created.
- * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed.
- * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted.
- * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was unmounted.
- * @G_FILE_MONITOR_EVENT_MOVED: the file was moved.
+ * 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.
*
- * Specifies what type of event a monitor event is.
+ * Since: 2.44
*/
/**
- * GFileMonitorFlags:
- * @G_FILE_MONITOR_NONE: No flags set.
- * @G_FILE_MONITOR_WATCH_MOUNTS: Watch for mount events.
- * @G_FILE_MONITOR_SEND_MOVED: Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events).
+ * GTaskThreadFunc:
+ * @task: the #GTask
+ * @source_object: (type GObject): @task's source object
+ * @task_data: @task's task data
+ * @cancellable: @task's #GCancellable, or %NULL
*
- * Flags used to set what a #GFileMonitor will watch for.
- */
-
-
-/**
- * GFileOutputStream:
+ * 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().
*
- * A subclass of GOutputStream for opened files. This adds
- * a few file-specific operations and seeking and truncating.
+ * 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.
*
- * #GFileOutputStream implements GSeekable.
- */
-
-
-/**
- * GFileProgressCallback:
- * @current_num_bytes: the current number of bytes in the operation.
- * @total_num_bytes: the total number of bytes in the operation.
- * @user_data: user data passed to the callback.
+ * Other than in that case, @task will be completed when the
+ * #GTaskThreadFunc returns, not when it calls a
+ * `g_task_return_` function.
*
- * When doing file operations that may take a while, such as moving
- * a file or copying a file, a progress callback is used to pass how
- * far along that operation is to the application.
+ * Since: 2.36
*/
/**
- * GFileQueryInfoFlags:
- * @G_FILE_QUERY_INFO_NONE: No flags set.
- * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: Don't follow symlinks.
+ * GTcpWrapperConnection:
*
- * Flags used when querying a #GFileInfo.
+ * #GTcpWrapperConnection is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GFileReadMoreCallback:
- * @file_contents: the data as currently read.
- * @file_size: the size of the data currently read.
- * @callback_data: data passed to the callback.
+ * GTestDBus:
*
- * When loading the partial contents of a file with g_file_load_partial_contents_async(),
- * it may become necessary to determine if any more data from the file should be loaded.
- * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data
- * should be read, or %FALSE otherwise.
+ * The #GTestDBus structure contains only private data and
+ * should only be accessed using the provided API.
*
- * Returns: %TRUE if more data should be read back. %FALSE otherwise.
+ * Since: 2.34
*/
/**
- * GFileType:
- * @G_FILE_TYPE_UNKNOWN: File's type is unknown.
- * @G_FILE_TYPE_REGULAR: File handle represents a regular file.
- * @G_FILE_TYPE_DIRECTORY: File handle represents a directory.
- * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems).
- * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, block device, or character device.
- * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems).
- * @G_FILE_TYPE_MOUNTABLE: File is a mountable location.
+ * GTestDBus:flags:
*
- * Indicates the file's on-disk type.
+ * #GTestDBusFlags specifying the behaviour of the D-Bus session.
+ *
+ * Since: 2.34
*/
/**
- * GFilenameCompleter:
+ * GThemedIcon:name:
*
- * Completes filenames based on files that exist within the file system.
+ * The icon name.
*/
/**
- * GFilenameCompleter::got-completion-data:
+ * GThemedIcon:names:
*
- * Emitted when the file name completion information comes available.
+ * A %NULL-terminated array of icon names.
*/
/**
- * GFilesystemPreviewType:
- * @G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS: Only preview files if user has explicitly requested it.
- * @G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL: Preview files if user has requested preview of "local" files.
- * @G_FILESYSTEM_PREVIEW_TYPE_NEVER: Never preview files.
+ * GThemedIcon:use-default-fallbacks:
*
- * Indicates a hint from the file system whether files should be
- * previewed in a file manager. Returned as the value of the key
- * #G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW.
+ * Whether to use the default fallbacks found by shortening the icon name
+ * at '-' characters. If the "names" array has more than one element,
+ * ignores any past the first.
+ *
+ * For example, if the icon name was "gnome-dev-cdrom-audio", the array
+ * would become
+ * |[<!-- language="C" -->
+ * {
+ * "gnome-dev-cdrom-audio",
+ * "gnome-dev-cdrom",
+ * "gnome-dev",
+ * "gnome",
+ * NULL
+ * };
+ * ]|
*/
/**
- * GFilterInputStream:
+ * GThreadedSocketService::run:
+ * @service: the #GThreadedSocketService.
+ * @connection: a new #GSocketConnection object.
+ * @source_object: the source_object passed to g_socket_listener_add_address().
+ *
+ * The ::run signal is emitted in a worker thread in response to an
+ * incoming connection. This thread is dedicated to handling
+ * @connection and may perform blocking IO. The signal handler need
+ * not return until the connection is closed.
*
- * A base class for all input streams that work on an underlying stream.
+ * Returns: %TRUE to stop further signal handlers from being called
*/
/**
- * GFilterOutputStream:
+ * GTlsBackend:
+ *
+ * TLS (Transport Layer Security, aka SSL) backend. This is an
+ * internal type used to coordinate the different classes implemented
+ * by a TLS backend.
*
- * A base class for all output streams that work on an underlying stream.
+ * Since: 2.28
*/
/**
- * GFlagsClass:
- * @g_type_class: the parent class
- * @mask: a mask covering all possible values.
- * @n_values: the number of possible values.
- * @values: an array of #GFlagsValue structs describing the individual values.
+ * GTlsCertificate:
+ *
+ * Abstract base class for TLS certificate types.
*
- * The class of a flags type holds information about its
- * possible values.
+ * Since: 2.28
*/
/**
- * GFlagsValue:
- * @value: the flags value
- * @value_name: the name of the value
- * @value_nick: the nickname of the value
+ * GTlsCertificate:certificate:
*
- * A structure which contains a single flags value, its name, and its
- * nickname.
+ * 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
*/
/**
- * GFreeFunc:
- * @data: a data pointer
+ * GTlsCertificate:certificate-pem:
+ *
+ * The PEM (ASCII) encoded representation of the certificate.
+ * This property and the #GTlsCertificate:certificate
+ * property represent the same data, just in different forms.
*
- * Declares a type of function which takes an arbitrary
- * data pointer argument and has no return value. It is
- * not currently used in GLib or GTK+.
+ * Since: 2.28
*/
/**
- * GHmac:
+ * GTlsCertificate:issuer:
*
- * An opaque structure representing a HMAC operation.
- * To create a new GHmac, use g_hmac_new(). To free
- * a GHmac, use g_hmac_unref().
+ * A #GTlsCertificate representing the entity that issued this
+ * certificate. If %NULL, this means that the certificate is either
+ * self-signed, or else the certificate of the issuer is not
+ * available.
*
- * Since: 2.30
+ * Since: 2.28
*/
/**
- * GIOErrorEnum:
- * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
- * @G_IO_ERROR_NOT_FOUND: File not found error.
- * @G_IO_ERROR_EXISTS: File already exists error.
- * @G_IO_ERROR_IS_DIRECTORY: File is a directory error.
- * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory.
- * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty.
- * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file.
- * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link.
- * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted.
- * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters.
- * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters.
- * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links.
- * @G_IO_ERROR_NO_SPACE: No space left on drive.
- * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument.
- * @G_IO_ERROR_PERMISSION_DENIED: Permission denied.
- * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend.
- * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted.
- * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted.
- * @G_IO_ERROR_CLOSED: File was closed.
- * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable.
- * @G_IO_ERROR_PENDING: Operations are still pending.
- * @G_IO_ERROR_READ_ONLY: File is read only.
- * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created.
- * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect.
- * @G_IO_ERROR_TIMED_OUT: Operation timed out.
- * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive.
- * @G_IO_ERROR_BUSY: File is busy.
- * @G_IO_ERROR_WOULD_BLOCK: Operation would block.
- * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations).
- * @G_IO_ERROR_WOULD_MERGE: Operation would merge files.
- * @G_IO_ERROR_FAILED_HANDLED: Operation failed and a helper program has already interacted with the user. Do not display any error dialog.
- * @G_IO_ERROR_TOO_MANY_OPEN_FILES: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20
- * @G_IO_ERROR_NOT_INITIALIZED: The object has not been initialized. Since 2.22
- * @G_IO_ERROR_ADDRESS_IN_USE: The requested address is already in use. Since 2.22
- * @G_IO_ERROR_PARTIAL_INPUT: Need more input to finish operation. Since 2.24
- * @G_IO_ERROR_INVALID_DATA: There input data was invalid. Since 2.24
- * @G_IO_ERROR_DBUS_ERROR: A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26.
- * @G_IO_ERROR_HOST_UNREACHABLE: Host unreachable. Since 2.26
- * @G_IO_ERROR_NETWORK_UNREACHABLE: Network unreachable. Since 2.26
- * @G_IO_ERROR_CONNECTION_REFUSED: Connection refused. Since 2.26
- * @G_IO_ERROR_PROXY_FAILED: Connection to proxy server failed. Since 2.26
- * @G_IO_ERROR_PROXY_AUTH_FAILED: Proxy authentication failed. Since 2.26
- * @G_IO_ERROR_PROXY_NEED_AUTH: Proxy server needs authentication. Since 2.26
- * @G_IO_ERROR_PROXY_NOT_ALLOWED: Proxy connection is not allowed by ruleset. Since 2.26
- *
- * Error codes returned by GIO functions.
- */
-
-
-/**
- * GIOModule:
- *
- * Opaque module base class for extending GIO.
+ * GTlsCertificate:private-key:
+ *
+ * The DER (binary) encoded representation of the certificate's
+ * private key, in either PKCS#1 format or unencrypted PKCS#8
+ * format. This property (or the #GTlsCertificate:private-key-pem
+ * 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 `openssl rsa`
+ * tool to convert PKCS#8 keys to PKCS#1.
+ *
+ * Since: 2.28
*/
/**
- * GIOModuleScope:
+ * GTlsCertificate:private-key-pem:
*
- * Represents a scope for loading IO modules. A scope can be used for blocking
- * duplicate modules, or blocking a module you don't want to load.
+ * The PEM (ASCII) encoded representation of the certificate's
+ * 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.
*
- * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
- * or g_io_modules_scan_all_in_directory_with_scope().
+ * PKCS#8 format is supported since 2.32; earlier releases only
+ * support PKCS#1. You can use the `openssl rsa`
+ * tool to convert PKCS#8 keys to PKCS#1.
*
- * Since: 2.30
+ * Since: 2.28
*/
/**
- * GIOModuleScopeFlags:
- * @G_IO_MODULES_SCOPE_NONE: No module scan flags
- * @G_IO_MODULES_SCOPE_BLOCK_DUPLICATES: When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module.
+ * GTlsClientConnection:
*
- * Flags for use with g_io_module_scope_new().
+ * Abstract base class for the backend-specific client connection
+ * type.
*
- * Since: 2.30
+ * Since: 2.28
*/
/**
- * GIOSchedulerJob:
+ * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
*
- * Opaque class for defining and scheduling IO jobs.
+ * A list of the distinguished names of the Certificate Authorities
+ * that the server will accept client certificates signed by. If the
+ * server requests a client certificate during the handshake, then
+ * this property will be set after the handshake completes.
+ *
+ * Each item in the list is a #GByteArray which contains the complete
+ * subject DN of the certificate authority.
+ *
+ * Since: 2.28
*/
/**
- * GIOSchedulerJobFunc:
- * @job: a #GIOSchedulerJob.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @user_data: the data to pass to callback function
+ * GTlsClientConnection:server-identity:
*
- * I/O Job function.
+ * A #GSocketConnectable describing the identity of the server that
+ * is expected on the other end of the connection.
*
- * Long-running jobs should periodically check the @cancellable
- * to see if they have been cancelled.
+ * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
+ * #GTlsClientConnection:validation-flags, this object will be used
+ * to determine the expected identify of the remote end of the
+ * connection; if #GTlsClientConnection:server-identity is not set,
+ * or does not match the identity presented by the server, then the
+ * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
*
- * complete the job, %FALSE if the job is complete (or cancelled)
+ * In addition to its use in verifying the server certificate,
+ * this is also used to give a hint to the server about what
+ * certificate we expect, which is useful for servers that serve
+ * virtual hosts.
*
- * Returns: %TRUE if this function should be called again to
+ * Since: 2.28
*/
/**
- * GIOStream:
+ * GTlsClientConnection:use-ssl3:
*
- * Base class for read-write streams.
- */
-
-
-/**
- * GIOStreamSpliceFlags:
- * @G_IO_STREAM_SPLICE_NONE: Do not close either stream.
- * @G_IO_STREAM_SPLICE_CLOSE_STREAM1: Close the first stream after the splice.
- * @G_IO_STREAM_SPLICE_CLOSE_STREAM2: Close the second stream after the splice.
- * @G_IO_STREAM_SPLICE_WAIT_FOR_BOTH: Wait for both splice operations to finish before calling the callback.
+ * 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.
*
- * GIOStreamSpliceFlags determine how streams should be spliced.
+ * 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
*/
/**
- * GIcon:
+ * GTlsClientConnection:validation-flags:
*
- * An abstract type that specifies an icon.
- */
-
-
-/**
- * GIconIface:
- * @g_iface: The parent interface.
- * @hash: A hash for a given #GIcon.
- * @equal: Checks if two #GIcon<!-- -->s are equal.
- * @to_tokens: Serializes a #GIcon into tokens. The tokens must not contain any whitespace. Don't implement if the #GIcon can't be serialized (Since 2.20).
- * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if the tokens are malformed. Don't implement if the #GIcon can't be serialized (Since 2.20).
+ * What steps to perform when validating a certificate received from
+ * a server. Server certificates that fail to validate in all of the
+ * ways indicated here will be rejected unless the application
+ * overrides the default via #GTlsConnection::accept-certificate.
*
- * GIconIface is used to implement GIcon types for various
- * different systems. See #GThemedIcon and #GLoadableIcon for
- * examples of how to implement this interface.
+ * Since: 2.28
*/
/**
- * GIconv:
+ * GTlsConnection:
*
- * The <structname>GIConv</structname> struct wraps an
- * iconv() conversion descriptor. It contains private data
- * and should only be accessed using the following functions.
+ * Abstract base class for the backend-specific #GTlsClientConnection
+ * and #GTlsServerConnection types.
+ *
+ * Since: 2.28
*/
/**
- * GInetAddress:
+ * GTlsConnection::accept-certificate:
+ * @conn: a #GTlsConnection
+ * @peer_cert: the peer's #GTlsCertificate
+ * @errors: the problems with @peer_cert.
*
- * An IPv4 or IPv6 internet address.
+ * Emitted during the TLS handshake after the peer certificate has
+ * been received. You can examine @peer_cert's certification path by
+ * calling g_tls_certificate_get_issuer() on it.
+ *
+ * For a client-side connection, @peer_cert is the server's
+ * certificate, and the signal will only be emitted if the
+ * certificate was not acceptable according to @conn's
+ * #GTlsClientConnection:validation_flags. If you would like the
+ * certificate to be accepted despite @errors, return %TRUE from the
+ * signal handler. Otherwise, if no handler accepts the certificate,
+ * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
+ *
+ * For a server-side connection, @peer_cert is the certificate
+ * presented by the client, if this was requested via the server's
+ * #GTlsServerConnection:authentication_mode. On the server side,
+ * the signal is always emitted when the client presents a
+ * certificate, and the certificate will only be accepted if a
+ * handler returns %TRUE.
+ *
+ * Note that if this signal is emitted as part of asynchronous I/O
+ * in the main thread, then you should not attempt to interact with
+ * the user before returning from the signal handler. If you want to
+ * let the user decide whether or not to accept the certificate, you
+ * would have to return %FALSE from the signal handler on the first
+ * attempt, and then after the connection attempt returns a
+ * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
+ * the user decides to accept the certificate, remember that fact,
+ * create a new connection, and return %TRUE from the signal handler
+ * the next time.
+ *
+ * If you are doing I/O in another thread, you do not
+ * 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.
+ * Since: 2.28
*/
/**
- * GInetAddress:is-any:
+ * GTlsConnection:base-io-stream:
*
- * Whether this is the "any" address for its family.
- * See g_inet_address_get_is_any().
+ * The #GIOStream that the connection wraps
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GInetAddress:is-link-local:
+ * GTlsConnection:certificate:
*
- * Whether this is a link-local address.
- * See g_inet_address_get_is_link_local().
+ * The connection's certificate; see
+ * g_tls_connection_set_certificate().
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GInetAddress:is-loopback:
+ * GTlsConnection:database:
*
- * Whether this is the loopback address for its family.
- * See g_inet_address_get_is_loopback().
+ * The certificate database to use when verifying this TLS connection.
+ * If no cerificate database is set, then the default database will be
+ * used. See g_tls_backend_get_default_database().
*
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * GInetAddress:is-mc-global:
+ * GTlsConnection:interaction:
*
- * Whether this is a global multicast address.
- * See g_inet_address_get_is_mc_global().
+ * A #GTlsInteraction object to be used when the connection or certificate
+ * database need to interact with the user. This will be used to prompt the
+ * user for passwords where necessary.
*
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * GInetAddress:is-mc-link-local:
+ * GTlsConnection:peer-certificate:
*
- * Whether this is a link-local multicast address.
- * See g_inet_address_get_is_mc_link_local().
+ * The connection's peer's certificate, after the TLS handshake has
+ * completed and the certificate has been accepted. Note in
+ * particular that this is not yet set during the emission of
+ * #GTlsConnection::accept-certificate.
*
- * Since: 2.22
+ * (You can watch for a #GObject::notify signal on this property to
+ * detect when a handshake has occurred.)
+ *
+ * Since: 2.28
*/
/**
- * GInetAddress:is-mc-node-local:
+ * GTlsConnection:peer-certificate-errors:
*
- * Whether this is a node-local multicast address.
- * See g_inet_address_get_is_mc_node_local().
+ * The errors noticed-and-ignored while verifying
+ * #GTlsConnection:peer-certificate. Normally this should be 0, but
+ * it may not be if #GTlsClientConnection:validation-flags is not
+ * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
+ * #GTlsConnection::accept-certificate overrode the default
+ * behavior.
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GInetAddress:is-mc-org-local:
+ * GTlsConnection:rehandshake-mode:
*
- * Whether this is an organization-local multicast address.
- * See g_inet_address_get_is_mc_org_local().
+ * The rehandshaking mode. See
+ * g_tls_connection_set_rehandshake_mode().
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GInetAddress:is-mc-site-local:
+ * GTlsConnection:require-close-notify:
*
- * Whether this is a site-local multicast address.
- * See g_inet_address_get_is_mc_site_local().
+ * Whether or not proper TLS close notification is required.
+ * See g_tls_connection_set_require_close_notify().
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GInetAddress:is-multicast:
+ * GTlsConnection:use-system-certdb:
*
- * Whether this is a multicast address.
- * See g_inet_address_get_is_multicast().
+ * Whether or not the system certificate database will be used to
+ * verify peer certificates. See
+ * g_tls_connection_set_use_system_certdb().
*
- * Since: 2.22
+ * Deprecated: 2.30: Use GTlsConnection:database instead
*/
/**
- * GInetAddress:is-site-local:
+ * GTlsDatabase:
*
- * Whether this is a site-local address.
- * See g_inet_address_get_is_loopback().
+ * Abstract base class for the backend-specific database types.
*
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * GInetAddressMask:
+ * GTlsFileDatabase:
*
- * A combination of an IPv4 or IPv6 base address and a length,
- * representing a range of IP addresses.
+ * Implemented by a #GTlsDatabase which allows you to load certificates
+ * from a file.
*
- * Since: 2.32
+ * Since: 2.30
*/
/**
- * GInetSocketAddress:
+ * GTlsFileDatabase:anchors:
+ *
+ * The path to a file containing PEM encoded certificate authority
+ * root anchors. The certificates in this file will be treated as
+ * root authorities for the purpose of verifying other certificates
+ * via the g_tls_database_verify_chain() operation.
*
- * An IPv4 or IPv6 socket address, corresponding to a <type>struct
- * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
+ * Since: 2.30
*/
/**
- * GInitable:
+ * GTlsInteraction:
*
- * Interface for initializable objects.
+ * An object representing interaction that the TLS connection and database
+ * might have with the user.
*
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * GInitableIface:
- * @g_iface: The parent interface.
- * @init: Initializes the object.
+ * 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_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.
*
- * Provides an interface for initializing object such that initialization
- * may fail.
+ * The class for #GTlsInteraction. Derived classes implement the various
+ * virtual interaction methods to handle TLS interactions.
*
- * Since: 2.22
+ * Derived classes can choose to implement whichever interactions methods they'd
+ * like to support by overriding those virtual methods in their class
+ * initialization function. If a derived class implements an async method,
+ * it must also implement the corresponding finish method.
+ *
+ * The synchronous interaction methods should implement to display modal dialogs,
+ * and the asynchronous methods to display modeless dialogs.
+ *
+ * If the user cancels an interaction, then the result should be
+ * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
+ * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
+ *
+ * Since: 2.30
*/
/**
- * GInitiallyUnowned:
+ * GTlsPassword:
*
- * All the fields in the <structname>GInitiallyUnowned</structname> structure
- * are private to the #GInitiallyUnowned implementation and should never be
- * accessed directly.
+ * An abstract interface representing a password used in TLS. Often used in
+ * user interaction such as unlocking a key storage token.
+ *
+ * Since: 2.30
*/
/**
- * GInitiallyUnownedClass:
+ * GTlsServerConnection:authentication-mode:
+ *
+ * The #GTlsAuthenticationMode for the server. This can be changed
+ * before calling g_tls_connection_handshake() if you want to
+ * rehandshake with a different mode from the initial handshake.
*
- * The class structure for the <structname>GInitiallyUnowned</structname> type.
+ * Since: 2.28
*/
/**
- * GInputStream:
+ * GUnixConnection:
*
- * Base class for streaming input operations.
+ * #GUnixConnection is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GInputVector:
- * @buffer: Pointer to a buffer where data will be written.
- * @size: the available size in @buffer.
+ * GUnixCredentialsMessage:credentials:
*
- * Structure used for scatter/gather data input.
- * You generally pass in an array of #GInputVector<!-- -->s
- * and the operation will store the read data starting in the
- * first buffer, switching to the next as needed.
+ * The credentials stored in the message.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * GInstanceInitFunc:
- * @instance: The instance to initialize.
- * @g_class: The class of the type the instance is created for.
+ * GUnixFDList:
*
- * A callback function used by the type system to initialize a new
- * instance of a type. This function initializes all instance members and
- * allocates any resources required by it.
- * Initialization of a derived instance involves calling all its parent
- * types instance initializers, so the class member of the instance
- * is altered during its initialization to always point to the class that
- * belongs to the type the current initializer was introduced for.
+ * #GUnixFDList is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GInterfaceFinalizeFunc:
- * @g_iface: The interface structure to finalize.
- * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ * GUnixFDMessage:
*
- * A callback function used by the type system to finalize an interface.
- * This function should destroy any internal data and release any resources
- * allocated by the corresponding GInterfaceInitFunc() function.
+ * #GUnixFDMessage is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GInterfaceInfo:
- * @interface_init: location of the interface initialization function
- * @interface_finalize: location of the interface finalization function
- * @interface_data: user-supplied data passed to the interface init/finalize functions
+ * GUnixInputStream:close-fd:
*
- * A structure that provides information to the type system which is
- * used specifically for managing interface types.
- */
-
-
-/**
- * GInterfaceInitFunc:
- * @g_iface: The interface structure to initialize.
- * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ * Whether to close the file descriptor when the stream is closed.
*
- * A callback function used by the type system to initialize a new
- * interface. This function should initialize all internal data and
- * allocate any resources required by the interface.
+ * Since: 2.20
*/
/**
- * GLIB_CHECK_VERSION:
- * @major: the major version to check for
- * @minor: the minor version to check for
- * @micro: the micro version to check for
- *
- * Checks the version of the GLib library that is being compiled
- * against.
- *
- * <example>
- * <title>Checking the version of the GLib library</title>
- * <programlisting>
- * if (!GLIB_CHECK_VERSION (1, 2, 0))
- * g_error ("GLib version 1.2.0 or above is needed");
- * </programlisting>
- * </example>
- *
- * See glib_check_version() for a runtime check.
+ * GUnixInputStream:fd:
*
- * is the same as or newer than the passed-in version.
+ * The file descriptor that the stream reads from.
*
- * Returns: %TRUE if the version of the GLib header files
+ * Since: 2.20
*/
/**
- * GLoadableIcon:
+ * GUnixMountMonitor::mountpoints-changed:
+ * @monitor: the object on which the signal is emitted
*
- * Generic type for all kinds of icons that can be loaded
- * as a stream.
+ * Emitted when the unix mount points have changed.
*/
/**
- * GLoadableIconIface:
- * @g_iface: The parent interface.
- * @load: Loads an icon.
- * @load_async: Loads an icon asynchronously.
- * @load_finish: Finishes an asynchronous icon load.
+ * GUnixMountMonitor::mounts-changed:
+ * @monitor: the object on which the signal is emitted
*
- * Interface for icons that can be loaded as a stream.
+ * Emitted when the unix mounts have changed.
*/
/**
- * GMainContext:
+ * 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.
*
- * The <structname>GMainContext</structname> struct is an opaque data
- * type representing a set of sources to be handled in a main loop.
+ * Types of UNIX mounts.
*/
/**
- * GMainLoop:
+ * GUnixOutputStream:close-fd:
+ *
+ * Whether to close the file descriptor when the stream is closed.
*
- * The <structname>GMainLoop</structname> struct is an opaque data type
- * representing the main event loop of a GLib or GTK+ application.
+ * Since: 2.20
*/
/**
- * GMarkupError:
- * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
- * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
- * @G_MARKUP_ERROR_PARSE: document was ill-formed
- * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
- * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
- * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid
- * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing
+ * GUnixOutputStream:fd:
+ *
+ * The file descriptor that the stream writes to.
*
- * Error codes returned by markup parsing.
+ * Since: 2.20
*/
/**
- * GMarkupParseContext:
- *
- * A parse context is used to parse a stream of bytes that
- * you expect to contain marked-up text.
+ * GUnixSocketAddress:
*
- * See g_markup_parse_context_new(), #GMarkupParser, and so
- * on for more details.
+ * A UNIX-domain (local) socket address, corresponding to a
+ * struct sockaddr_un.
*/
/**
- * GMarkupParseFlags:
- * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
- * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12
- * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions
+ * GUnixSocketAddress:abstract:
+ *
+ * Whether or not this is an abstract address
*
- * Flags that affect the behaviour of the parser.
+ * Deprecated: Use #GUnixSocketAddress:address-type, which
+ * distinguishes between zero-padded and non-zero-padded
+ * abstract addresses.
*/
/**
- * GMarkupParser:
- * @start_element: Callback to invoke when the opening tag of an element is seen.
- * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>.
- * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections.
- * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections.
- * @error: Callback to invoke when an error occurs.
+ * GVolume::changed:
*
- * Any of the fields in #GMarkupParser can be %NULL, in which case they
- * will be ignored. Except for the @error function, any of these callbacks
- * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
- * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
- * errors are intended to be set from these callbacks. If you set an error
- * from a callback, g_markup_parse_context_parse() will report that error
- * back to its caller.
+ * Emitted when the volume has been changed.
*/
/**
- * GMemVTable:
- * @malloc: function to use for allocating memory.
- * @realloc: function to use for reallocating memory.
- * @free: function to use to free memory.
- * @calloc: function to use for allocating zero-filled memory.
- * @try_malloc: function to use for allocating memory without a default error handler.
- * @try_realloc: function to use for reallocating memory without a default error handler.
+ * GVolume::removed:
*
- * A set of functions used to perform memory allocation. The same #GMemVTable must
- * be used for all allocations in the same program; a call to g_mem_set_vtable(),
- * if it exists, should be prior to any use of GLib.
+ * This signal is emitted when the #GVolume have been removed. If
+ * the recipient is holding references to the object they should
+ * release them so the object can be finalized.
*/
/**
- * GMemoryInputStream:
+ * GVolumeMonitor::drive-changed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: the drive that changed
*
- * Implements #GInputStream for arbitrary memory chunks.
+ * Emitted when a drive changes.
*/
/**
- * GMemoryOutputStream:
+ * GVolumeMonitor::drive-connected:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: a #GDrive that was connected.
*
- * Implements #GOutputStream for arbitrary memory chunks.
+ * Emitted when a drive is connected to the system.
*/
/**
- * GMemoryOutputStream:data:
- *
- * Pointer to buffer where data will be written.
+ * GVolumeMonitor::drive-disconnected:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: a #GDrive that was disconnected.
*
- * Since: 2.24
+ * Emitted when a drive is disconnected from the system.
*/
/**
- * GMemoryOutputStream:data-size:
+ * GVolumeMonitor::drive-eject-button:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: the drive where the eject button was pressed
*
- * Size of data written to the buffer.
+ * Emitted when the eject button is pressed on @drive.
*
- * Since: 2.24
+ * Since: 2.18
*/
/**
- * GMemoryOutputStream:destroy-function: (skip)
+ * GVolumeMonitor::drive-stop-button:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: the drive where the stop button was pressed
*
- * Function called with the buffer as argument when the stream is destroyed.
+ * Emitted when the stop button is pressed on @drive.
*
- * Since: 2.24
+ * Since: 2.22
*/
/**
- * GMemoryOutputStream:realloc-function: (skip)
- *
- * Function with realloc semantics called to enlarge the buffer.
+ * GVolumeMonitor::mount-added:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that was added.
*
- * Since: 2.24
+ * Emitted when a mount is added.
*/
/**
- * GMemoryOutputStream:size:
- *
- * Current size of the data buffer.
+ * GVolumeMonitor::mount-changed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that changed.
*
- * Since: 2.24
+ * Emitted when a mount changes.
*/
/**
- * GMenu:
- *
- * #GMenu is an opaque structure type. You must access it using the
- * functions below.
+ * GVolumeMonitor::mount-pre-unmount:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that is being unmounted.
*
- * Since: 2.32
+ * Emitted when a mount is about to be removed.
*/
/**
- * GMenuAttributeIter:
- *
- * #GMenuAttributeIter is an opaque structure type. You must access it
- * using the functions below.
+ * GVolumeMonitor::mount-removed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that was removed.
*
- * Since: 2.32
+ * Emitted when a mount is removed.
*/
/**
- * GMenuItem:
- *
- * #GMenuItem is an opaque structure type. You must access it using the
- * functions below.
+ * GVolumeMonitor::volume-added:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @volume: a #GVolume that was added.
*
- * Since: 2.32
+ * Emitted when a mountable volume is added to the system.
*/
/**
- * GMenuLinkIter:
- *
- * #GMenuLinkIter is an opaque structure type. You must access it using
- * the functions below.
+ * GVolumeMonitor::volume-changed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @volume: a #GVolume that changed.
*
- * Since: 2.32
+ * Emitted when mountable volume is changed.
*/
/**
- * GMenuModel:
- *
- * #GMenuModel is an opaque structure type. You must access it using the
- * functions below.
+ * GVolumeMonitor::volume-removed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @volume: a #GVolume that was removed.
*
- * Since: 2.32
+ * Emitted when a mountable volume is removed from the system.
*/
/**
- * GMenuModel::items-changed:
- * @model: the #GMenuModel that is changing
- * @position: the position of the change
- * @removed: the number of items removed
- * @added: the number of items added
- *
- * Emitted when a change has occured to the menu.
- *
- * The only changes that can occur to a menu is that items are removed
- * or added. Items may not change (except by being removed and added
- * back in the same location). This signal is capable of describing
- * both of those changes (at the same time).
- *
- * The signal means that starting at the index @position, @removed
- * items were removed and @added items were added in their place. If
- * @removed is zero then only items were added. If @added is zero
- * then only items were removed.
+ * GWin32InputStream:close-handle:
*
- * As an example, if the menu contains items a, b, c, d (in that
- * order) and the signal (2, 1, 3) occurs then the new composition of
- * the menu will be a, b, _, _, _, d (with each _ representing some
- * new item).
+ * Whether to close the file handle when the stream is closed.
*
- * Signal handlers may query the model (particularly the added items)
- * and expect to see the results of the modification that is being
- * reported. The signal is emitted after the modification.
+ * Since: 2.26
*/
/**
- * GMount:
+ * GWin32InputStream:handle:
*
- * A handle to an object implementing the #GMountIface interface.
- */
-
-
-/**
- * GMount::changed:
- * @mount: the object on which the signal is emitted
+ * The handle that the stream reads from.
*
- * Emitted when the mount has been changed.
+ * Since: 2.26
*/
/**
- * GMount::pre-unmount:
- * @mount: the object on which the signal is emitted
+ * GWin32OutputStream:close-handle:
*
- * This signal is emitted when the #GMount is about to be
- * unmounted.
+ * Whether to close the file handle when the stream is closed.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * GMount::unmounted:
- * @mount: the object on which the signal is emitted
+ * GWin32OutputStream:handle:
*
- * This signal is emitted when the #GMount have been
- * unmounted. If the recipient is holding references to the
- * object they should release them so the object can be
- * finalized.
- */
-
-
-/**
- * GMountIface:
- * @g_iface: The parent interface.
- * @changed: Changed signal that is emitted when the mount's state has changed.
- * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized.
- * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file.
- * @get_root: Gets a #GFile to the root directory of the #GMount.
- * @get_name: Gets a string containing the name of the #GMount.
- * @get_icon: Gets a #GIcon for the #GMount.
- * @get_uuid: Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
- * @get_volume: Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume.
- * @get_drive: Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive.
- * @can_unmount: Checks if a #GMount can be unmounted.
- * @can_eject: Checks if a #GMount can be ejected.
- * @unmount: Starts unmounting a #GMount.
- * @unmount_finish: Finishes an unmounting operation.
- * @eject: Starts ejecting a #GMount.
- * @eject_finish: Finishes an eject operation.
- * @remount: Starts remounting a #GMount.
- * @remount_finish: Finishes a remounting operation.
- * @guess_content_type: Starts guessing the type of the content of a #GMount. See g_mount_guess_content_type() for more information on content type guessing. This operation was added in 2.18.
- * @guess_content_type_finish: Finishes a contenet type guessing operation. Added in 2.18.
- * @guess_content_type_sync: Synchronous variant of @guess_content_type. Added in 2.18
- * @unmount_with_operation: Starts unmounting a #GMount using a #GMountOperation. Since 2.22.
- * @unmount_with_operation_finish: Finishes an unmounting operation using a #GMountOperation. Since 2.22.
- * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22.
- * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
- * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24.
- * @get_sort_key: Gets a key used for sorting #GMount instance or %NULL if no such key exists. Since 2.32.
+ * The file handle that the stream writes to.
*
- * Interface for implementing operations for mounts.
+ * Since: 2.26
*/
/**
- * GMountMountFlags:
- * @G_MOUNT_MOUNT_NONE: No flags set.
+ * GZlibCompressor:
*
- * Flags used when mounting a mount.
+ * Zlib decompression
*/
/**
- * GMountOperation:
+ * GZlibCompressor:file-info:
+ *
+ * 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 GZIP header.
*
- * Class for providing authentication methods for mounting operations,
- * such as mounting a file locally, or authenticating with a server.
+ * Since: 2.26
*/
/**
- * GMountOperation::aborted:
- *
- * Emitted by the backend when e.g. a device becomes unavailable
- * while a mount operation is in progress.
- *
- * Implementations of GMountOperation should handle this signal
- * by dismissing open password dialogs.
+ * GZlibDecompressor:
*
- * Since: 2.20
+ * Zlib decompression
*/
/**
- * GMountOperation::ask-password:
- * @op: a #GMountOperation requesting a password.
- * @message: string containing a message to display to the user.
- * @default_user: string containing the default user name.
- * @default_domain: string containing the default domain.
- * @flags: a set of #GAskPasswordFlags.
+ * GZlibDecompressor:file-info:
*
- * Emitted when a mount operation asks the user for a password.
+ * A #GFileInfo containing the information found in the GZIP header
+ * of the data stream processed, or %NULL if the header was not yet
+ * fully processed, is not present at all, or the compressor's
+ * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
*
- * 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.26
*/
/**
- * GMountOperation::ask-question:
- * @op: a #GMountOperation asking a question.
- * @message: string containing a message to display to the user.
- * @choices: an array of strings for each possible choice.
- *
- * Emitted when asking the user a question and gives a list of
- * choices for the user to choose from.
+ * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
*
- * 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.
+ * The purpose used to verify the client certificate in a TLS connection.
+ * Used by TLS servers.
*/
/**
- * GMountOperation::reply:
- * @op: a #GMountOperation.
- * @result: a #GMountOperationResult indicating how the request was handled
+ * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
*
- * Emitted when the user has replied to the mount operation.
+ * The purpose used to verify the server certificate in a TLS connection. This
+ * is the most common purpose in use. Used by TLS clients.
*/
/**
- * GMountOperation::show-processes:
- * @op: a #GMountOperation.
- * @message: string containing a message to display to the user.
- * @processes: 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
- * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
- *
- * Note that this signal may be emitted several times to update the
- * list of blocking processes as processes close files. The
- * application should only respond with g_mount_operation_reply() to
- * the latest signal (setting #GMountOperation:choice to the choice
- * the user made).
+ * G_TYPE_SETTINGS_SCHEMA:
*
- * 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.
+ * A boxed #GType corresponding to #GSettingsSchema.
*
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * GMountOperation:anonymous:
+ * G_TYPE_SETTINGS_SCHEMA_SOURCE:
*
- * Whether to use an anonymous user when authenticating.
- */
-
-
-/**
- * GMountOperation:choice:
+ * A boxed #GType corresponding to #GSettingsSchemaSource.
*
- * The index of the user's choice when a question is asked during the
- * mount operation. See the #GMountOperation::ask-question signal.
+ * Since: 2.32
*/
/**
- * GMountOperation:domain:
+ * SECTION:_GFreedesktopDBus
+ * @title: _GFreedesktopDBus
+ * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface
*
- * The domain to use for the mount operation.
+ * This section contains code for working with the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface in C.
*/
/**
- * GMountOperation:password:
+ * SECTION:extensionpoints
+ * @short_description: Extension Points
+ * @include: gio.h
+ * @see_also: [Extending GIO][extending-gio]
*
- * The password that is used for authentication when carrying out
- * the mount operation.
+ * #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 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.
+ *
+ * A module can implement an extension point by specifying the #GType
+ * that implements the functionality. Additionally, each implementation
+ * 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
+ * ep = g_io_extension_point_register ("my-extension-point");
+ * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
+ * ]|
+ *
+ * |[<!-- 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 (),
+ * "my-example",
+ * 10);
+ * ]|
+ *
+ * It is up to the code that registered the extension point how
+ * it uses the implementations that have been associated with it.
+ * Depending on the use case, it may use all implementations, or
+ * only the one with the highest priority, or pick a specific
+ * one by name.
+ *
+ * To avoid opening all modules just to find out what extension
+ * points they implement, GIO makes use of a caching mechanism,
+ * see [gio-querymodules][gio-querymodules].
+ * You are expected to run this command after installing a
+ * GIO module.
+ *
+ * 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
+ * `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.
*/
/**
- * GMountOperation:password-save:
+ * SECTION:gaction
+ * @title: GAction
+ * @short_description: An action interface
+ * @include: gio/gio.h
*
- * Determines if and how the password information should be saved.
- */
-
-
-/**
- * GMountOperation:username:
+ * #GAction represents a single named action.
*
- * The user name that is used for authentication when carrying out
- * the mount operation.
- */
-
-
-/**
- * GMountOperationResult:
- * @G_MOUNT_OPERATION_HANDLED: The request was fulfilled and the user specified data is now available
- * @G_MOUNT_OPERATION_ABORTED: The user requested the mount operation to be aborted
- * @G_MOUNT_OPERATION_UNHANDLED: The request was unhandled (i.e. not implemented)
+ * The main interface to an action is that it can be activated with
+ * g_action_activate(). This results in the 'activate' signal being
+ * emitted. An activation has a #GVariant parameter (which may be
+ * %NULL). The correct type for the parameter is determined by a static
+ * parameter type (which is given at construction time).
*
- * #GMountOperationResult is returned as a result when a request for
- * information is send by the mounting operation.
- */
-
-
-/**
- * GMountUnmountFlags:
- * @G_MOUNT_UNMOUNT_NONE: No flags set.
- * @G_MOUNT_UNMOUNT_FORCE: Unmount even if there are outstanding file operations on the mount.
+ * An action may optionally have a state, in which case the state may be
+ * set with g_action_change_state(). This call takes a #GVariant. The
+ * correct type for the state is determined by a static state type
+ * (which is given at construction time).
*
- * Flags used when an unmounting a mount.
- */
-
-
-/**
- * GNetworkAddress:
+ * The state may have a hint associated with it, specifying its valid
+ * range.
*
- * A #GSocketConnectable for resolving a hostname and connecting to
- * that host.
- */
-
-
-/**
- * GNetworkMonitor:
+ * #GAction is merely the interface to the concept of an action, as
+ * described above. Various implementations of actions exist, including
+ * #GSimpleAction.
*
- * #GNetworkMonitor monitors the status of network connections and
- * indicates when a possibly-user-visible change has occurred.
+ * In all cases, the implementing class is responsible for storing the
+ * name of the action, the parameter type, the enabled state, the
+ * optional state type and the state and emitting the appropriate
+ * signals when these change. The implementor responsible for filtering
+ * calls to g_action_activate() and g_action_change_state() for type
+ * safety and for the state being enabled.
*
- * Since: 2.32
+ * Probably the only useful thing to do with a #GAction is to put it
+ * inside of a #GSimpleActionGroup.
*/
/**
- * GNetworkMonitor::network-changed:
- * @monitor: a #GNetworkMonitor
- * @available: the current value of #GNetworkMonitor:network-available
- *
- * Emitted when the network configuration changes. If @available is
- * %TRUE, then some hosts may be reachable that were not reachable
- * before, while others that were reachable before may no longer be
- * reachable. If @available is %FALSE, then no remote hosts are
- * reachable.
+ * SECTION:gactiongroup
+ * @title: GActionGroup
+ * @short_description: A group of actions
+ * @include: gio/gio.h
+ * @see_also: #GAction
*
- * Since: 2.32
- */
-
-
-/**
- * GNetworkMonitor:network-available:
+ * #GActionGroup represents a group of actions. Actions can be used to
+ * expose functionality in a structured way, either from one part of a
+ * program to another, or to the outside world. Action groups are often
+ * used together with a #GMenuModel that provides additional
+ * representation data for displaying the actions to the user, e.g. in
+ * a menu.
*
- * Whether the network is considered available. That is, whether the
- * system has a default route for at least one of IPv4 or IPv6.
+ * The main way to interact with the actions in a GActionGroup is to
+ * activate them with g_action_group_activate_action(). Activating an
+ * action may require a #GVariant parameter. The required type of the
+ * parameter can be inquired with g_action_group_get_action_parameter_type().
+ * Actions may be disabled, see g_action_group_get_action_enabled().
+ * Activating a disabled action has no effect.
*
- * Real-world networks are of course much more complicated than
- * this; the machine may be connected to a wifi hotspot that
- * requires payment before allowing traffic through, or may be
- * 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
- * %FALSE, the application can reasonably expect that no remote
- * hosts at all are reachable, and should indicate this to the user
- * in its UI.)
+ * Actions may optionally have a state in the form of a #GVariant. The
+ * current state of an action can be inquired with
+ * g_action_group_get_action_state(). Activating a stateful action may
+ * change its state, but it is also possible to set the state by calling
+ * g_action_group_change_action_state().
*
- * See also #GNetworkMonitor::network-changed.
+ * As typical example, consider a text editing application which has an
+ * option to change the current font to 'bold'. A good way to represent
+ * this would be a stateful action, with a boolean state. Activating the
+ * action would toggle the state.
*
- * Since: 2.32
- */
-
-
-/**
- * GNetworkService:
+ * Each action in the group has a unique name (which is a string). All
+ * method calls, except g_action_group_list_actions() take the name of
+ * an action as an argument.
*
- * A #GSocketConnectable for resolving a SRV record and connecting to
- * that service.
- */
-
-
-/**
- * GNormalizeMode:
- * @G_NORMALIZE_DEFAULT: standardize differences that do not affect the text content, such as the above-mentioned accent representation
- * @G_NORMALIZE_NFD: another name for %G_NORMALIZE_DEFAULT
- * @G_NORMALIZE_DEFAULT_COMPOSE: like %G_NORMALIZE_DEFAULT, but with composed forms rather than a maximally decomposed form
- * @G_NORMALIZE_NFC: another name for %G_NORMALIZE_DEFAULT_COMPOSE
- * @G_NORMALIZE_ALL: beyond %G_NORMALIZE_DEFAULT also standardize the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same
- * @G_NORMALIZE_NFKD: another name for %G_NORMALIZE_ALL
- * @G_NORMALIZE_ALL_COMPOSE: like %G_NORMALIZE_ALL, but with composed forms rather than a maximally decomposed form
- * @G_NORMALIZE_NFKC: another name for %G_NORMALIZE_ALL_COMPOSE
+ * The #GActionGroup API is meant to be the 'public' API to the action
+ * group. The calls here are exactly the interaction that 'external
+ * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
+ * 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 set() call.
*
- * Defines how a Unicode string is transformed in a canonical
- * form, standardizing such issues as whether a character with
- * an accent is represented as a base character and combining
- * accent or as a single precomposed character. Unicode strings
- * should generally be normalized before comparing them.
- */
-
-
-/**
- * GObject:
+ * Signals are emitted on the action group in response to state changes
+ * on individual actions.
*
- * All the fields in the <structname>GObject</structname> structure are private
- * to the #GObject implementation and should never be accessed directly.
+ * Implementations of #GActionGroup should provide implementations for
+ * the virtual functions g_action_group_list_actions() and
+ * g_action_group_query_action(). The other virtual functions should
+ * not be implemented - their "wrappers" are actually implemented with
+ * calls to g_action_group_query_action().
*/
/**
- * GObjectClass:
- * @g_type_class: the parent class
- * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons.
- * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system.
- * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
- * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class.
- * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class.
- * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed.
- * @notify: the class closure for the notify signal
- * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation.
- *
- * The class structure for the <structname>GObject</structname> type.
- *
- * <example>
- * <title>Implementing singletons using a constructor</title>
- * <programlisting>
- * static MySingleton *the_singleton = NULL;
- *
- * static GObject*
- * my_singleton_constructor (GType type,
- * guint n_construct_params,
- * GObjectConstructParam *construct_params)
- * {
- * GObject *object;
+ * SECTION:gactiongroupexporter
+ * @title: GActionGroup exporter
+ * @include: gio/gio.h
+ * @short_description: Export GActionGroups on D-Bus
+ * @see_also: #GActionGroup, #GDBusActionGroup
*
- * if (!the_singleton)
- * {
- * object = G_OBJECT_CLASS (parent_class)->constructor (type,
- * n_construct_params,
- * construct_params);
- * the_singleton = MY_SINGLETON (object);
- * }
- * else
- * object = g_object_ref (G_OBJECT (the_singleton));
+ * These functions support exporting a #GActionGroup on D-Bus.
+ * The D-Bus interface that is used is a private implementation
+ * detail.
*
- * return object;
- * }
- * </programlisting></example>
+ * To access an exported #GActionGroup remotely, use
+ * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
*/
/**
- * GObjectConstructParam:
- * @pspec: the #GParamSpec of the construct parameter
- * @value: the value to set the parameter to
+ * SECTION:gactionmap
+ * @title: GActionMap
+ * @include: gio/gio.h
+ * @short_description: Interface for action containers
*
- * The <structname>GObjectConstructParam</structname> struct is an auxiliary
- * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
- * a #GObjectClass.
- */
-
-
-/**
- * GObjectFinalizeFunc:
- * @object: the #GObject being finalized
+ * The GActionMap interface is implemented by #GActionGroup
+ * implementations that operate by containing a number of
+ * named #GAction instances, such as #GSimpleActionGroup.
*
- * The type of the @finalize function of #GObjectClass.
- */
-
-
-/**
- * GObjectGetPropertyFunc:
- * @object: a #GObject
- * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
- * @value: a #GValue to return the property value in
- * @pspec: the #GParamSpec describing the property
+ * One useful application of this interface is to map the
+ * names of actions from various action groups to unique,
+ * prefixed names (e.g. by prepending "app." or "win.").
+ * This is the motivation for the 'Map' part of the interface
+ * name.
*
- * The type of the @get_property function of #GObjectClass.
+ * Since: 2.32
*/
/**
- * GObjectSetPropertyFunc:
- * @object: a #GObject
- * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
- * @value: the new value for the property
- * @pspec: the #GParamSpec describing the property
+ * SECTION:gappinfo
+ * @short_description: Application information and launch contexts
+ * @include: gio/gio.h
+ * @see_also: #GAppInfoMonitor
*
- * The type of the @set_property function of #GObjectClass.
- */
-
-
-/**
- * GOptionArg:
- * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
- * @G_OPTION_ARG_STRING: The option takes a string argument.
- * @G_OPTION_ARG_INT: The option takes an integer argument.
- * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument.
- * @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
- * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings.
- * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings.
- * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12
- * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12
+ * #GAppInfo and #GAppLaunchContext are used for describing and launching
+ * applications installed on the system.
*
- * The #GOptionArg enum values determine which type of extra argument the
- * options expect to find. If an option expects an extra argument, it
- * can be specified in several ways; with a short option:
- * <option>-x arg</option>, with a long option: <option>--name arg</option>
- * or combined in a single argument: <option>--name=arg</option>.
- */
-
-
-/**
- * GOptionArgFunc:
- * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name.
- * @value: The value to be parsed.
- * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
- * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks.
+ * 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 `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.
*
- * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
- * options.
+ * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
+ * back to the GIO URI in the #GFile constructors (since gvfs
+ * implements the #GVfs extension point). As such, if the application
+ * needs to examine the URI, it needs to use g_file_get_uri() or
+ * similar on #GFile. In other words, an application cannot assume
+ * that the URI passed to e.g. g_file_new_for_commandline_arg() is
+ * equal to the result of g_file_get_uri(). The following snippet
+ * illustrates this:
*
- * occurred, in which case @error should be set with g_set_error()
+ * |[
+ * GFile *f;
+ * char *uri;
*
- * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
- */
-
-
-/**
- * GOptionContext:
+ * file = g_file_new_for_commandline_arg (uri_from_commandline);
*
- * A <structname>GOptionContext</structname> struct defines which options
- * are accepted by the commandline option parser. The struct has only private
- * fields and should not be directly accessed.
- */
-
-
-/**
- * GOptionEntry:
- * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
- * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name.
- * @flags: Flags from #GOptionFlags.
- * @arg: The type of the option, as a #GOptionArg.
- * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().
- * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain().
- * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain().
+ * uri = g_file_get_uri (file);
+ * strcmp (uri, uri_from_commandline) == 0;
+ * g_free (uri);
*
- * A <structname>GOptionEntry</structname> defines a single option.
- * To have an effect, they must be added to a #GOptionGroup with
- * g_option_context_add_main_entries() or g_option_group_add_entries().
- */
-
-
-/**
- * GOptionError:
- * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options().
- * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
- * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
+ * if (g_file_has_uri_scheme (file, "cdda"))
+ * {
+ * // do something special with uri
+ * }
+ * g_object_unref (file);
+ * ]|
*
- * Error codes returned by option parsing.
+ * 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.
*/
/**
- * GOptionErrorFunc:
- * @context: The active #GOptionContext
- * @group: The group to which the function belongs
- * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
- * @error: The #GError containing details about the parse error
+ * SECTION:gappinfomonitor
+ * @short_description: Monitor application information for changes
*
- * The type of function to be used as callback when a parse error occurs.
- */
-
-
-/**
- * GOptionFlags:
- * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output.
- * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group.
- * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed.
- * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8
- * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8
- * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
- * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8.
+ * #GAppInfoMonitor is a very simple object used for monitoring the app
+ * info database for changes (ie: newly installed or removed
+ * applications).
*
- * Flags which modify individual options.
- */
-
-
-/**
- * GOptionGroup:
+ * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
+ * to the "changed" signal.
*
- * A <structname>GOptionGroup</structname> struct defines the options in a single
- * group. The struct has only private fields and should not be directly accessed.
+ * 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.
*
- * All options in a group share the same translation function. Libraries which
- * need to parse commandline options are expected to provide a function for
- * getting a <structname>GOptionGroup</structname> holding their options, which
- * the application can then add to its #GOptionContext.
+ * Since: 2.40
*/
/**
- * GOptionParseFunc:
- * @context: The active #GOptionContext
- * @group: The group to which the function belongs
- * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
- * @error: A return location for error details
- *
- * The type of function that can be called before and after parsing.
- *
- * occurred, in which case @error should be set with g_set_error()
+ * SECTION:gapplication
+ * @title: GApplication
+ * @short_description: Core application class
+ * @include: gio/gio.h
*
- * Returns: %TRUE if the function completed successfully, %FALSE if an error
- */
-
-
-/**
- * GOutputStream:
+ * 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.
*
- * Base class for writing output.
+ * GApplication provides convenient life cycle management by maintaining
+ * 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
+ * concept is platform-dependent, but corresponds roughly to a graphical
+ * 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 "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
+ * [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().
*
- * All classes derived from GOutputStream should implement synchronous
- * writing, splicing, flushing and closing streams, but may implement
- * asynchronous versions.
- */
-
-
-/**
- * GOutputStreamSpliceFlags:
- * @G_OUTPUT_STREAM_SPLICE_NONE: Do not close either stream.
- * @G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE: Close the source stream after the splice.
- * @G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET: Close the target stream after the splice.
+ * On Linux, the application identifier is claimed as a well-known bus name
+ * on the user's session bus. This means that the uniqueness of your
+ * application is scoped to the current session. It also means that your
+ * application may provide additional services (through registration of other
+ * object paths) at that bus name. The registration of these object paths
+ * should be done with the shared GDBus session bus. Note that due to the
+ * internal architecture of GDBus, method calls can be dispatched at any time
+ * (even if a main loop is not running). For this reason, you must ensure that
+ * any object paths that you wish to register are registered before #GApplication
+ * attempts to acquire the bus name of your application (which happens in
+ * g_application_register()). Unfortunately, this means that you cannot use
+ * g_application_get_is_remote() to decide if you want to register object paths.
*
- * GOutputStreamSpliceFlags determine how streams should be spliced.
- */
-
-
-/**
- * GOutputVector:
- * @buffer: Pointer to a buffer of data to read.
- * @size: the size of @buffer.
+ * GApplication also implements the #GActionGroup and #GActionMap
+ * interfaces and lets you easily export actions by adding them with
+ * g_action_map_add_action(). When invoking an action by calling
+ * g_action_group_activate_action() on the application, it is always
+ * invoked in the primary instance. The actions are also exported on
+ * the session bus, and GIO provides the #GDBusActionGroup wrapper to
+ * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
+ * for remote access to exported #GMenuModels.
*
- * Structure used for scatter/gather data output.
- * You generally pass in an array of #GOutputVector<!-- -->s
- * and the operation will use all the buffers as if they were
- * one buffer.
+ * There is a number of different entry points into a GApplication:
*
- * Since: 2.22
- */
-
-
-/**
- * GParamFlags:
- * @G_PARAM_READABLE: the parameter is readable
- * @G_PARAM_WRITABLE: the parameter is writable
- * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
- * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
- * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required
- * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
- * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8
- * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
- * @G_PARAM_PRIVATE: internal
- * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26
+ * - via 'Activate' (i.e. just starting the application)
*
- * Through the #GParamFlags flag values, certain aspects of parameters
- * can be configured.
- */
-
-
-/**
- * GParamSpec:
- * @g_type_instance: private #GTypeInstance portion
- * @name: name of this parameter: always an interned string
- * @flags: #GParamFlags flags for this parameter
- * @value_type: the #GValue type for this parameter
- * @owner_type: #GType type that uses (introduces) this parameter
+ * - via 'Open' (i.e. opening some files)
*
- * All other fields of the <structname>GParamSpec</structname> struct are private and
- * should not be used directly.
- */
-
-
-/**
- * GParamSpecBoolean:
- * @parent_instance: private #GParamSpec portion
- * @default_value: default value for the property specified
+ * - by handling a command-line
*
- * A #GParamSpec derived structure that contains the meta data for boolean properties.
- */
-
-
-/**
- * GParamSpecBoxed:
- * @parent_instance: private #GParamSpec portion
+ * - via activating an action
*
- * A #GParamSpec derived structure that contains the meta data for boxed properties.
- */
-
-
-/**
- * GParamSpecChar:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * The #GApplication::startup signal lets you handle the application
+ * initialization for all of these in a single place.
*
- * A #GParamSpec derived structure that contains the meta data for character properties.
- */
-
-
-/**
- * GParamSpecClass:
- * @g_type_class: the parent class
- * @value_type: the #GValue type for this parameter
- * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class.
- * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default().
- * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_validate().
- * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp().
+ * 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().
*
- * The class structure for the <structname>GParamSpec</structname> type.
- * Normally, <structname>GParamSpec</structname> classes are filled by
- * g_param_type_register_static().
- */
-
-
-/**
- * GParamSpecDouble:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
- * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90.
+ * As the name indicates, the platform data may vary depending on the
+ * operating system, but it always includes the current directory (key
+ * "cwd"), and optionally the environment (ie the set of environment
+ * variables and their values) of the calling process (key "environ").
+ * The environment is only added to the platform data if the
+ * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
+ * can add their own platform data by overriding the @add_platform_data
+ * virtual function. For instance, #GtkApplication adds startup notification
+ * data in this way.
*
- * A #GParamSpec derived structure that contains the meta data for double properties.
- */
-
-
-/**
- * GParamSpecEnum:
- * @parent_instance: private #GParamSpec portion
- * @enum_class: the #GEnumClass for the enum
- * @default_value: default value for the property specified
+ * To parse commandline arguments you may handle the
+ * #GApplication::command-line signal or override the local_command_line()
+ * vfunc, to parse them in either the primary instance or the local instance,
+ * respectively.
*
- * A #GParamSpec derived structure that contains the meta data for enum
- * properties.
- */
-
-
-/**
- * GParamSpecFlags:
- * @parent_instance: private #GParamSpec portion
- * @flags_class: the #GFlagsClass for the flags
- * @default_value: default value for the property specified
+ * 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).
*
- * A #GParamSpec derived structure that contains the meta data for flags
- * properties.
- */
-
-
-/**
- * GParamSpecFloat:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
- * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30.
+ * 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).
*
- * A #GParamSpec derived structure that contains the meta data for float properties.
+ * 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).
*/
/**
- * GParamSpecGType:
- * @parent_instance: private #GParamSpec portion
- * @is_a_type: a #GType whose subtypes can occur as values
+ * SECTION:gapplicationcommandline
+ * @title: GApplicationCommandLine
+ * @short_description: A command-line invocation of an application
+ * @include: gio/gio.h
+ * @see_also: #GApplication
*
- * A #GParamSpec derived structure that contains the meta data for #GType properties.
+ * #GApplicationCommandLine represents a command-line invocation of
+ * an application. It is created by #GApplication and emitted
+ * in the #GApplication::command-line signal and virtual function.
*
- * Since: 2.10
- */
-
-
-/**
- * GParamSpecInt:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * The class contains the list of arguments that the program was invoked
+ * with. It is also possible to query if the commandline invocation was
+ * local (ie: the current process is running in direct response to the
+ * invocation) or remote (ie: some other process forwarded the
+ * commandline to this process).
*
- * A #GParamSpec derived structure that contains the meta data for integer properties.
- */
-
-
-/**
- * GParamSpecInt64:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * 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
+ * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
+ * for an example.
*
- * A #GParamSpec derived structure that contains the meta data for 64bit integer properties.
- */
-
-
-/**
- * GParamSpecLong:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * The exit status of the originally-invoked process may be set and
+ * messages can be printed to stdout or stderr of that process. The
+ * lifecycle of the originally-invoked process is tied to the lifecycle
+ * of this object (ie: the process exits when the last reference is
+ * dropped).
*
- * A #GParamSpec derived structure that contains the meta data for long integer properties.
- */
-
-
-/**
- * GParamSpecObject:
- * @parent_instance: private #GParamSpec portion
+ * The main use for #GApplicationCommandLine (and the
+ * #GApplication::command-line signal) is 'Emacs server' like use cases:
+ * 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.
*
- * A #GParamSpec derived structure that contains the meta data for object properties.
- */
-
-
-/**
- * GParamSpecOverride:
+ * 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;
*
- * This is a type of #GParamSpec type that simply redirects operations to
- * another paramspec. All operations other than getting or
- * setting the value are redirected, including accessing the nick and
- * blurb, validating a value, and so forth. See
- * g_param_spec_get_redirect_target() for retrieving the overidden
- * property. #GParamSpecOverride is used in implementing
- * g_object_class_override_property(), and will not be directly useful
- * unless you are implementing a new base type similar to GObject.
+ * argv = g_application_command_line_get_arguments (cmdline, &argc);
*
- * Since: 2.4
- */
-
-
-/**
- * GParamSpecParam:
- * @parent_instance: private #GParamSpec portion
+ * g_application_command_line_print (cmdline,
+ * "This text is written back\n"
+ * "to stdout of the caller\n");
*
- * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM
- * properties.
- */
-
-
-/**
- * GParamSpecPointer:
- * @parent_instance: private #GParamSpec portion
+ * for (i = 0; i < argc; i++)
+ * g_print ("argument %d: %s\n", i, argv[i]);
*
- * A #GParamSpec derived structure that contains the meta data for pointer properties.
- */
-
-
-/**
- * GParamSpecString:
- * @parent_instance: private #GParamSpec portion
- * @default_value: default value for the property specified
- * @cset_first: a string containing the allowed values for the first byte
- * @cset_nth: a string containing the allowed values for the subsequent bytes
- * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth.
- * @null_fold_if_empty: replace empty string by %NULL
- * @ensure_non_null: replace %NULL strings by an empty string
+ * g_strfreev (argv);
*
- * A #GParamSpec derived structure that contains the meta data for string
- * properties.
- */
-
-
-/**
- * GParamSpecTypeInfo:
- * @instance_size: Size of the instance (object) structure.
- * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
- * @instance_init: Location of the instance initialization function (optional).
- * @value_type: The #GType of values conforming to this #GParamSpec
- * @finalize: The instance finalization function (optional).
- * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default().
- * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_validate().
- * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp().
+ * 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)
*
- * This structure is used to provide the type system with the information
- * required to initialize and destruct (finalize) a parameter's class and
- * instances thereof.
- * The initialized structure is passed to the g_param_type_register_static()
- * The type system will perform a deep copy of this structure, so its memory
- * does not need to be persistent across invocation of
- * g_param_type_register_static().
- */
-
-
-/**
- * GParamSpecUChar:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * 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;
+ * }
*
- * A #GParamSpec derived structure that contains the meta data for unsigned character properties.
- */
-
-
-/**
- * GParamSpecUInt:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * static void
+ * test_application_class_init (TestApplicationClass *class)
+ * {
+ * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
*
- * A #GParamSpec derived structure that contains the meta data for unsigned integer properties.
- */
-
-
-/**
- * GParamSpecUInt64:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * ...
+ * }
+ * ]|
+ * 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.
*
- * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.
- */
-
-
-/**
- * GParamSpecULong:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * The complete example can be found here:
+ * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
*
- * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.
- */
-
-
-/**
- * GParamSpecUnichar:
- * @parent_instance: private #GParamSpec portion
- * @default_value: default value for the property specified
+ * 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;
*
- * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.
- */
-
-
-/**
- * GParamSpecValueArray:
- * @parent_instance: private #GParamSpec portion
- * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL
- * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements
+ * // do the heavy lifting in an idle
*
- * A #GParamSpec derived structure that contains the meta data for #GValueArray properties.
- */
-
-
-/**
- * GParamSpecVariant:
- * @parent_instance: private #GParamSpec portion
- * @type: a #GVariantType, or %NULL
- * @default_value: a #GVariant, or %NULL
+ * g_application_command_line_set_exit_status (cmdline, 0);
+ * g_object_unref (cmdline); // this releases the application
*
- * A #GParamSpec derived structure that contains the meta data for #GVariant properties.
+ * return G_SOURCE_REMOVE;
+ * }
*
- * Since: 2.26
- */
-
-
-/**
- * GParameter:
- * @name: the parameter name
- * @value: the parameter value
+ * static int
+ * command_line (GApplication *application,
+ * GApplicationCommandLine *cmdline)
+ * {
+ * // keep the application running until we are done with this commandline
+ * g_application_hold (application);
*
- * The <structname>GParameter</structname> struct is an auxiliary structure used
- * to hand parameter name/value pairs to g_object_newv().
- */
-
-
-/**
- * GPasswordSave:
- * @G_PASSWORD_SAVE_NEVER: never save a password.
- * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session.
- * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently.
+ * g_object_set_data_full (G_OBJECT (cmdline),
+ * "application", application,
+ * (GDestroyNotify)g_application_release);
*
- * #GPasswordSave is used to indicate the lifespan of a saved password.
+ * g_object_ref (cmdline);
+ * g_idle_add (my_cmdline_handler, cmdline);
*
- * #Gvfs stores passwords in the Gnome keyring when this flag allows it
- * to, and later retrieves it again from there.
- */
-
-
-/**
- * GPermission:
+ * 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.
*
- * #GPermission is an opaque data structure and can only be accessed
- * using the following functions.
+ * The complete example can be found here:
+ * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
*/
/**
- * GPermission:allowed:
+ * SECTION:gasyncinitable
+ * @short_description: Asynchronously failable object initialization interface
+ * @include: gio/gio.h
+ * @see_also: #GInitable
*
- * %TRUE if the caller currently has permission to perform the action that
- * @permission represents the permission to perform.
- */
-
-
-/**
- * GPermission:can-acquire:
+ * This is the asynchronous version of #GInitable; it behaves the same
+ * in all ways except that initialization is asynchronous. For more details
+ * see the descriptions on #GInitable.
*
- * %TRUE if it is generally possible to acquire the permission by calling
- * g_permission_acquire().
- */
-
-
-/**
- * GPermission:can-release:
+ * A class may implement both the #GInitable and #GAsyncInitable interfaces.
*
- * %TRUE if it is generally possible to release the permission by calling
- * g_permission_release().
- */
-
-
-/**
- * GPid:
+ * Users of objects implementing this are not intended to use the interface
+ * method directly; instead it will be used automatically in various ways.
+ * For C applications you generally just call g_async_initable_new_async()
+ * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
+ * g_async_initable_init_async() under the cover, calling back with %NULL and
+ * a set %GError on failure.
*
- * A type which is used to hold a process identification.
+ * A typical implementation might look something like this:
*
- * On UNIX, processes are identified by a process id (an integer),
- * while Windows uses process handles (which are pointers).
- */
-
-
-/**
- * GPollFD:
- * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32)
- * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR.
- * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
+ * |[<!-- language="C" -->
+ * enum {
+ * NOT_INITIALIZED,
+ * INITIALIZING,
+ * INITIALIZED
+ * };
*
- * Represents a file descriptor, which events to poll for, and which events
- * occurred.
- */
-
-
-/**
- * GPollFunc:
- * @ufds: an array of #GPollFD elements
- * @nfsd: the number of elements in @ufds
- * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout.
+ * static void
+ * _foo_ready_cb (Foo *self)
+ * {
+ * GList *l;
*
- * Specifies the type of function passed to g_main_context_set_poll_func().
- * The semantics of the function should match those of the poll() system call.
+ * self->priv->state = INITIALIZED;
*
- * reported, or -1 if an error occurred.
+ * for (l = self->priv->init_results; l != NULL; l = l->next)
+ * {
+ * GTask *task = l->data;
*
- * Returns: the number of #GPollFD elements which have events or errors
- */
-
-
-/**
- * GPollableInputStream:
+ * if (self->priv->success)
+ * g_task_return_boolean (task, TRUE);
+ * else
+ * g_task_return_new_error (task, ...);
+ * g_object_unref (task);
+ * }
*
- * An interface for a #GInputStream that can be polled for readability.
- *
- * Since: 2.28
- */
-
-
-/**
- * GPollableInputStreamInterface:
- * @g_iface: The parent interface.
- * @can_poll: Checks if the #GPollableInputStream instance is actually pollable
- * @is_readable: Checks if the stream is readable
- * @create_source: Creates a #GSource to poll the stream
- * @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK
- *
- * The interface for pollable input streams.
- *
- * The default implementation of @can_poll always returns %TRUE.
- *
- * The default implementation of @read_nonblocking calls
- * g_pollable_input_stream_is_readable(), and then calls
- * g_input_stream_read() if it returns %TRUE. This means you only need
- * to override it if it is possible that your @is_readable
- * implementation may return %TRUE when the stream is not actually
- * readable.
- *
- * Since: 2.28
- */
-
-
-/**
- * GPollableOutputStream:
- *
- * An interface for a #GOutputStream that can be polled for readability.
- *
- * Since: 2.28
- */
-
-
-/**
- * GPollableOutputStreamInterface:
- * @g_iface: The parent interface.
- * @can_poll: Checks if the #GPollableOutputStream instance is actually pollable
- * @is_writable: Checks if the stream is writable
- * @create_source: Creates a #GSource to poll the stream
- * @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK
- *
- * The interface for pollable output streams.
- *
- * The default implementation of @can_poll always returns %TRUE.
- *
- * The default implementation of @write_nonblocking calls
- * g_pollable_output_stream_is_writable(), and then calls
- * g_output_stream_write() if it returns %TRUE. This means you only
- * need to override it if it is possible that your @is_writable
- * implementation may return %TRUE when the stream is not actually
- * writable.
- *
- * Since: 2.28
- */
-
-
-/**
- * GPollableSourceFunc:
- * @pollable_stream: the #GPollableInputStream or #GPollableOutputStream
- * @user_data: data passed in by the user.
- *
- * This is the function type of the callback used for the #GSource
- * returned by g_pollable_input_stream_create_source() and
- * g_pollable_output_stream_create_source().
- *
- * Returns: it should return %FALSE if the source should be removed.
- * Since: 2.28
- */
-
-
-/**
- * GPrintFunc:
- * @string: the message to output
- *
- * Specifies the type of the print handler functions.
- * These are called with the complete formatted string to output.
- */
-
-
-/**
- * GProxy:
- *
- * Interface that handles proxy connection and payload.
- *
- * Since: 2.26
- */
-
-
-/**
- * GProxyAddress:
- *
- * A #GInetSocketAddress representing a connection via a proxy server
- *
- * Since: 2.26
- */
-
-
-/**
- * GProxyAddressEnumerator:
- *
- * A subclass of #GSocketAddressEnumerator that takes another address
- * enumerator and wraps its results in #GProxyAddress<!-- -->es as
- * directed by the default #GProxyResolver.
- */
-
-
-/**
- * GProxyInterface:
- * @g_iface: The parent interface.
- * @connect: Connect to proxy server and wrap (if required) the #connection to handle payload.
- * @connect_async: Same has connect() but asynchronous.
- * @connect_finish: Returns the result of connect_async()
- *
- * Provides an interface for handling proxy connection and payload.
- *
- * Since: 2.26
- */
-
-
-/**
- * GProxyResolver:
- *
- * Interface that can be used to resolve proxy address.
- */
-
-
-/**
- * GQueue:
- * @head: a pointer to the first element of the queue
- * @tail: a pointer to the last element of the queue
- * @length: the number of elements in the queue
- *
- * Contains the public fields of a
- * <link linkend="glib-Double-ended-Queues">Queue</link>.
- */
-
-
-/**
- * GReallocFunc:
- * @data: memory block to reallocate
- * @size: size to reallocate @data to
- *
- * Changes the size of the memory block pointed to by @data to
- * @size bytes.
- *
- * The function should have the same semantics as realloc().
- *
- * Returns: a pointer to the reallocated memory
- */
-
-
-/**
- * GRegex:
- *
- * A GRegex is the "compiled" form of a regular expression pattern. This
- * structure is opaque and its fields cannot be accessed directly.
- *
- * Since: 2.14
- */
-
-
-/**
- * GRegexCompileFlags:
- * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting.
- * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting.
- * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting.
- * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting.
- * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
- * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
- * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
- * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
- * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
- * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
- * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'.
- * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'.
- *
- * Flags specifying compile-time options.
- *
- * Since: 2.14
- */
-
-
-/**
- * GRegexError:
- * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed.
- * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed.
- * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string.
- * @G_REGEX_ERROR_MATCH: The match process failed.
- * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16
- * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16
- * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16
- * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16
- * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16
- * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16
- * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16
- * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16
- * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16
- * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16
- * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16
- * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16
- * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16
- * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16
- * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16
- * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16
- * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16
- * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16
- * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16
- * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16
- * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16
- * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16
- * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16
- * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16
- * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16
- * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16
- * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16
- * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16
- * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16
- * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16
- * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16
- * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16
- * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16
- * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16
- * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16
- * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16
- * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16
- * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16
- *
- * Error codes returned by regular expressions functions.
- *
- * Since: 2.14
- */
-
-
-/**
- * GRegexEvalCallback:
- * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string.
- * @result: a #GString containing the new string
- * @user_data: user data passed to g_regex_replace_eval()
- *
- * Specifies the type of the function passed to g_regex_replace_eval().
- * It is called for each occurrence of the pattern in the string passed
- * to g_regex_replace_eval(), and it should append the replacement to
- * @result.
- *
- * Returns: %FALSE to continue the replacement process, %TRUE to stop it
- * Since: 2.14
- */
-
-
-/**
- * GRegexMatchFlags:
- * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
- * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A".
- * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z".
- * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b".
- * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match().
- * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator.
- * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator.
- * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator.
- * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized.
- *
- * Flags specifying match-time options.
- *
- * Since: 2.14
- */
-
-
-/**
- * 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.
- */
-
-
-/**
- * GResolverError:
- * @G_RESOLVER_ERROR_NOT_FOUND: the requested name/address/service was not found
- * @G_RESOLVER_ERROR_TEMPORARY_FAILURE: the requested information could not be looked up due to a network error or similar problem
- * @G_RESOLVER_ERROR_INTERNAL: unknown error
- *
- * An error code used with %G_RESOLVER_ERROR in a #GError returned
- * from a #GResolver routine.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSeekable:
- *
- * Seek object for streaming operations.
- */
-
-
-/**
- * GSeekableIface:
- * @g_iface: The parent interface.
- * @tell: Tells the current location within a stream.
- * @can_seek: Checks if seeking is supported by the stream.
- * @seek: Seeks to a location within a stream.
- * @can_truncate: Chekcs if truncation is suppored by the stream.
- * @truncate_fn: Truncates a stream.
- *
- * Provides an interface for implementing seekable functionality on I/O Streams.
- */
-
-
-/**
- * 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
- *
- * 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.
- *
- * event. FALSE to propagate the event further.
- *
- * Returns: %TRUE to stop other handlers from being invoked for the
- */
-
-
-/**
- * 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
- * value.
- *
- * This signal supports detailed connections. You can connect to the
- * detailed signal "changed::x" in order to only receive callbacks
- * when key "x" changes.
- */
-
-
-/**
- * GSettings::writable-change-event:
- * @settings: the object on which the signal was emitted
- * @key: the quark of the key, or 0
- *
- * The "writable-change-event" signal is emitted once per writability
- * change event that affects this settings object. You should connect
- * to this signal if you are interested in viewing groups of changes
- * before they are split out into multiple emissions of the
- * "writable-changed" signal. For most use cases it is more
- * appropriate to use the "writable-changed" signal.
- *
- * In the event that the writability change applies only to a single
- * key, @key will be set to the #GQuark for that key. In the event
- * that the writability change affects the entire settings object,
- * @key will be 0.
- *
- * The default handler for this signal invokes the "writable-changed"
- * and "changed" signals for each affected key. This is done because
- * changes in writability might also imply changes in value (if for
- * example, a new mandatory setting is introduced). If any other
- * connected handler returns %TRUE then this default functionality
- * will be suppressed.
- *
- * event. FALSE to propagate the event further.
- *
- * Returns: %TRUE to stop other handlers from being invoked for the
- */
-
-
-/**
- * GSettings::writable-changed:
- * @settings: the object on which the signal was emitted
- * @key: the key
- *
- * The "writable-changed" signal is emitted when the writability of a
- * key has potentially changed. You should call
- * g_settings_is_writable() in order to determine the new status.
- *
- * This signal supports detailed connections. You can connect to the
- * detailed signal "writable-changed::x" in order to only receive
- * callbacks when the writability of "x" changes.
- */
-
-
-/**
- * GSettings:context:
- *
- * The name of the context that the settings are stored in.
- */
-
-
-/**
- * GSettings:delay-apply:
- *
- * Whether the #GSettings object is in 'delay-apply' mode. See
- * g_settings_delay() for details.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSettings:has-unapplied:
- *
- * If this property is %TRUE, the #GSettings object has outstanding
- * changes that will be applied when g_settings_apply() is called.
- */
-
-
-/**
- * GSettings:path:
- *
- * The path within the backend where the settings are stored.
- */
-
-
-/**
- * GSettings:schema:
- *
- * The name of the schema that describes the types of keys
- * for this #GSettings object.
- *
- * The type of this property is *not* #GSettingsSchema.
- * #GSettingsSchema has only existed since version 2.32 and
- * unfortunately this name was used in previous versions to refer to
- * the schema ID rather than the schema itself. Take care to use the
- * '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.
- */
-
-
-/**
- * GSettings:schema-id:
- *
- * The name of the schema that describes the types of keys
- * for this #GSettings object.
- */
-
-
-/**
- * GSettings:settings-schema:
- *
- * The #GSettingsSchema describing the types of keys for this
- * #GSettings object.
- *
- * Ideally, this property would be called 'schema'. #GSettingsSchema
- * has only existed since version 2.32, however, and before then the
- * 'schema' property was used to refer to the ID of the schema rather
- * than the schema itself. Take care.
- */
-
-
-/**
- * GSettingsBackend:
- *
- * An implementation of a settings storage repository.
- */
-
-
-/**
- * GSettingsBindFlags:
- * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
- * @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable.
- * @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable.
- * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting
- * @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting
- * @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to g_settings_bind_with_mapping().
- *
- * Flags used when creating a binding. These flags determine in which
- * direction the binding works. The default is to synchronize in both
- * directions.
- */
-
-
-/**
- * GSettingsBindGetMapping:
- * @value: return location for the property value
- * @variant: the #GVariant
- * @user_data: user data that was specified when the binding was created
- *
- * The type for the function that is used to convert from #GSettings to
- * an object property. The @value is already initialized to hold values
- * of the appropriate type.
- *
- * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
- */
-
-
-/**
- * GSettingsBindSetMapping:
- * @value: a #GValue containing the property value to map
- * @expected_type: the #GVariantType to create
- * @user_data: user data that was specified when the binding was created
- *
- * The type for the function that is used to convert an object property
- * value to a #GVariant for storing it in #GSettings.
- *
- * or %NULL in case of an error
- *
- * Returns: a new #GVariant holding the data from @value,
- */
-
-
-/**
- * GSettingsGetMapping:
- * @value: the #GVariant to map, or %NULL
- * @result: (out): the result of the mapping
- * @user_data: (closure): the user data that was passed to g_settings_get_mapped()
- *
- * The type of the function that is used to convert from a value stored
- * in a #GSettings to a value that is useful to the application.
- *
- * If the value is successfully mapped, the result should be stored at
- * @result and %TRUE returned. If mapping fails (for example, if @value
- * is not in the right format) then %FALSE should be returned.
- *
- * If @value is %NULL then it means that the mapping function is being
- * given a "last chance" to successfully return a valid value. %TRUE
- * must be returned in this case.
- *
- * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
- */
-
-
-/**
- * GSettingsSchema:
- *
- * This is an opaque structure type. You may not access it directly.
- *
- * Since: 2.32
- */
-
-
-/**
- * GSettingsSchemaSource:
- *
- * This is an opaque structure type. You may not access it directly.
- *
- * Since: 2.32
- */
-
-
-/**
- * GSignalAccumulator:
- * @ihint: Signal invocation hint, see #GSignalInvocationHint.
- * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission.
- * @handler_return: A #GValue holding the return value of the signal handler.
- * @data: Callback data that was specified when creating the signal.
- *
- * The signal accumulator is a special callback function that can be used
- * to collect return values of the various callbacks that are called
- * during a signal emission. The signal accumulator is specified at signal
- * creation time, if it is left %NULL, no accumulation of callback return
- * values is performed. The return value of signal emissions is then the
- * value returned by the last callback.
- *
- * should be aborted. Returning %FALSE means to abort the
- * current emission and %TRUE is returned for continuation.
- *
- * Returns: The accumulator function returns whether the signal emission
- */
-
-
-/**
- * GSignalCMarshaller:
- *
- * This is the signature of marshaller functions, required to marshall
- * arrays of parameter values to signal emissions into C language callback
- * invocations. It is merely an alias to #GClosureMarshal since the #GClosure
- * mechanism takes over responsibility of actual function invocation for the
- * signal system.
- */
-
-
-/**
- * GSignalEmissionHook:
- * @ihint: Signal invocation hint, see #GSignalInvocationHint.
- * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted.
- * @param_values: (array length=n_param_values): the instance on which the signal was emitted, followed by the parameters of the emission.
- * @data: user data associated with the hook.
- *
- * A simple function pointer to get invoked when the signal is emitted. This
- * allows you to tie a hook to the signal type, so that it will trap all
- * emissions of that signal, from any object.
- *
- * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
- *
- * hook is disconnected (and destroyed).
- *
- * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
- */
-
-
-/**
- * GSignalFlags:
- * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
- * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
- * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
- * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted.
- * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions.
- * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code.
- * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
- * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30.
- * @G_SIGNAL_DEPRECATED: The signal is deprecated and will be removed in a future version. A warning will be generated if it is connected while running with G_ENABLE_DIAGNOSTIC=1. Since 2.32.
- *
- * The signal flags are used to specify a signal's behaviour, the overall
- * signal description outlines how especially the RUN flags control the
- * stages of a signal emission.
- */
-
-
-/**
- * GSignalInvocationHint:
- * @signal_id: The signal id of the signal invoking the callback
- * @detail: The detail passed on for this emission
- * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
- *
- * The #GSignalInvocationHint structure is used to pass on additional information
- * to callbacks during a signal emission.
- */
-
-
-/**
- * GSignalMatchType:
- * @G_SIGNAL_MATCH_ID: The signal id must be equal.
- * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
- * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
- * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
- * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
- * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
- *
- * The match types specify what g_signal_handlers_block_matched(),
- * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
- * match signals by.
- */
-
-
-/**
- * GSignalQuery:
- * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown.
- * @signal_name: The signal name.
- * @itype: The interface/instance type that this signal can be emitted for.
- * @signal_flags: The signal flags as passed in to g_signal_new().
- * @return_type: The return type for user callbacks.
- * @n_params: The number of parameters that user callbacks take.
- * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> @return_type callback (#gpointer data1, [param_types param_names,] gpointer data2); </programlisting>
- *
- * A structure holding in-depth information for a specific signal. It is
- * filled in by the g_signal_query() function.
- */
-
-
-/**
- * GSimpleAction::activate:
- * @simple: the #GSimpleAction
- * @parameter: (allow-none): the parameter to the activation
- *
- * Indicates that the action was just activated.
- *
- * @parameter will always be of the expected type. In the event that
- * an incorrect type was given, no signal will be emitted.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleAction::change-state:
- * @simple: the #GSimpleAction
- * @value: (allow-none): the requested value for the state
- *
- * Indicates that the action just received a request to change its
- * state.
- *
- * @value will always be of the correct state type. In the event that
- * an incorrect type was given, no signal will be emitted.
- *
- * 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
- * call g_simple_action_set_state() from the handler.
- *
- * <example>
- * <title>Example 'change-state' handler</title>
- * <programlisting>
- * static void
- * change_volume_state (GSimpleAction *action,
- * GVariant *value,
- * gpointer user_data)
- * {
- * gint requested;
- *
- * requested = g_variant_get_int32 (value);
- *
- * // Volume only goes from 0 to 10
- * if (0 <= requested && requested <= 10)
- * g_simple_action_set_state (action, value);
- * }
- * </programlisting>
- * </example>
- *
- * The handler need not set the state to the requested value. It
- * could set it to any value at all, or take some other action.
- *
- * Since: 2.30
- */
-
-
-/**
- * GSimpleAction:enabled:
- *
- * If @action is currently enabled.
- *
- * If the action is disabled then calls to g_action_activate() and
- * g_action_change_state() have no effect.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleAction:name:
- *
- * The name of the action. This is mostly meaningful for identifying
- * the action once it has been added to a #GSimpleActionGroup.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleAction:parameter-type:
- *
- * The type of the parameter that must be given when activating the
- * action.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleAction:state:
- *
- * The state of the action, or %NULL if the action is stateless.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleAction:state-type:
- *
- * The #GVariantType of the state that the action has, or %NULL if the
- * action is stateless.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleActionGroup:
- *
- * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API.
- *
- * Since: 2.28
- */
-
-
-/**
- * GSimpleAsyncResult:
- *
- * A simple implementation of #GAsyncResult.
- */
-
-
-/**
- * GSimpleAsyncThreadFunc:
- * @res: a #GSimpleAsyncResult.
- * @object: a #GObject.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- *
- * Simple thread function that runs an asynchronous operation and
- * checks for cancellation.
- */
-
-
-/**
- * GSimplePermission:
- *
- * #GSimplePermission is an opaque data structure. There are no methods
- * except for those defined by #GPermission.
- */
-
-
-/**
- * GSocket:
- *
- * A lowlevel network socket object.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocket:timeout:
- *
- * The timeout in seconds on socket I/O
- *
- * Since: 2.26
- */
-
-
-/**
- * GSocketAddress:
- *
- * A socket endpoint address, corresponding to <type>struct sockaddr</type>
- * or one of its subtypes.
- */
-
-
-/**
- * GSocketAddressEnumerator:
- *
- * Enumerator type for objects that contain or generate
- * #GSocketAddress<!-- -->es.
- */
-
-
-/**
- * GSocketClient:
- *
- * A helper class for network servers to listen for and accept connections.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocketConnectable:
- *
- * Interface for objects that contain or generate #GSocketAddress<!-- -->es.
- */
-
-
-/**
- * GSocketConnectableIface:
- * @g_iface: The parent interface.
- * @enumerate: Creates a #GSocketAddressEnumerator
- * @proxy_enumerate: Creates a #GProxyAddressEnumerator
- *
- * Provides an interface for returning a #GSocketAddressEnumerator
- * and #GProxyAddressEnumerator
- */
-
-
-/**
- * GSocketConnection:
- *
- * A socket connection GIOStream object for connection-oriented sockets.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocketControlMessage:
- *
- * Base class for socket-type specific control messages that can be sent and
- * received over #GSocket.
- */
-
-
-/**
- * GSocketControlMessageClass:
- * @get_size: gets the size of the message.
- * @get_level: gets the protocol of the message.
- * @get_type: gets the protocol specific type of the message.
- * @serialize: Writes out the message data.
- * @deserialize: Tries to deserialize a message.
- *
- *
- */
-
-
-/**
- * GSocketFamily:
- * @G_SOCKET_FAMILY_INVALID: no address family
- * @G_SOCKET_FAMILY_IPV4: the IPv4 family
- * @G_SOCKET_FAMILY_IPV6: the IPv6 family
- * @G_SOCKET_FAMILY_UNIX: the UNIX domain family
- *
- * The protocol family of a #GSocketAddress. (These values are
- * identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX,
- * if available.)
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocketListenerClass:
- * @changed: virtual method called when the set of socket listened to changes
- *
- *
- */
-
-
-/**
- * GSocketMsgFlags:
- * @G_SOCKET_MSG_NONE: No flags.
- * @G_SOCKET_MSG_OOB: Request to send/receive out of band data.
- * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue.
- * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks.
- *
- * Flags used in g_socket_receive_message() and g_socket_send_message().
- * The flags listed in the enum are some commonly available flags, but the
- * values used for them are the same as on the platform, and any other flags
- * are passed in/out as is. So to use a platform specific flag, just include
- * the right system header and pass in the flag.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocketProtocol:
- * @G_SOCKET_PROTOCOL_UNKNOWN: The protocol type is unknown
- * @G_SOCKET_PROTOCOL_DEFAULT: The default protocol for the family/type
- * @G_SOCKET_PROTOCOL_TCP: TCP over IP
- * @G_SOCKET_PROTOCOL_UDP: UDP over IP
- * @G_SOCKET_PROTOCOL_SCTP: SCTP over IP
- *
- * A protocol identifier is specified when creating a #GSocket, which is a
- * family/type specific identifier, where 0 means the default protocol for
- * the particular family/type.
- *
- * This enum contains a set of commonly available and used protocols. You
- * can also pass any other identifiers handled by the platform in order to
- * use protocols not listed here.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocketService:
- *
- * A helper class for handling accepting incomming connections in the
- * glib mainloop.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSocketService::incoming:
- * @service: the #GSocketService
- * @connection: a new #GSocketConnection object
- * @source_object: 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
- * handling of @connection, but may not block; in essence,
- * asynchronous operations must be used.
- *
- * @connection will be unreffed once the signal handler returns,
- * so you need to ref it yourself if you are planning to use it.
- *
- * Returns: %TRUE to stop other handlers from being called
- * Since: 2.22
- */
-
-
-/**
- * GSocketServiceClass:
- * @incomming: signal emitted when new connections are accepted
- *
- *
- */
-
-
-/**
- * GSocketSourceFunc:
- * @socket: the #GSocket
- * @condition: the current condition at the source fired.
- * @user_data: data passed in by the user.
- *
- * This is the function type of the callback used for the #GSource
- * returned by g_socket_create_source().
- *
- * Returns: it should return %FALSE if the source should be removed.
- * Since: 2.22
- */
-
-
-/**
- * GSocketType:
- * @G_SOCKET_TYPE_INVALID: Type unknown or wrong
- * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP).
- * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP)
- * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP).
- *
- * Flags used when creating a #GSocket. Some protocols may not implement
- * all the socket types.
- *
- * Since: 2.22
- */
-
-
-/**
- * GSource:
- *
- * The <structname>GSource</structname> struct is an opaque data type
- * representing an event source.
- */
-
-
-/**
- * GSourceCallbackFuncs:
- * @ref: Called when a reference is added to the callback object
- * @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
- *
- *
- */
-
-
-/**
- * GSourceDummyMarshal:
- *
- * This is just a placeholder for #GClosureMarshal,
- * which cannot be used here for dependency reasons.
- */
-
-
-/**
- * GSourceFunc:
- * @user_data: data passed to the function, set when the source was created with one of the above functions
- *
- * Specifies the type of function passed to g_timeout_add(),
- * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
- *
- * Returns: %FALSE if the source should be removed
- */
-
-
-/**
- * GSourceFuncs:
- * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout_ values returned which were >= 0.
- * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
- * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source.
- * @finalize: Called when the source is finalized.
- *
- * The <structname>GSourceFuncs</structname> struct contains a table of
- * functions used to handle event sources in a generic manner.
- *
- * For idle sources, the prepare and check functions always return %TRUE
- * to indicate that the source is always ready to be processed. The prepare
- * function also returns a timeout value of 0 to ensure that the poll() call
- * doesn't block (since that would be time wasted which could have been spent
- * running the idle function).
- *
- * For timeout sources, the prepare and check functions both return %TRUE
- * if the timeout interval has expired. The prepare function also returns
- * a timeout value to ensure that the poll() call doesn't block too long
- * and miss the next timeout.
- *
- * For file descriptor sources, the prepare function typically returns %FALSE,
- * since it must wait until poll() has been called before it knows whether
- * any events need to be processed. It sets the returned timeout to -1 to
- * indicate that it doesn't mind how long the poll() call blocks. In the
- * check function, it tests the results of the poll() call to see if the
- * required condition has been met, and returns %TRUE if so.
- */
-
-
-/**
- * GSpawnChildSetupFunc:
- * @user_data: user data to pass to the function.
- *
- * Specifies the type of the setup function passed to g_spawn_async(),
- * g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very
- * limited ways, be used to affect the child's execution.
- *
- * On POSIX platforms, the function is called in the child after GLib
- * has performed all the setup it plans to perform, but before calling
- * exec(). Actions taken in this function will only affect the child,
- * not the parent.
- *
- * On Windows, the function is called in the parent. Its usefulness on
- * Windows is thus questionable. In many cases executing the child setup
- * function in the parent can have ill effects, and you should be very
- * careful when porting software to Windows that uses child setup
- * functions.
- *
- * However, even on POSIX, you are extremely limited in what you can
- * safely do from a #GSpawnChildSetupFunc, because any mutexes that
- * were held by other threads in the parent process at the time of the
- * fork() will still be locked in the child process, and they will
- * never be unlocked (since the threads that held them don't exist in
- * the child). POSIX allows only async-signal-safe functions (see
- * <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
- * to be called in the child between fork() and exec(), which
- * drastically limits the usefulness of child setup functions.
- *
- * In particular, it is not safe to call any function which may
- * call malloc(), which includes POSIX functions such as setenv().
- * If you need to set up the child environment differently from
- * the parent, you should use g_get_environ(), g_environ_setenv(),
- * and g_environ_unsetenv(), and then pass the complete environment
- * list to the <literal>g_spawn...</literal> function.
- */
-
-
-/**
- * GSpawnError:
- * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
- * @G_SPAWN_ERROR_READ: Read or select on pipes failed.
- * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
- * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
- * @G_SPAWN_ERROR_2BIG: execv() returned <literal>E2BIG</literal>
- * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
- * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
- * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
- * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
- * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
- * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
- * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
- * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
- * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
- * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
- * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
- * @G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error->message</literal> should explain.
- *
- * Error codes returned by spawning processes.
- */
-
-
-/**
- * GSpawnFlags:
- * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling exec() in the child.
- * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you must use g_child_watch_add() yourself (or call waitpid() or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
- * @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path, it will be looked for in the user's <envar>PATH</envar>.
- * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded, instead of going to the same location as the parent's standard output.
- * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
- * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard input (by default, the child's standard input is attached to <filename>/dev/null</filename>).
- * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally g_spawn_async_with_pipes() uses <literal>argv[0]</literal> as the file to execute, and passes all of <literal>argv</literal> to the child.
- *
- * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
- */
-
-
-/**
- * GSrvTarget:
- *
- * A single target host/port that a network service is running on.
- */
-
-
-/**
- * GStrv:
- *
- * A C representable type name for #G_TYPE_STRV.
- */
-
-
-/**
- * GTcpConnection:
- *
- * A #GSocketConnection for UNIX domain socket connections.
- *
- * Since: 2.22
- */
-
-
-/**
- * GTestLogFatalFunc:
- * @log_domain: the log domain of the message
- * @log_level: the log level of the message (including the fatal and recursion flags)
- * @message: the message to process
- * @user_data: user data, set in g_test_log_set_fatal_handler()
- *
- * Specifies the prototype of fatal log handler functions.
- *
- * Returns: %TRUE if the program should abort, %FALSE otherwise
- * Since: 2.22
- */
-
-
-/**
- * GThemedIcon:
- *
- * An implementation of #GIcon for themed icons.
- */
-
-
-/**
- * GThemedIcon:name:
- *
- * The icon name.
- */
-
-
-/**
- * GThemedIcon:names:
- *
- * A %NULL-terminated array of icon names.
- */
-
-
-/**
- * GThemedIcon:use-default-fallbacks:
- *
- * Whether to use the default fallbacks found by shortening the icon name
- * at '-' characters. If the "names" array has more than one element,
- * ignores any past the first.
- *
- * For example, if the icon name was "gnome-dev-cdrom-audio", the array
- * would become
- * |[
- * {
- * "gnome-dev-cdrom-audio",
- * "gnome-dev-cdrom",
- * "gnome-dev",
- * "gnome",
- * NULL
- * };
- * ]|
- */
-
-
-/**
- * GThreadedSocketService:
- *
- * A helper class for handling accepting incoming connections in the
- * glib mainloop and handling them in a thread.
- *
- * Since: 2.22
- */
-
-
-/**
- * GThreadedSocketService::run:
- * @service: the #GThreadedSocketService.
- * @connection: a new #GSocketConnection object.
- * @source_object: the source_object passed to g_socket_listener_add_address().
- *
- * The ::run signal is emitted in a worker thread in response to an
- * incoming connection. This thread is dedicated to handling
- * @connection and may perform blocking IO. The signal handler need
- * not return until the connection is closed.
- *
- * Returns: %TRUE to stop further signal handlers from being called
- */
-
-
-/**
- * GTimeSpan:
- *
- * A value representing an interval of time, in microseconds.
- *
- * Since: 2.26
- */
-
-
-/**
- * GTimeType:
- * @G_TIME_TYPE_STANDARD: the time is in local standard time
- * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time
- * @G_TIME_TYPE_UNIVERSAL: the time is in UTC
- *
- * Disambiguates a given time in two ways.
- *
- * First, specifies if the given time is in universal or local time.
- *
- * Second, if the time is in local time, specifies if it is local
- * standard time or local daylight time. This is important for the case
- * where the same local time occurs twice (during daylight savings time
- * transitions, for example).
- */
-
-
-/**
- * GTlsAuthenticationMode:
- * @G_TLS_AUTHENTICATION_NONE: client authentication not required
- * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested
- * @G_TLS_AUTHENTICATION_REQUIRED: client authentication is required
- *
- * The client authentication mode for a #GTlsServerConnection.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsBackend:
- *
- * TLS (Transport Layer Security, aka SSL) backend. This is an
- * internal type used to coordinate the different classes implemented
- * by a TLS backend.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsBackendInterface:
- * @g_iface: The parent interface.
- * @supports_tls: returns whether the backend supports TLS.
- * @get_default_database: returns a default #GTlsDatabase instance.
- * @get_certificate_type: returns the #GTlsCertificate implementation type
- * @get_client_connection_type: returns the #GTlsClientConnection implementation type
- * @get_server_connection_type: returns the #GTlsServerConnection implementation type
- * @get_file_database_type: returns the #GTlsFileDatabase implementation type.
- *
- * Provides an interface for describing TLS-related types.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsCertificate:
- *
- * Abstract base class for TLS certificate types.
- *
- * Since: 2.28
- */
-
-
-/**
- * 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.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsCertificate:certificate-pem:
- *
- * The PEM (ASCII) encoded representation of the certificate's
- * public key. This property and the #GTlsCertificate:certificate
- * property represent the same data, just in different forms.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsCertificate:issuer:
- *
- * A #GTlsCertificate representing the entity that issued this
- * certificate. If %NULL, this means that the certificate is either
- * self-signed, or else the certificate of the issuer is not
- * available.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsCertificate:private-key:
- *
- * The DER (binary) encoded representation of the certificate's
- * private key, in either PKCS#1 format or unencrypted PKCS#8
- * format. This property (or the #GTlsCertificate:private-key-pem
- * 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>
- * 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
- * #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>
- * tool to convert PKCS#8 keys to PKCS#1.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsCertificateFlags:
- * @G_TLS_CERTIFICATE_UNKNOWN_CA: The signing certificate authority is not known.
- * @G_TLS_CERTIFICATE_BAD_IDENTITY: The certificate does not match the expected identity of the site that it was retrieved from.
- * @G_TLS_CERTIFICATE_NOT_ACTIVATED: The certificate's activation time is still in the future
- * @G_TLS_CERTIFICATE_EXPIRED: The certificate has expired
- * @G_TLS_CERTIFICATE_REVOKED: The certificate has been revoked according to the #GTlsConnection's certificate revocation list.
- * @G_TLS_CERTIFICATE_INSECURE: The certificate's algorithm is considered insecure.
- * @G_TLS_CERTIFICATE_GENERIC_ERROR: Some other error occurred validating the certificate
- * @G_TLS_CERTIFICATE_VALIDATE_ALL: the combination of all of the above flags
- *
- * A set of flags describing TLS certification validation. This can be
- * used to set which validation steps to perform (eg, with
- * g_tls_client_connection_set_validation_flags()), or to describe why
- * a particular certificate was rejected (eg, in
- * #GTlsConnection::accept-certificate).
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsClientConnection:
- *
- * TLS client-side connection; the client-side implementation of a
- * #GTlsConnection
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsClientConnection:accepted-cas:
- *
- * A list of the distinguished names of the Certificate Authorities
- * that the server will accept client certificates signed by. If the
- * server requests a client certificate during the handshake, then
- * this property will be set after the handshake completes.
- *
- * Each item in the list is a #GByteArray which contains the complete
- * subject DN of the certificate authority.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsClientConnection:server-identity:
- *
- * A #GSocketConnectable describing the identity of the server that
- * is expected on the other end of the connection.
- *
- * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
- * #GTlsClientConnection:validation-flags, this object will be used
- * to determine the expected identify of the remote end of the
- * connection; if #GTlsClientConnection:server-identity is not set,
- * or does not match the identity presented by the server, then the
- * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
- *
- * In addition to its use in verifying the server certificate,
- * this is also used to give a hint to the server about what
- * certificate we expect, which is useful for servers that serve
- * virtual hosts.
- *
- * Since: 2.28
- */
-
-
-/**
- * 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.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsClientConnection:validation-flags:
- *
- * What steps to perform when validating a certificate received from
- * a server. Server certificates that fail to validate in all of the
- * ways indicated here will be rejected unless the application
- * overrides the default via #GTlsConnection::accept-certificate.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:
- *
- * TLS connection. This is an abstract type that will be subclassed by
- * a TLS-library-specific subtype.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection::accept-certificate:
- * @conn: a #GTlsConnection
- * @peer_cert: the peer's #GTlsCertificate
- * @errors: the problems with @peer_cert.
- *
- * Emitted during the TLS handshake after the peer certificate has
- * been received. You can examine @peer_cert's certification path by
- * calling g_tls_certificate_get_issuer() on it.
- *
- * For a client-side connection, @peer_cert is the server's
- * certificate, and the signal will only be emitted if the
- * certificate was not acceptable according to @conn's
- * #GTlsClientConnection:validation_flags. If you would like the
- * certificate to be accepted despite @errors, return %TRUE from the
- * signal handler. Otherwise, if no handler accepts the certificate,
- * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
- *
- * For a server-side connection, @peer_cert is the certificate
- * presented by the client, if this was requested via the server's
- * #GTlsServerConnection:authentication_mode. On the server side,
- * the signal is always emitted when the client presents a
- * certificate, and the certificate will only be accepted if a
- * handler returns %TRUE.
- *
- * Note that if this signal is emitted as part of asynchronous I/O
- * in the main thread, then you should not attempt to interact with
- * the user before returning from the signal handler. If you want to
- * let the user decide whether or not to accept the certificate, you
- * would have to return %FALSE from the signal handler on the first
- * attempt, and then after the connection attempt returns a
- * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
- * the user decides to accept the certificate, remember that fact,
- * create a new connection, and return %TRUE from the signal handler
- * the next time.
- *
- * If you are doing I/O in another thread, you do not
- * need to worry about this, and can simply block in the signal
- * handler until the UI thread returns an answer.
- *
- * 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
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:base-io-stream:
- *
- * The #GIOStream that the connection wraps
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:certificate:
- *
- * The connection's certificate; see
- * g_tls_connection_set_certificate().
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:database:
- *
- * The certificate database to use when verifying this TLS connection.
- * If no cerificate database is set, then the default database will be
- * used. See g_tls_backend_get_default_database().
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsConnection:interaction:
- *
- * A #GTlsInteraction object to be used when the connection or certificate
- * database need to interact with the user. This will be used to prompt the
- * user for passwords where necessary.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsConnection:peer-certificate:
- *
- * The connection's peer's certificate, after the TLS handshake has
- * completed and the certificate has been accepted. Note in
- * particular that this is not yet set during the emission of
- * #GTlsConnection::accept-certificate.
- *
- * (You can watch for a #GObject::notify signal on this property to
- * detect when a handshake has occurred.)
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:peer-certificate-errors:
- *
- * The errors noticed-and-ignored while verifying
- * #GTlsConnection:peer-certificate. Normally this should be 0, but
- * it may not be if #GTlsClientConnection:validation-flags is not
- * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
- * #GTlsConnection::accept-certificate overrode the default
- * behavior.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:rehandshake-mode:
- *
- * The rehandshaking mode. See
- * g_tls_connection_set_rehandshake_mode().
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:require-close-notify:
- *
- * Whether or not proper TLS close notification is required.
- * See g_tls_connection_set_require_close_notify().
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsConnection:use-system-certdb:
- *
- * Whether or not the system certificate database will be used to
- * verify peer certificates. See
- * g_tls_connection_set_use_system_certdb().
- *
- * Deprecated: 2.30: Use GTlsConnection:database instead
- */
-
-
-/**
- * GTlsDatabase:
- *
- * Abstract base class for the backend-specific database types.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsDatabaseLookupFlags:
- * @G_TLS_DATABASE_LOOKUP_NONE: No lookup flags
- * @G_TLS_DATABASE_LOOKUP_KEYPAIR: Restrict lookup to certificates that have a private key.
- *
- * Flags for g_tls_database_lookup_handle(), g_tls_database_lookup_issuer(),
- * and g_tls_database_lookup_issued().
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsError:
- * @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available
- * @G_TLS_ERROR_MISC: Miscellaneous TLS error
- * @G_TLS_ERROR_BAD_CERTIFICATE: A certificate could not be parsed
- * @G_TLS_ERROR_NOT_TLS: The TLS handshake failed because the peer does not seem to be a TLS server.
- * @G_TLS_ERROR_HANDSHAKE: The TLS handshake failed because the peer's certificate was not acceptable.
- * @G_TLS_ERROR_CERTIFICATE_REQUIRED: The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate().
- * @G_TLS_ERROR_EOF: The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify().
- *
- * An error code used with %G_TLS_ERROR in a #GError returned from a
- * TLS-related routine.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsFileDatabase:
- *
- * Implemented by a #GTlsDatabase which allows you to load certificates
- * from a file.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsFileDatabase:anchors:
- *
- * The path to a file containing PEM encoded certificate authority
- * root anchors. The certificates in this file will be treated as
- * root authorities for the purpose of verifying other certificates
- * via the g_tls_database_verify_chain() operation.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsFileDatabaseInterface:
- * @g_iface: The parent interface.
- *
- * Provides an interface for #GTlsFileDatabase implementations.
- */
-
-
-/**
- * GTlsInteraction:
- *
- * An object representing interaction that the TLS connection and database
- * might have with the user.
- *
- * Since: 2.30
- */
-
-
-/**
- * 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_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.
- *
- * The class for #GTlsInteraction. Derived classes implement the various
- * virtual interaction methods to handle TLS interactions.
- *
- * Derived classes can choose to implement whichever interactions methods they'd
- * like to support by overriding those virtual methods in their class
- * initialization function. If a derived class implements an async method,
- * it must also implement the corresponding finish method.
- *
- * The synchronous interaction methods should implement to display modal dialogs,
- * and the asynchronous methods to display modeless dialogs.
- *
- * If the user cancels an interaction, then the result should be
- * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
- * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsInteractionResult:
- * @G_TLS_INTERACTION_UNHANDLED: The interaction was unhandled (i.e. not implemented).
- * @G_TLS_INTERACTION_HANDLED: The interaction completed, and resulting data is available.
- * @G_TLS_INTERACTION_FAILED: The interaction has failed, or was cancelled. and the operation should be aborted.
- *
- * #GTlsInteractionResult is returned by various functions in #GTlsInteraction
- * when finishing an interaction request.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsPassword:
- *
- * An abstract interface representing a password used in TLS. Often used in
- * user interaction such as unlocking a key storage token.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsPasswordFlags:
- * @G_TLS_PASSWORD_NONE: No flags
- * @G_TLS_PASSWORD_RETRY: The password was wrong, and the user should retry.
- * @G_TLS_PASSWORD_MANY_TRIES: Hint to the user that the password has been wrong many times, and the user may not have many chances left.
- * @G_TLS_PASSWORD_FINAL_TRY: Hint to the user that this is the last try to get this password right.
- *
- * Various flags for the password.
- *
- * Since: 2.30
- */
-
-
-/**
- * GTlsRehandshakeMode:
- * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking
- * @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only
- * @G_TLS_REHANDSHAKE_UNSAFELY: Allow unsafe rehandshaking
- *
- * When to allow rehandshaking. See
- * g_tls_connection_set_rehandshake_mode().
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsServerConnection:
- *
- * TLS server-side connection. This is the server-side implementation
- * of a #GTlsConnection.
- *
- * Since: 2.28
- */
-
-
-/**
- * GTlsServerConnection:authentication-mode:
- *
- * The #GTlsAuthenticationMode for the server. This can be changed
- * before calling g_tls_connection_handshake() if you want to
- * rehandshake with a different mode from the initial handshake.
- *
- * Since: 2.28
- */
-
-
-/**
- * GToggleNotify:
- * @data: Callback data passed to g_object_add_toggle_ref()
- * @object: The object on which g_object_add_toggle_ref() was called.
- * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references.
- *
- * A callback function used for notification when the state
- * of a toggle reference changes. See g_object_add_toggle_ref().
- */
-
-
-/**
- * GTranslateFunc:
- * @str: the untranslated string
- * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func()
- *
- * The type of functions which are used to translate user-visible
- * strings, for <option>--help</option> output.
- *
- * The returned string is owned by GLib and must not be freed.
- *
- * Returns: a translation of the string for the current locale.
- */
-
-
-/**
- * GType:
- *
- * A numerical value which represents the unique identifier of a registered
- * type.
- */
-
-
-/**
- * GTypeClass:
- *
- * An opaque structure used as the base of all classes.
- */
-
-
-/**
- * GTypeClassCacheFunc:
- * @cache_data: data that was given to the g_type_add_class_cache_func() call
- * @g_class: The #GTypeClass structure which is unreferenced
- *
- * A callback function which is called when the reference count of a class
- * drops to zero. It may use g_type_class_ref() to prevent the class from
- * being freed. You should not call g_type_class_unref() from a
- * #GTypeClassCacheFunc function to prevent infinite recursion, use
- * g_type_class_unref_uncached() instead.
- *
- * The functions have to check the class id passed in to figure
- * whether they actually want to cache the class of this type, since all
- * classes are routed through the same #GTypeClassCacheFunc chain.
- *
- * called, %FALSE to continue.
- *
- * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
- */
-
-
-/**
- * GTypeDebugFlags:
- * @G_TYPE_DEBUG_NONE: Print no messages.
- * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
- * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
- * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
- *
- * The <type>GTypeDebugFlags</type> enumeration values can be passed to
- * g_type_init_with_debug_flags() to trigger debugging messages during runtime.
- * Note that the messages can also be triggered by setting the
- * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of
- * "objects" and "signals".
- */
-
-
-/**
- * GTypeFlags:
- * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type.
- * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init().
- *
- * Bit masks used to check or determine characteristics of a type.
- */
-
-
-/**
- * GTypeFundamentalFlags:
- * @G_TYPE_FLAG_CLASSED: Indicates a classed type.
- * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
- * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
- * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
- *
- * Bit masks used to check or determine specific characteristics of a
- * fundamental type.
- */
-
-
-/**
- * GTypeFundamentalInfo:
- * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
- *
- * A structure that provides information to the type system which is
- * used specifically for managing fundamental types.
- */
-
-
-/**
- * GTypeInfo:
- * @class_size: Size of the class structure (required for interface, classed and instantiatable types).
- * @base_init: Location of the base initialization function (optional).
- * @base_finalize: Location of the base finalization function (optional).
- * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties.
- * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional)
- * @class_data: User-supplied data passed to the class init/finalize functions.
- * @instance_size: Size of the instance (object) structure (required for instantiatable types only).
- * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
- * @instance_init: Location of the instance initialization function (optional, for instantiatable types only).
- * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types).
- *
- * This structure is used to provide the type system with the information
- * required to initialize and destruct (finalize) a type's class and
- * its instances.
- * The initialized structure is passed to the g_type_register_static() function
- * (or is copied into the provided #GTypeInfo structure in the
- * g_type_plugin_complete_type_info()). The type system will perform a deep
- * copy of this structure, so its memory does not need to be persistent
- * across invocation of g_type_register_static().
- */
-
-
-/**
- * GTypeInstance:
- *
- * An opaque structure used as the base of all type instances.
- */
-
-
-/**
- * GTypeInterface:
- *
- * An opaque structure used as the base of all interface types.
- */
-
-
-/**
- * GTypeInterfaceCheckFunc:
- * @check_data: data passed to g_type_add_interface_check().
- * @g_iface: the interface that has been initialized
- *
- * A callback called after an interface vtable is initialized.
- * See g_type_add_interface_check().
- *
- * Since: 2.4
- */
-
-
-/**
- * GTypeModule:
- * @name: the name of the module
- *
- * The members of the <structname>GTypeModule</structname> structure should not
- * be accessed directly, except for the @name field.
- */
-
-
-/**
- * GTypeModuleClass:
- * @parent_class: the parent class
- * @load: loads the module and registers one or more types using g_type_module_register_type().
- * @unload: unloads the module
- *
- * In order to implement dynamic loading of types based on #GTypeModule,
- * the @load and @unload functions in #GTypeModuleClass must be implemented.
- */
-
-
-/**
- * GTypePlugin:
- *
- * The <structname>GTypePlugin</structname> typedef is used as a placeholder
- * for objects that implement the <structname>GTypePlugin</structname>
- * interface.
- */
-
-
-/**
- * GTypePluginClass:
- * @use_plugin: Increases the use count of the plugin.
- * @unuse_plugin: Decreases the use count of the plugin.
- * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function.
- * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function.
- *
- * The #GTypePlugin interface is used by the type system in order to handle
- * the lifecycle of dynamically loaded types.
- */
-
-
-/**
- * GTypePluginCompleteInterfaceInfo:
- * @plugin: the #GTypePlugin
- * @instance_type: the #GType of an instantiable type to which the interface is added
- * @interface_type: the #GType of the interface whose info is completed
- * @info: the #GInterfaceInfo to fill in
- *
- * The type of the @complete_interface_info function of #GTypePluginClass.
- */
-
-
-/**
- * GTypePluginCompleteTypeInfo:
- * @plugin: the #GTypePlugin
- * @g_type: the #GType whose info is completed
- * @info: the #GTypeInfo struct to fill in
- * @value_table: the #GTypeValueTable to fill in
- *
- * The type of the @complete_type_info function of #GTypePluginClass.
- */
-
-
-/**
- * GTypePluginUnuse:
- * @plugin: the #GTypePlugin whose use count should be decreased
- *
- * The type of the @unuse_plugin function of #GTypePluginClass.
- */
-
-
-/**
- * GTypePluginUse:
- * @plugin: the #GTypePlugin whose use count should be increased
- *
- * The type of the @use_plugin function of #GTypePluginClass, which gets called
- * to increase the use count of @plugin.
- */
-
-
-/**
- * GTypeQuery:
- * @type: the #GType value of the type.
- * @type_name: the name of the type.
- * @class_size: the size of the class structure.
- * @instance_size: the size of the instance structure.
- *
- * A structure holding information for a specific type. It is
- * filled in by the g_type_query() function.
- */
-
-
-/**
- * GTypeValueTable:
- * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]|
- * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]|
- * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of @src_value into @dest_value in a way, that even after @src_value has been freed, the contents of @dest_value remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
- * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]|
- * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'.
- * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup @value similar to value_init(); e.g. for a string value that does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. @n_collect_values is exactly the string length of @collect_format, and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. @collect_flags is an argument provided as a hint by the caller. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the signal emission code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined.
- * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
- * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. @n_collect_values equals the string length of @lcopy_format, and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
- *
- * The #GTypeValueTable provides the functions required by the #GValue implementation,
- * to serve as a container for values of a type.
- */
-
-
-/**
- * GUnicodeBreakType:
- * @G_UNICODE_BREAK_MANDATORY: Mandatory Break (BK)
- * @G_UNICODE_BREAK_CARRIAGE_RETURN: Carriage Return (CR)
- * @G_UNICODE_BREAK_LINE_FEED: Line Feed (LF)
- * @G_UNICODE_BREAK_COMBINING_MARK: Attached Characters and Combining Marks (CM)
- * @G_UNICODE_BREAK_SURROGATE: Surrogates (SG)
- * @G_UNICODE_BREAK_ZERO_WIDTH_SPACE: Zero Width Space (ZW)
- * @G_UNICODE_BREAK_INSEPARABLE: Inseparable (IN)
- * @G_UNICODE_BREAK_NON_BREAKING_GLUE: Non-breaking ("Glue") (GL)
- * @G_UNICODE_BREAK_CONTINGENT: Contingent Break Opportunity (CB)
- * @G_UNICODE_BREAK_SPACE: Space (SP)
- * @G_UNICODE_BREAK_AFTER: Break Opportunity After (BA)
- * @G_UNICODE_BREAK_BEFORE: Break Opportunity Before (BB)
- * @G_UNICODE_BREAK_BEFORE_AND_AFTER: Break Opportunity Before and After (B2)
- * @G_UNICODE_BREAK_HYPHEN: Hyphen (HY)
- * @G_UNICODE_BREAK_NON_STARTER: Nonstarter (NS)
- * @G_UNICODE_BREAK_OPEN_PUNCTUATION: Opening Punctuation (OP)
- * @G_UNICODE_BREAK_CLOSE_PUNCTUATION: Closing Punctuation (CL)
- * @G_UNICODE_BREAK_QUOTATION: Ambiguous Quotation (QU)
- * @G_UNICODE_BREAK_EXCLAMATION: Exclamation/Interrogation (EX)
- * @G_UNICODE_BREAK_IDEOGRAPHIC: Ideographic (ID)
- * @G_UNICODE_BREAK_NUMERIC: Numeric (NU)
- * @G_UNICODE_BREAK_INFIX_SEPARATOR: Infix Separator (Numeric) (IS)
- * @G_UNICODE_BREAK_SYMBOL: Symbols Allowing Break After (SY)
- * @G_UNICODE_BREAK_ALPHABETIC: Ordinary Alphabetic and Symbol Characters (AL)
- * @G_UNICODE_BREAK_PREFIX: Prefix (Numeric) (PR)
- * @G_UNICODE_BREAK_POSTFIX: Postfix (Numeric) (PO)
- * @G_UNICODE_BREAK_COMPLEX_CONTEXT: Complex Content Dependent (South East Asian) (SA)
- * @G_UNICODE_BREAK_AMBIGUOUS: Ambiguous (Alphabetic or Ideographic) (AI)
- * @G_UNICODE_BREAK_UNKNOWN: Unknown (XX)
- * @G_UNICODE_BREAK_NEXT_LINE: Next Line (NL)
- * @G_UNICODE_BREAK_WORD_JOINER: Word Joiner (WJ)
- * @G_UNICODE_BREAK_HANGUL_L_JAMO: Hangul L Jamo (JL)
- * @G_UNICODE_BREAK_HANGUL_V_JAMO: Hangul V Jamo (JV)
- * @G_UNICODE_BREAK_HANGUL_T_JAMO: Hangul T Jamo (JT)
- * @G_UNICODE_BREAK_HANGUL_LV_SYLLABLE: Hangul LV Syllable (H2)
- * @G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE: Hangul LVT Syllable (H3)
- * @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28
- *
- * These are the possible line break classifications.
- *
- * The five Hangul types were added in Unicode 4.1, so, has been
- * introduced in GLib 2.10. Note that new types may be added in the future.
- * Applications should be ready to handle unknown values.
- * They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
- *
- * See <ulink url="http://www.unicode.org/unicode/reports/tr14/">http://www.unicode.org/unicode/reports/tr14/</ulink>.
- */
-
-
-/**
- * GUnicodeScript:
- * @G_UNICODE_SCRIPT_COMMON: a character used by multiple different scripts
- * @G_UNICODE_SCRIPT_INHERITED: a mark glyph that takes its script from the i base glyph to which it is attached
- * @G_UNICODE_SCRIPT_ARABIC: Arabic
- * @G_UNICODE_SCRIPT_ARMENIAN: Armenian
- * @G_UNICODE_SCRIPT_BENGALI: Bengali
- * @G_UNICODE_SCRIPT_BOPOMOFO: Bopomofo
- * @G_UNICODE_SCRIPT_CHEROKEE: Cherokee
- * @G_UNICODE_SCRIPT_COPTIC: Coptic
- * @G_UNICODE_SCRIPT_CYRILLIC: Cyrillic
- * @G_UNICODE_SCRIPT_DESERET: Deseret
- * @G_UNICODE_SCRIPT_DEVANAGARI: Devanagari
- * @G_UNICODE_SCRIPT_ETHIOPIC: Ethiopic
- * @G_UNICODE_SCRIPT_GEORGIAN: Georgian
- * @G_UNICODE_SCRIPT_GOTHIC: Gothic
- * @G_UNICODE_SCRIPT_GREEK: Greek
- * @G_UNICODE_SCRIPT_GUJARATI: Gujarati
- * @G_UNICODE_SCRIPT_GURMUKHI: Gurmukhi
- * @G_UNICODE_SCRIPT_HAN: Han
- * @G_UNICODE_SCRIPT_HANGUL: Hangul
- * @G_UNICODE_SCRIPT_HEBREW: Hebrew
- * @G_UNICODE_SCRIPT_HIRAGANA: Hiragana
- * @G_UNICODE_SCRIPT_KANNADA: Kannada
- * @G_UNICODE_SCRIPT_KATAKANA: Katakana
- * @G_UNICODE_SCRIPT_KHMER: Khmer
- * @G_UNICODE_SCRIPT_LAO: Lao
- * @G_UNICODE_SCRIPT_LATIN: Latin
- * @G_UNICODE_SCRIPT_MALAYALAM: Malayalam
- * @G_UNICODE_SCRIPT_MONGOLIAN: Mongolian
- * @G_UNICODE_SCRIPT_MYANMAR: Myanmar
- * @G_UNICODE_SCRIPT_OGHAM: Ogham
- * @G_UNICODE_SCRIPT_OLD_ITALIC: Old Italic
- * @G_UNICODE_SCRIPT_ORIYA: Oriya
- * @G_UNICODE_SCRIPT_RUNIC: Runic
- * @G_UNICODE_SCRIPT_SINHALA: Sinhala
- * @G_UNICODE_SCRIPT_SYRIAC: Syriac
- * @G_UNICODE_SCRIPT_TAMIL: Tamil
- * @G_UNICODE_SCRIPT_TELUGU: Telugu
- * @G_UNICODE_SCRIPT_THAANA: Thaana
- * @G_UNICODE_SCRIPT_THAI: Thai
- * @G_UNICODE_SCRIPT_TIBETAN: Tibetan Canadian Aboriginal
- * @G_UNICODE_SCRIPT_YI: Yi
- * @G_UNICODE_SCRIPT_TAGALOG: Tagalog
- * @G_UNICODE_SCRIPT_HANUNOO: Hanunoo
- * @G_UNICODE_SCRIPT_BUHID: Buhid
- * @G_UNICODE_SCRIPT_TAGBANWA: Tagbanwa
- * @G_UNICODE_SCRIPT_BRAILLE: Braille
- * @G_UNICODE_SCRIPT_CYPRIOT: Cypriot
- * @G_UNICODE_SCRIPT_LIMBU: Limbu
- * @G_UNICODE_SCRIPT_OSMANYA: Osmanya
- * @G_UNICODE_SCRIPT_SHAVIAN: Shavian
- * @G_UNICODE_SCRIPT_LINEAR_B: Linear B
- * @G_UNICODE_SCRIPT_TAI_LE: Tai Le
- * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic New Tai Lue
- * @G_UNICODE_SCRIPT_BUGINESE: Buginese
- * @G_UNICODE_SCRIPT_GLAGOLITIC: Glagolitic
- * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh Syloti Nagri Old Persian
- * @G_UNICODE_SCRIPT_KHAROSHTHI: Kharoshthi
- * @G_UNICODE_SCRIPT_UNKNOWN: an unassigned code point
- * @G_UNICODE_SCRIPT_BALINESE: Balinese
- * @G_UNICODE_SCRIPT_CUNEIFORM: Cuneiform
- * @G_UNICODE_SCRIPT_PHOENICIAN: Phoenician
- * @G_UNICODE_SCRIPT_PHAGS_PA: Phags-pa
- * @G_UNICODE_SCRIPT_NKO: N'Ko
- * @G_UNICODE_SCRIPT_KAYAH_LI: Kayah Li. Since 2.16.3
- * @G_UNICODE_SCRIPT_LEPCHA: Lepcha. Since 2.16.3
- * @G_UNICODE_SCRIPT_REJANG: Rejang. Since 2.16.3
- * @G_UNICODE_SCRIPT_SUNDANESE: Sundanese. Since 2.16.3
- * @G_UNICODE_SCRIPT_SAURASHTRA: Saurashtra. Since 2.16.3
- * @G_UNICODE_SCRIPT_CHAM: Cham. Since 2.16.3
- * @G_UNICODE_SCRIPT_OL_CHIKI: Ol Chiki. Since 2.16.3
- * @G_UNICODE_SCRIPT_VAI: Vai. Since 2.16.3
- * @G_UNICODE_SCRIPT_CARIAN: Carian. Since 2.16.3
- * @G_UNICODE_SCRIPT_LYCIAN: Lycian. Since 2.16.3
- * @G_UNICODE_SCRIPT_LYDIAN: Lydian. Since 2.16.3
- * @G_UNICODE_SCRIPT_AVESTAN: Avestan. Since 2.26
- * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26 Egyptian Hieroglpyhs. Since 2.26 Imperial Aramaic. Since 2.26 Inscriptional Pahlavi. Since 2.26 Inscriptional Parthian. Since 2.26
- * @G_UNICODE_SCRIPT_JAVANESE: Javanese. Since 2.26
- * @G_UNICODE_SCRIPT_KAITHI: Kaithi. Since 2.26
- * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26 Meetei Mayek. Since 2.26 Old South Arabian. Since 2.26
- * @G_UNICODE_SCRIPT_OLD_TURKIC: Old Turkic. Since 2.28
- * @G_UNICODE_SCRIPT_SAMARITAN: Samaritan. Since 2.26
- * @G_UNICODE_SCRIPT_TAI_THAM: Tai Tham. Since 2.26
- * @G_UNICODE_SCRIPT_TAI_VIET: Tai Viet. Since 2.26
- * @G_UNICODE_SCRIPT_BATAK: Batak. Since 2.28
- * @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
- * @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
- *
- * The #GUnicodeScript enumeration identifies different writing
- * systems. The values correspond to the names as defined in the
- * Unicode standard. The enumeration has been added in GLib 2.14,
- * and is interchangeable with #PangoScript.
- *
- * Note that new types may be added in the future. Applications
- * should be ready to handle unknown values.
- * See <ulink
- * url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
- * #24: Script names</ulink>.
- */
-
-
-/**
- * GUnicodeType:
- * @G_UNICODE_CONTROL: General category "Other, Control" (Cc)
- * @G_UNICODE_FORMAT: General category "Other, Format" (Cf)
- * @G_UNICODE_UNASSIGNED: General category "Other, Not Assigned" (Cn)
- * @G_UNICODE_PRIVATE_USE: General category "Other, Private Use" (Co)
- * @G_UNICODE_SURROGATE: General category "Other, Surrogate" (Cs)
- * @G_UNICODE_LOWERCASE_LETTER: General category "Letter, Lowercase" (Ll)
- * @G_UNICODE_MODIFIER_LETTER: General category "Letter, Modifier" (Lm)
- * @G_UNICODE_OTHER_LETTER: General category "Letter, Other" (Lo)
- * @G_UNICODE_TITLECASE_LETTER: General category "Letter, Titlecase" (Lt)
- * @G_UNICODE_UPPERCASE_LETTER: General category "Letter, Uppercase" (Lu)
- * @G_UNICODE_SPACING_MARK: General category "Mark, Spacing" (Mc)
- * @G_UNICODE_ENCLOSING_MARK: General category "Mark, Enclosing" (Me)
- * @G_UNICODE_NON_SPACING_MARK: General category "Mark, Nonspacing" (Mn)
- * @G_UNICODE_DECIMAL_NUMBER: General category "Number, Decimal Digit" (Nd)
- * @G_UNICODE_LETTER_NUMBER: General category "Number, Letter" (Nl)
- * @G_UNICODE_OTHER_NUMBER: General category "Number, Other" (No)
- * @G_UNICODE_CONNECT_PUNCTUATION: General category "Punctuation, Connector" (Pc)
- * @G_UNICODE_DASH_PUNCTUATION: General category "Punctuation, Dash" (Pd)
- * @G_UNICODE_CLOSE_PUNCTUATION: General category "Punctuation, Close" (Pe)
- * @G_UNICODE_FINAL_PUNCTUATION: General category "Punctuation, Final quote" (Pf)
- * @G_UNICODE_INITIAL_PUNCTUATION: General category "Punctuation, Initial quote" (Pi)
- * @G_UNICODE_OTHER_PUNCTUATION: General category "Punctuation, Other" (Po)
- * @G_UNICODE_OPEN_PUNCTUATION: General category "Punctuation, Open" (Ps)
- * @G_UNICODE_CURRENCY_SYMBOL: General category "Symbol, Currency" (Sc)
- * @G_UNICODE_MODIFIER_SYMBOL: General category "Symbol, Modifier" (Sk)
- * @G_UNICODE_MATH_SYMBOL: General category "Symbol, Math" (Sm)
- * @G_UNICODE_OTHER_SYMBOL: General category "Symbol, Other" (So)
- * @G_UNICODE_LINE_SEPARATOR: General category "Separator, Line" (Zl)
- * @G_UNICODE_PARAGRAPH_SEPARATOR: General category "Separator, Paragraph" (Zp)
- * @G_UNICODE_SPACE_SEPARATOR: General category "Separator, Space" (Zs)
- *
- * These are the possible character classifications from the
- * Unicode specification.
- * See <ulink url="http://www.unicode.org/Public/UNIDATA/UnicodeData.html">http://www.unicode.org/Public/UNIDATA/UnicodeData.html</ulink>.
- */
-
-
-/**
- * GUnixCredentialsMessage:
- *
- * The #GUnixCredentialsMessage structure contains only private data
- * and should only be accessed using the provided API.
- *
- * Since: 2.26
- */
-
-
-/**
- * GUnixCredentialsMessage:credentials:
- *
- * The credentials stored in the message.
- *
- * Since: 2.26
- */
-
-
-/**
- * GUnixCredentialsMessageClass:
- *
- * Class structure for #GUnixCredentialsMessage.
- *
- * Since: 2.26
- */
-
-
-/**
- * GUnixInputStream:
- *
- * Implements #GInputStream for reading from selectable unix file descriptors
- */
-
-
-/**
- * GUnixInputStream:close-fd:
- *
- * Whether to close the file descriptor when the stream is closed.
- *
- * Since: 2.20
- */
-
-
-/**
- * GUnixInputStream:fd:
- *
- * The file descriptor that the stream reads from.
- *
- * Since: 2.20
- */
-
-
-/**
- * GUnixMountEntry:
- *
- * Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>).
- * This corresponds roughly to a mtab entry.
- */
-
-
-/**
- * GUnixMountMonitor:
- *
- * Watches #GUnixMount<!-- -->s for changes.
- */
-
-
-/**
- * GUnixMountMonitor::mountpoints-changed:
- * @monitor: the object on which the signal is emitted
- *
- * Emitted when the unix mount points have changed.
- */
-
-
-/**
- * GUnixMountMonitor::mounts-changed:
- * @monitor: the object on which the signal is emitted
- *
- * Emitted when the unix mounts have changed.
- */
-
-
-/**
- * GUnixMountPoint:
- *
- * Defines a Unix mount point (e.g. <filename>/dev</filename>).
- * This corresponds roughly to a fstab entry.
- */
-
-
-/**
- * GUnixOutputStream:
- *
- * Implements #GOutputStream for outputting to selectable unix file descriptors
- */
-
-
-/**
- * GUnixOutputStream:close-fd:
- *
- * Whether to close the file descriptor when the stream is closed.
- *
- * Since: 2.20
- */
-
-
-/**
- * GUnixOutputStream:fd:
- *
- * The file descriptor that the stream writes to.
- *
- * Since: 2.20
- */
-
-
-/**
- * GUnixSocketAddress:
- *
- * A UNIX-domain (local) socket address, corresponding to a
- * <type>struct sockaddr_un</type>.
- */
-
-
-/**
- * GUnixSocketAddress:abstract:
- *
- * Whether or not this is an abstract address
- *
- * distinguishes between zero-padded and non-zero-padded
- * abstract addresses.
- *
- * Deprecated: Use #GUnixSocketAddress:address-type, which
- */
-
-
-/**
- * GUnixSocketAddressType:
- * @G_UNIX_SOCKET_ADDRESS_INVALID: invalid
- * @G_UNIX_SOCKET_ADDRESS_ANONYMOUS: anonymous
- * @G_UNIX_SOCKET_ADDRESS_PATH: a filesystem path
- * @G_UNIX_SOCKET_ADDRESS_ABSTRACT: an abstract name
- * @G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED: an abstract name, 0-padded to the full length of a unix socket name
- *
- * The type of name used by a #GUnixSocketAddress.
- * %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain
- * socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS
- * indicates a socket not bound to any name (eg, a client-side socket,
- * or a socket created with socketpair()).
- *
- * For abstract sockets, there are two incompatible ways of naming
- * them; the man pages suggest using the entire <literal>struct
- * sockaddr_un</literal> as the name, padding the unused parts of the
- * %sun_path field with zeroes; this corresponds to
- * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs
- * instead just use a portion of %sun_path, and pass an appropriate
- * smaller length to bind() or connect(). This is
- * %G_UNIX_SOCKET_ADDRESS_ABSTRACT.
- *
- * Since: 2.26
- */
-
-
-/**
- * GUserDirectory:
- * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory
- * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory
- * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory
- * @G_USER_DIRECTORY_MUSIC: the user's Music directory
- * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory
- * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory
- * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory
- * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory
- * @G_USER_N_DIRECTORIES: the number of enum values
- *
- * These are logical ids for special directories which are defined
- * depending on the platform used. You should use g_get_user_special_dir()
- * to retrieve the full path associated to the logical id.
- *
- * The #GUserDirectory enumeration can be extended at later date. Not
- * every platform has a directory for every logical id in this
- * enumeration.
- *
- * Since: 2.14
- */
-
-
-/**
- * GValue:
- *
- * An opaque structure used to hold different types of values.
- * The data within the structure has protected scope: it is accessible only
- * to functions within a #GTypeValueTable structure, or implementations of
- * the g_value_*() API. That is, code portions which implement new fundamental
- * types.
- * #GValue users cannot make any assumptions about how data is stored
- * within the 2 element @data union, and the @g_type member should
- * only be accessed through the G_VALUE_TYPE() macro.
- */
-
-
-/**
- * GValueArray:
- * @n_values: number of values contained in the array
- * @values: array of values
- *
- * A #GValueArray contains an array of #GValue elements.
- */
-
-
-/**
- * GValueTransform:
- * @src_value: Source value.
- * @dest_value: Target value.
- *
- * The type of value transformation functions which can be registered with
- * g_value_register_transform_func().
- */
-
-
-/**
- * GVariantType:
- *
- * A type in the GVariant type system.
- *
- * Two types may not be compared by value; use g_variant_type_equal() or
- * g_variant_type_is_subtype_of(). May be copied using
- * g_variant_type_copy() and freed using g_variant_type_free().
- */
-
-
-/**
- * GVfs:
- *
- * Virtual File System object.
- */
-
-
-/**
- * GVoidFunc:
- *
- * Declares a type of function which takes no arguments
- * and has no return value. It is used to specify the type
- * function passed to g_atexit().
- */
-
-
-/**
- * GVolume:
- *
- * Opaque mountable volume object.
- */
-
-
-/**
- * GVolume::changed:
- *
- * Emitted when the volume has been changed.
- */
-
-
-/**
- * GVolume::removed:
- *
- * This signal is emitted when the #GVolume have been removed. If
- * the recipient is holding references to the object they should
- * release them so the object can be finalized.
- */
-
-
-/**
- * GVolumeIface:
- * @g_iface: The parent interface.
- * @changed: Changed signal that is emitted when the volume's state has changed.
- * @removed: The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.
- * @get_name: Gets a string containing the name of the #GVolume.
- * @get_icon: Gets a #GIcon for the #GVolume.
- * @get_uuid: Gets the UUID for the #GVolume. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
- * @get_drive: Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive.
- * @get_mount: Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted.
- * @can_mount: Returns %TRUE if the #GVolume can be mounted.
- * @can_eject: Checks if a #GVolume can be ejected.
- * @mount_fn: Mounts a given #GVolume. #GVolume implementations must emit the #GMountOperation::aborted signal before completing a mount operation that is aborted while awaiting input from the user through a #GMountOperation instance.
- * @mount_finish: Finishes a mount operation.
- * @eject: Ejects a given #GVolume.
- * @eject_finish: Finishes an eject operation.
- * @get_identifier: Returns the <link linkend="volume-identifier">identifier</link> of the given kind, or %NULL if the #GVolume doesn't have one.
- * @enumerate_identifiers: Returns an array strings listing the kinds of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
- * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
- * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if it is not known.
- * @eject_with_operation: Starts ejecting a #GVolume using a #GMountOperation. Since 2.22.
- * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
- * @get_sort_key: Gets a key used for sorting #GVolume instance or %NULL if no such key exists. Since 2.32.
- *
- * Interface for implementing operations for mountable volumes.
- */
-
-
-/**
- * GVolumeMonitor:
- *
- * A Volume Monitor that watches for volume events.
- */
-
-
-/**
- * GVolumeMonitor::drive-changed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: the drive that changed
- *
- * Emitted when a drive changes.
- */
-
-
-/**
- * GVolumeMonitor::drive-connected:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: a #GDrive that was connected.
- *
- * Emitted when a drive is connected to the system.
- */
-
-
-/**
- * GVolumeMonitor::drive-disconnected:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: a #GDrive that was disconnected.
- *
- * Emitted when a drive is disconnected from the system.
- */
-
-
-/**
- * GVolumeMonitor::drive-eject-button:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: the drive where the eject button was pressed
- *
- * Emitted when the eject button is pressed on @drive.
- *
- * Since: 2.18
- */
-
-
-/**
- * GVolumeMonitor::drive-stop-button:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: the drive where the stop button was pressed
- *
- * Emitted when the stop button is pressed on @drive.
- *
- * Since: 2.22
- */
-
-
-/**
- * GVolumeMonitor::mount-added:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that was added.
- *
- * Emitted when a mount is added.
- */
-
-
-/**
- * GVolumeMonitor::mount-changed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that changed.
- *
- * Emitted when a mount changes.
- */
-
-
-/**
- * GVolumeMonitor::mount-pre-unmount:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that is being unmounted.
- *
- * Emitted when a mount is about to be removed.
- */
-
-
-/**
- * GVolumeMonitor::mount-removed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that was removed.
+ * g_list_free (self->priv->init_results);
+ * self->priv->init_results = NULL;
+ * }
*
- * Emitted when a mount is removed.
- */
-
-
-/**
- * GVolumeMonitor::volume-added:
- * @volume_monitor: The volume monitor emitting the signal.
- * @volume: a #GVolume that was added.
+ * static void
+ * foo_init_async (GAsyncInitable *initable,
+ * int io_priority,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * Foo *self = FOO (initable);
+ * GTask *task;
+ *
+ * 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,
+ * task);
+ * self->priv->state = INITIALIZING;
+ * break;
+ * case INITIALIZING:
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * task);
+ * break;
+ * case INITIALIZED:
+ * if (!self->priv->success)
+ * g_task_return_new_error (task, ...);
+ * else
+ * g_task_return_boolean (task, TRUE);
+ * g_object_unref (task);
+ * break;
+ * }
+ * }
*
- * Emitted when a mountable volume is added to the system.
- */
-
-
-/**
- * GVolumeMonitor::volume-changed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @volume: a #GVolume that changed.
+ * static gboolean
+ * foo_init_finish (GAsyncInitable *initable,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
*
- * Emitted when mountable volume is changed.
- */
-
-
-/**
- * GVolumeMonitor::volume-removed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @volume: a #GVolume that was removed.
+ * return g_task_propagate_boolean (G_TASK (result), error);
+ * }
*
- * Emitted when a mountable volume is removed from the system.
- */
-
-
-/**
- * GWeakNotify:
- * @data: data that was provided when the weak reference was established
- * @where_the_object_was: the object being finalized
+ * static void
+ * foo_async_initable_iface_init (gpointer g_iface,
+ * gpointer data)
+ * {
+ * GAsyncInitableIface *iface = g_iface;
*
- * A #GWeakNotify function can be added to an object as a callback that gets
- * triggered when the object is finalized. Since the object is already being
- * finalized when the #GWeakNotify is called, there's not much you could do
- * with the object, apart from e.g. using its address as hash-index or the like.
+ * iface->init_async = foo_init_async;
+ * iface->init_finish = foo_init_finish;
+ * }
+ * ]|
*/
/**
- * GWin32InputStream:close-handle:
+ * SECTION:gasyncresult
+ * @short_description: Asynchronous Function Results
+ * @include: gio/gio.h
+ * @see_also: #GTask
*
- * Whether to close the file handle when the stream is closed.
+ * Provides a base class for implementing asynchronous function results.
*
- * Since: 2.26
- */
-
-
-/**
- * GWin32InputStream:handle:
+ * Asynchronous operations are broken up into two separate operations
+ * which are chained together by a #GAsyncReadyCallback. To begin
+ * an asynchronous operation, provide a #GAsyncReadyCallback to the
+ * asynchronous function. This callback will be triggered when the
+ * operation has completed, and will be passed a #GAsyncResult instance
+ * filled with the details of the operation's success or failure, the
+ * object the asynchronous function was started for and any error codes
+ * returned. The asynchronous callback function is then expected to call
+ * the corresponding "_finish()" function, passing the object the
+ * function was called for, the #GAsyncResult instance, and (optionally)
+ * an @error to grab any error conditions that may have occurred.
*
- * The handle that the stream reads from.
+ * The "_finish()" function for an operation takes the generic result
+ * (of type #GAsyncResult) and returns the specific result that the
+ * operation in question yields (e.g. a #GFileEnumerator for a
+ * "enumerate children" operation). If the result or error status of the
+ * operation is not needed, there is no need to call the "_finish()"
+ * function; GIO will take care of cleaning up the result and error
+ * information after the #GAsyncReadyCallback returns. You can pass
+ * %NULL for the #GAsyncReadyCallback if you don't need to take any
+ * action at all after the operation completes. Applications may also
+ * take a reference to the #GAsyncResult and call "_finish()" later;
+ * however, the "_finish()" function may be called at most once.
*
- * Since: 2.26
- */
-
-
-/**
- * GWin32OutputStream:close-handle:
+ * Example of a typical asynchronous operation flow:
+ * |[<!-- language="C" -->
+ * void _theoretical_frobnitz_async (Theoretical *t,
+ * GCancellable *c,
+ * GAsyncReadyCallback cb,
+ * gpointer u);
*
- * Whether to close the file handle when the stream is closed.
+ * gboolean _theoretical_frobnitz_finish (Theoretical *t,
+ * GAsyncResult *res,
+ * GError **e);
*
- * Since: 2.26
- */
-
-
-/**
- * GWin32OutputStream:handle:
+ * static void
+ * frobnitz_result_func (GObject *source_object,
+ * GAsyncResult *res,
+ * gpointer user_data)
+ * {
+ * gboolean success = FALSE;
*
- * The file handle that the stream writes to.
+ * success = _theoretical_frobnitz_finish (source_object, res, NULL);
*
- * Since: 2.26
- */
-
-
-/**
- * GZlibCompressor:
+ * if (success)
+ * g_printf ("Hurray!\n");
+ * else
+ * g_printf ("Uh oh!\n");
*
- * Zlib decompression
- */
-
-
-/**
- * GZlibCompressor:file-info:
+ * ...
*
- * 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.
+ * }
*
- * Since: 2.26
- */
-
-
-/**
- * GZlibCompressorFormat:
- * @G_ZLIB_COMPRESSOR_FORMAT_ZLIB: deflate compression with zlib header
- * @G_ZLIB_COMPRESSOR_FORMAT_GZIP: gzip file format
- * @G_ZLIB_COMPRESSOR_FORMAT_RAW: deflate compression with no header
+ * int main (int argc, void *argv[])
+ * {
+ * ...
*
- * Used to select the type of data format to use for #GZlibDecompressor
- * and #GZlibCompressor.
+ * _theoretical_frobnitz_async (theoretical_data,
+ * NULL,
+ * frobnitz_result_func,
+ * NULL);
*
- * Since: 2.24
- */
-
-
-/**
- * GZlibDecompressor:
+ * ...
+ * }
+ * ]|
*
- * Zlib decompression
- */
-
-
-/**
- * GZlibDecompressor:file-info:
+ * 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.
*
- * A #GFileInfo containing the information found in the GZIP header
- * of the data stream processed, or %NULL if the header was not yet
- * fully processed, is not present at all, or the compressor's
- * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
+ * ## I/O Priority # {#io-priority}
*
- * Since: 2.26
+ * 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.
*/
/**
- * G_BOOKMARK_FILE_ERROR:
+ * SECTION:gbufferedinputstream
+ * @short_description: Buffered Input Stream
+ * @include: gio/gio.h
+ * @see_also: #GFilterInputStream, #GInputStream
*
- * Error domain for bookmark file parsing.
- * Errors in this domain will be from the #GBookmarkFileError
- * enumeration. See #GError for information on error domains.
- */
-
-
-/**
- * G_BREAKPOINT:
+ * Buffered input stream implements #GFilterInputStream and provides
+ * for buffered reads.
*
- * Inserts a breakpoint instruction into the code.
+ * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
*
- * On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
- */
-
-
-/**
- * G_CALLBACK:
- * @f: a function pointer.
+ * To create a buffered input stream, use g_buffered_input_stream_new(),
+ * or g_buffered_input_stream_new_sized() to specify the buffer's size at
+ * construction.
*
- * Cast a function pointer to a #GCallback.
+ * To get the size of a buffer within a buffered input stream, use
+ * g_buffered_input_stream_get_buffer_size(). To change the size of a
+ * buffered input stream's buffer, use
+ * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
+ * cannot be reduced below the size of the data within the buffer.
*/
/**
- * G_CCLOSURE_SWAP_DATA:
- * @cclosure: a #GCClosure
- *
- * Checks whether the user data of the #GCClosure should be passed as the
- * first parameter to the callback. See g_cclosure_new_swap().
+ * SECTION:gbufferedoutputstream
+ * @short_description: Buffered Output Stream
+ * @include: gio/gio.h
+ * @see_also: #GFilterOutputStream, #GOutputStream
*
- * Returns: %TRUE if data has to be swapped.
- */
-
-
-/**
- * G_CLOSURE_NEEDS_MARSHAL:
- * @closure: a #GClosure
+ * Buffered output stream implements #GFilterOutputStream and provides
+ * for buffered writes.
*
- * Check if the closure still needs a marshaller. See g_closure_set_marshal().
+ * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
*
- * @closure.
+ * To create a buffered output stream, use g_buffered_output_stream_new(),
+ * or g_buffered_output_stream_new_sized() to specify the buffer's size
+ * at construction.
*
- * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
+ * To get the size of a buffer within a buffered input stream, use
+ * g_buffered_output_stream_get_buffer_size(). To change the size of a
+ * buffered output stream's buffer, use
+ * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
+ * size cannot be reduced below the size of the data within the buffer.
*/
/**
- * G_CLOSURE_N_NOTIFIERS:
- * @cl: a #GClosure
+ * SECTION:gbytesicon
+ * @short_description: An icon stored in memory as a GBytes
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon, #GBytes
*
- * Get the total number of notifiers connected with the closure @cl.
- * The count includes the meta marshaller, the finalize and invalidate notifiers
- * and the marshal guards. Note that each guard counts as two notifiers.
- * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
- * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().
+ * #GBytesIcon specifies an image held in memory in a common format (usually
+ * png) to be used as icon.
*
- * Returns: number of notifiers
+ * Since: 2.38
*/
/**
- * G_CONVERT_ERROR:
+ * SECTION:gcancellable
+ * @short_description: Thread-safe Operation Cancellation Stack
+ * @include: gio/gio.h
*
- * Error domain for character set conversions. Errors in this domain will
- * be from the #GConvertError enumeration. See #GError for information on
- * error domains.
+ * GCancellable is a thread-safe operation cancellation stack used
+ * throughout GIO to allow for cancellation of synchronous and
+ * asynchronous operations.
*/
/**
- * G_DATALIST_FLAGS_MASK:
+ * SECTION:gcharsetconverter
+ * @short_description: Convert between charsets
+ * @include: gio/gio.h
*
- * A bitmask that restricts the possible flags passed to
- * g_datalist_set_flags(). Passing a flags value where
- * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.
+ * #GCharsetConverter is an implementation of #GConverter based on
+ * GIConv.
*/
/**
- * G_DBUS_ERROR:
- *
- * Error domain for errors generated by a remote message bus. Errors
- * in this domain will be from the #GDBusError enumeration. See
- * #GError for more information on error domains.
- *
- * Note that errors in this error domain is intended only for
- * returning errors from a remote message bus process. Errors
- * generated locally in-process by e.g. #GDBusConnection is from the
- * %G_IO_ERROR domain.
+ * SECTION:gcontenttype
+ * @short_description: Platform-specific content typing
+ * @include: gio/gio.h
*
- * Since: 2.26
+ * A content type is a platform specific string that defines the type
+ * 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.
*/
/**
- * G_DEFINE_ABSTRACT_TYPE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- *
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE(), but defines an abstract type.
- * See G_DEFINE_TYPE_EXTENDED() for an example.
+ * SECTION:gconverter
+ * @short_description: Data conversion interface
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
*
- * Since: 2.4
- */
-
-
-/**
- * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
+ * #GConverter is implemented by objects that convert
+ * binary data in various ways. The conversion can be
+ * stateful and may fail at any place.
*
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to
- * insert custom code into the *_get_type() function, e.g. interface implementations
- * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
+ * Some example conversions are: character set conversion,
+ * compression, decompression and regular expression
+ * replace.
*
- * Since: 2.4
+ * Since: 2.24
*/
/**
- * G_DEFINE_BOXED_TYPE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @copy_func: the #GBoxedCopyFunc for the new type
- * @free_func: the #GBoxedFreeFunc for the new type
+ * SECTION:gconverterinputstream
+ * @short_description: Converter Input Stream
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GConverter
*
- * A convenience macro for boxed type implementations, which defines a
- * type_name_get_type() function registering the boxed type.
+ * Converter input stream implements #GInputStream and allows
+ * conversion of data of various types during reading.
*
- * Since: 2.26
+ * As of GLib 2.34, #GConverterInputStream implements
+ * #GPollableInputStream.
*/
/**
- * G_DEFINE_BOXED_TYPE_WITH_CODE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @copy_func: the #GBoxedCopyFunc for the new type
- * @free_func: the #GBoxedFreeFunc for the new type
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ * SECTION:gconverteroutputstream
+ * @short_description: Converter Output Stream
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream, #GConverter
*
- * A convenience macro for boxed type implementations.
- * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
- * type_name_get_type() function, e.g. to register value transformations with
- * g_value_register_transform_func().
+ * Converter output stream implements #GOutputStream and allows
+ * conversion of data of various types during reading.
*
- * Since: 2.26
+ * As of GLib 2.34, #GConverterOutputStream implements
+ * #GPollableOutputStream.
*/
/**
- * G_DEFINE_DYNAMIC_TYPE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- *
- * A convenience macro for dynamic type implementations, which declares a
- * class initialization function, an instance initialization function (see
- * #GTypeInfo for information about these) and a static variable named
- * @t_n<!-- -->_parent_class pointing to the parent class. Furthermore,
- * it defines a <function>*_get_type()</function> and a static
- * <function>*_register_type()</function> function for use in your
- * <function>module_init()</function>.
- * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
+ * SECTION:gcredentials
+ * @short_description: An object containing credentials
+ * @include: gio/gio.h
*
- * Since: 2.14
- */
-
-
-/**
- * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @TYPE_PARENT: The #GType of the parent type.
- * @flags: #GTypeFlags to pass to g_type_module_register_type()
- * @CODE: Custom code that gets inserted in the *_get_type() function.
+ * The #GCredentials type is a reference-counted wrapper for native
+ * credentials. This information is typically used for identifying,
+ * authenticating and authorizing other processes.
*
- * A more general version of G_DEFINE_DYNAMIC_TYPE() which
- * allows to specify #GTypeFlags and custom code.
+ * Some operating systems supports looking up the credentials of the
+ * remote peer of a communication endpoint - see e.g.
+ * g_socket_get_credentials().
*
- * |[
- * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_THING,
- * 0,
- * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
- * ]|
- * expands to
- * |[
- * static void gtk_gadget_init (GtkGadget *self);
- * static void gtk_gadget_class_init (GtkGadgetClass *klass);
- * static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
+ * Some operating systems supports securely sending and receiving
+ * credentials over a Unix Domain Socket, see
+ * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
+ * g_unix_connection_receive_credentials() for details.
*
- * static gpointer gtk_gadget_parent_class = NULL;
- * static GType gtk_gadget_type_id = 0;
+ * 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.
*
- * static void gtk_gadget_class_intern_init (gpointer klass)
- * {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
- * }
+ * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
+ * credential type is a struct cmsgcred. This corresponds
+ * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
*
- * GType
- * gtk_gadget_get_type (void)
- * {
- * return gtk_gadget_type_id;
- * }
+ * On NetBSD, the native credential type is a struct unpcbid.
+ * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
*
- * static void
- * gtk_gadget_register_type (GTypeModule *type_module)
- * {
- * const GTypeInfo g_define_type_info = {
- * sizeof (GtkGadgetClass),
- * (GBaseInitFunc) NULL,
- * (GBaseFinalizeFunc) NULL,
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * (GClassFinalizeFunc) gtk_gadget_class_finalize,
- * NULL, // class_data
- * sizeof (GtkGadget),
- * 0, // n_preallocs
- * (GInstanceInitFunc) gtk_gadget_init,
- * NULL // value_table
- * };
- * gtk_gadget_type_id = g_type_module_register_type (type_module,
- * GTK_TYPE_THING,
- * GtkGadget,
- * &g_define_type_info,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * }
- * ]|
+ * On OpenBSD, the native credential type is a struct sockpeercred.
+ * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
*
- * Since: 2.14
+ * On Solaris (including OpenSolaris and its derivatives), the native
+ * credential type is a ucred_t. This corresponds to
+ * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
*/
/**
- * G_DEFINE_INTERFACE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
- *
- * A convenience macro for #GTypeInterface definitions, which declares
- * a default vtable initialization function and defines a *_get_type()
- * function.
- *
- * The macro expects the interface initialization function to have the
- * name <literal>t_n ## _default_init</literal>, and the interface
- * structure to have the name <literal>TN ## Interface</literal>.
+ * SECTION:gdatainputstream
+ * @short_description: Data Input Stream
+ * @include: gio/gio.h
+ * @see_also: #GInputStream
*
- * Since: 2.24
+ * Data input stream implements #GInputStream and includes functions for
+ * reading structured data directly from a binary input stream.
*/
/**
- * G_DEFINE_INTERFACE_WITH_CODE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
- *
- * A convenience macro for #GTypeInterface definitions. Similar to
- * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
- * *_get_type() function, e.g. additional interface implementations
- * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
- * G_DEFINE_TYPE_EXTENDED() for a similar example using
- * G_DEFINE_TYPE_WITH_CODE().
+ * SECTION:gdataoutputstream
+ * @short_description: Data Output Stream
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream
*
- * Since: 2.24
+ * Data output stream implements #GOutputStream and includes functions for
+ * writing data directly to an output stream.
*/
/**
- * G_DEFINE_POINTER_TYPE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- *
- * A convenience macro for pointer type implementations, which defines a
- * type_name_get_type() function registering the pointer type.
+ * SECTION:gdbusactiongroup
+ * @title: GDBusActionGroup
+ * @short_description: A D-Bus GActionGroup implementation
+ * @include: gio/gio.h
+ * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter]
*
- * Since: 2.26
+ * #GDBusActionGroup is an implementation of the #GActionGroup
+ * interface that can be used as a proxy for an action group
+ * that is exported over D-Bus with g_dbus_connection_export_action_group().
*/
/**
- * G_DEFINE_POINTER_TYPE_WITH_CODE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
- *
- * A convenience macro for pointer type implementations.
- * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the
- * type_name_get_type() function.
+ * SECTION:gdbusaddress
+ * @title: D-Bus Addresses
+ * @short_description: D-Bus connection endpoints
+ * @include: gio/gio.h
*
- * Since: 2.26
+ * 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 [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses).
*/
/**
- * G_DEFINE_TYPE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
+ * SECTION:gdbusauthobserver
+ * @short_description: Object used for authenticating connections
+ * @include: gio/gio.h
+ *
+ * The #GDBusAuthObserver type provides a mechanism for participating
+ * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
+ * peers. Simply instantiate a #GDBusAuthObserver and connect to the
+ * signals you are interested in. Note that new signals may be added
+ * in the future
+ *
+ * ## Controlling Authentication # {#auth-observer}
*
- * A convenience macro for type implementations, which declares a
- * class initialization function, an instance initialization function (see #GTypeInfo for information about
- * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
- * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
+ * 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:
*
- * Since: 2.4
+ * |[<!-- language="C" -->
+ * static gboolean
+ * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
+ * GIOStream *stream,
+ * GCredentials *credentials,
+ * gpointer user_data)
+ * {
+ * gboolean authorized;
+ *
+ * authorized = FALSE;
+ * if (credentials != NULL)
+ * {
+ * GCredentials *own_credentials;
+ * own_credentials = g_credentials_new ();
+ * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
+ * authorized = TRUE;
+ * g_object_unref (own_credentials);
+ * }
+ *
+ * return authorized;
+ * }
+ * ]|
*/
/**
- * G_DEFINE_TYPE_EXTENDED:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- * @_f_: #GTypeFlags to pass to g_type_register_static()
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ * SECTION:gdbusconnection
+ * @short_description: D-Bus Connections
+ * @include: gio/gio.h
*
- * The most general convenience macro for type implementations, on which
- * G_DEFINE_TYPE(), etc are based.
+ * The #GDBusConnection type is used for D-Bus connections to remote
+ * peers such as a message buses. It is a low-level API that offers a
+ * lot of flexibility. For instance, it lets you establish a connection
+ * over any transport that can by represented as an #GIOStream.
*
- * |[
- * G_DEFINE_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_WIDGET,
- * 0,
- * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
- * ]|
- * expands to
- * |[
- * static void gtk_gadget_init (GtkGadget *self);
- * static void gtk_gadget_class_init (GtkGadgetClass *klass);
- * static gpointer gtk_gadget_parent_class = NULL;
- * static void gtk_gadget_class_intern_init (gpointer klass)
- * {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
- * }
+ * This class is rarely used directly in D-Bus clients. If you are writing
+ * 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. 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
+ * g_bus_get(), and the synchronous versions of those methods, give you an
+ * initialized connection. Language bindings for GIO should use
+ * g_initable_new() or g_async_initable_new_async(), which also initialize the
+ * connection.
+ *
+ * If you construct an uninitialized #GDBusConnection, such as via
+ * g_object_new(), you must initialize it via g_initable_init() or
+ * g_async_initable_init_async() before using its methods or properties.
+ * Calling methods or accessing properties on a #GDBusConnection that has not
+ * completed initialization successfully is considered to be invalid, and leads
+ * to undefined behaviour. In particular, if initialization fails with a
+ * #GError, the only valid thing you can do with that #GDBusConnection is to
+ * free it with g_object_unref().
*
- * GType
- * gtk_gadget_get_type (void)
- * {
- * static volatile gsize g_define_type_id__volatile = 0;
- * if (g_once_init_enter (&g_define_type_id__volatile))
- * {
- * GType g_define_type_id =
- * g_type_register_static_simple (GTK_TYPE_WIDGET,
- * g_intern_static_string ("GtkGadget"),
- * sizeof (GtkGadgetClass),
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * sizeof (GtkGadget),
- * (GInstanceInitFunc) gtk_gadget_init,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
- * }
- * return g_define_type_id__volatile;
- * }
- * ]|
- * The only pieces which have to be manually provided are the definitions of
- * the instance and class structure and the definitions of the instance and
- * class init functions.
+ * ## An example D-Bus server # {#gdbus-server}
*
- * Since: 2.4
- */
-
-
-/**
- * G_DEFINE_TYPE_WITH_CODE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ * 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)
*
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
- * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
- * See G_DEFINE_TYPE_EXTENDED() for an example.
+ * ## An example for exporting a subtree # {#gdbus-subtree-server}
*
- * Since: 2.4
- */
-
-
-/**
- * G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME:
+ * 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)
*
- * Extension point for default handler to URI association. See
- * <link linkend="extending-gio">Extending GIO</link>.
- */
-
-
-/**
- * G_ENUM_CLASS:
- * @class: a valid #GEnumClass
+ * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
*
- * Casts a derived #GEnumClass structure into a #GEnumClass structure.
- */
-
-
-/**
- * G_ENUM_CLASS_TYPE:
- * @class: a #GEnumClass
+ * 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)
*
- * Get the type identifier from a given #GEnumClass structure.
+ * ## An example for exporting a GObject # {#gdbus-export}
*
- * Returns: the #GType
+ * 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)
*/
/**
- * G_ENUM_CLASS_TYPE_NAME:
- * @class: a #GEnumClass
+ * SECTION:gdbuserror
+ * @title: GDBusError
+ * @short_description: Mapping D-Bus errors to and from GError
+ * @include: gio/gio.h
*
- * Get the static type name from a given #GEnumClass structure.
+ * All facilities that return errors from remote methods (such as
+ * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
+ * errors (e.g. errors returned from the other peer) and locally
+ * in-process generated errors.
*
- * Returns: the type name.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
+ * To check if a returned #GError is an error from a remote peer, use
+ * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
+ * use g_dbus_error_get_remote_error(). Before presenting an error,
+ * always use g_dbus_error_strip_remote_error().
*
- * A key in the "access" namespace for checking deletion privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to delete the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
+ * In addition, facilities used to return errors to a remote peer also
+ * use #GError. See g_dbus_method_invocation_return_error() for
+ * discussion about how the D-Bus error name is set.
*
- * A key in the "access" namespace for getting execution privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to execute the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
+ * Applications can associate a #GError error domain with a set of D-Bus errors in order to
+ * automatically map from D-Bus errors to #GError and back. This
+ * is typically done in the function returning the #GQuark for the
+ * error domain:
+ * |[<!-- language="C" -->
+ * // foo-bar-error.h:
*
- * A key in the "access" namespace for getting read privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to read the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
+ * #define FOO_BAR_ERROR (foo_bar_error_quark ())
+ * GQuark foo_bar_error_quark (void);
*
- * A key in the "access" namespace for checking renaming privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to rename the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
+ * typedef enum
+ * {
+ * FOO_BAR_ERROR_FAILED,
+ * FOO_BAR_ERROR_ANOTHER_ERROR,
+ * FOO_BAR_ERROR_SOME_THIRD_ERROR,
+ * FOO_BAR_N_ERRORS / *< skip >* /
+ * } FooBarError;
*
- * A key in the "access" namespace for checking trashing privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to move the file to
- * the trash.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
+ * // foo-bar-error.c:
*
- * A key in the "access" namespace for getting write privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to write to the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
+ * static const GDBusErrorEntry foo_bar_error_entries[] =
+ * {
+ * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
+ * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
+ * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
+ * };
*
- * A key in the "dos" namespace for checking if the file's archive flag
- * is set. This attribute is %TRUE if the archive flag is set. This attribute
- * is only available for DOS file systems. Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
+ * // 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);
*
- * A key in the "dos" namespace for checking if the file's backup flag
- * is set. This attribute is %TRUE if the backup flag is set. This attribute
- * is only available for DOS file systems. Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ETAG_VALUE:
+ * GQuark
+ * foo_bar_error_quark (void)
+ * {
+ * static volatile gsize quark_volatile = 0;
+ * g_dbus_error_register_error_domain ("foo-bar-error-quark",
+ * &quark_volatile,
+ * foo_bar_error_entries,
+ * G_N_ELEMENTS (foo_bar_error_entries));
+ * return (GQuark) quark_volatile;
+ * }
+ * ]|
+ * 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 org.project.Foo.Bar.Error.AnotherError.
*
- * A key in the "etag" namespace for getting the value of the file's
- * entity tag. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_FREE:
+ * 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
+ * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
*
- * A key in the "filesystem" namespace for getting the number of bytes of free space left on the
- * file system. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * Note that errors in the %G_DBUS_ERROR error domain is intended only
+ * for returning errors from a remote message bus process. Errors
+ * generated locally in-process by e.g. #GDBusConnection is from the
+ * %G_IO_ERROR domain.
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_READONLY:
+ * SECTION:gdbusinterface
+ * @short_description: Base type for D-Bus interfaces
+ * @include: gio/gio.h
*
- * A key in the "filesystem" namespace for checking if the file system
- * is read only. Is set to %TRUE if the file system is read only.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * The #GDBusInterface type is the base type for D-Bus interfaces both
+ * on the service side (see #GDBusInterfaceSkeleton) and client side
+ * (see #GDBusProxy).
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE:
+ * SECTION:gdbusinterfaceskeleton
+ * @short_description: Service-side D-Bus interface
+ * @include: gio/gio.h
*
- * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system,
- * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * Abstract base class for D-Bus interfaces on the service side.
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE:
+ * SECTION:gdbusintrospection
+ * @title: D-Bus Introspection Data
+ * @short_description: Node and interface description data structures
+ * @include: gio/gio.h
+ *
+ * Various data structures and convenience routines to parse and
+ * generate D-Bus introspection XML. Introspection information is
+ * used when registering objects with g_dbus_connection_register_object().
*
- * A key in the "filesystem" namespace for getting the file system's type.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * The format of D-Bus introspection XML is specified in the
+ * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW:
+ * SECTION:gdbusmenumodel
+ * @title: GDBusMenuModel
+ * @short_description: A D-Bus GMenuModel implementation
+ * @include: gio/gio.h
+ * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter]
*
- * A key in the "filesystem" namespace for hinting a file manager
- * application whether it should preview (e.g. thumbnail) files on the
- * file system. The value for this key contain a
- * #GFilesystemPreviewType.
+ * #GDBusMenuModel is an implementation of #GMenuModel that can be used
+ * as a proxy for a menu model that is exported over D-Bus with
+ * g_dbus_connection_export_menu_model().
*/
/**
- * G_FILE_ATTRIBUTE_GVFS_BACKEND:
+ * SECTION:gdbusmessage
+ * @short_description: D-Bus Message
+ * @include: gio/gio.h
*
- * A key in the "gvfs" namespace that gets the name of the current
- * GVFS backend in use. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A type for representing D-Bus messages that can be sent or received
+ * on a #GDBusConnection.
*/
/**
- * G_FILE_ATTRIBUTE_ID_FILE:
+ * SECTION:gdbusmethodinvocation
+ * @short_description: Object for handling remote calls
+ * @include: gio/gio.h
*
- * A key in the "id" namespace for getting a file identifier.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- * An example use would be during listing files, to avoid recursive
- * directory scanning.
+ * Instances of the #GDBusMethodInvocation class are used when
+ * handling D-Bus method calls. It provides a way to asynchronously
+ * return results and errors.
+ *
+ * The normal way to obtain a #GDBusMethodInvocation object is to receive
+ * it as an argument to the handle_method_call() function in a
+ * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
*/
/**
- * G_FILE_ATTRIBUTE_ID_FILESYSTEM:
+ * SECTION:gdbusnameowning
+ * @title: Owning Bus Names
+ * @short_description: Simple API for owning bus names
+ * @include: gio/gio.h
+ *
+ * Convenience API for owning bus names.
*
- * A key in the "id" namespace for getting the file system identifier.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- * An example use would be during drag and drop to see if the source
- * and target are on the same filesystem (default to move) or not (default
- * to copy).
+ * 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)
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT:
+ * SECTION:gdbusnamewatching
+ * @title: Watching Bus Names
+ * @short_description: Simple API for watching bus names
+ * @include: gio/gio.h
+ *
+ * Convenience API for watching bus names.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * 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)
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
+ * SECTION:gdbusobject
+ * @short_description: Base type for D-Bus objects
+ * @include: gio/gio.h
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * The #GDBusObject type is the base type for D-Bus objects on both
+ * the service side (see #GDBusObjectSkeleton) and the client side
+ * (see #GDBusObjectProxy). It is essentially just a container of
+ * interfaces.
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL:
+ * SECTION:gdbusobjectmanager
+ * @short_description: Base type for D-Bus object managers
+ * @include: gio/gio.h
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * The #GDBusObjectManager type is the base type for service- and
+ * client-side implementations of the standardized
+ * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+ * interface.
*
- * Since: 2.22
+ * See #GDBusObjectManagerClient for the client-side implementation
+ * and #GDBusObjectManagerServer for the service-side implementation.
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START:
+ * SECTION:gdbusobjectmanagerclient
+ * @short_description: Client-side object manager
+ * @include: gio/gio.h
+ *
+ * #GDBusObjectManagerClient is used to create, monitor and delete object
+ * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
+ * code implementing the
+ * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
+ * interface).
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * Once an instance of this type has been created, you can connect to
+ * the #GDBusObjectManager::object-added and
+ * #GDBusObjectManager::object-removed signals and inspect the
+ * #GDBusObjectProxy objects returned by
+ * g_dbus_object_manager_get_objects().
*
- * Since: 2.22
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED:
+ * If the name for a #GDBusObjectManagerClient is not owned by anyone at
+ * object construction time, the default behavior is to request the
+ * message bus to launch an owner for the name. This behavior can be
+ * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
+ * flag. It's also worth noting that this only works if the name of
+ * interest is activatable in the first place. E.g. in some cases it
+ * is not possible to launch an owner for the requested name. In this
+ * case, #GDBusObjectManagerClient object construction still succeeds but
+ * there will be no object proxies
+ * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
+ * the #GDBusObjectManagerClient:name-owner property is %NULL.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started
- * degraded.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * The owner of the requested name can come and go (for example
+ * consider a system service being restarted) – #GDBusObjectManagerClient
+ * handles this case too; simply connect to the #GObject::notify
+ * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
+ * property. When the name owner vanishes, the behavior is that
+ * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
+ * emission of the #GObject::notify signal) and then
+ * #GDBusObjectManager::object-removed signals are synthesized
+ * for all currently existing object proxies. Since
+ * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
+ * use this information to disambiguate a synthesized signal from a
+ * genuine signal caused by object removal on the remote
+ * #GDBusObjectManager. Similarly, when a new name owner appears,
+ * #GDBusObjectManager::object-added signals are synthesized
+ * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
+ * object proxies have been added, the #GDBusObjectManagerClient:name-owner
+ * 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. `:1.42`) and %NULL even in the case where
+ * the name of interest is atomically replaced
*
- * Since: 2.22
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP:
+ * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
+ * instances. All signals (including the
+ * 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.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * To avoid having the application connect to signals on the returned
+ * #GDBusObjectProxy and #GDBusProxy objects, the
+ * #GDBusObject::interface-added,
+ * #GDBusObject::interface-removed,
+ * #GDBusProxy::g-properties-changed and
+ * #GDBusProxy::g-signal signals
+ * are also emitted on the #GDBusObjectManagerClient instance managing these
+ * objects. The signals emitted are
+ * #GDBusObjectManager::interface-added,
+ * #GDBusObjectManager::interface-removed,
+ * #GDBusObjectManagerClient::interface-proxy-properties-changed and
+ * #GDBusObjectManagerClient::interface-proxy-signal.
*
- * Since: 2.22
+ * Note that all callbacks and signals are emitted in the
+ * [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
+ * the same context and, consequently, will deliver signals in the
+ * same main loop.
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT:
+ * SECTION:gdbusobjectmanagerserver
+ * @short_description: Service-side object manager
+ * @include: gio/gio.h
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI:
+ * #GDBusObjectManagerServer is used to export #GDBusObject instances using
+ * 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
+ * clients can keep caches up to date by only listening to D-Bus
+ * signals.
*
- * A key in the "mountable" namespace for getting the HAL UDI for the mountable
- * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * See #GDBusObjectManagerClient for the client-side code that is
+ * intended to be used with #GDBusObjectManagerServer or any D-Bus
+ * object implementing the org.freedesktop.DBus.ObjectManager
+ * interface.
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC:
+ * SECTION:gdbusobjectproxy
+ * @short_description: Client-side D-Bus object
+ * @include: gio/gio.h
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE)
- * is automatically polled for media.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A #GDBusObjectProxy is an object used to represent a remote object
+ * with one or more D-Bus interfaces. Normally, you don't instantiate
+ * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
+ * is used to obtain it.
*
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE:
+ * SECTION:gdbusobjectskeleton
+ * @short_description: Service-side D-Bus object
+ * @include: gio/gio.h
*
- * A key in the "mountable" namespace for getting the #GDriveStartStopType.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
+ * interfaces. The set of exported interfaces on the object may be
+ * dynamic and change at runtime.
*
- * Since: 2.22
+ * This type is intended to be used with #GDBusObjectManager.
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE:
+ * SECTION:gdbusproxy
+ * @short_description: Client-side D-Bus interface proxy
+ * @include: gio/gio.h
*
- * A key in the "mountable" namespace for getting the unix device.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE:
+ * #GDBusProxy is a base class used for proxies to access a D-Bus
+ * interface on a remote object. A #GDBusProxy can be constructed for
+ * both well-known and unique names.
*
- * A key in the "mountable" namespace for getting the unix device file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * By default, #GDBusProxy will cache all properties (and listen to
+ * changes) of the remote object, and proxy all signals that gets
+ * emitted. This behaviour can be changed by passing suitable
+ * #GDBusProxyFlags when the proxy is created. If the proxy is for a
+ * well-known name, the property cache is flushed when the name owner
+ * vanishes and reloaded when a name owner appears.
*
- * Since: 2.22
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_OWNER_GROUP:
+ * If a #GDBusProxy is used for a well-known name, the owner of the
+ * name is tracked and can be read from
+ * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
+ * get notified of changes. Additionally, only signals and property
+ * changes emitted from the current name owner are considered and
+ * calls are always sent to the current name owner. This avoids a
+ * number of race conditions when the name is lost by one owner and
+ * claimed by another. However, if no name owner currently exists,
+ * then calls will be sent to the well-known name which may result in
+ * the message bus launching an owner (unless
+ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
*
- * A key in the "owner" namespace for getting the file owner's group.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_OWNER_USER:
+ * 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. This [example][gdbus-example-gdbus-codegen] shows how this can
+ * easily be done using the [gdbus-codegen][gdbus-codegen] tool.
*
- * A key in the "owner" namespace for getting the user name of the
- * file's owner. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
+ * 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
+ * [thread-default main context][g-main-context-push-thread-default]
+ * of the thread where the instance was constructed.
*
- * A key in the "owner" namespace for getting the real name of the
- * user that owns the file. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * 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)
*/
/**
- * G_FILE_ATTRIBUTE_PREVIEW_ICON:
+ * SECTION:gdbusserver
+ * @short_description: Helper for accepting connections
+ * @include: gio/gio.h
+ *
+ * #GDBusServer is a helper for listening to and accepting D-Bus
+ * connections. This can be used to create a new D-Bus server, allowing two
+ * peers to use the D-Bus protocol for their own specialized communication.
+ * A server instance provided in this way will not perform message routing or
+ * implement the org.freedesktop.DBus interface.
*
- * A key in the "preview" namespace for getting a #GIcon that can be
- * used to get preview of the file. For example, it may be a low
- * resolution thumbnail without metadata. Corresponding
- * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value
- * for this key should contain a #GIcon.
+ * 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().
*
- * Since: 2.20
+ * 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).
*/
/**
- * G_FILE_ATTRIBUTE_SELINUX_CONTEXT:
+ * SECTION:gdbusutils
+ * @title: D-Bus Utilities
+ * @short_description: Various utilities related to D-Bus
+ * @include: gio/gio.h
*
- * A key in the "selinux" namespace for getting the file's SELinux
- * context. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only
- * available if GLib has been built with SELinux support.
+ * Various utility routines related to D-Bus.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE:
+ * SECTION:gdesktopappinfo
+ * @title: GDesktopAppInfo
+ * @short_description: Application information from desktop files
+ * @include: gio/gdesktopappinfo.h
*
- * A key in the "standard" namespace for getting the amount of disk space
- * that is consumed by the file (in bytes). This will generally be larger
- * than the file size (due to block size overhead) but can occasionally be
- * smaller (for example, for sparse files).
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * #GDesktopAppInfo is an implementation of #GAppInfo based on
+ * desktop files.
*
- * Since: 2.20
+ * 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.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE:
+ * SECTION:gdrive
+ * @short_description: Drive management
+ * @include: gio/gio.h
*
- * A key in the "standard" namespace for getting the content type of the file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- * The value for this key should contain a valid content type.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME:
+ * #GDrive - this represent a piece of hardware connected to the machine.
+ * It's generally only created for removable hardware or hardware with
+ * removable media.
*
- * A key in the "standard" namespace for getting the copy name of the file.
- * The copy name is an optional version of the name. If available it's always
- * in UTF8, and corresponds directly to the original filename (only transcoded to
- * UTF8). This is useful if you want to copy the file to another filesystem that
- * might have a different encoding. If the filename is not a valid string in the
- * encoding selected for the filesystem it is in then the copy name will not be set.
+ * #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, determining whether media change is
+ * automatically detected and ejecting the media.
*
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION:
+ * If the #GDrive reports that media isn't automatically detected, one
+ * can poll for media; typically one should not do this periodically
+ * as a poll for media operation is potententially expensive and may
+ * spin up the drive creating noise.
*
- * A key in the "standard" namespace for getting the description of the file.
- * The description is a utf8 string that describes the file, generally containing
- * the filename, but can also contain furter information. Example descriptions
- * could be "filename (on hostname)" for a remote file or "filename (in trash)"
- * for a file in the trash. This is useful for instance as the window title
- * when displaying a directory or for a bookmarks menu.
+ * #GDrive supports starting and stopping drives with authentication
+ * support for the former. This can be used to support a diverse set
+ * of use cases including connecting/disconnecting iSCSI devices,
+ * powering down external disk enclosures and starting/stopping
+ * multi-disk devices such as RAID devices. Note that the actual
+ * semantics and side-effects of starting/stopping a #GDrive may vary
+ * according to implementation. To choose the correct verbs in e.g. a
+ * file manager, use g_drive_get_start_stop_type().
*
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * For porting from GnomeVFS note that there is no equivalent of
+ * #GDrive in that API.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME:
+ * SECTION:gemblem
+ * @short_description: An object for emblems
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
+ *
+ * #GEmblem is an implementation of #GIcon that supports
+ * having an emblem, which is an icon with additional properties.
+ * It can than be added to a #GEmblemedIcon.
*
- * A key in the "standard" namespace for getting the display name of the file.
- * A display name is guaranteed to be in UTF8 and can thus be displayed in
- * the UI.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * Currently, only metainformation about the emblem's origin is
+ * supported. More may be added in the future.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME:
+ * SECTION:gemblemedicon
+ * @short_description: Icon with emblems
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
*
- * A key in the "standard" namespace for edit name of the file.
- * An edit name is similar to the display name, but it is meant to be
- * used when you want to rename the file in the UI. The display name
- * might contain information you don't want in the new filename (such as
- * "(invalid unicode)" if the filename was in an invalid encoding).
+ * #GEmblemedIcon is an implementation of #GIcon that supports
+ * adding an emblem to an icon. Adding multiple emblems to an
+ * icon is ensured via g_emblemed_icon_add_emblem().
*
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * Note that #GEmblemedIcon allows no control over the position
+ * of the emblems. See also #GEmblem for more information.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE:
+ * SECTION:gfile
+ * @short_description: File and Directory Handling
+ * @include: gio/gio.h
+ * @see_also: #GFileInfo, #GFileEnumerator
*
- * A key in the "standard" namespace for getting the fast content type.
- * The fast content type isn't as reliable as the regular one, as it
- * only uses the filename to guess it, but it is faster to calculate than the
- * regular content type.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_ICON:
+ * #GFile is a high level abstraction for manipulating files on a
+ * 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).
*
- * A key in the "standard" namespace for getting the icon for the file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
- * The value for this key should contain a #GIcon.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP:
+ * 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 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.
*
- * A key in the "standard" namespace for checking if a file is a backup file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN:
+ * 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 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 #GFiles.
*
- * A key in the "standard" namespace for checking if a file is hidden.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK:
+ * Many #GFile operations have both synchronous and asynchronous versions
+ * to suit your application. Asynchronous versions of synchronous functions
+ * simply have _async() appended to their function names. The asynchronous
+ * I/O functions call a #GAsyncReadyCallback which is then used to finalize
+ * the operation, producing a GAsyncResult which is then passed to the
+ * function's matching _finish() operation.
*
- * A key in the "standard" namespace for checking if the file is a symlink.
- * Typically the actual type is something else, if we followed the symlink
- * to get the type.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL:
+ * 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.
*
- * A key in the "standard" namespace for checking if a file is virtual.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_NAME:
+ * 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.
*
- * A key in the "standard" namespace for getting the name of the file.
- * The name is the on-disk filename which may not be in any known encoding,
- * and can thus not be generally displayed as is.
- * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the
- * name in a user interface.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_SIZE:
+ * ## Entity Tags # {#gfile-etag}
*
- * A key in the "standard" namespace for getting the file's size (in bytes).
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * 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
+ * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
+ * for HTTP Etag headers, which are a very similar concept.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER:
+ * SECTION:gfileattribute
+ * @short_description: Key-Value Paired File Attributes
+ * @include: gio/gio.h
+ * @see_also: #GFile, #GFileInfo
*
- * A key in the "standard" namespace for setting the sort order of a file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
- * An example use would be in file managers, which would use this key
- * to set the order files are displayed. Files with smaller sort order
- * should be sorted first, and files without sort order as if sort order
- * was zero.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET:
+ * File attributes in GIO consist of a list of key-value pairs.
*
- * A key in the "standard" namespace for getting the symlink target, if the file
- * is a symlink. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_STANDARD_TARGET_URI:
+ * 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
+ * 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.
+ *
+ * The list of possible attributes for a filesystem (pointed to by a #GFile) is
+ * available as a #GFileAttributeInfoList. This list is queryable by key names
+ * as indicated earlier.
+ *
+ * Information is stored within the list in #GFileAttributeInfo structures.
+ * The info structure can store different types, listed in the enum
+ * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
+ * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
*
- * A key in the "standard" namespace for getting the target URI for the file, in
- * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
+ * install default keys and values for their given file system, architecture,
+ * 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).
+ *
+ * ## 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.
+ * For more information about writing GIO modules, see #GIOModule.
+ *
+ * <!-- TODO: Implementation note about using extended attributes on supported
+ * file systems -->
+ *
+ * ## 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
+ * away the "user." prefix from the extended user attribute, and prepending
+ * "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 escape sequences of the form \x`nn`
+ * where `nn` is a 2-digit hexadecimal number.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_TYPE:
+ * SECTION:gfiledescriptorbased
+ * @short_description: Interface for file descriptor based IO
+ * @include: gio/gfiledescriptorbased.h
+ * @see_also: #GInputStream, #GOutputStream
+ *
+ * #GFileDescriptorBased is implemented by streams (implementations of
+ * #GInputStream or #GOutputStream) that are based on file descriptors.
*
- * A key in the "standard" namespace for storing file types.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
- * The value for this key should contain a #GFileType.
+ * 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
*/
/**
- * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED:
+ * SECTION:gfileenumerator
+ * @short_description: Enumerated Files Routines
+ * @include: gio/gio.h
+ *
+ * #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 #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.
*
- * A key in the "thumbnail" namespace for checking if thumbnailing failed.
- * This attribute is %TRUE if thumbnailing failed. Corresponding
- * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * 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
+ * on it, and it should be freed with g_object_unref().
*/
/**
- * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
+ * SECTION:gfileicon
+ * @short_description: Icons pointing to an image file
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon
*
- * A key in the "thumbnail" namespace for getting the path to the thumbnail
- * image. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ * #GFileIcon specifies an icon by pointing to an image file
+ * to be used as icon.
*/
/**
- * G_FILE_ATTRIBUTE_TIME_ACCESS:
+ * SECTION:gfileinfo
+ * @short_description: File Information and Attributes
+ * @include: gio/gio.h
+ * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute]
*
- * A key in the "time" namespace for getting the time the file was last
- * accessed. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
- * file was last accessed.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
+ * 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.
*
- * A key in the "time" namespace for getting the microseconds of the time
- * the file was last accessed. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_TIME_CHANGED:
+ * 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
+ * stream, use g_file_input_stream_query_info() or
+ * g_file_output_stream_query_info() (or their async variants).
*
- * A key in the "time" namespace for getting the time the file was last
- * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
- * and contains the UNIX time since the file was last changed.
+ * To change the actual attributes of a file, you should then set the
+ * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
+ * or g_file_set_attributes_async() on a GFile.
*
- * This corresponds to the traditional UNIX ctime.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
+ * However, not all attributes can be changed in the file. For instance,
+ * the actual size of a file cannot be changed via g_file_info_set_size().
+ * You may call g_file_query_settable_attributes() and
+ * g_file_query_writable_namespaces() to discover the settable attributes
+ * of a particular file at runtime.
*
- * A key in the "time" namespace for getting the microseconds of the time
- * the file was last changed. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * #GFileAttributeMatcher allows for searching through a #GFileInfo for
+ * attributes.
*/
/**
- * G_FILE_ATTRIBUTE_TIME_CREATED:
+ * SECTION:gfileinputstream
+ * @short_description: File input streaming operations
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GDataInputStream, #GSeekable
*
- * A key in the "time" namespace for getting the time the file was created.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
- * and contains the UNIX time since the file was created.
+ * GFileInputStream provides input streams that take their
+ * content from a file.
*
- * This corresponds to the NTFS ctime.
+ * GFileInputStream implements #GSeekable, which allows the input
+ * stream to jump to arbitrary positions in the file, provided the
+ * filesystem of the file allows it. To find the position of a file
+ * input stream, use g_seekable_tell(). To find out if a file input
+ * stream supports seeking, use g_seekable_can_seek().
+ * To position a file input stream, use g_seekable_seek().
*/
/**
- * G_FILE_ATTRIBUTE_TIME_CREATED_USEC:
+ * SECTION:gfileiostream
+ * @short_description: File read and write streaming operations
+ * @include: gio/gio.h
+ * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
*
- * A key in the "time" namespace for getting the microseconds of the time
- * the file was created. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_TIME_MODIFIED:
+ * GFileIOStream provides io streams that both read and write to the same
+ * file handle.
*
- * A key in the "time" namespace for getting the time the file was last
- * modified. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
- * file was modified.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC:
+ * GFileIOStream implements #GSeekable, which allows the io
+ * stream to jump to arbitrary positions in the file and to truncate
+ * the file, provided the filesystem of the file supports these
+ * operations.
+ *
+ * To find the position of a file io stream, use
+ * g_seekable_tell().
+ *
+ * To find out if a file io stream supports seeking, use g_seekable_can_seek().
+ * To position a file io stream, use g_seekable_seek().
+ * To find out if a file io stream supports truncating, use
+ * g_seekable_can_truncate(). To truncate a file io
+ * stream, use g_seekable_truncate().
+ *
+ * The default implementation of all the #GFileIOStream operations
+ * and the implementation of #GSeekable just call into the same operations
+ * on the output stream.
*
- * A key in the "time" namespace for getting the miliseconds of the time
- * the file was last modified. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE:
+ * SECTION:gfilemonitor
+ * @short_description: File Monitor
+ * @include: gio/gio.h
+ *
+ * Monitors a file or directory for changes.
*
- * A key in the "trash" namespace. When requested against
- * items in "trash:///", will return the date and time when the file
- * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * To obtain a #GFileMonitor for a file or directory, use
+ * g_file_monitor(), g_file_monitor_file(), or
+ * g_file_monitor_directory().
*
- * Since: 2.24.
+ * 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
+ * [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).
*/
/**
- * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT:
+ * SECTION:gfilenamecompleter
+ * @short_description: Filename Completer
+ * @include: gio/gio.h
*
- * A key in the "trash" namespace. When requested against
- * "trash:///" returns the number of (toplevel) items in the trash folder.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Completes partial file and directory names given a partial string by
+ * looking in the file system for clues. Can return a list of possible
+ * completion strings for widget implementations.
*/
/**
- * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH:
+ * SECTION:gfileoutputstream
+ * @short_description: File output streaming operations
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
+ *
+ * GFileOutputStream provides output streams that write their
+ * content to a file.
*
- * A key in the "trash" namespace. When requested against
- * items in "trash:///", will return the original path to the file before it
- * was trashed. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * GFileOutputStream implements #GSeekable, which allows the output
+ * stream to jump to arbitrary positions in the file and to truncate
+ * the file, provided the filesystem of the file supports these
+ * operations.
*
- * Since: 2.24.
+ * To find the position of a file output stream, use g_seekable_tell().
+ * To find out if a file output stream supports seeking, use
+ * g_seekable_can_seek().To position a file output stream, use
+ * g_seekable_seek(). To find out if a file output stream supports
+ * truncating, use g_seekable_can_truncate(). To truncate a file output
+ * stream, use g_seekable_truncate().
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
+ * SECTION:gfilterinputstream
+ * @short_description: Filter Input Stream
+ * @include: gio/gio.h
*
- * A key in the "unix" namespace for getting the number of blocks allocated
- * for the file. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * Base class for input stream implementations that perform some
+ * kind of filtering operation on a base stream. Typical examples
+ * of filtering operations are character set conversion, compression
+ * and byte order flipping.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
+ * SECTION:gfilteroutputstream
+ * @short_description: Filter Output Stream
+ * @include: gio/gio.h
*
- * A key in the "unix" namespace for getting the block size for the file
- * system. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Base class for output stream implementations that perform some
+ * kind of filtering operation on a base stream. Typical examples
+ * of filtering operations are character set conversion, compression
+ * and byte order flipping.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_DEVICE:
+ * SECTION:gicon
+ * @short_description: Interface for icons
+ * @include: gio/gio.h
+ *
+ * #GIcon is a very minimal interface for icons. It provides functions
+ * for checking the equality of two icons, hashing of icons and
+ * serializing an icon to and from strings.
+ *
+ * #GIcon does not provide the actual pixmap for the icon as this is out
+ * of GIO's scope, however implementations of #GIcon may contain the name
+ * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
+ *
+ * To obtain a hash of a #GIcon, see g_icon_hash().
+ *
+ * To check if two #GIcons are equal, see g_icon_equal().
+ *
+ * For serializing a #GIcon, use g_icon_serialize() and
+ * g_icon_deserialize().
*
- * A key in the "unix" namespace for getting the device id of the device the
- * file is located on (see stat() documentation). This attribute is only
- * available for UNIX file systems. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * 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 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.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_GID:
+ * 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
+ * look up the #GInetAddress for a hostname. Use
+ * g_resolver_lookup_by_address() or
+ * g_resolver_lookup_by_address_async() to look up the hostname for a
+ * #GInetAddress.
*
- * A key in the "unix" namespace for getting the group ID for the file.
- * This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * To actually connect to a remote host, you will need a
+ * #GInetSocketAddress (which includes a #GInetAddress as well as a
+ * port number).
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_INODE:
+ * SECTION:ginetaddressmask
+ * @short_description: An IPv4/IPv6 address mask
+ * @include: gio/gio.h
*
- * A key in the "unix" namespace for getting the inode of the file.
- * This attribute is only available for UNIX file systems. Corresponding
- * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
+ * described by a base address and a length indicating how many bits
+ * of the base address are relevant for matching purposes. These are
+ * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
+ * SECTION:ginetsocketaddress
+ * @short_description: Internet GSocketAddress
+ * @include: gio/gio.h
*
- * A key in the "unix" namespace for checking if the file represents a
- * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount
- * point. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * An IPv4 or IPv6 socket address; that is, the combination of a
+ * #GInetAddress and a port number.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_MODE:
+ * SECTION:ginitable
+ * @short_description: Failable object initialization interface
+ * @include: gio/gio.h
+ * @see_also: #GAsyncInitable
+ *
+ * #GInitable is implemented by objects that can fail during
+ * initialization. If an object implements this interface then
+ * it must be initialized as the first thing after construction,
+ * either via g_initable_init() or g_async_initable_init_async()
+ * (the latter is only available if it also implements #GAsyncInitable).
+ *
+ * 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. They will often fail with g_critical() or g_warning(), but
+ * this must not be relied on.
*
- * A key in the "unix" namespace for getting the mode of the file
- * (e.g. whether the file is a regular file, symlink, etc). See lstat()
- * documentation. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Users of objects implementing this are not intended to use
+ * the interface method directly, instead it will be used automatically
+ * in various ways. For C applications you generally just call
+ * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
+ * This will call g_initable_init() under the cover, returning %NULL and
+ * setting a #GError on failure (at which point the instance is
+ * unreferenced).
+ *
+ * For bindings in languages where the native constructor supports
+ * exceptions the binding could check for objects implemention %GInitable
+ * during normal construction and automatically initialize them, throwing
+ * an exception on failure.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_NLINK:
+ * SECTION:ginputstream
+ * @short_description: Base class for implementing streaming input
+ * @include: gio/gio.h
+ *
+ * #GInputStream has functions to read from a stream (g_input_stream_read()),
+ * to close a stream (g_input_stream_close()) and to skip some content
+ * (g_input_stream_skip()).
+ *
+ * To copy the content of an input stream to an output stream without
+ * manually handling the reads and writes, use g_output_stream_splice().
*
- * A key in the "unix" namespace for getting the number of hard links
- * for a file. See lstat() documentation. This attribute is only available
- * for UNIX file systems. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * All of these functions have async variants too.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_RDEV:
+ * SECTION:gioerror
+ * @short_description: Error helper functions
+ * @include: gio/gio.h
*
- * A key in the "unix" namespace for getting the device ID for the file
- * (if it is a special file). See lstat() documentation. This attribute
- * is only available for UNIX file systems. Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Contains helper functions for reporting errors to the user.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_UID:
+ * SECTION:giomodule
+ * @short_description: Loadable GIO Modules
+ * @include: gio/gio.h
*
- * A key in the "unix" namespace for getting the user ID for the file.
- * This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Provides an interface and default functions for loading and unloading
+ * modules. This is used internally to make GIO extensible, but can also
+ * be used by others to implement module loading.
*/
/**
- * G_FLAGS_CLASS:
- * @class: a valid #GFlagsClass
+ * SECTION:gioscheduler
+ * @short_description: I/O Scheduler
+ * @include: gio/gio.h
+ *
+ * As of GLib 2.36, #GIOScheduler is deprecated in favor of
+ * #GThreadPool and #GTask.
*
- * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
+ * Schedules asynchronous I/O operations. #GIOScheduler integrates
+ * into the main event loop (#GMainLoop) and uses threads.
*/
/**
- * G_FLAGS_CLASS_TYPE:
- * @class: a #GFlagsClass
+ * SECTION:giostream
+ * @short_description: Base class for implementing read/write streams
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
+ *
+ * GIOStream represents an object that has both read and write streams.
+ * Generally the two streams acts as separate input and output streams,
+ * but they share some common resources and state. For instance, for
+ * seekable streams they may use the same position in both streams.
+ *
+ * Examples of #GIOStream objects are #GSocketConnection which represents
+ * a two-way network connection, and #GFileIOStream which represent a
+ * file handle opened in read-write mode.
+ *
+ * To do the actual reading and writing you need to get the substreams
+ * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
+ *
+ * The #GIOStream object owns the input and the output streams, not the other
+ * way around, so keeping the substreams alive will not keep the #GIOStream
+ * object alive. If the #GIOStream object is freed it will be closed, thus
+ * closing the substream, so even if the substreams stay alive they will
+ * always just return a %G_IO_ERROR_CLOSED for all operations.
*
- * Get the type identifier from a given #GFlagsClass structure.
+ * 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 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.
*
- * Returns: the #GType
+ * Since: 2.22
*/
/**
- * G_FLAGS_CLASS_TYPE_NAME:
- * @class: a #GFlagsClass
+ * 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
*
- * Get the static type name from a given #GFlagsClass structure.
+ * #GListStore is a simple implementation of #GListModel that stores all
+ * items in memory.
*
- * Returns: the type name.
+ * It provides insertions, deletions, and lookups in logarithmic time
+ * with a fast path for the common case of iterating the list linearly.
*/
/**
- * G_IMPLEMENT_INTERFACE:
- * @TYPE_IFACE: The #GType of the interface to add
- * @iface_init: The interface init function
- *
- * A convenience macro to ease interface addition in the @_C_ section
- * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
- * See G_DEFINE_TYPE_EXTENDED() for an example.
- *
- * Note that this macro can only be used together with the G_DEFINE_TYPE_*
- * macros, since it depends on variable names from those macros.
+ * SECTION:gloadableicon
+ * @short_description: Loadable Icons
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GThemedIcon
*
- * Since: 2.4
+ * Extends the #GIcon interface and adds the ability to
+ * load icons from streams.
*/
/**
- * G_IMPLEMENT_INTERFACE_DYNAMIC:
- * @TYPE_IFACE: The #GType of the interface to add
- * @iface_init: The interface init function
- *
- * A convenience macro to ease interface addition in the @_C_ section
- * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
- * for an example.
+ * SECTION:gmemoryinputstream
+ * @short_description: Streaming input operations on memory chunks
+ * @include: gio/gio.h
+ * @see_also: #GMemoryOutputStream
*
- * Note that this macro can only be used together with the
- * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
- * names from that macro.
+ * #GMemoryInputStream is a class for using arbitrary
+ * memory chunks as input for GIO streaming input operations.
*
- * Since: 2.24
+ * As of GLib 2.34, #GMemoryInputStream implements
+ * #GPollableInputStream.
*/
/**
- * G_INITIALLY_UNOWNED:
- * @object: Object which is subject to casting.
+ * SECTION:gmemoryoutputstream
+ * @short_description: Streaming output operations on memory chunks
+ * @include: gio/gio.h
+ * @see_also: #GMemoryInputStream
*
- * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*)
- * pointer. Depending on the current debugging level, this function may invoke
- * certain runtime checks to identify invalid casts.
- */
-
-
-/**
- * G_INITIALLY_UNOWNED_CLASS:
- * @class: a valid #GInitiallyUnownedClass
+ * #GMemoryOutputStream is a class for using arbitrary
+ * memory chunks as output for GIO streaming output operations.
*
- * Casts a derived #GInitiallyUnownedClass structure into a
- * #GInitiallyUnownedClass structure.
+ * As of GLib 2.34, #GMemoryOutputStream trivially implements
+ * #GPollableOutputStream: it always polls as ready.
*/
/**
- * G_INITIALLY_UNOWNED_GET_CLASS:
- * @object: a #GInitiallyUnowned instance.
+ * SECTION:gmenu
+ * @title: GMenu
+ * @short_description: A simple implementation of GMenuModel
+ * @include: gio/gio.h
*
- * Get the class structure associated to a #GInitiallyUnowned instance.
+ * #GMenu is a simple implementation of #GMenuModel.
+ * You populate a #GMenu by adding #GMenuItem instances to it.
*
- * Returns: pointer to object class structure.
+ * There are some convenience functions to allow you to directly
+ * add items (avoiding #GMenuItem) for the common cases. To add
+ * a regular item, use g_menu_insert(). To add a section, use
+ * g_menu_insert_section(). To add a submenu, use
+ * g_menu_insert_submenu().
*/
/**
- * G_IO_ERROR:
+ * SECTION:gmenuexporter
+ * @title: GMenuModel exporter
+ * @short_description: Export GMenuModels on D-Bus
+ * @include: gio/gio.h
+ * @see_also: #GMenuModel, #GDBusMenuModel
*
- * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration.
- * See #GError for more information on error domains.
- */
-
-
-/**
- * G_IS_ENUM_CLASS:
- * @class: a #GEnumClass
+ * These functions support exporting a #GMenuModel on D-Bus.
+ * The D-Bus interface that is used is a private implementation
+ * detail.
*
- * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
- * or derived.
+ * To access an exported #GMenuModel remotely, use
+ * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
*/
/**
- * G_IS_FLAGS_CLASS:
- * @class: a #GFlagsClass
+ * SECTION:gmenumodel
+ * @title: GMenuModel
+ * @short_description: An abstract class representing the contents of a menu
+ * @include: gio/gio.h
+ * @see_also: #GActionGroup
*
- * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
- * or derived.
- */
-
-
-/**
- * G_IS_INITIALLY_UNOWNED:
- * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.
+ * #GMenuModel represents the contents of a menu -- an ordered list of
+ * menu items. The items are associated with actions, which can be
+ * activated through them. Items can be grouped in sections, and may
+ * have submenus associated with them. Both items and sections usually
+ * have some representation data, such as labels or icons. The type of
+ * the associated action (ie whether it is stateful, and what kind of
+ * state it has) can influence the representation of the item.
*
- * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.
- */
-
-
-/**
- * G_IS_INITIALLY_UNOWNED_CLASS:
- * @class: a #GInitiallyUnownedClass
+ * The conceptual model of menus in #GMenuModel is hierarchical:
+ * sections and submenus are again represented by #GMenuModels.
+ * Menus themselves do not define their own roles. Rather, the role
+ * of a particular #GMenuModel is defined by the item that references
+ * it (or, in the case of the 'root' menu, is defined by the context
+ * in which it is used).
*
- * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type
- * %G_TYPE_INITIALLY_UNOWNED or derived.
- */
-
-
-/**
- * G_IS_OBJECT:
- * @object: Instance to check for being a %G_TYPE_OBJECT.
+ * As an example, consider the visible portions of this menu:
*
- * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
- */
-
-
-/**
- * G_IS_OBJECT_CLASS:
- * @class: a #GObjectClass
+ * ## An example menu # {#menu-example}
*
- * Checks whether @class "is a" valid #GObjectClass structure of type
- * %G_TYPE_OBJECT or derived.
- */
-
-
-/**
- * G_IS_PARAM_SPEC:
- * @pspec: a #GParamSpec
+ * 
*
- * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
- * or derived.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_BOOLEAN:
- * @pspec: a valid #GParamSpec instance
+ * There are 8 "menus" visible in the screenshot: one menubar, two
+ * submenus and 5 sections:
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.
+ * - 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)
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_BOXED:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.
+ * ## A menu example # {#menu-model}
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_CHAR:
- * @pspec: a valid #GParamSpec instance
+ * 
+ *
+ * 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,
+ * a display system may show a section header instead of a separator.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.
+ * The motivation for this abstract model of application controls is
+ * that modern user interfaces tend to make these controls available
+ * 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 [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.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_CLASS:
- * @pclass: a #GParamSpecClass
+ * The API of #GMenuModel is very generic, with iterators for the
+ * attributes and links of an item, see g_menu_model_iterate_item_attributes()
+ * and g_menu_model_iterate_item_links(). The 'standard' attributes and
+ * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
+ * and %G_MENU_LINK_SUBMENU.
+ *
+ * Items in a #GMenuModel represent active controls if they refer to
+ * an action that can get activated when the user interacts with the
+ * menu item. The reference to the action is encoded by the string id
+ * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
+ * identifies an action in an action group. Which action group(s) provide
+ * actions depends on the context in which the menu model is used.
+ * E.g. when the model is exported as the application menu of a
+ * #GtkApplication, actions can be application-wide or window-specific
+ * (and thus come from two different action groups). By convention, the
+ * application-wide actions have names that start with "app.", while the
+ * names of window-specific actions start with "win.".
+ *
+ * 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:
+ * - 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.
+ *
+ * Selecting such a menu item will activate the action (with no parameter).
+ *
+ * ## 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.
+ *
+ * Selecting a toggle menu item will activate the action. The menu item should
+ * be rendered as "checked" when the state is true.
+ *
+ * ## String Parameter and State
*
- * Checks whether @pclass "is a" valid #GParamSpecClass structure of type
- * %G_TYPE_PARAM or derived.
+ * 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.
+ *
+ * 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.
*/
/**
- * G_IS_PARAM_SPEC_DOUBLE:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gmount
+ * @short_description: Mount management
+ * @include: gio/gio.h
+ * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
+ *
+ * The #GMount interface represents user-visible mounts. Note, when
+ * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.
+ * #GMount is a "mounted" filesystem that you can access. Mounted is in
+ * quotes because it's not the same as a unix mount, it might be a gvfs
+ * mount, but you can still access the files on it if you use GIO. Might or
+ * might not be related to a volume object.
*
- * Returns: %TRUE on success.
+ * Unmounting a #GMount instance is an asynchronous operation. For
+ * more information about asynchronous operations, see #GAsyncResult
+ * 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
+ * #GAsyncReady structure will be passed to the callback. That
+ * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
+ * and the #GAsyncReady data to see if the operation was completed
+ * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
+ * is called, then it will be filled with any error information.
*/
/**
- * G_IS_PARAM_SPEC_ENUM:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gmountoperation
+ * @short_description: Object used for authentication and user interaction
+ * @include: gio/gio.h
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.
+ * #GMountOperation provides a mechanism for interacting with the user.
+ * It can be used for authenticating mountable operations, such as loop
+ * mounting files, hard drive partitions or server locations. It can
+ * also be used to ask the user questions or show a list of applications
+ * preventing unmount or eject operations from completing.
+ *
+ * Note that #GMountOperation is used for more than just #GMount
+ * objects – for example it is also used in g_drive_start() and
+ * g_drive_stop().
*
- * Returns: %TRUE on success.
+ * Users should instantiate a subclass of this that implements all the
+ * various callbacks to show the required dialogs, such as
+ * #GtkMountOperation. If no user interaction is desired (for example
+ * when automounting filesystems at login time), usually %NULL can be
+ * passed, see each method taking a #GMountOperation for details.
*/
/**
- * G_IS_PARAM_SPEC_FLAGS:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gnetworkaddress
+ * @short_description: A GSocketConnectable for resolving hostnames
+ * @include: gio/gio.h
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.
+ * #GNetworkAddress provides an easy way to resolve a hostname and
+ * then attempt to connect to that host, handling the possibility of
+ * multiple IP addresses and multiple address families.
*
- * Returns: %TRUE on success.
+ * See #GSocketConnectable for and example of using the connectable
+ * interface.
*/
/**
- * G_IS_PARAM_SPEC_FLOAT:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.
+ * 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.
*
- * Returns: %TRUE on success.
+ * 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.
*/
/**
- * G_IS_PARAM_SPEC_GTYPE:
- * @pspec: a #GParamSpec
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.
+ * SECTION:gnetworkmonitor
+ * @title: GNetworkMonitor
+ * @short_description: Network status monitor
+ * @include: gio/gio.h
*
- * Since: 2.10
- * Returns: %TRUE on success.
+ * #GNetworkMonitor provides an easy-to-use cross-platform API
+ * for monitoring network connectivity. On Linux, the implementation
+ * is based on the kernel's netlink interface.
*/
/**
- * G_IS_PARAM_SPEC_INT:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gnetworkservice
+ * @short_description: A GSocketConnectable for resolving SRV records
+ * @include: gio/gio.h
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.
+ * Like #GNetworkAddress does with hostnames, #GNetworkService
+ * provides an easy way to resolve a SRV record, and then attempt to
+ * connect to one of the hosts that implements that service, handling
+ * service priority/weighting, multiple IP addresses, and multiple
+ * address families.
*
- * Returns: %TRUE on success.
+ * See #GSrvTarget for more information about SRV records, and see
+ * #GSocketConnectable for and example of using the connectable
+ * interface.
*/
/**
- * G_IS_PARAM_SPEC_INT64:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.
+ * 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.
*
- * Returns: %TRUE on success.
+ * A notification can be sent with g_application_send_notification().
+ *
+ * Since: 2.40
*/
/**
- * G_IS_PARAM_SPEC_LONG:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:goutputstream
+ * @short_description: Base class for implementing streaming output
+ * @include: gio/gio.h
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.
+ * #GOutputStream has functions to write to a stream (g_output_stream_write()),
+ * to close a stream (g_output_stream_close()) and to flush pending writes
+ * (g_output_stream_flush()).
+ *
+ * To copy the content of an input stream to an output stream without
+ * manually handling the reads and writes, use g_output_stream_splice().
*
- * Returns: %TRUE on success.
+ * All of these functions have async variants too.
*/
/**
- * G_IS_PARAM_SPEC_OBJECT:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gpermission
+ * @title: GPermission
+ * @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.
+ *
+ * You can query if the action is currently allowed and if it is
+ * possible to acquire the permission so that the action will be allowed
+ * in the future.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
+ * There is also an API to actually acquire the permission and one to
+ * release it.
*
- * Returns: %TRUE on success.
+ * As an example, a #GPermission might represent the ability for the
+ * user to write to a #GSettings object. This #GPermission object could
+ * then be used to decide if it is appropriate to show a "Click here to
+ * unlock" button in a dialog and to provide the mechanism to invoke
+ * when that button is clicked.
*/
/**
- * G_IS_PARAM_SPEC_OVERRIDE:
- * @pspec: a #GParamSpec
+ * SECTION:gpollableinputstream
+ * @short_description: Interface for pollable input streams
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.
+ * #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.
*
- * Since: 2.4
- * Returns: %TRUE on success.
+ * Since: 2.28
*/
/**
- * G_IS_PARAM_SPEC_PARAM:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gpollableoutputstream
+ * @short_description: Interface for pollable output streams
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.
+ * #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.
*
- * Returns: %TRUE on success.
+ * Since: 2.28
*/
/**
- * G_IS_PARAM_SPEC_POINTER:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.
+ * SECTION:gpollableutils
+ * @short_description: Utilities for pollable streams
+ * @include: gio/gio.h
*
- * Returns: %TRUE on success.
+ * Utility functions for #GPollableInputStream and
+ * #GPollableOutputStream implementations.
*/
/**
- * G_IS_PARAM_SPEC_STRING:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gpropertyaction
+ * @title: GPropertyAction
+ * @short_description: A GAction reflecting a GObject property
+ * @include: gio/gio.h
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.
+ * A #GPropertyAction is a way to get a #GAction with a state value
+ * reflecting and controlling the value of a #GObject property.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_UCHAR:
- * @pspec: a valid #GParamSpec instance
+ * 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).
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.
+ * 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.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_UINT:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.
+ * Flags types are not currently supported.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_UINT64:
- * @pspec: a valid #GParamSpec instance
+ * Properties of object types, boxed types and pointer types are not
+ * supported and probably never will be.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.
+ * Properties of #GVariant types are not currently supported.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_ULONG:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.
+ * In all other cases, the parameter type will correspond to the type of
+ * the property.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_UNICHAR:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.
+ * 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.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_IS_PARAM_SPEC_VALUE_ARRAY:
- * @pspec: a valid #GParamSpec instance
+ * 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.
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
+ * 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().
*
- * Returns: %TRUE on success.
+ * Since: 2.38
*/
/**
- * G_IS_PARAM_SPEC_VARIANT:
- * @pspec: a #GParamSpec
+ * SECTION:gproxy
+ * @short_description: Interface for proxy handling
+ * @include: gio/gio.h
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT.
+ * A #GProxy handles connecting to a remote host via a given type of
+ * proxy server. It is implemented by the 'gio-proxy' extension point.
+ * The extensions are named after their proxy protocol name. As an
+ * example, a SOCKS5 proxy implementation can be retrieved with the
+ * name 'socks5' using the function
+ * g_io_extension_point_get_extension_by_name().
*
- * Returns: %TRUE on success
* Since: 2.26
*/
/**
- * G_IS_VALUE:
- * @value: A #GValue structure.
- *
- * Checks if @value is a valid and initialized #GValue structure.
+ * SECTION:gproxyaddress
+ * @short_description: An internet address with proxy information
+ * @include: gio/gio.h
*
- * Returns: %TRUE on success.
+ * Support for proxied #GInetSocketAddress.
*/
/**
- * G_MARKUP_ERROR:
+ * SECTION:gproxyresolver
+ * @short_description: Asynchronous and cancellable network proxy resolver
+ * @include: gio/gio.h
*
- * Error domain for markup parsing.
- * Errors in this domain will be from the #GMarkupError enumeration.
- * See #GError for information on error domains.
+ * #GProxyResolver provides synchronous and asynchronous network proxy
+ * resolution. #GProxyResolver is used within #GSocketClient through
+ * the method g_socket_connectable_proxy_enumerate().
*/
/**
- * G_NETWORK_MONITOR_EXTENSION_POINT_NAME:
+ * SECTION:gremoteactiongroup
+ * @title: GRemoteActionGroup
+ * @short_description: A GActionGroup that interacts with other processes
+ * @include: gio/gio.h
*
- * Extension point for network status monitoring functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * 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.
*
- * Since: 2.30
- */
-
-
-/**
- * G_NODE_IS_LEAF:
- * @node: a #GNode
+ * 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
+ * "platform data" #GVariant to be specified: a dictionary providing
+ * context for the action invocation (for example: timestamps, startup
+ * notification IDs, etc).
*
- * Returns %TRUE if a #GNode is a leaf node.
+ * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
+ * mechanism to send platform data for action invocations over D-Bus.
*
- * (i.e. it has no children)
+ * Additionally, g_dbus_connection_export_action_group() will check if
+ * the exported #GActionGroup implements #GRemoteActionGroup and use the
+ * `_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.
*
- * Returns: %TRUE if the #GNode is a leaf node
+ * Since: 2.32
*/
/**
- * G_NODE_IS_ROOT:
- * @node: a #GNode
- *
- * Returns %TRUE if a #GNode is the root of a tree.
+ * SECTION:gresolver
+ * @short_description: Asynchronous and cancellable DNS resolver
+ * @include: gio/gio.h
*
- * (i.e. it has no parent or siblings)
+ * #GResolver provides cancellable synchronous and asynchronous DNS
+ * resolution, for hostnames (g_resolver_lookup_by_address(),
+ * g_resolver_lookup_by_name() and their async variants) and SRV
+ * (service) records (g_resolver_lookup_service()).
*
- * Returns: %TRUE if the #GNode is the root of a tree
+ * #GNetworkAddress and #GNetworkService provide wrappers around
+ * #GResolver functionality that also implement #GSocketConnectable,
+ * making it easy to connect to a remote host/service.
*/
/**
- * G_OBJECT:
- * @object: Object which is subject to casting.
+ * SECTION:gresource
+ * @short_description: Resource framework
+ * @include: gio/gio.h
*
- * Casts a #GObject or derived pointer into a (GObject*) pointer.
- * Depending on the current debugging level, this function may invoke
- * certain runtime checks to identify invalid casts.
- */
-
-
-/**
- * G_OBJECT_CLASS:
- * @class: a valid #GObjectClass
+ * 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 [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
+ * the resource files are efficient (as they are already in memory, shared with other instances) and
+ * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
+ * also makes it easier to create relocatable applications.
+ *
+ * Resource files can also be marked as compressed. Such files will be included in the resource bundle
+ * in a compressed form, but will be automatically uncompressed when the resource is used. This
+ * 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
+ * `preprocess` attribute to a comma-separated list of preprocessing options.
+ * The only options currently supported are:
+ *
+ * `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.
+ *
+ * `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 `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 [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.
+ *
+ * An example resource description:
+ * |[
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * <gresources>
+ * <gresource prefix="/org/gtk/Example">
+ * <file>data/splashscreen.png</file>
+ * <file compressed="true">dialog.ui</file>
+ * <file preprocess="xml-stripblanks">menumarkup.xml</file>
+ * </gresource>
+ * </gresources>
+ * ]|
*
- * Casts a derived #GObjectClass structure into a #GObjectClass structure.
- */
-
-
-/**
- * G_OBJECT_CLASS_NAME:
- * @class: a valid #GObjectClass
+ * This will create a resource bundle with the following files:
+ * |[
+ * /org/gtk/Example/data/splashscreen.png
+ * /org/gtk/Example/dialog.ui
+ * /org/gtk/Example/menumarkup.xml
+ * ]|
*
- * Return the name of a class structure's type.
+ * 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.
*
- * should not be freed.
+ * 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.
*
- * Returns: Type name of @class. The string is owned by the type system and
- */
-
-
-/**
- * G_OBJECT_CLASS_TYPE:
- * @class: a valid #GObjectClass
+ * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
+ * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
+ * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
+ * the resource data.
*
- * Get the type id of a class structure.
+ * There are two forms of the generated source, the default version uses the compiler support for constructor
+ * and destructor functions (where available) to automatically create and register the #GResource on startup
+ * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
+ * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
+ * even on the minor ones where this is not available. (Constructor support is available for at least Win32, MacOS and Linux.)
*
- * Returns: Type id of @class.
+ * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
+ * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
+ * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
+ * is for your own resources, and resource data is often used once, during parsing, and then released.
+ *
+ * Since: 2.32
*/
/**
- * G_OBJECT_GET_CLASS:
- * @object: a #GObject instance.
+ * SECTION:gseekable
+ * @short_description: Stream seeking interface
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
*
- * Get the class structure associated to a #GObject instance.
+ * #GSeekable is implemented by streams (implementations of
+ * #GInputStream or #GOutputStream) that support seeking.
*
- * Returns: pointer to object class structure.
- */
-
-
-/**
- * G_OBJECT_TYPE:
- * @object: Object to return the type id for.
+ * Seekable streams largely fall into two categories: resizable and
+ * fixed-size.
*
- * Get the type id of an object.
+ * #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.
*
- * Returns: Type id of @object.
+ * #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.
*/
/**
- * G_OBJECT_TYPE_NAME:
- * @object: Object to return the type name for.
- *
- * Get the name of an object's type.
+ * SECTION:gsettings
+ * @short_description: High-level API for application settings
+ * @include: gio/gio.h
*
- * should not be freed.
+ * The #GSettings class provides a convenient API for storing and retrieving
+ * application settings.
*
- * Returns: Type name of @object. The string is owned by the type system and
- */
-
-
-/**
- * G_OBJECT_WARN_INVALID_PROPERTY_ID:
- * @object: the #GObject on which set_property() or get_property() was called
- * @property_id: the numeric id of the property
- * @pspec: the #GParamSpec of the property
+ * Reads and writes can be considered to be non-blocking. Reading
+ * settings with #GSettings is typically extremely fast: on
+ * approximately the same order of magnitude (but slower than) a
+ * #GHashTable lookup. Writing settings is also extremely fast in terms
+ * of time to return to your application, but can be extremely expensive
+ * for other threads and other processes. Many settings backends
+ * (including dconf) have lazy initialisation which means in the common
+ * case of the user using their computer without modifying any settings
+ * a lot of work can be avoided. For dconf, the D-Bus service doesn't
+ * even need to be started in this case. For this reason, you should
+ * only ever modify #GSettings keys in response to explicit user action.
+ * Particular care should be paid to ensure that modifications are not
+ * made during startup -- for example, when setting the initial value
+ * of preferences widgets. The built-in g_settings_bind() functionality
+ * is careful not to write settings in response to notify signals as a
+ * result of modifications that it makes to widgets.
*
- * This macro should be used to emit a standard warning about unexpected
- * properties in set_property() and get_property() implementations.
- */
-
-
-/**
- * G_OPTION_ERROR:
+ * When creating a GSettings instance, you have to specify a schema
+ * that describes the keys in your settings and their types and default
+ * values, as well as some other information.
*
- * Error domain for option parsing. Errors in this domain will
- * be from the #GOptionError enumeration. See #GError for information on
- * error domains.
- */
-
-
-/**
- * G_OPTION_REMAINING:
+ * Normally, a schema has as fixed path that determines where the settings
+ * are stored in the conceptual global tree of settings. However, schemas
+ * can also be 'relocatable', i.e. not equipped with a fixed path. This is
+ * useful e.g. when the schema describes an 'account', and you want to be
+ * able to store a arbitrary number of accounts.
*
- * If a long option in the main group has this name, it is not treated as a
- * regular option. Instead it collects all non-option arguments which would
- * otherwise be left in <literal>argv</literal>. The option must be of type
- * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
- * or %G_OPTION_ARG_FILENAME_ARRAY.
+ * Paths must start with and end with a forward slash character ('/')
+ * and must not contain two sequential slash characters. Paths should
+ * be chosen based on a domain name associated with the program or
+ * library to which the settings belong. Examples of paths are
+ * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
+ * Paths should not start with "/apps/", "/desktop/" or "/system/" as
+ * they often did in GConf.
*
+ * Unlike other configuration systems (like GConf), GSettings does not
+ * restrict keys to basic types like strings and numbers. GSettings stores
+ * values as #GVariant, and allows any #GVariantType for keys. Key names
+ * are restricted to lowercase characters, numbers and '-'. Furthermore,
+ * the names must begin with a lowercase character, must not end
+ * with a '-', and must not contain consecutive dashes.
*
- * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
- * for leftover arguments has the advantage that GOption takes care of
- * necessary encoding conversions for strings or filenames.
+ * 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".
*
- * Since: 2.6
- */
-
-
-/**
- * G_PARAM_MASK:
+ * 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
+ * gettext-domain attribute of the <schemalist> or <schema>
+ * elements and the category that is specified in the l10n attribute of
+ * the <key> element.
*
- * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
- */
-
-
-/**
- * G_PARAM_READWRITE:
+ * GSettings uses schemas in a compact binary form that is created
+ * 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">
*
- * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
- */
-
-
-/**
- * G_PARAM_SPEC:
- * @pspec: a valid #GParamSpec
+ * <key name="greeting" type="s">
+ * <default l10n="messages">"Hello, earthlings"</default>
+ * <summary>A greeting</summary>
+ * <description>
+ * Greeting of the invading martians
+ * </description>
+ * </key>
*
- * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
- * a #GParamSpec object.
- */
-
-
-/**
- * G_PARAM_SPEC_BOOLEAN:
- * @pspec: a valid #GParamSpec instance
+ * <key name="box" type="(ii)">
+ * <default>(20,30)</default>
+ * </key>
*
- * Cast a #GParamSpec instance into a #GParamSpecBoolean.
- */
-
-
-/**
- * G_PARAM_SPEC_BOXED:
- * @pspec: a valid #GParamSpec instance
+ * </schema>
+ * </schemalist>
+ * ]|
*
- * Cast a #GParamSpec instance into a #GParamSpecBoxed.
- */
-
-
-/**
- * G_PARAM_SPEC_CHAR:
- * @pspec: a valid #GParamSpec instance
+ * An example for ranges, choices and enumerated types:
+ * |[
+ * <schemalist>
*
- * Cast a #GParamSpec instance into a #GParamSpecChar.
- */
-
-
-/**
- * G_PARAM_SPEC_CLASS:
- * @pclass: a valid #GParamSpecClass
+ * <enum id="org.gtk.Test.myenum">
+ * <value nick="first" value="1"/>
+ * <value nick="second" value="2"/>
+ * </enum>
+ *
+ * <flags id="org.gtk.Test.myflags">
+ * <value nick="flag1" value="1"/>
+ * <value nick="flag2" value="2"/>
+ * <value nick="flag3" value="4"/>
+ * </flags>
+ *
+ * <schema id="org.gtk.Test">
+ *
+ * <key name="key-with-range" type="i">
+ * <range min="1" max="100"/>
+ * <default>10</default>
+ * </key>
+ *
+ * <key name="key-with-choices" type="s">
+ * <choices>
+ * <choice value='Elisabeth'/>
+ * <choice value='Annabeth'/>
+ * <choice value='Joe'/>
+ * </choices>
+ * <aliases>
+ * <alias value='Anna' target='Annabeth'/>
+ * <alias value='Beth' target='Elisabeth'/>
+ * </aliases>
+ * <default>'Joe'</default>
+ * </key>
+ *
+ * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
+ * <default>'first'</default>
+ * </key>
+ *
+ * <key name='flags-key' flags='org.gtk.Test.myflags'>
+ * <default>["flag1","flag2"]</default>
+ * </key>
+ * </schema>
+ * </schemalist>
+ * ]|
*
- * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
- */
-
-
-/**
- * G_PARAM_SPEC_DOUBLE:
- * @pspec: a valid #GParamSpec instance
+ * ## Vendor overrides
*
- * Cast a #GParamSpec instance into a #GParamSpecDouble.
- */
-
-
-/**
- * G_PARAM_SPEC_ENUM:
- * @pspec: a valid #GParamSpec instance
+ * 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
+ * ]|
*
- * Cast a #GParamSpec instance into a #GParamSpecEnum.
- */
-
-
-/**
- * G_PARAM_SPEC_FLAGS:
- * @pspec: a valid #GParamSpec instance
+ * glib-compile-schemas expects schema files to have the extension
+ * `.gschema.override`.
*
- * Cast a #GParamSpec instance into a #GParamSpecFlags.
- */
-
-
-/**
- * G_PARAM_SPEC_FLOAT:
- * @pspec: a valid #GParamSpec instance
+ * ## Binding
*
- * Cast a #GParamSpec instance into a #GParamSpecFloat.
- */
-
-
-/**
- * G_PARAM_SPEC_GET_CLASS:
- * @pspec: a valid #GParamSpec
+ * 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.
*
- * Retrieves the #GParamSpecClass of a #GParamSpec.
+ * 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_PARAM_SPEC_GTYPE:
- * @pspec: a #GParamSpec
+ * SECTION:gsettingsbackend
+ * @title: GSettingsBackend
+ * @short_description: Interface for settings backend implementations
+ * @include: gio/gsettingsbackend.h
+ * @see_also: #GSettings, #GIOExtensionPoint
*
- * Casts a #GParamSpec into a #GParamSpecGType.
+ * The #GSettingsBackend interface defines a generic interface for
+ * non-strictly-typed data that is stored in a hierarchy. To implement
+ * an alternative storage backend for #GSettings, you need to implement
+ * the #GSettingsBackend interface and then make it implement the
+ * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
*
- * Since: 2.10
- */
-
-
-/**
- * G_PARAM_SPEC_INT:
- * @pspec: a valid #GParamSpec instance
+ * The interface defines methods for reading and writing values, a
+ * method for determining if writing of certain values will fail
+ * (lockdown) and a change notification mechanism.
*
- * Cast a #GParamSpec instance into a #GParamSpecInt.
- */
-
-
-/**
- * G_PARAM_SPEC_INT64:
- * @pspec: a valid #GParamSpec instance
+ * The semantics of the interface are very precisely defined and
+ * implementations must carefully adhere to the expectations of
+ * callers that are documented on each of the interface methods.
*
- * Cast a #GParamSpec instance into a #GParamSpecInt64.
- */
-
-
-/**
- * G_PARAM_SPEC_LONG:
- * @pspec: a valid #GParamSpec instance
+ * Some of the GSettingsBackend functions accept or return a #GTree.
+ * These trees always have strings as keys and #GVariant as values.
+ * g_settings_backend_create_tree() is a convenience function to create
+ * suitable trees.
*
- * Cast a #GParamSpec instance into a #GParamSpecLong.
+ * 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
+ * `gio/gsettingsbackend.h`.
*/
/**
- * G_PARAM_SPEC_OBJECT:
- * @pspec: a valid #GParamSpec instance
+ * SECTION:gsettingsschema
+ * @short_description: Introspecting and controlling the loading
+ * of GSettings schemas
+ * @include: gio/gio.h
*
- * Casts a #GParamSpec instance into a #GParamSpecObject.
- */
-
-
-/**
- * G_PARAM_SPEC_OVERRIDE:
- * @pspec: a #GParamSpec
+ * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
+ * mechanism for advanced control over the loading of schemas and a
+ * mechanism for introspecting their content.
*
- * Casts a #GParamSpec into a #GParamSpecOverride.
+ * Plugin loading systems that wish to provide plugins a way to access
+ * settings face the problem of how to make the schemas for these
+ * settings visible to GSettings. Typically, a plugin will want to ship
+ * the schema along with itself and it won't be installed into the
+ * standard system directories for schemas.
*
- * Since: 2.4
- */
-
-
-/**
- * G_PARAM_SPEC_PARAM:
- * @pspec: a valid #GParamSpec instance
+ * #GSettingsSchemaSource provides a mechanism for dealing with this by
+ * allowing the creation of a new 'schema source' from which schemas can
+ * be acquired. This schema source can then become part of the metadata
+ * associated with the plugin and queried whenever the plugin requires
+ * access to some settings.
*
- * Casts a #GParamSpec instance into a #GParamSpecParam.
- */
-
-
-/**
- * G_PARAM_SPEC_POINTER:
- * @pspec: a valid #GParamSpec instance
+ * Consider the following example:
*
- * Casts a #GParamSpec instance into a #GParamSpecPointer.
- */
-
-
-/**
- * G_PARAM_SPEC_STRING:
- * @pspec: a valid #GParamSpec instance
+ * |[<!-- language="C" -->
+ * typedef struct
+ * {
+ * ...
+ * GSettingsSchemaSource *schema_source;
+ * ...
+ * } Plugin;
*
- * Casts a #GParamSpec instance into a #GParamSpecString.
- */
-
-
-/**
- * G_PARAM_SPEC_TYPE:
- * @pspec: a valid #GParamSpec
+ * Plugin *
+ * initialise_plugin (const gchar *dir)
+ * {
+ * Plugin *plugin;
*
- * Retrieves the #GType of this @pspec.
- */
-
-
-/**
- * G_PARAM_SPEC_TYPE_NAME:
- * @pspec: a valid #GParamSpec
+ * ...
*
- * Retrieves the #GType name of this @pspec.
- */
-
-
-/**
- * G_PARAM_SPEC_UCHAR:
- * @pspec: a valid #GParamSpec instance
+ * plugin->schema_source =
+ * g_settings_new_schema_source_from_directory (dir,
+ * g_settings_schema_source_get_default (), FALSE, NULL);
*
- * Cast a #GParamSpec instance into a #GParamSpecUChar.
- */
-
-
-/**
- * G_PARAM_SPEC_UINT:
- * @pspec: a valid #GParamSpec instance
+ * ...
*
- * Cast a #GParamSpec instance into a #GParamSpecUInt.
- */
-
-
-/**
- * G_PARAM_SPEC_UINT64:
- * @pspec: a valid #GParamSpec instance
+ * return plugin;
+ * }
*
- * Cast a #GParamSpec instance into a #GParamSpecUInt64.
- */
-
-
-/**
- * G_PARAM_SPEC_ULONG:
- * @pspec: a valid #GParamSpec instance
+ * ...
*
- * Cast a #GParamSpec instance into a #GParamSpecULong.
- */
-
-
-/**
- * G_PARAM_SPEC_UNICHAR:
- * @pspec: a valid #GParamSpec instance
+ * GSettings *
+ * plugin_get_settings (Plugin *plugin,
+ * const gchar *schema_id)
+ * {
+ * GSettingsSchema *schema;
*
- * Cast a #GParamSpec instance into a #GParamSpecUnichar.
- */
-
-
-/**
- * G_PARAM_SPEC_VALUE_ARRAY:
- * @pspec: a valid #GParamSpec instance
+ * if (schema_id == NULL)
+ * schema_id = plugin->identifier;
*
- * Cast a #GParamSpec instance into a #GParamSpecValueArray.
- */
-
-
-/**
- * G_PARAM_SPEC_VALUE_TYPE:
- * @pspec: a valid #GParamSpec
+ * schema = g_settings_schema_source_lookup (plugin->schema_source,
+ * schema_id, FALSE);
*
- * Retrieves the #GType to initialize a #GValue for this parameter.
- */
-
-
-/**
- * G_PARAM_SPEC_VARIANT:
- * @pspec: a #GParamSpec
+ * if (schema == NULL)
+ * {
+ * ... disable the plugin or abort, etc ...
+ * }
*
- * Casts a #GParamSpec into a #GParamSpecVariant.
+ * return g_settings_new_full (schema, NULL, NULL);
+ * }
+ * ]|
*
- * Since: 2.26
- */
-
-
-/**
- * G_PARAM_STATIC_STRINGS:
+ * The code above shows how hooks should be added to the code that
+ * initialises (or enables) the plugin to create the schema source and
+ * how an API can be added to the plugin system to provide a convenient
+ * way for the plugin to access its settings, using the schemas that it
+ * ships.
*
- * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+ * From the standpoint of the plugin, it would need to ensure that it
+ * ships a gschemas.compiled file as part of itself, and then simply do
+ * the following:
*
- * Since 2.13.0
- */
-
-
-/**
- * G_PARAM_USER_SHIFT:
+ * |[<!-- language="C" -->
+ * {
+ * GSettings *settings;
+ * gint some_value;
*
- * Minimum shift count to be used for user defined flags, to be stored in
- * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT.
- */
-
-
-/**
- * G_PRIORITY_DEFAULT:
+ * settings = plugin_get_settings (self, NULL);
+ * some_value = g_settings_get_int (settings, "some-value");
+ * ...
+ * }
+ * ]|
*
- * Use this for default priority event sources.
+ * It's also possible that the plugin system expects the schema source
+ * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
+ * In that case, the plugin loading system must compile the schemas for
+ * itself before attempting to create the settings source.
*
- * In GLib this priority is used when adding timeout functions
- * with g_timeout_add(). In GDK this priority is used for events
- * from the X server.
+ * Since: 2.32
*/
/**
- * G_PRIORITY_DEFAULT_IDLE:
+ * SECTION:gsimpleaction
+ * @title: GSimpleAction
+ * @short_description: A simple GAction implementation
+ * @include: gio/gio.h
*
- * Use this for default priority idle functions.
+ * A #GSimpleAction is the obvious simple implementation of the #GAction
+ * interface. This is the easiest way to create an action for purposes of
+ * adding it to a #GSimpleActionGroup.
*
- * In GLib this priority is used when adding idle functions with
- * g_idle_add().
+ * See also #GtkAction.
*/
/**
- * G_PRIORITY_HIGH:
- *
- * Use this for high priority event sources.
+ * SECTION:gsimpleactiongroup
+ * @title: GSimpleActionGroup
+ * @short_description: A simple GActionGroup implementation
+ * @include: gio/gio.h
*
- * It is not used within GLib or GTK+.
+ * #GSimpleActionGroup is a hash table filled with #GAction objects,
+ * implementing the #GActionGroup and #GActionMap interfaces.
*/
/**
- * G_PRIORITY_HIGH_IDLE:
+ * SECTION:gsimpleasyncresult
+ * @short_description: Simple asynchronous results implementation
+ * @include: gio/gio.h
+ * @see_also: #GAsyncResult, #GTask
*
- * Use this for high priority idle functions.
+ * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
+ * #GTask, which provides a simpler API.
*
- * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
- * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
- * done to ensure that any pending resizes are processed before any
- * pending redraws, so that widgets are not redrawn twice unnecessarily.)
- */
-
-
-/**
- * G_PRIORITY_LOW:
+ * #GSimpleAsyncResult implements #GAsyncResult.
*
- * Use this for very low priority background tasks.
+ * 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
+ * asynchronously, a boolean value for checking the success or failure
+ * of an operation, or a #gssize for operations which return the number
+ * of bytes modified by the operation; all of the simple return cases
+ * are covered.
*
- * It is not used within GLib or GTK+.
- */
-
-
-/**
- * G_PROXY_EXTENSION_POINT_NAME:
+ * Most of the time, an application will not need to know of the details
+ * of this API; it is handled transparently, and any necessary operations
+ * are handled by #GAsyncResult's interface. However, if implementing a
+ * new GIO module, for writing language bindings, or for complex
+ * applications that need better control of how asynchronous operations
+ * are completed, it is important to understand this functionality.
*
- * Extension point for proxy functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * GSimpleAsyncResults are tagged with the calling function to ensure
+ * that asynchronous functions and their finishing functions are used
+ * together correctly.
*
- * Since: 2.26
- */
-
-
-/**
- * G_PROXY_RESOLVER_EXTENSION_POINT_NAME:
+ * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
+ * If the result needs to be created for a #GError, use
+ * g_simple_async_result_new_from_error() or
+ * g_simple_async_result_new_take_error(). If a #GError is not available
+ * (e.g. the asynchronous operation's doesn't take a #GError argument),
+ * but the result still needs to be created for an error condition, use
+ * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
+ * if your application or binding requires passing a variable argument list
+ * directly), and the error can then be propagated through the use of
+ * g_simple_async_result_propagate_error().
*
- * Extension point for proxy resolving functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
- */
-
-
-/**
- * G_QUEUE_INIT:
+ * An asynchronous operation can be made to ignore a cancellation event by
+ * calling g_simple_async_result_set_handle_cancellation() with a
+ * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
+ * operations that are dangerous to cancel, such as close (which would
+ * cause a leak if cancelled before being run).
*
- * A statically-allocated #GQueue must be initialized with this
- * macro before it can be used. This macro can be used to initialize
- * a variable, but it cannot be assigned to a variable. In that case
- * you have to use g_queue_init().
+ * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
+ * 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
+ * [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.
*
- * |[
- * GQueue my_queue = G_QUEUE_INIT;
- * ]|
+ * To set the results of an asynchronous function,
+ * g_simple_async_result_set_op_res_gpointer(),
+ * g_simple_async_result_set_op_res_gboolean(), and
+ * g_simple_async_result_set_op_res_gssize()
+ * are provided, setting the operation's result to a gpointer, gboolean, or
+ * gssize, respectively.
*
- * Since: 2.14
- */
-
-
-/**
- * G_REGEX_ERROR:
+ * Likewise, to get the result of an asynchronous function,
+ * g_simple_async_result_get_op_res_gpointer(),
+ * g_simple_async_result_get_op_res_gboolean(), and
+ * g_simple_async_result_get_op_res_gssize() are
+ * provided, getting the operation's result as a gpointer, gboolean, and
+ * gssize, respectively.
*
- * Error domain for regular expressions. Errors in this domain will be
- * from the #GRegexError enumeration. See #GError for information on
- * error domains.
+ * For the details of the requirements implementations must respect, see
+ * #GAsyncResult. A typical implementation of an asynchronous operation
+ * using GSimpleAsyncResult looks something like this:
*
- * Since: 2.14
- */
-
-
-/**
- * G_RESOLVER_ERROR:
+ * |[<!-- 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.
+ * GSimpleAsyncResult *result = user_data;
+ *
+ * if (cake == NULL)
+ * g_simple_async_result_set_error (result,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_NO_FLOUR,
+ * "Go to the supermarket");
+ * else
+ * g_simple_async_result_set_op_res_gpointer (result,
+ * g_object_ref (cake),
+ * 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().
+ * g_simple_async_result_complete (result);
+ * g_object_unref (result);
+ * }
*
- * Error domain for #GResolver. Errors in this domain will be from the
- * #GResolverError enumeration. See #GError for more information on
- * error domains.
- */
-
-
-/**
- * G_SETTINGS_BACKEND_EXTENSION_POINT_NAME:
+ * void
+ * baker_bake_cake_async (Baker *self,
+ * guint radius,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * GSimpleAsyncResult *simple;
+ * Cake *cake;
+ *
+ * if (radius < 3)
+ * {
+ * g_simple_async_report_error_in_idle (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_TOO_SMALL,
+ * "%ucm radius cakes are silly",
+ * radius);
+ * return;
+ * }
+ *
+ * simple = g_simple_async_result_new (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * baker_bake_cake_async);
+ * cake = _baker_get_cached_cake (self, radius);
+ *
+ * if (cake != NULL)
+ * {
+ * g_simple_async_result_set_op_res_gpointer (simple,
+ * g_object_ref (cake),
+ * 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.
+ * g_object_unref (cake);
+ * return;
+ * }
+ *
+ * _baker_prepare_cake (self, radius, baked_cb, simple);
+ * }
*
- * Extension point for #GSettingsBackend functionality.
- */
-
-
-/**
- * G_SIGNAL_FLAGS_MASK:
+ * Cake *
+ * baker_bake_cake_finish (Baker *self,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * GSimpleAsyncResult *simple;
+ * Cake *cake;
*
- * A mask for all #GSignalFlags bits.
- */
-
-
-/**
- * G_SIGNAL_MATCH_MASK:
+ * g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ * G_OBJECT (self),
+ * baker_bake_cake_async),
+ * NULL);
*
- * A mask for all #GSignalMatchType bits.
- */
-
-
-/**
- * G_SIGNAL_TYPE_STATIC_SCOPE:
+ * simple = (GSimpleAsyncResult *) result;
*
- * This macro flags signal argument types for which the signal system may
- * assume that instances thereof remain persistent across all signal emissions
- * they are used in. This is only useful for non ref-counted, value-copy types.
+ * if (g_simple_async_result_propagate_error (simple, error))
+ * return NULL;
*
- * To flag a signal argument in this way, add
- * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
- * of g_signal_new().
- * |[
- * g_signal_new ("size_request",
- * G_TYPE_FROM_CLASS (gobject_class),
- * G_SIGNAL_RUN_FIRST,
- * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
- * NULL, NULL,
- * _gtk_marshal_VOID__BOXED,
- * G_TYPE_NONE, 1,
- * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+ * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
+ * return g_object_ref (cake);
+ * }
* ]|
*/
/**
- * G_SOURCE_CONTINUE:
+ * SECTION:gsimpleiostream
+ * @short_description: A wrapper around an input and an output stream.
+ * @include: gio/gio.h
+ * @see_also: #GIOStream
*
- * Use this macro as the return value of a #GSourceFunc to leave
- * the #GSource in the main loop.
+ * 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.
*
- * Since: 2.28
+ * 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
*/
/**
- * G_SOURCE_REMOVE:
+ * SECTION:gsimplepermission
+ * @title: GSimplePermission
+ * @short_description: A GPermission that doesn't change value
+ * @include: gio/gio.h
*
- * Use this macro as the return value of a #GSourceFunc to remove
- * the #GSource from the main loop.
+ * #GSimplePermission is a trivial implementation of #GPermission that
+ * represents a permission that is either always or never allowed. The
+ * value is given at construction and doesn't change.
*
- * Since: 2.28
+ * Calling request or release will result in errors.
*/
/**
- * G_SPAWN_ERROR:
+ * SECTION:gsimpleproxyresolver
+ * @short_description: Simple proxy resolver implementation
+ * @include: gio/gio.h
+ * @see_also: g_socket_client_set_proxy_resolver()
*
- * Error domain for spawning processes. Errors in this domain will
- * be from the #GSpawnError enumeration. See #GError for information on
- * error domains.
- */
-
-
-/**
- * G_TIME_SPAN_DAY:
+ * #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.
*
- * Evaluates to a time span of one day.
+ * #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.26
+ * Since: 2.36
*/
/**
- * G_TIME_SPAN_HOUR:
+ * SECTION:gsocket
+ * @short_description: Low-level socket object
+ * @include: gio/gio.h
+ * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
*
- * Evaluates to a time span of one hour.
+ * 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.
+ * It supports both the UNIX socket implementations and winsock2 on Windows.
*
- * Since: 2.26
- */
-
-
-/**
- * G_TIME_SPAN_MILLISECOND:
+ * #GSocket is the platform independent base upon which the higher level
+ * network primitives are based. Applications are not typically meant to
+ * use it directly, but rather through classes like #GSocketClient,
+ * #GSocketService and #GSocketConnection. However there may be cases where
+ * direct use of #GSocket is useful.
*
- * Evaluates to a time span of one millisecond.
+ * #GSocket implements the #GInitable interface, so if it is manually constructed
+ * by e.g. g_object_new() you must call g_initable_init() and check the
+ * results before using the object. This is done automatically in
+ * g_socket_new() and g_socket_new_from_fd(), so these functions can return
+ * %NULL.
*
- * Since: 2.26
- */
-
-
-/**
- * G_TIME_SPAN_MINUTE:
+ * Sockets operate in two general modes, blocking or non-blocking. When
+ * in blocking mode all operations block until the requested operation
+ * is finished or there is an error. In non-blocking mode all calls that
+ * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
+ * To know when a call would successfully run you can call g_socket_condition_check(),
+ * or g_socket_condition_wait(). You can also use g_socket_create_source() and
+ * attach it to a #GMainContext to get callbacks when I/O is possible.
+ * Note that all sockets are always set to non blocking mode in the system, and
+ * blocking mode is emulated in GSocket.
*
- * Evaluates to a time span of one minute.
+ * When working in non-blocking mode applications should always be able to
+ * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
+ * function said that I/O was possible. This can easily happen in case
+ * of a race condition in the application, but it can also happen for other
+ * reasons. For instance, on Windows a socket is always seen as writable
+ * until a write returns %G_IO_ERROR_WOULD_BLOCK.
*
- * Since: 2.26
- */
-
-
-/**
- * G_TIME_SPAN_SECOND:
+ * #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
+ * specified or received in each I/O operation.
*
- * Evaluates to a time span of one second.
+ * All socket file descriptors are set to be close-on-exec.
*
- * Since: 2.26
- */
-
-
-/**
- * G_TLS_BACKEND_EXTENSION_POINT_NAME:
+ * Note that creating a #GSocket causes the signal %SIGPIPE to be
+ * ignored for the remainder of the program. If you are writing a
+ * command-line utility that uses #GSocket, you may need to take into
+ * account the fact that your program will not automatically be killed
+ * if it tries to write to %stdout after it has been closed.
*
- * Extension point for TLS functionality via #GTlsBackend.
- * See <link linkend="extending-gio">Extending GIO</link>.
- */
-
-
-/**
- * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
+ * 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.
*
- * The purpose used to verify the client certificate in a TLS connection.
- * Used by TLS servers.
+ * Since: 2.22
*/
/**
- * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
+ * SECTION:gsocketaddress
+ * @short_description: Abstract base class representing endpoints
+ * for socket communication
+ * @include: gio/gio.h
*
- * The purpose used to verify the server certificate in a TLS connection. This
- * is the most common purpose in use. Used by TLS clients.
+ * #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.
*/
/**
- * G_TLS_ERROR:
+ * SECTION:gsocketclient
+ * @short_description: Helper for connecting to a network service
+ * @include: gio/gio.h
+ * @see_also: #GSocketConnection, #GSocketListener
*
- * Error domain for TLS. Errors in this domain will be from the
- * #GTlsError enumeration. See #GError for more information on error
- * domains.
- */
-
-
-/**
- * G_TYPE_ARRAY:
+ * #GSocketClient is a lightweight high-level utility class for connecting to
+ * a network host using a connection oriented socket type.
+ *
+ * You create a #GSocketClient object, set any options you want, and then
+ * call a sync or async connect operation, which returns a #GSocketConnection
+ * subclass on success.
+ *
+ * The type of the #GSocketConnection object returned depends on the type of
+ * the underlying socket that is in use. For instance, for a TCP/IP connection
+ * it will be a #GTcpConnection.
*
- * The #GType for a boxed type holding a #GArray reference.
+ * As #GSocketClient is a lightweight object, you don't need to cache it. You
+ * can just create a new one any time you need one.
*
* Since: 2.22
*/
/**
- * G_TYPE_BOOLEAN:
+ * SECTION:gsocketconnectable
+ * @short_description: Interface for potential socket endpoints
+ * @include: gio/gio.h
*
- * The fundamental type corresponding to #gboolean.
- */
-
-
-/**
- * G_TYPE_BOXED:
+ * Objects that describe one or more potential socket endpoints
+ * implement #GSocketConnectable. Callers can then use
+ * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
+ * to try out each socket address in turn until one succeeds, as shown
+ * in the sample code below.
*
- * The fundamental type from which all boxed types are derived.
+ * |[<!-- language="C" -->
+ * MyConnectionType *
+ * connect_to_host (const char *hostname,
+ * guint16 port,
+ * GCancellable *cancellable,
+ * GError **error)
+ * {
+ * MyConnection *conn = NULL;
+ * GSocketConnectable *addr;
+ * GSocketAddressEnumerator *enumerator;
+ * GSocketAddress *sockaddr;
+ * GError *conn_error = NULL;
+ *
+ * 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).
+ * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
+ * {
+ * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
+ * g_object_unref (sockaddr);
+ * }
+ * g_object_unref (enumerator);
+ *
+ * if (conn)
+ * {
+ * if (conn_error)
+ * {
+ * // 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 initial lookup failed, or else the caller cancelled us.
+ * if (conn_error)
+ * g_error_free (conn_error);
+ * return NULL;
+ * }
+ * else
+ * {
+ * g_error_propagate (error, conn_error);
+ * return NULL;
+ * }
+ * }
+ * ]|
*/
/**
- * G_TYPE_BYTES:
+ * SECTION:gsocketconnection
+ * @short_description: A socket connection
+ * @include: gio/gio.h
+ * @see_also: #GIOStream, #GSocketClient, #GSocketListener
*
- * The #GType for #GBytes.
+ * #GSocketConnection is a #GIOStream for a connected socket. They
+ * can be created either by #GSocketClient when connecting to a host,
+ * or by #GSocketListener when accepting a new client.
*
- * Since: 2.32
- */
-
-
-/**
- * G_TYPE_BYTE_ARRAY:
+ * The type of the #GSocketConnection object returned from these calls
+ * depends on the type of the underlying socket that is in use. For
+ * instance, for a TCP/IP connection it will be a #GTcpConnection.
+ *
+ * Choosing what type of object to construct is done with the socket
+ * connection factory, and it is possible for 3rd parties to register
+ * custom socket connection types for specific combination of socket
+ * family/type/protocol using g_socket_connection_factory_register_type().
*
- * The #GType for a boxed type holding a #GByteArray reference.
+ * 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
*/
/**
- * G_TYPE_CHAR:
+ * SECTION:gsocketcontrolmessage
+ * @title: GSocketControlMessage
+ * @short_description: A GSocket control message
+ * @include: gio/gio.h
+ * @see_also: #GSocket.
*
- * The fundamental type corresponding to #gchar.
- * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
- * This may or may not be the same type a the C type "gchar".
- */
-
-
-/**
- * G_TYPE_CHECK_CLASS_CAST:
- * @g_class: Location of a #GTypeClass structure.
- * @g_type: The type to be returned.
- * @c_type: The corresponding C type of class structure of @g_type.
+ * A #GSocketControlMessage is a special-purpose utility message that
+ * can be sent to or received from a #GSocket. These types of
+ * messages are often called "ancillary data".
*
- * Checks that @g_class is a class structure of the type identified by @g_type
- * and issues a warning if this is not the case. Returns @g_class casted
- * to a pointer to @c_type.
+ * 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 descriptor over
+ * a UNIX socket).
*
- * This macro should only be used in type implementations.
- */
-
-
-/**
- * G_TYPE_CHECK_CLASS_TYPE:
- * @g_class: Location of a #GTypeClass structure.
- * @g_type: The type to be checked.
+ * These messages are sent with g_socket_send_message() and received
+ * with g_socket_receive_message().
*
- * Checks if @g_class is a class structure of the type identified by
- * @g_type.
+ * To extend the set of control message that can be sent, subclass this
+ * class and override the get_size, get_level, get_type and serialize
+ * methods.
*
- * This macro should only be used in type implementations.
+ * To extend the set of control messages that can be received, subclass
+ * this class and implement the deserialize method. Also, make sure your
+ * class is registered with the GType typesystem before calling
+ * g_socket_receive_message() to read such a message.
*
- * Returns: %TRUE on success.
+ * Since: 2.22
*/
/**
- * G_TYPE_CHECK_INSTANCE:
- * @instance: Location of a #GTypeInstance structure.
+ * SECTION:gsocketlistener
+ * @title: GSocketListener
+ * @short_description: Helper for accepting network client connections
+ * @include: gio/gio.h
+ * @see_also: #GThreadedSocketService, #GSocketService.
*
- * Checks if @instance is a valid #GTypeInstance structure,
- * otherwise issues a warning and returns %FALSE.
+ * A #GSocketListener is an object that keeps track of a set
+ * of server sockets and helps you accept sockets from any of the
+ * socket, either sync or async.
*
- * This macro should only be used in type implementations.
+ * If you want to implement a network server, also look at #GSocketService
+ * and #GThreadedSocketService which are subclass of #GSocketListener
+ * that makes this even easier.
*
- * Returns: %TRUE on success.
+ * Since: 2.22
*/
/**
- * G_TYPE_CHECK_INSTANCE_CAST:
- * @instance: Location of a #GTypeInstance structure.
- * @g_type: The type to be returned.
- * @c_type: The corresponding C type of @g_type.
+ * SECTION:gsocketservice
+ * @title: GSocketService
+ * @short_description: Make it easy to implement a network service
+ * @include: gio/gio.h
+ * @see_also: #GThreadedSocketService, #GSocketListener.
*
- * Checks that @instance is an instance of the type identified by @g_type
- * and issues a warning if this is not the case. Returns @instance casted
- * to a pointer to @c_type.
+ * A #GSocketService is an object that represents a service that
+ * is provided to the network or over local sockets. When a new
+ * connection is made to the service the #GSocketService::incoming
+ * signal is emitted.
*
- * This macro should only be used in type implementations.
- */
-
-
-/**
- * G_TYPE_CHECK_INSTANCE_TYPE:
- * @instance: Location of a #GTypeInstance structure.
- * @g_type: The type to be checked
+ * A #GSocketService is a subclass of #GSocketListener and you need
+ * to add the addresses you want to accept connections on with the
+ * #GSocketListener APIs.
+ *
+ * There are two options for implementing a network service based on
+ * #GSocketService. The first is to create the service using
+ * g_socket_service_new() and to connect to the #GSocketService::incoming
+ * signal. The second is to subclass #GSocketService and override the
+ * default signal handler implementation.
*
- * Checks if @instance is an instance of the type identified by @g_type.
+ * In either case, the handler must immediately return, or else it
+ * will block additional incoming connections from being serviced.
+ * If you are interested in writing connection handlers that contain
+ * blocking code then see #GThreadedSocketService.
*
- * This macro should only be used in type implementations.
+ * 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.
*
- * Returns: %TRUE on success.
+ * Since: 2.22
*/
/**
- * G_TYPE_CHECK_VALUE:
- * @value: a #GValue
- *
- * Checks if @value has been initialized to hold values
- * of a value type.
+ * SECTION:gsrvtarget
+ * @short_description: DNS SRV record target
+ * @include: gio/gio.h
*
- * This macro should only be used in type implementations.
+ * SRV (service) records are used by some network protocols to provide
+ * service-specific aliasing and load-balancing. For example, XMPP
+ * (Jabber) uses SRV records to locate the XMPP server for a domain;
+ * rather than connecting directly to "example.com" or assuming a
+ * specific server hostname like "xmpp.example.com", an XMPP client
+ * would look up the "xmpp-client" SRV record for "example.com", and
+ * then connect to whatever host was pointed to by that record.
*
- * Returns: %TRUE on success.
+ * You can use g_resolver_lookup_service() or
+ * 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
+ * #GSrvTarget at all.
*/
/**
- * G_TYPE_CHECK_VALUE_TYPE:
- * @value: a #GValue
- * @g_type: The type to be checked.
+ * SECTION:gsubprocess
+ * @title: GSubprocess
+ * @short_description: Child processes
+ * @include: gio/gio.h
+ * @see_also: #GSubprocessLauncher
+ *
+ * #GSubprocess allows the creation of and interaction with child
+ * processes.
+ *
+ * Processes can be communicated with using standard GIO-style APIs (ie:
+ * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
+ * process termination (ie: cancellable and with an asynchronous
+ * variant).
*
- * Checks if @value has been initialized to hold values
- * of type @g_type.
+ * 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.
*
- * This macro should only be used in type implementations.
+ * 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.
*
- * Returns: %TRUE on success.
+ * Since: 2.40
*/
/**
- * G_TYPE_CLASS_GET_PRIVATE:
- * @klass: the class of a type deriving from @private_type.
- * @g_type: the type identifying which private data to retrieve.
- * @c_type: The C type for the private structure.
+ * SECTION:gtask
+ * @short_description: Cancellable synchronous or asynchronous task
+ * and result
+ * @include: gio/gio.h
+ * @see_also: #GAsyncResult
*
- * Gets the private class structure for a particular type.
- * The private structure must have been registered in the
- * get_type() function with g_type_add_class_private().
+ * 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);
+ * }
+ * ]|
*
- * This macro should only be used in type implementations.
+ * ## 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);
+ * }
+ * ]|
*
- * Since: 2.24
- * Returns: a pointer to the private data structure.
- */
-
-
-/**
- * G_TYPE_CLOSURE:
+ * ## 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);
+ * }
+ * ]|
*
- * The #GType for #GClosure.
- */
-
-
-/**
- * G_TYPE_DATE:
+ * ## 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;
+ * }
+ * ]|
*
- * The #GType for #GDate.
+ * ## 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()).
*/
/**
- * G_TYPE_DATE_TIME:
+ * SECTION:gtcpconnection
+ * @title: GTcpConnection
+ * @short_description: A TCP GSocketConnection
+ * @include: gio/gio.h
+ * @see_also: #GSocketConnection.
*
- * The #GType for a boxed type holding a #GDateTime.
+ * This is the subclass of #GSocketConnection that is created
+ * for TCP/IP sockets.
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * G_TYPE_DBUS_ANNOTATION_INFO:
+ * SECTION:gtcpwrapperconnection
+ * @title: GTcpWrapperConnection
+ * @short_description: Wrapper for non-GSocketConnection-based,
+ * GSocket-based GIOStreams
+ * @include: gio/gio.h
+ * @see_also: #GSocketConnection.
*
- * The #GType for a boxed type holding a #GDBusAnnotationInfo.
+ * 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
+ * always return a #GSocketConnection, even when the connection it has
+ * actually created is not directly a #GSocketConnection.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * G_TYPE_DBUS_ARG_INFO:
+ * SECTION:gtestdbus
+ * @short_description: D-Bus testing helper
+ * @include: gio/gio.h
*
- * The #GType for a boxed type holding a #GDBusArgInfo.
+ * 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) .
*
- * Since: 2.26
+ * CLEANFILES += gschemas.compiled
+ * ]|
*/
/**
- * G_TYPE_DBUS_INTERFACE_INFO:
- *
- * The #GType for a boxed type holding a #GDBusInterfaceInfo.
+ * SECTION:gthemedicon
+ * @short_description: Icon theming support
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon
*
- * Since: 2.26
+ * #GThemedIcon is an implementation of #GIcon that supports icon themes.
+ * #GThemedIcon contains a list of all of the icons present in an icon
+ * theme, so that icons can be looked up quickly. #GThemedIcon does
+ * not provide actual pixmaps for icons, just the icon names.
+ * Ideally something like gtk_icon_theme_choose_icon() should be used to
+ * resolve the list of names so that fallback icons work nicely with
+ * themes that inherit other themes.
*/
/**
- * G_TYPE_DBUS_METHOD_INFO:
+ * SECTION:gthreadedsocketservice
+ * @title: GThreadedSocketService
+ * @short_description: A threaded GSocketService
+ * @include: gio/gio.h
+ * @see_also: #GSocketService.
*
- * The #GType for a boxed type holding a #GDBusMethodInfo.
+ * A #GThreadedSocketService is a simple subclass of #GSocketService
+ * that handles incoming connections by creating a worker thread and
+ * dispatching the connection to it by emitting the
+ * #GThreadedSocketService::run signal in the new thread.
*
- * Since: 2.26
- */
-
-
-/**
- * G_TYPE_DBUS_NODE_INFO:
+ * The signal handler may perform blocking IO and need not return
+ * until the connection is closed.
*
- * The #GType for a boxed type holding a #GDBusNodeInfo.
+ * The service is implemented using a thread pool, so there is a
+ * limited amount of threads available to serve incoming requests.
+ * The service automatically stops the #GSocketService from accepting
+ * new connections when all threads are busy.
*
- * Since: 2.26
+ * As with #GSocketService, you may connect to #GThreadedSocketService::run,
+ * or subclass and override the default handler.
*/
/**
- * G_TYPE_DBUS_PROPERTY_INFO:
+ * SECTION:gtls
+ * @title: TLS Overview
+ * @short_description: TLS (aka SSL) support for GSocketConnection
+ * @include: gio/gio.h
*
- * The #GType for a boxed type holding a #GDBusPropertyInfo.
+ * #GTlsConnection and related classes provide TLS (Transport Layer
+ * Security, previously known as SSL, Secure Sockets Layer) support for
+ * gio-based network streams.
*
- * Since: 2.26
- */
-
-
-/**
- * G_TYPE_DBUS_SIGNAL_INFO:
+ * In the simplest case, for a client connection, you can just set the
+ * #GSocketClient:tls flag on a #GSocketClient, and then any
+ * connections created by that client will have TLS negotiated
+ * automatically, using appropriate default settings, and rejecting
+ * any invalid or self-signed certificates (unless you change that
+ * default by setting the #GSocketClient:tls-validation-flags
+ * property). The returned object will be a #GTcpWrapperConnection,
+ * which wraps the underlying #GTlsClientConnection.
*
- * The #GType for a boxed type holding a #GDBusSignalInfo.
+ * For greater control, you can create your own #GTlsClientConnection,
+ * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
+ * pollable input and output streams) and then connect to its signals,
+ * such as #GTlsConnection::accept-certificate, before starting the
+ * handshake.
*
- * Since: 2.26
+ * Server-side TLS is similar, using #GTlsServerConnection. At the
+ * moment, there is no support for automatically wrapping server-side
+ * connections in the way #GSocketClient does for client-side
+ * connections.
*/
/**
- * G_TYPE_DOUBLE:
+ * SECTION:gtlsbackend
+ * @title: GTlsBackend
+ * @short_description: TLS backend implementation
+ * @include: gio/gio.h
*
- * The fundamental type corresponding to #gdouble.
- */
-
-
-/**
- * G_TYPE_ENUM:
+ * TLS (Transport Layer Security, aka SSL) backend
*
- * The fundamental type from which all enumeration types are derived.
+ * Since: 2.28
*/
/**
- * G_TYPE_ERROR:
+ * SECTION:gtlscertificate
+ * @title: GTlsCertificate
+ * @short_description: TLS certificate
+ * @include: gio/gio.h
+ * @see_also: #GTlsConnection
*
- * The #GType for a boxed type holding a #GError.
+ * A certificate used for TLS authentication and encryption.
+ * This can represent either a certificate only (eg, the certificate
+ * received by a client from a server), or the combination of
+ * a certificate and a private key (which is needed when acting as a
+ * #GTlsServerConnection).
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * G_TYPE_FLAGS:
+ * SECTION:gtlsclientconnection
+ * @short_description: TLS client-side connection
+ * @include: gio/gio.h
*
- * The fundamental type from which all flags types are derived.
+ * #GTlsClientConnection is the client-side subclass of
+ * #GTlsConnection, representing a client-side TLS connection.
*/
/**
- * G_TYPE_FLAG_RESERVED_ID_BIT:
+ * SECTION:gtlsconnection
+ * @short_description: TLS connection type
+ * @include: gio/gio.h
*
- * A bit in the type number that's supposed to be left untouched.
- */
-
-
-/**
- * G_TYPE_FLOAT:
+ * #GTlsConnection is the base TLS connection class type, which wraps
+ * a #GIOStream and provides TLS encryption on top of it. Its
+ * subclasses, #GTlsClientConnection and #GTlsServerConnection,
+ * implement client-side and server-side TLS, respectively.
*
- * The fundamental type corresponding to #gfloat.
+ * Since: 2.28
*/
/**
- * G_TYPE_FROM_CLASS:
- * @g_class: Location of a valid #GTypeClass structure.
+ * SECTION:gtlsdatabase
+ * @short_description: TLS database type
+ * @include: gio/gio.h
*
- * Get the type identifier from a given @class structure.
+ * #GTlsDatabase is used to lookup certificates and other information
+ * from a certificate or key store. It is an abstract base class which
+ * TLS library specific subtypes override.
*
- * This macro should only be used in type implementations.
+ * Most common client applications will not directly interact with
+ * #GTlsDatabase. It is used internally by #GTlsConnection.
*
- * Returns: the #GType
+ * Since: 2.30
*/
/**
- * G_TYPE_FROM_INSTANCE:
- * @instance: Location of a valid #GTypeInstance structure.
- *
- * Get the type identifier from a given @instance structure.
+ * SECTION:gtlsfiledatabase
+ * @short_description: TLS file based database type
+ * @include: gio/gio.h
*
- * This macro should only be used in type implementations.
+ * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
+ * their certificate information from a file. It is an interface which
+ * TLS library specific subtypes implement.
*
- * Returns: the #GType
+ * Since: 2.30
*/
/**
- * G_TYPE_FROM_INTERFACE:
- * @g_iface: Location of a valid #GTypeInterface structure.
+ * SECTION:gtlsinteraction
+ * @short_description: Interaction with the user during TLS operations.
+ * @include: gio/gio.h
*
- * Get the type identifier from a given @interface structure.
+ * #GTlsInteraction provides a mechanism for the TLS connection and database
+ * code to interact with the user. It can be used to ask the user for passwords.
*
- * This macro should only be used in type implementations.
+ * To use a #GTlsInteraction with a TLS connection use
+ * g_tls_connection_set_interaction().
*
- * Returns: the #GType
- */
-
-
-/**
- * G_TYPE_FUNDAMENTAL:
- * @type: A #GType value.
+ * Callers should instantiate a derived class that implements the various
+ * interaction methods to show the required dialogs.
*
- * The fundamental type which is the ancestor of @type.
- * Fundamental types are types that serve as ultimate bases for the derived types,
- * thus they are the roots of distinct inheritance hierarchies.
- */
-
-
-/**
- * G_TYPE_FUNDAMENTAL_MAX:
+ * Callers should use the 'invoke' functions like
+ * g_tls_interaction_invoke_ask_password() to run interaction methods. These
+ * functions make sure that the interaction is invoked in the main loop
+ * and not in the current thread, if the current thread is not running the
+ * main loop.
*
- * An integer constant that represents the number of identifiers reserved
- * for types that are assigned at compile-time.
+ * Derived classes can choose to implement whichever interactions methods they'd
+ * like to support by overriding those virtual methods in their class
+ * initialization function. Any interactions not implemented will return
+ * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
+ * it must also implement the corresponding finish method.
*/
/**
- * G_TYPE_FUNDAMENTAL_SHIFT:
+ * SECTION:gtlspassword
+ * @title: GTlsPassword
+ * @short_description: TLS Passwords for prompting
+ * @include: gio/gio.h
*
- * Shift value used in converting numbers to type IDs.
+ * Holds a password used in TLS.
*/
/**
- * G_TYPE_GSTRING:
+ * SECTION:gtlsserverconnection
+ * @short_description: TLS server-side connection
+ * @include: gio/gio.h
+ *
+ * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
+ * representing a server-side TLS connection.
*
- * The #GType for #GString.
+ * Since: 2.28
*/
/**
- * G_TYPE_GTYPE:
+ * SECTION:gunixconnection
+ * @title: GUnixConnection
+ * @short_description: A UNIX domain GSocketConnection
+ * @include: gio/gunixconnection.h
+ * @see_also: #GSocketConnection.
+ *
+ * This is the subclass of #GSocketConnection that is created
+ * for UNIX domain sockets.
+ *
+ * It contains functions to do some of the UNIX socket specific
+ * functionality like passing file descriptors.
+ *
+ * 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.
*
- * The type for #GType.
+ * Since: 2.22
*/
/**
- * G_TYPE_HASH_TABLE:
+ * SECTION:gunixcredentialsmessage
+ * @title: GUnixCredentialsMessage
+ * @short_description: A GSocketControlMessage containing credentials
+ * @include: gio/gunixcredentialsmessage.h
+ * @see_also: #GUnixConnection, #GSocketControlMessage
*
- * The #GType for a boxed type holding a #GHashTable reference.
+ * This #GSocketControlMessage contains a #GCredentials instance. It
+ * may be sent using g_socket_send_message() and received using
+ * g_socket_receive_message() over UNIX sockets (ie: sockets in the
+ * %G_SOCKET_FAMILY_UNIX family).
*
- * Since: 2.10
+ * For an easier way to send and receive credentials over
+ * stream-oriented UNIX sockets, see
+ * g_unix_connection_send_credentials() and
+ * g_unix_connection_receive_credentials(). To receive credentials of
+ * a foreign process connected to a socket, use
+ * g_socket_get_credentials().
*/
/**
- * G_TYPE_HAS_VALUE_TABLE:
- * @type: A #GType value.
+ * SECTION:gunixfdlist
+ * @title: GUnixFDList
+ * @short_description: An object containing a set of UNIX file descriptors
+ * @include: gio/gunixfdlist.h
+ * @see_also: #GUnixFDMessage
+ *
+ * A #GUnixFDList contains a list of file descriptors. It owns the file
+ * descriptors that it contains, closing them when finalized.
*
- * Checks if @type has a #GTypeValueTable.
+ * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
+ * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
+ * and received using g_socket_receive_message().
*
- * Returns: %TRUE on success.
+ * 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.
*/
/**
- * G_TYPE_INITIALLY_UNOWNED:
+ * SECTION:gunixfdmessage
+ * @title: GUnixFDMessage
+ * @short_description: A GSocketControlMessage containing a GUnixFDList
+ * @include: gio/gunixfdmessage.h
+ * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
+ *
+ * This #GSocketControlMessage contains a #GUnixFDList.
+ * It may be sent using g_socket_send_message() and received using
+ * g_socket_receive_message() over UNIX sockets (ie: sockets in the
+ * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
+ * between processes by the kernel.
+ *
+ * For an easier way to send and receive file descriptors over
+ * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
+ * g_unix_connection_receive_fd().
*
- * The type for #GInitiallyUnowned.
+ * 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.
*/
/**
- * G_TYPE_INSTANCE_GET_CLASS:
- * @instance: Location of the #GTypeInstance structure.
- * @g_type: The #GType of the class to be returned.
- * @c_type: The C type of the class structure.
- *
- * Get the class structure of a given @instance, casted
- * to a specified ancestor type @g_type of the instance.
- *
- * Note that while calling a GInstanceInitFunc(), the class pointer gets
- * modified, so it might not always return the expected pointer.
+ * SECTION:gunixinputstream
+ * @short_description: Streaming input operations for UNIX file descriptors
+ * @include: gio/gunixinputstream.h
+ * @see_also: #GInputStream
*
- * This macro should only be used in type implementations.
+ * #GUnixInputStream implements #GInputStream for reading from a UNIX
+ * file descriptor, including asynchronous operations. (If the file
+ * descriptor refers to a socket or pipe, this will use poll() to do
+ * asynchronous I/O. If it refers to a regular file, it will fall back
+ * to doing asynchronous I/O in another thread.)
*
- * Returns: a pointer to the class structure
+ * 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.
*/
/**
- * G_TYPE_INSTANCE_GET_INTERFACE:
- * @instance: Location of the #GTypeInstance structure.
- * @g_type: The #GType of the interface to be returned.
- * @c_type: The C type of the interface structure.
- *
- * Get the interface structure for interface @g_type of a given @instance.
+ * SECTION:gunixmounts
+ * @include: gio/gunixmounts.h
+ * @short_description: UNIX mounts
*
- * This macro should only be used in type implementations.
+ * Routines for managing mounted UNIX mount points and paths.
*
- * Returns: a pointer to the interface structure
+ * 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.
*/
/**
- * G_TYPE_INSTANCE_GET_PRIVATE:
- * @instance: the instance of a type deriving from @private_type.
- * @g_type: the type identifying which private data to retrieve.
- * @c_type: The C type for the private structure.
- *
- * Gets the private structure for a particular type.
- * The private structure must have been registered in the
- * class_init function with g_type_class_add_private().
+ * SECTION:gunixoutputstream
+ * @short_description: Streaming output operations for UNIX file descriptors
+ * @include: gio/gunixoutputstream.h
+ * @see_also: #GOutputStream
*
- * This macro should only be used in type implementations.
+ * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
+ * file descriptor, including asynchronous operations. (If the file
+ * descriptor refers to a socket or pipe, this will use poll() to do
+ * asynchronous I/O. If it refers to a regular file, it will fall back
+ * to doing asynchronous I/O in another thread.)
*
- * Since: 2.4
- * Returns: a pointer to the private data structure.
+ * 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.
*/
/**
- * G_TYPE_INT:
+ * SECTION:gunixsocketaddress
+ * @short_description: UNIX GSocketAddress
+ * @include: gio/gunixsocketaddress.h
*
- * The fundamental type corresponding to #gint.
- */
-
-
-/**
- * G_TYPE_INT64:
+ * Support for UNIX-domain (also known as local) sockets.
*
- * The fundamental type corresponding to #gint64.
- */
-
-
-/**
- * G_TYPE_INTERFACE:
+ * UNIX domain sockets are generally visible in the filesystem.
+ * However, some systems support abstract socket names which are not
+ * visible in the filesystem and not affected by the filesystem
+ * permissions, visibility, etc. Currently this is only supported
+ * under Linux. If you attempt to use abstract sockets on other
+ * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
+ * errors. You can use g_unix_socket_address_abstract_names_supported()
+ * to see if abstract names are supported.
*
- * The fundamental type from which all interfaces are derived.
+ * 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.
*/
/**
- * G_TYPE_INVALID:
+ * SECTION:gvfs
+ * @short_description: Virtual File System
+ * @include: gio/gio.h
*
- * An invalid #GType used as error return value in some functions which return
- * a #GType.
+ * Entry point for using GIO functionality.
*/
/**
- * G_TYPE_IO_CHANNEL:
+ * SECTION:gvolume
+ * @short_description: Volume management
+ * @include: gio/gio.h
*
- * The #GType for #GIOChannel.
- */
-
-
-/**
- * G_TYPE_IO_CONDITION:
+ * The #GVolume interface represents user-visible objects that can be
+ * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
+ * equivalent of #GnomeVFSDrive.
*
- * The #GType for #GIOCondition.
- */
-
-
-/**
- * G_TYPE_IS_ABSTRACT:
- * @type: A #GType value.
+ * Mounting a #GVolume instance is an asynchronous operation. For more
+ * information about asynchronous operations, see #GAsyncResult and
+ * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
+ * least) the #GVolume instance, optionally a #GMountOperation object
+ * and a #GAsyncReadyCallback.
*
- * Checks if @type is an abstract type. An abstract type cannot be
- * instantiated and is normally used as an abstract base class for
- * derived classes.
+ * Typically, one will only want to pass %NULL for the
+ * #GMountOperation if automounting all volumes when a desktop session
+ * starts since it's not desirable to put up a lot of dialogs asking
+ * for credentials.
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_TYPE_IS_CLASSED:
- * @type: A #GType value.
+ * The callback will be fired when the operation has resolved (either
+ * with success or failure), and a #GAsyncReady structure will be
+ * passed to the callback. That callback should then call
+ * g_volume_mount_finish() with the #GVolume instance and the
+ * #GAsyncReady data to see if the operation was completed
+ * successfully. If an @error is present when g_volume_mount_finish()
+ * is called, then it will be filled with any error information.
*
- * Checks if @type is a classed type.
+ * ## Volume Identifiers # {#volume-identifier}
*
- * Returns: %TRUE on success.
- */
-
-
-/**
- * G_TYPE_IS_DEEP_DERIVABLE:
- * @type: A #GType value.
+ * 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. `/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.
*
- * Checks if @type is a deep derivable type. A deep derivable type
- * can be used as the base class of a deep (multi-level) class hierarchy.
*
- * Returns: %TRUE on success.
+ * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
+ * when the gvfs hal volume monitor is in use. Other volume monitors
+ * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
+ * identifier, which can be used to obtain a hal device by means of
+ * libhal_manager_find_device_string_match().
*/
/**
- * G_TYPE_IS_DERIVABLE:
- * @type: A #GType value.
+ * SECTION:gvolumemonitor
+ * @short_description: Volume Monitor
+ * @include: gio/gio.h
+ * @see_also: #GFileMonitor
*
- * Checks if @type is a derivable type. A derivable type can
- * be used as the base class of a flat (single-level) class hierarchy.
+ * #GVolumeMonitor is for listing the user interesting devices and volumes
+ * on the computer. In other words, what a file selector or file manager
+ * would show in a sidebar.
*
- * Returns: %TRUE on success.
+ * #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.
*/
/**
- * G_TYPE_IS_DERIVED:
- * @type: A #GType value.
+ * SECTION:gwin32inputstream
+ * @short_description: Streaming input operations for Windows file handles
+ * @include: gio/gwin32inputstream.h
+ * @see_also: #GInputStream
*
- * Checks if @type is derived (or in object-oriented terminology:
- * inherited) from another type (this holds true for all non-fundamental
- * types).
+ * #GWin32InputStream implements #GInputStream for reading from a
+ * Windows file handle.
*
- * Returns: %TRUE on success.
+ * 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.
*/
/**
- * G_TYPE_IS_ENUM:
- * @type: a #GType ID.
+ * SECTION:gwin32outputstream
+ * @short_description: Streaming output operations for Windows file handles
+ * @include: gio/gwin32outputstream.h
+ * @see_also: #GOutputStream
*
- * Checks whether @type "is a" %G_TYPE_ENUM.
+ * #GWin32OutputStream implements #GOutputStream for writing to a
+ * Windows file handle.
*
- * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.
+ * 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_TYPE_IS_FLAGS:
- * @type: a #GType ID.
- *
- * Checks whether @type "is a" %G_TYPE_FLAGS.
+ * SECTION:gzcompressor
+ * @short_description: Zlib compressor
+ * @include: gio/gio.h
*
- * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.
+ * #GZlibCompressor is an implementation of #GConverter that
+ * compresses data using zlib.
*/
/**
- * G_TYPE_IS_FUNDAMENTAL:
- * @type: A #GType value.
- *
- * Checks if @type is a fundamental type.
+ * SECTION:gzdecompressor
+ * @short_description: Zlib decompressor
+ * @include: gio/gio.h
*
- * Returns: %TRUE on success.
+ * #GZlibDecompressor is an implementation of #GConverter that
+ * decompresses data compressed with zlib.
*/
/**
- * G_TYPE_IS_INSTANTIATABLE:
- * @type: A #GType value.
+ * _GFreedesktopDBus:
*
- * Checks if @type can be instantiated. Instantiation is the
- * process of creating an instance (object) of this type.
- *
- * Returns: %TRUE on success.
+ * Abstract interface type for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
*/
/**
- * G_TYPE_IS_INTERFACE:
- * @type: A #GType value.
+ * _GFreedesktopDBus::handle-add-match:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_rule: Argument passed by remote caller.
*
- * Checks if @type is an interface type.
- * An interface type provides a pure API, the implementation
- * of which is provided by another type (which is then said to conform
- * to the interface). GLib interfaces are somewhat analogous to Java
- * interfaces and C++ classes containing only pure virtual functions,
- * with the difference that GType interfaces are not derivable (but see
- * g_type_interface_add_prerequisite() for an alternative).
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method.
*
- * Returns: %TRUE on success.
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_add_match() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
+ *
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_IS_OBJECT:
- * @type: Type id to check
+ * _GFreedesktopDBus::handle-get-connection-selinux-security-context:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
*
- * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method.
*
- * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
- */
-
-
-/**
- * G_TYPE_IS_PARAM:
- * @type: a #GType ID
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_selinux_security_context() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * Checks whether @type "is a" %G_TYPE_PARAM.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_IS_VALUE:
- * @type: A #GType value.
+ * _GFreedesktopDBus::handle-get-connection-unix-process-id:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
+ *
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method.
*
- * Checks whether the passed in type ID can be used for g_value_init().
- * That is, this macro checks whether this type provides an implementation
- * of the #GTypeValueTable functions required for a type to create a #GValue of.
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_unix_process_id() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * Returns: Whether @type is suitable as a #GValue type.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_IS_VALUE_ABSTRACT:
- * @type: A #GType value.
+ * _GFreedesktopDBus::handle-get-connection-unix-user:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
+ *
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method.
*
- * Checks if @type is an abstract value type. An abstract value type introduces
- * a value table, but can't be used for g_value_init() and is normally used as
- * an abstract base type for derived value types.
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_connection_unix_user() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * Returns: %TRUE on success.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_IS_VALUE_TYPE:
- * @type: A #GType value.
+ * _GFreedesktopDBus::handle-get-id:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ *
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method.
*
- * Checks if @type is a value type and can be used with g_value_init().
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_id() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * Returns: %TRUE on success.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_KEY_FILE:
+ * _GFreedesktopDBus::handle-get-name-owner:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
*
- * The #GType for a boxed type holding a #GKeyFile.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method.
*
- * Since: 2.32
- */
-
-
-/**
- * G_TYPE_LONG:
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_get_name_owner() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * The fundamental type corresponding to #glong.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_MAIN_CONTEXT:
+ * _GFreedesktopDBus::handle-hello:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
*
- * The #GType for a boxed type holding a #GMainContext.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method.
*
- * Since: 2.30
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_hello() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
+ *
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_MAIN_LOOP:
+ * _GFreedesktopDBus::handle-list-activatable-names:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
*
- * The #GType for a boxed type holding a #GMainLoop.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method.
*
- * Since: 2.30
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_activatable_names() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
+ *
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_MAKE_FUNDAMENTAL:
- * @x: the fundamental type number.
+ * _GFreedesktopDBus::handle-list-names:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
*
- * Get the type ID for the fundamental type number @x.
- * Use g_type_fundamental_next() instead of this macro to create new fundamental
- * types.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method.
*
- * Returns: the GType
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_names() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
+ *
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_MATCH_INFO:
+ * _GFreedesktopDBus::handle-list-queued-owners:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
*
- * The #GType for a boxed type holding a #GMatchInfo reference.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method.
*
- * Since: 2.30
- */
-
-
-/**
- * G_TYPE_NONE:
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_list_queued_owners() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * A fundamental type which is used as a replacement for the C
- * <literal>void</literal> return type.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_OBJECT:
+ * _GFreedesktopDBus::handle-name-has-owner:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
*
- * The fundamental type for #GObject.
- */
-
-
-/**
- * G_TYPE_PARAM:
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method.
*
- * The fundamental type from which all #GParamSpec types are derived.
- */
-
-
-/**
- * G_TYPE_PARAM_BOOLEAN:
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_name_has_owner() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * The #GType of #GParamSpecBoolean.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_BOXED:
+ * _GFreedesktopDBus::handle-release-name:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
*
- * The #GType of #GParamSpecBoxed.
- */
-
-
-/**
- * G_TYPE_PARAM_CHAR:
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method.
*
- * The #GType of #GParamSpecChar.
- */
-
-
-/**
- * G_TYPE_PARAM_DOUBLE:
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_release_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * The #GType of #GParamSpecDouble.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_ENUM:
+ * _GFreedesktopDBus::handle-reload-config:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
*
- * The #GType of #GParamSpecEnum.
- */
-
-
-/**
- * G_TYPE_PARAM_FLAGS:
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method.
*
- * The #GType of #GParamSpecFlags.
- */
-
-
-/**
- * G_TYPE_PARAM_FLOAT:
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_reload_config() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * The #GType of #GParamSpecFloat.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_GTYPE:
+ * _GFreedesktopDBus::handle-remove-match:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_rule: Argument passed by remote caller.
*
- * The #GType of #GParamSpecGType.
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method.
*
- * Since: 2.10
- */
-
-
-/**
- * G_TYPE_PARAM_INT:
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_remove_match() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * The #GType of #GParamSpecInt.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_INT64:
+ * _GFreedesktopDBus::handle-request-name:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
+ * @arg_flags: Argument passed by remote caller.
*
- * The #GType of #GParamSpecInt64.
- */
-
-
-/**
- * G_TYPE_PARAM_LONG:
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method.
*
- * The #GType of #GParamSpecLong.
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_request_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
+ *
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_OBJECT:
+ * _GFreedesktopDBus::handle-start-service-by-name:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_name: Argument passed by remote caller.
+ * @arg_flags: Argument passed by remote caller.
+ *
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method.
+ *
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_start_service_by_name() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * The #GType of #GParamSpecObject.
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_OVERRIDE:
+ * _GFreedesktopDBus::handle-update-activation-environment:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: A #GDBusMethodInvocation.
+ * @arg_environment: Argument passed by remote caller.
+ *
+ * Signal emitted when a remote caller is invoking the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method.
*
- * The #GType of #GParamSpecOverride.
+ * If a signal handler returns %TRUE, it means the signal handler will handle the invocation (e.g. take a reference to @invocation and eventually call _g_freedesktop_dbus_complete_update_activation_environment() or e.g. g_dbus_method_invocation_return_error() on it) and no order signal handlers will run. If no signal handler handles the invocation, the %G_DBUS_ERROR_UNKNOWN_METHOD error is returned.
*
- * Since: 2.4
+ * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run.
*/
/**
- * G_TYPE_PARAM_PARAM:
+ * _GFreedesktopDBus::name-acquired:
+ * @object: A #_GFreedesktopDBus.
+ * @arg_name: Argument.
*
- * The #GType of #GParamSpecParam.
+ * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> is received.
+ *
+ * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
*/
/**
- * G_TYPE_PARAM_POINTER:
+ * _GFreedesktopDBus::name-lost:
+ * @object: A #_GFreedesktopDBus.
+ * @arg_name: Argument.
+ *
+ * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> is received.
*
- * The #GType of #GParamSpecPointer.
+ * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
*/
/**
- * G_TYPE_PARAM_STRING:
+ * _GFreedesktopDBus::name-owner-changed:
+ * @object: A #_GFreedesktopDBus.
+ * @arg_name: Argument.
+ * @arg_old_owner: Argument.
+ * @arg_new_owner: Argument.
*
- * The #GType of #GParamSpecString.
+ * On the client-side, this signal is emitted whenever the D-Bus signal <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> is received.
+ *
+ * On the service-side, this signal can be used with e.g. g_signal_emit_by_name() to make the object emit the D-Bus signal.
*/
/**
- * G_TYPE_PARAM_UCHAR:
+ * _GFreedesktopDBusIface:
+ * @parent_iface: The parent interface.
+ * @handle_add_match: Handler for the #_GFreedesktopDBus::handle-add-match signal.
+ * @handle_get_connection_selinux_security_context: Handler for the #_GFreedesktopDBus::handle-get-connection-selinux-security-context signal.
+ * @handle_get_connection_unix_process_id: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-process-id signal.
+ * @handle_get_connection_unix_user: Handler for the #_GFreedesktopDBus::handle-get-connection-unix-user signal.
+ * @handle_get_id: Handler for the #_GFreedesktopDBus::handle-get-id signal.
+ * @handle_get_name_owner: Handler for the #_GFreedesktopDBus::handle-get-name-owner signal.
+ * @handle_hello: Handler for the #_GFreedesktopDBus::handle-hello signal.
+ * @handle_list_activatable_names: Handler for the #_GFreedesktopDBus::handle-list-activatable-names signal.
+ * @handle_list_names: Handler for the #_GFreedesktopDBus::handle-list-names signal.
+ * @handle_list_queued_owners: Handler for the #_GFreedesktopDBus::handle-list-queued-owners signal.
+ * @handle_name_has_owner: Handler for the #_GFreedesktopDBus::handle-name-has-owner signal.
+ * @handle_release_name: Handler for the #_GFreedesktopDBus::handle-release-name signal.
+ * @handle_reload_config: Handler for the #_GFreedesktopDBus::handle-reload-config signal.
+ * @handle_remove_match: Handler for the #_GFreedesktopDBus::handle-remove-match signal.
+ * @handle_request_name: Handler for the #_GFreedesktopDBus::handle-request-name signal.
+ * @handle_start_service_by_name: Handler for the #_GFreedesktopDBus::handle-start-service-by-name signal.
+ * @handle_update_activation_environment: Handler for the #_GFreedesktopDBus::handle-update-activation-environment signal.
+ * @name_acquired: Handler for the #_GFreedesktopDBus::name-acquired signal.
+ * @name_lost: Handler for the #_GFreedesktopDBus::name-lost signal.
+ * @name_owner_changed: Handler for the #_GFreedesktopDBus::name-owner-changed signal.
*
- * The #GType of #GParamSpecUChar.
+ * Virtual table for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
*/
/**
- * G_TYPE_PARAM_UINT:
+ * _GFreedesktopDBusProxy:
*
- * The #GType of #GParamSpecUInt.
+ * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API.
*/
/**
- * G_TYPE_PARAM_UINT64:
+ * _GFreedesktopDBusProxyClass:
+ * @parent_class: The parent class.
*
- * The #GType of #GParamSpecUInt64.
+ * Class structure for #_GFreedesktopDBusProxy.
*/
/**
- * G_TYPE_PARAM_ULONG:
+ * _GFreedesktopDBusSkeleton:
*
- * The #GType of #GParamSpecULong.
+ * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API.
*/
/**
- * G_TYPE_PARAM_UNICHAR:
+ * _GFreedesktopDBusSkeletonClass:
+ * @parent_class: The parent class.
*
- * The #GType of #GParamSpecUnichar.
+ * Class structure for #_GFreedesktopDBusSkeleton.
*/
/**
- * G_TYPE_PARAM_VALUE_ARRAY:
+ * _g_dbus_initialize:
*
- * The #GType of #GParamSpecValueArray.
+ * Does various one-time init things such as
+ *
+ * - registering the G_DBUS_ERROR error domain
+ * - parses the G_DBUS_DEBUG environment variable
*/
/**
- * G_TYPE_PARAM_VARIANT:
+ * _g_file_attribute_value_as_string:
+ * @attr: a #GFileAttributeValue.
*
- * The #GType of #GParamSpecVariant.
+ * Converts a #GFileAttributeValue to a string for display.
+ * The returned string should be freed when no longer needed.
*
- * Since: 2.26
+ * Returns: a string from the @attr, %NULL on error, or "<invalid>"
+ * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
*/
/**
- * G_TYPE_POINTER:
+ * _g_file_attribute_value_clear:
+ * @attr: a #GFileAttributeValue.
*
- * The fundamental type corresponding to #gpointer.
+ * Clears the value of @attr and sets its type to
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID.
*/
/**
- * G_TYPE_PTR_ARRAY:
- *
- * The #GType for a boxed type holding a #GPtrArray reference.
+ * _g_file_attribute_value_free:
+ * @attr: a #GFileAttributeValue.
*
- * Since: 2.22
+ * Frees the memory used by @attr.
*/
/**
- * G_TYPE_REGEX:
+ * _g_file_attribute_value_get_boolean:
+ * @attr: a #GFileAttributeValue.
*
- * The #GType for a boxed type holding a #GRegex reference.
+ * Gets the boolean value from a file attribute value. If the value is not the
+ * right type then %FALSE will be returned.
*
- * Since: 2.14
+ * Returns: the boolean value contained within the attribute, or %FALSE.
*/
/**
- * G_TYPE_RESERVED_BSE_FIRST:
+ * _g_file_attribute_value_get_byte_string:
+ * @attr: a #GFileAttributeValue.
*
- * First fundamental type number to create a new fundamental type id with
- * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
- */
-
-
-/**
- * G_TYPE_RESERVED_BSE_LAST:
+ * Gets the byte string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
*
- * Last fundamental type number reserved for BSE.
+ * Returns: the byte string contained within the attribute or %NULL.
*/
/**
- * G_TYPE_RESERVED_GLIB_FIRST:
+ * _g_file_attribute_value_get_int32:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the signed 32-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * First fundamental type number to create a new fundamental type id with
- * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
+ * Returns: the signed 32-bit integer from the attribute, or 0.
*/
/**
- * G_TYPE_RESERVED_GLIB_LAST:
+ * _g_file_attribute_value_get_int64:
+ * @attr: a #GFileAttributeValue.
*
- * Last fundamental type number reserved for GLib.
+ * Gets the signed 64-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
+ *
+ * Returns: the signed 64-bit integer from the attribute, or 0.
*/
/**
- * G_TYPE_RESERVED_USER_FIRST:
+ * _g_file_attribute_value_get_object:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the GObject from a file attribute value. If the value
+ * is not the right type then %NULL will be returned.
*
- * First available fundamental type number to create new fundamental
- * type id with G_TYPE_MAKE_FUNDAMENTAL().
+ * Returns: the GObject from the attribute, or %NULL.
*/
/**
- * G_TYPE_SETTINGS_SCHEMA:
+ * _g_file_attribute_value_get_string:
+ * @attr: a #GFileAttributeValue.
*
- * A boxed #GType corresponding to #GSettingsSchema.
+ * Gets the string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
*
- * Since: 2.32
+ * Returns: the UTF-8 string value contained within the attribute, or %NULL.
*/
/**
- * G_TYPE_SETTINGS_SCHEMA_SOURCE:
+ * _g_file_attribute_value_get_uint32:
+ * @attr: a #GFileAttributeValue.
*
- * A boxed #GType corresponding to #GSettingsSchemaSource.
+ * Gets the unsigned 32-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * Since: 2.32
+ * Returns: the unsigned 32-bit integer from the attribute, or 0.
*/
/**
- * G_TYPE_SOURCE:
+ * _g_file_attribute_value_get_uint64:
+ * @attr: a #GFileAttributeValue.
*
- * The #GType for a boxed type holding a #GSource.
+ * Gets the unsigned 64-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
*
- * Since: 2.30
+ * Returns: the unsigned 64-bit integer from the attribute, or 0.
*/
/**
- * G_TYPE_STRING:
+ * _g_file_attribute_value_new:
+ *
+ * Creates a new file attribute.
*
- * The fundamental type corresponding to nul-terminated C strings.
+ * Returns: a #GFileAttributeValue.
*/
/**
- * G_TYPE_STRV:
- *
- * The #GType for a boxed type holding a %NULL-terminated array of strings.
- *
- * The code fragments in the following example show the use of a property of
- * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
- * and g_object_get().
- *
- * |[
- * g_object_class_install_property (object_class,
- * PROP_AUTHORS,
- * g_param_spec_boxed ("authors",
- * _("Authors"),
- * _("List of authors"),
- * G_TYPE_STRV,
- * G_PARAM_READWRITE));
- *
- * gchar *authors[] = { "Owen", "Tim", NULL };
- * g_object_set (obj, "authors", authors, NULL);
- *
- * gchar *writers[];
- * g_object_get (obj, "authors", &writers, NULL);
- * /* do something with writers */
- * g_strfreev (writers);
- * ]|
+ * _g_file_attribute_value_set_boolean:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gboolean to set within the type.
*
- * Since: 2.4
+ * Sets the attribute value to the given boolean value.
*/
/**
- * G_TYPE_UCHAR:
+ * _g_file_attribute_value_set_byte_string:
+ * @attr: a #GFileAttributeValue.
+ * @string: a byte string to set within the type.
*
- * The fundamental type corresponding to #guchar.
+ * Sets the attribute value to a given byte string.
*/
/**
- * G_TYPE_UINT:
+ * _g_file_attribute_value_set_int32:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gint32 to set within the type.
*
- * The fundamental type corresponding to #guint.
+ * Sets the attribute value to the given signed 32-bit integer.
*/
/**
- * G_TYPE_UINT64:
+ * _g_file_attribute_value_set_int64:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gint64 to set within the type.
*
- * The fundamental type corresponding to #guint64.
+ * Sets the attribute value to a given signed 64-bit integer.
*/
/**
- * G_TYPE_ULONG:
+ * _g_file_attribute_value_set_object:
+ * @attr: a #GFileAttributeValue.
+ * @obj: a #GObject.
*
- * The fundamental type corresponding to #gulong.
+ * Sets the attribute to contain the value @obj.
+ * The @attr references the GObject internally.
*/
/**
- * G_TYPE_VALUE:
+ * _g_file_attribute_value_set_string:
+ * @attr: a #GFileAttributeValue.
+ * @string: a UTF-8 string to set within the type.
*
- * The type ID of the "GValue" type which is a boxed type,
- * used to pass around pointers to GValues.
+ * Sets the attribute value to a given UTF-8 string.
*/
/**
- * G_TYPE_VALUE_ARRAY:
+ * _g_file_attribute_value_set_uint32:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #guint32 to set within the type.
*
- * The type ID of the "GValueArray" type which is a boxed type,
- * used to pass around pointers to GValueArrays.
+ * Sets the attribute value to the given unsigned 32-bit integer.
*/
/**
- * G_TYPE_VARIANT:
- *
- * The fundamental type corresponding to #GVariant.
- *
- * All floating #GVariant instances passed through the #GType system are
- * consumed.
- *
- * Note that callbacks in closures, and signal handlers
- * for signals of return type %G_TYPE_VARIANT, must never return floating
- * variants.
+ * _g_file_attribute_value_set_uint64:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #guint64 to set within the type.
*
- * Note: GLib 2.24 did include a boxed type with this name. It was replaced
- * with this fundamental type in 2.26.
- *
- * Since: 2.26
+ * Sets the attribute value to a given unsigned 64-bit integer.
*/
/**
- * G_TYPE_VARIANT_BUILDER:
+ * _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.
*
- * The #GType for a boxed type holding a #GVariantBuilder.
+ * 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.
*
- * Since: 2.30
+ * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_TYPE_VARIANT_TYPE:
+ * _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.
*
- * The #GType for a boxed type holding a #GVariantType.
+ * Finishes an operation started with _g_freedesktop_dbus_call_add_match().
*
- * Since: 2.24
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_UNICHAR_MAX_DECOMPOSITION_LENGTH:
+ * _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.
*
- * The maximum length (in codepoints) of a compatibility or canonical
- * decomposition of a single Unicode character.
+ * 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.
*
- * This is as defined by Unicode 6.1.
+ * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method.
*
- * Since: 2.32
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_UNICODE_COMBINING_MARK:
+ * _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.
*
- * Older name for %G_UNICODE_SPACING_MARK.
+ * 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.
*
- * Deprecated: 2.30: Use %G_UNICODE_SPACING_MARK.
+ * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
+ * _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.
*
- * Allowed characters in a path. Includes "!$&'()*+,;=:@/".
- */
-
-
-/**
- * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context().
*
- * Allowed characters in path elements. Includes "!$&'()*+,;=:@".
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
+ * _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.
*
- * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:".
+ * 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_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
+ * _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.
*
- * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@".
+ * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
+ * _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().
*
- * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=".
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS:
- * @value: A #GValue structure.
- * @type: A #GType value.
+ * _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.
*
- * Checks if @value holds (or contains) a value of @type.
- * This macro will also check for @value != %NULL and issue a
- * warning if the check fails.
+ * 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.
*
- * Returns: %TRUE if @value holds the @type.
+ * 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_VALUE_HOLDS_BOOLEAN:
- * @value: a valid #GValue structure
+ * _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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.
+ * 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.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_BOXED:
- * @value: a valid #GValue structure
+ * _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.
*
- * Checks whether the given #GValue can hold values derived
- * from type %G_TYPE_BOXED.
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user().
*
- * Returns: %TRUE on success.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_CHAR:
- * @value: a valid #GValue structure
+ * _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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.
+ * 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.
*
- * Returns: %TRUE on success.
+ * 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_VALUE_HOLDS_DOUBLE:
- * @value: a valid #GValue structure
+ * _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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</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_id_finish() to get the result of the operation.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_ENUM:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_get_id_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_id().
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_id().
*
- * Returns: %TRUE on success.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_FLAGS:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_get_id_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_FLOAT:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_get_name_owner:
+ * @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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</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_name_owner_finish() to get the result of the operation.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_GTYPE:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_get_name_owner_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_name_owner().
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.
+ * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner().
*
- * Since: 2.12
- * Returns: %TRUE on success.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_INT:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_get_name_owner_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_INT.
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_get_name_owner() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_INT64:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_hello:
+ * @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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_INT64.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</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_hello_finish() to get the result of the operation.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_LONG:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_hello_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_hello().
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_LONG.
+ * Finishes an operation started with _g_freedesktop_dbus_call_hello().
*
- * Returns: %TRUE on success.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_OBJECT:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_hello_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_PARAM:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_activatable_names:
+ * @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.
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</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_list_activatable_names_finish() to get the result of the operation.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_POINTER:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_activatable_names_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.
+ * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names().
*
- * Returns: %TRUE on success.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_STRING:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_activatable_names_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_STRING.
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_UCHAR:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_names:
+ * @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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</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_list_names_finish() to get the result of the operation.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_UINT:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_names_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_names: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_UINT.
+ * Finishes an operation started with _g_freedesktop_dbus_call_list_names().
*
- * Returns: %TRUE on success.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_UINT64:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_names_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_names: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_HOLDS_ULONG:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_queued_owners:
+ * @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.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</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_list_queued_owners_finish() to get the result of the operation.
*
- * Returns: %TRUE on success.
+ * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_HOLDS_VARIANT:
- * @value: a valid #GValue structure
+ * _g_freedesktop_dbus_call_list_queued_owners_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
+ * @error: Return location for error or %NULL.
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT.
+ * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners().
*
- * Returns: %TRUE on success.
- * Since: 2.26
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_INIT:
+ * _g_freedesktop_dbus_call_list_queued_owners_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * A #GValue must be initialized before it can be used.
- * This macro can be used as initializer instead of an explicit
- * <literal>{ 0 }</literal> when declaring a variable,
- * but it cannot be assigned to a variable.
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * |[
- * GValue value = G_VALUE_INIT;
- * ]|
+ * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method.
*
- * Since: 2.30
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_NOCOPY_CONTENTS:
+ * _g_freedesktop_dbus_call_name_has_owner:
+ * @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.
*
- * If passed to G_VALUE_COLLECT(), allocated data won't be copied
- * but used verbatim. This does not affect ref-counted types like
- * objects.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</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_name_has_owner_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VALUE_TYPE:
- * @value: A #GValue structure.
+ * _g_freedesktop_dbus_call_name_has_owner_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_name_has_owner().
+ * @error: Return location for error or %NULL.
*
- * Get the type identifier of @value.
+ * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner().
*
- * Returns: the #GType.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VALUE_TYPE_NAME:
- * @value: A #GValue structure.
+ * _g_freedesktop_dbus_call_name_has_owner_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_has_owner: (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.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * Gets the the type name of @value.
+ * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method.
*
- * Returns: the type name.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE:
- * @type_string: a well-formed #GVariantType type string
- *
- * Converts a string to a const #GVariantType. Depending on the
- * current debugging level, this function may perform a runtime check
- * to ensure that @string is a valid GVariant type string.
+ * _g_freedesktop_dbus_call_release_name:
+ * @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.
*
- * It is always a programmer error to use this macro with an invalid
- * type string. If in doubt, use g_variant_type_string_is_valid() to
- * check if the string is valid.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</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_release_name_finish() to get the result of the operation.
*
- * Since 2.24
+ * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VARIANT_TYPE_ANY:
+ * _g_freedesktop_dbus_call_release_name_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_value: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_release_name().
+ * @error: Return location for error or %NULL.
*
- * An indefinite type that is a supertype of every type (including
- * itself).
+ * Finishes an operation started with _g_freedesktop_dbus_call_release_name().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_ARRAY:
+ * _g_freedesktop_dbus_call_release_name_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @out_value: (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.ReleaseName">ReleaseName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * An indefinite type that is a supertype of every array type.
+ * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_BASIC:
+ * _g_freedesktop_dbus_call_reload_config:
+ * @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.
+ *
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</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_reload_config_finish() to get the result of the operation.
*
- * An indefinite type that is a supertype of every basic (ie:
- * non-container) type.
+ * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VARIANT_TYPE_BOOLEAN:
+ * _g_freedesktop_dbus_call_reload_config_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_reload_config().
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with _g_freedesktop_dbus_call_reload_config().
*
- * The type of a value that can be either %TRUE or %FALSE.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_BYTE:
+ * _g_freedesktop_dbus_call_reload_config_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
+ *
+ * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method.
*
- * The type of an integer value that can range from 0 to 255.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_BYTESTRING:
+ * _g_freedesktop_dbus_call_remove_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.
*
- * The type of an array of bytes. This type is commonly used to pass
- * around strings that may not be valid utf8. In that case, the
- * convention is that the nul terminator character should be included as
- * the last character in the array.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</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_remove_match_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VARIANT_TYPE_BYTESTRING_ARRAY:
+ * _g_freedesktop_dbus_call_remove_match_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_remove_match().
+ * @error: Return location for error or %NULL.
*
- * The type of an array of byte strings (an array of arrays of bytes).
+ * Finishes an operation started with _g_freedesktop_dbus_call_remove_match().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_DICTIONARY:
+ * _g_freedesktop_dbus_call_remove_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.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * An indefinite type that is a supertype of every dictionary type --
- * that is, any array type that has an element type equal to any
- * dictionary entry type.
+ * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_DICT_ENTRY:
+ * _g_freedesktop_dbus_call_request_name:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @arg_flags: 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.
*
- * An indefinite type that is a supertype of every dictionary entry
- * type.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</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_request_name_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VARIANT_TYPE_DOUBLE:
+ * _g_freedesktop_dbus_call_request_name_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_value: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_request_name().
+ * @error: Return location for error or %NULL.
*
- * The type of a double precision IEEE754 floating point number.
- * These guys go up to about 1.80e308 (plus and minus) but miss out on
- * some numbers in between. In any case, that's far greater than the
- * estimated number of fundamental particles in the observable
- * universe.
+ * Finishes an operation started with _g_freedesktop_dbus_call_request_name().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_HANDLE:
+ * _g_freedesktop_dbus_call_request_name_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @arg_flags: Argument to pass with the method invocation.
+ * @out_value: (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.RequestName">RequestName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * The type of a 32bit signed integer value, that by convention, is used
- * as an index into an array of file descriptors that are sent alongside
- * a D-Bus message.
+ * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method.
*
- * If you are not interacting with D-Bus, then there is no reason to make
- * use of this type.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_INT16:
+ * _g_freedesktop_dbus_call_start_service_by_name:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @arg_flags: 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.
*
- * The type of an integer value that can range from -32768 to 32767.
+ * Asynchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</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_start_service_by_name_finish() to get the result of the operation.
+ *
+ * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VARIANT_TYPE_INT32:
+ * _g_freedesktop_dbus_call_start_service_by_name_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @out_value: (out): Return location for return parameter or %NULL to ignore.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_start_service_by_name().
+ * @error: Return location for error or %NULL.
*
- * The type of an integer value that can range from -2147483648 to
- * 2147483647.
+ * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name().
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_INT64:
+ * _g_freedesktop_dbus_call_start_service_by_name_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_name: Argument to pass with the method invocation.
+ * @arg_flags: Argument to pass with the method invocation.
+ * @out_value: (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.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * The type of an integer value that can range from
- * -9223372036854775808 to 9223372036854775807.
+ * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_MAYBE:
+ * _g_freedesktop_dbus_call_update_activation_environment:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_environment: 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.UpdateActivationEnvironment">UpdateActivationEnvironment()</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_update_activation_environment_finish() to get the result of the operation.
*
- * An indefinite type that is a supertype of every maybe type.
+ * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method.
*/
/**
- * G_VARIANT_TYPE_OBJECT_PATH:
+ * _g_freedesktop_dbus_call_update_activation_environment_finish:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_update_activation_environment().
+ * @error: Return location for error or %NULL.
*
- * The type of a D-Bus object reference. These are strings of a
- * specific format used to identify objects at a given destination on
- * the bus.
+ * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment().
*
- * If you are not interacting with D-Bus, then there is no reason to make
- * use of this type. If you are, then the D-Bus specification contains a
- * precise description of valid object paths.
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_OBJECT_PATH_ARRAY:
+ * _g_freedesktop_dbus_call_update_activation_environment_sync:
+ * @proxy: A #_GFreedesktopDBusProxy.
+ * @arg_environment: 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.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
*
- * The type of an array of object paths.
+ * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method.
+ *
+ * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set.
*/
/**
- * G_VARIANT_TYPE_SIGNATURE:
+ * _g_freedesktop_dbus_complete_add_match:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
*
- * The type of a D-Bus type signature. These are strings of a specific
- * format used as type signatures for D-Bus methods and messages.
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * If you are not interacting with D-Bus, then there is no reason to make
- * use of this type. If you are, then the D-Bus specification contains a
- * precise description of valid signature strings.
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_STRING:
+ * _g_freedesktop_dbus_complete_get_connection_selinux_security_context:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @security_context: Parameter to return.
*
- * The type of a string. "" is a string. %NULL is not a string.
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_STRING_ARRAY:
+ * _g_freedesktop_dbus_complete_get_connection_unix_process_id:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @pid: Parameter to return.
+ *
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * The type of an array of strings.
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_TUPLE:
+ * _g_freedesktop_dbus_complete_get_connection_unix_user:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @uid: Parameter to return.
*
- * An indefinite type that is a supertype of every tuple type,
- * regardless of the number of items in the tuple.
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_UINT16:
+ * _g_freedesktop_dbus_complete_get_id:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @unique_id: Parameter to return.
+ *
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * The type of an integer value that can range from 0 to 65535.
- * There were about this many people living in Toronto in the 1870s.
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_UINT32:
+ * _g_freedesktop_dbus_complete_get_name_owner:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @unique_name: Parameter to return.
*
- * The type of an integer value that can range from 0 to 4294967295.
- * That's one number for everyone who was around in the late 1970s.
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_UINT64:
+ * _g_freedesktop_dbus_complete_hello:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @assigned_name: Parameter to return.
+ *
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * The type of an integer value that can range from 0 to
- * 18446744073709551616. That's a really big number, but a Rubik's
- * cube can have a bit more than twice as many possible positions.
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_UNIT:
+ * _g_freedesktop_dbus_complete_list_activatable_names:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @activatable_names: Parameter to return.
*
- * The empty tuple type. Has only one instance. Known also as "triv"
- * or "void".
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_VARDICT:
+ * _g_freedesktop_dbus_complete_list_names:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @names: Parameter to return.
*
- * The type of a dictionary mapping strings to variants (the ubiquitous
- * "a{sv}" type).
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * Since: 2.30
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VARIANT_TYPE_VARIANT:
+ * _g_freedesktop_dbus_complete_list_queued_owners:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @queued_owners: Parameter to return.
*
- * The type of a box that contains any other value (including another
- * variant).
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VFS_EXTENSION_POINT_NAME:
+ * _g_freedesktop_dbus_complete_name_has_owner:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @has_owner: Parameter to return.
*
- * Extension point for #GVfs functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
+ * _g_freedesktop_dbus_complete_release_name:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @value: Parameter to return.
+ *
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * The string used to obtain a Hal UDI with g_volume_get_identifier().
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_LABEL:
+ * _g_freedesktop_dbus_complete_reload_config:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
*
- * The string used to obtain a filesystem label with g_volume_get_identifier().
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
+ * _g_freedesktop_dbus_complete_remove_match:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ *
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * The string used to obtain a NFS mount with g_volume_get_identifier().
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
+ * _g_freedesktop_dbus_complete_request_name:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @value: Parameter to return.
*
- * The string used to obtain a Unix device path with g_volume_get_identifier().
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_UUID:
+ * _g_freedesktop_dbus_complete_start_service_by_name:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @value: Parameter to return.
+ *
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
*
- * The string used to obtain a UUID with g_volume_get_identifier().
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * G_VOLUME_MONITOR_EXTENSION_POINT_NAME:
+ * _g_freedesktop_dbus_complete_update_activation_environment:
+ * @object: A #_GFreedesktopDBus.
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
*
- * Extension point for volume monitor functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * Helper function used in service implementations to finish handling invocations of the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method. If you instead want to finish handling an invocation by returning an error, use g_dbus_method_invocation_return_error() or similar.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*/
/**
- * SECTION:extensionpoints
- * @short_description: Extension Points
- * @include: gio.h
- * @see_also: <link linkend="extending-gio">Extending GIO</link>
- *
- * #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
- * 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.
- *
- * A module can implement an extension point by specifying the #GType
- * that implements the functionality. Additionally, each implementation
- * of an extension point has a name, and a priority. Use
- * g_io_extension_point_implement() to implement an extension point.
- *
- * |[
- * GIOExtensionPoint *ep;
- *
- * /* 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 */
- * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
- * g_io_extension_point_implement ("my-extension-point",
- * my_example_impl_get_type (),
- * "my-example",
- * 10);
- * ]|
- *
- * It is up to the code that registered the extension point how
- * it uses the implementations that have been associated with it.
- * Depending on the use case, it may use all implementations, or
- * only the one with the highest priority, or pick a specific
- * one by name.
- *
- * 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>.
- * You are expected to run this command after installing a
- * GIO module.
+ * _g_freedesktop_dbus_emit_name_acquired:
+ * @object: A #_GFreedesktopDBus.
+ * @arg_name: Argument to pass with the signal.
*
- * The <envar>GIO_EXTRA_MODULES</envar> 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
- * directories, then the latter one will be ignored. If additional
- * directories are specified GIO will load modules from the built-in
- * directory last.
+ * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameAcquired">"NameAcquired"</link> D-Bus signal.
*/
/**
- * SECTION:gaction
- * @title: GAction
- * @short_description: An action interface
- *
- * #GAction represents a single named action.
- *
- * The main interface to an action is that it can be activated with
- * g_action_activate(). This results in the 'activate' signal being
- * emitted. An activation has a #GVariant parameter (which may be
- * %NULL). The correct type for the parameter is determined by a static
- * parameter type (which is given at construction time).
- *
- * An action may optionally have a state, in which case the state may be
- * set with g_action_change_state(). This call takes a #GVariant. The
- * correct type for the state is determined by a static state type
- * (which is given at construction time).
+ * _g_freedesktop_dbus_emit_name_lost:
+ * @object: A #_GFreedesktopDBus.
+ * @arg_name: Argument to pass with the signal.
*
- * The state may have a hint associated with it, specifying its valid
- * range.
- *
- * #GAction is merely the interface to the concept of an action, as
- * described above. Various implementations of actions exist, including
- * #GSimpleAction and #GtkAction.
- *
- * In all cases, the implementing class is responsible for storing the
- * name of the action, the parameter type, the enabled state, the
- * optional state type and the state and emitting the appropriate
- * signals when these change. The implementor responsible for filtering
- * calls to g_action_activate() and g_action_change_state() for type
- * safety and for the state being enabled.
- *
- * Probably the only useful thing to do with a #GAction is to put it
- * inside of a #GSimpleActionGroup.
+ * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameLost">"NameLost"</link> D-Bus signal.
*/
/**
- * SECTION:gactiongroup
- * @title: GActionGroup
- * @short_description: A group of actions
- * @see_also: #GAction
- *
- * #GActionGroup represents a group of actions. Actions can be used to
- * expose functionality in a structured way, either from one part of a
- * program to another, or to the outside world. Action groups are often
- * used together with a #GMenuModel that provides additional
- * representation data for displaying the actions to the user, e.g. in
- * a menu.
- *
- * The main way to interact with the actions in a GActionGroup is to
- * activate them with g_action_group_activate_action(). Activating an
- * action may require a #GVariant parameter. The required type of the
- * parameter can be inquired with g_action_group_get_action_parameter_type().
- * Actions may be disabled, see g_action_group_get_action_enabled().
- * Activating a disabled action has no effect.
- *
- * Actions may optionally have a state in the form of a #GVariant. The
- * current state of an action can be inquired with
- * g_action_group_get_action_state(). Activating a stateful action may
- * change its state, but it is also possible to set the state by calling
- * g_action_group_change_action_state().
- *
- * As typical example, consider a text editing application which has an
- * option to change the current font to 'bold'. A good way to represent
- * this would be a stateful action, with a boolean state. Activating the
- * action would toggle the state.
- *
- * Each action in the group has a unique name (which is a string). All
- * method calls, except g_action_group_list_actions() take the name of
- * an action as an argument.
+ * _g_freedesktop_dbus_emit_name_owner_changed:
+ * @object: A #_GFreedesktopDBus.
+ * @arg_name: Argument to pass with the signal.
+ * @arg_old_owner: Argument to pass with the signal.
+ * @arg_new_owner: Argument to pass with the signal.
*
- * The #GActionGroup API is meant to be the 'public' API to the action
- * group. The calls here are exactly the interaction that 'external
- * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
- * 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.
+ * Emits the <link linkend="gdbus-signal-org-freedesktop-DBus.NameOwnerChanged">"NameOwnerChanged"</link> D-Bus signal.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_interface_info:
*
- * Signals are emitted on the action group in response to state changes
- * on individual actions.
+ * Gets a machine-readable description of the <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link> D-Bus interface.
*
- * Implementations of #GActionGroup should provide implementations for
- * the virtual functions g_action_group_list_actions() and
- * g_action_group_query_action(). The other virtual functions should
- * not be implemented - their "wrappers" are actually implemented with
- * calls to g_action_group_query_action().
+ * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
*/
/**
- * SECTION:gactiongroupexporter
- * @title: GActionGroup exporter
- * @short_description: Export GActionGroups on D-Bus
- * @see_also: #GActionGroup, #GDBusActionGroup
+ * _g_freedesktop_dbus_override_properties:
+ * @klass: The class structure for a #GObject<!-- -->-derived class.
+ * @property_id_begin: The property id to assign to the first overridden property.
*
- * These functions support exporting a #GActionGroup on D-Bus.
- * The D-Bus interface that is used is a private implementation
- * detail.
+ * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
+ * The properties are overridden in the order they are defined.
*
- * To access an exported #GActionGroup remotely, use
- * g_dbus_action_group_new() to obtain a #GDBusActionGroup.
+ * Returns: The last property id.
*/
/**
- * SECTION:gactionmap
- * @title: GActionMap
- * @short_description: Interface for action containers
+ * _g_freedesktop_dbus_proxy_new:
+ * @connection: A #GDBusConnection.
+ * @flags: Flags from the #GDBusProxyFlags enumeration.
+ * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+ * @object_path: An object path.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: User data to pass to @callback.
*
- * The GActionMap interface is implemented by #GActionGroup
- * implementations that operate by containing a number of
- * named #GAction instances, such as #GSimpleActionGroup.
+ * Asynchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new() for more details.
*
- * One useful application of this interface is to map the
- * names of actions from various action groups to unique,
- * prefixed names (e.g. by prepending "app." or "win.").
- * This is the motivation for the 'Map' part of the interface
- * name.
+ * 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_proxy_new_finish() to get the result of the operation.
*
- * Since: 2.32
+ * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor.
*/
/**
- * SECTION:gappinfo
- * @short_description: Application information and launch contexts
- * @include: gio/gio.h
- *
- * #GAppInfo and #GAppLaunchContext are used for describing and launching
- * applications installed on the system.
+ * _g_freedesktop_dbus_proxy_new_finish:
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new().
+ * @error: Return location for error or %NULL
*
- * 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
- * path (in gvfs there's no FUSE mount for it); such URIs will be
- * passed unmodified to the application.
+ * Finishes an operation started with _g_freedesktop_dbus_proxy_new().
*
- * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
- * back to the GIO URI in the #GFile constructors (since gvfs
- * implements the #GVfs extension point). As such, if the application
- * needs to examine the URI, it needs to use g_file_get_uri() or
- * similar on #GFile. In other words, an application cannot assume
- * that the URI passed to e.g. g_file_new_for_commandline_arg() is
- * equal to the result of g_file_get_uri(). The following snippet
- * illustrates this:
+ * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_proxy_new_for_bus:
+ * @bus_type: A #GBusType.
+ * @flags: Flags from the #GDBusProxyFlags enumeration.
+ * @name: A bus name (well-known or unique).
+ * @object_path: An object path.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: User data to pass to @callback.
*
- * <programlisting>
- * GFile *f;
- * char *uri;
+ * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
*
- * file = g_file_new_for_commandline_arg (uri_from_commandline);
+ * 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_proxy_new_for_bus_finish() to get the result of the operation.
*
- * uri = g_file_get_uri (file);
- * strcmp (uri, uri_from_commandline) == 0; // FALSE
- * g_free (uri);
+ * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_proxy_new_for_bus_finish:
+ * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_proxy_new_for_bus().
+ * @error: Return location for error or %NULL
*
- * if (g_file_has_uri_scheme (file, "cdda"))
- * {
- * // do something special with uri
- * }
- * g_object_unref (file);
- * </programlisting>
+ * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus().
*
- * 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.
+ * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
*/
/**
- * SECTION:gapplication
- * @title: GApplication
- * @short_description: Core application class
+ * _g_freedesktop_dbus_proxy_new_for_bus_sync:
+ * @bus_type: A #GBusType.
+ * @flags: Flags from the #GDBusProxyFlags enumeration.
+ * @name: A bus name (well-known or unique).
+ * @object_path: An object path.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL
*
- * A #GApplication is the foundation of an application, unique for a
- * given application identifier. The GApplication class 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.
+ * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
*
- * One of the core features that GApplication provides is process
- * uniqueness, in the context of a "session". The session concept is
- * platform-dependent, but corresponds roughly to a graphical 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>. On Linux, the D-Bus session
- * bus is used for communication.
+ * The calling thread is blocked until a reply is received.
*
- * 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.
+ * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor.
*
- * Before using GApplication, you must choose an "application identifier".
- * 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>.
- * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
- * For details on valid application identifiers, see g_application_id_is_valid().
+ * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_proxy_new_sync:
+ * @connection: A #GDBusConnection.
+ * @flags: Flags from the #GDBusProxyFlags enumeration.
+ * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+ * @object_path: An object path.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL
*
- * On Linux, the application identifier is claimed as a well-known bus name
- * on the user's session bus. This means that the uniqueness of your
- * application is scoped to the current session. It also means that your
- * application may provide additional services (through registration of other
- * object paths) at that bus name. The registration of these object paths
- * should be done with the shared GDBus session bus. Note that due to the
- * internal architecture of GDBus, method calls can be dispatched at any time
- * (even if a main loop is not running). For this reason, you must ensure that
- * any object paths that you wish to register are registered before #GApplication
- * attempts to acquire the bus name of your application (which happens in
- * g_application_register()). Unfortunately, this means that you cannot use
- * g_application_get_is_remote() to decide if you want to register object paths.
+ * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new_sync() for more details.
*
- * GApplication also implements the #GActionGroup and #GActionMap
- * interfaces and lets you easily export actions by adding them with
- * g_action_map_add_action(). When invoking an action by calling
- * g_action_group_activate_action() on the application, it is always
- * invoked in the primary instance. The actions are also exported on
- * the session bus, and GIO provides the #GDBusActionGroup wrapper to
- * conveniently access them remotely. Additionally, g_application_set_app_menu()
- * and g_application_set_menubar() can be used to export representation
- * data for the actions, in the form of #GMenuModels. GIO provides
- * a #GDBusMenuModel wrapper for remote access to exported #GMenuModels.
+ * The calling thread is blocked until a reply is received.
*
- * 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>
- * The #GApplication::startup signal lets you handle the application
- * initialization for all of these in a single place.
+ * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor.
*
- * 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(),
- * g_application_command_line_get_environ() and
- * g_application_command_line_get_platform_data().
+ * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set.
+ */
+
+
+/**
+ * _g_freedesktop_dbus_skeleton_new:
*
- * As the name indicates, the platform data may vary depending on the
- * operating system, but it always includes the current directory (key
- * "cwd"), and optionally the environment (ie the set of environment
- * variables and their values) of the calling process (key "environ").
- * The environment is only added to the platform data if the
- * #G_APPLICATION_SEND_ENVIONMENT flag is set. GApplication subclasses
- * can add their own platform data by overriding the @add_platform_data
- * virtual function. For instance, #GtkApplication adds startup notification
- * data in this way.
+ * Creates a skeleton object for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>.
*
- * To parse commandline arguments you may handle the
- * #GApplication::command-line signal or override the local_command_line()
- * vfunc, to parse them in either the primary instance or the local instance,
- * respectively.
+ * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object.
+ */
+
+
+/**
+ * _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.
+ *
+ * Retrieves the default object 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.
*
- * <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>
+ * If an extension point implementation implements #GInitable, then
+ * that implementation will only be used if it initializes
+ * successfully. Otherwise, if @verify_func is not %NULL, then it will
+ * be called on each candidate implementation after construction, to
+ * check if it is actually usable or not.
*
- * <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>
+ * The result is cached after it is generated the first time, and
+ * the function is thread-safe.
*
- * <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>
+ * Returns: (transfer none): an object implementing
+ * @extension_point, or %NULL if there are no usable
+ * implementations.
*/
/**
- * SECTION:gapplicationcommandline
- * @title: GApplicationCommandLine
- * @short_description: A command-line invocation of an application
- * @see_also: #GApplication
- *
- * #GApplicationCommandLine represents a command-line invocation of
- * an application. It is created by #GApplication and emitted
- * in the #GApplication::command-line signal and virtual function.
+ * _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
*
- * The class contains the list of arguments that the program was invoked
- * with. It is also possible to query if the commandline invocation was
- * local (ie: the current process is running in direct response to the
- * invocation) or remote (ie: some other process forwarded the
- * commandline to this process).
+ * Retrieves the default class implementing @extension_point.
*
- * 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.
+ * 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.
*
- * The exit status of the originally-invoked process may be set and
- * messages can be printed to stdout or stderr of that process. The
- * lifecycle of the originally-invoked process is tied to the lifecycle
- * of this object (ie: the process exits when the last reference is
- * dropped).
+ * 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 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
- * 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.
+ * The result is cached after it is generated the first time, and
+ * the function is thread-safe.
*
- * <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
- * 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>
+ * Returns: (transfer none): an object implementing
+ * @extension_point, or %NULL if there are no usable
+ * implementations.
*/
/**
- * SECTION:gasyncinitable
- * @short_description: Asynchronously failable object initialization interface
- * @include: gio/gio.h
- * @see_also: #GInitable
+ * g_action_activate:
+ * @action: a #GAction
+ * @parameter: (allow-none): the parameter to the activation
*
- * This is the asynchronous version of #GInitable; it behaves the same
- * in all ways except that initialization is asynchronous. For more details
- * see the descriptions on #GInitable.
+ * Activates the action.
*
- * A class may implement both the #GInitable and #GAsyncInitable interfaces.
+ * @parameter must be the correct type of parameter for the action (ie:
+ * the parameter type given at construction time). If the parameter
+ * type was %NULL then @parameter must also be %NULL.
*
- * Users of objects implementing this are not intended to use the interface
- * method directly; instead it will be used automatically in various ways.
- * For C applications you generally just call g_async_initable_new_async()
- * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
- * g_async_initable_init_async() under the cover, calling back with %NULL and
- * a set %GError on failure.
+ * If the @parameter GVariant is floating, it is consumed.
*
- * A typical implementation might look something like this:
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_change_state:
+ * @action: a #GAction
+ * @value: the new state
*
- * |[
- * enum {
- * NOT_INITIALIZED,
- * INITIALIZING,
- * INITIALIZED
- * };
+ * Request for the state of @action to be changed to @value.
*
- * static void
- * _foo_ready_cb (Foo *self)
- * {
- * GList *l;
+ * The action must be stateful and @value must be of the correct type.
+ * See g_action_get_state_type().
+ *
+ * This call merely requests a change. The action may refuse to change
+ * its state or may change its state to something other than @value.
+ * See g_action_get_state_hint().
+ *
+ * If the @value GVariant is floating, it is consumed.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_action_get_enabled:
+ * @action: a #GAction
*
- * self->priv->state = INITIALIZED;
+ * Checks if @action is currently enabled.
*
- * for (l = self->priv->init_results; l != NULL; l = l->next)
- * {
- * GSimpleAsyncResult *simple = l->data;
+ * An action must be enabled in order to be activated or in order to
+ * have its state changed from outside callers.
*
- * if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
+ * Returns: whether the action is enabled
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_get_name:
+ * @action: a #GAction
*
- * g_simple_async_result_complete (simple);
- * g_object_unref (simple);
- * }
+ * Queries the name of @action.
*
- * g_list_free (self->priv->init_results);
- * self->priv->init_results = NULL;
- * }
+ * Returns: the name of the action
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_get_parameter_type:
+ * @action: a #GAction
*
- * static void
- * foo_init_async (GAsyncInitable *initable,
- * int io_priority,
- * GCancellable *cancellable,
- * GAsyncReadyCallback callback,
- * gpointer user_data)
- * {
- * Foo *self = FOO (initable);
- * GSimpleAsyncResult *simple;
+ * Queries the type of the parameter that must be given when activating
+ * @action.
*
- * simple = g_simple_async_result_new (G_OBJECT (initable)
- * callback,
- * user_data,
- * foo_init_async);
+ * When activating the action using g_action_activate(), the #GVariant
+ * given to that function must be of the type returned by this function.
*
- * switch (self->priv->state)
- * {
- * case NOT_INITIALIZED:
- * _foo_get_ready (self);
- * self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
- * self->priv->state = INITIALIZING;
- * break;
- * case INITIALIZING:
- * self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
- * 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);
- * break;
- * }
- * }
+ * In the case that this function returns %NULL, you must not give any
+ * #GVariant, but %NULL instead.
*
- * static gboolean
- * foo_init_finish (GAsyncInitable *initable,
- * GAsyncResult *result,
- * GError **error)
- * {
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (initable), foo_init_async), FALSE);
+ * Returns: (allow-none): the parameter type
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_get_state:
+ * @action: a #GAction
*
- * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
- * error))
- * return FALSE;
+ * Queries the current state of @action.
*
- * return TRUE;
- * }
+ * If the action is not stateful then %NULL will be returned. If the
+ * action is stateful then the type of the return value is the type
+ * given by g_action_get_state_type().
*
- * static void
- * foo_async_initable_iface_init (gpointer g_iface,
- * gpointer data)
- * {
- * GAsyncInitableIface *iface = g_iface;
+ * The return value (if non-%NULL) should be freed with
+ * g_variant_unref() when it is no longer required.
*
- * iface->init_async = foo_init_async;
- * iface->init_finish = foo_init_finish;
- * }
- * ]|
+ * Returns: (transfer full): the current state of the action
+ * Since: 2.28
*/
/**
- * SECTION:gasyncresult
- * @short_description: Asynchronous Function Results
- * @include: gio/gio.h
- * @see_also: #GSimpleAsyncResult
- *
- * Provides a base class for implementing asynchronous function results.
+ * g_action_get_state_hint:
+ * @action: a #GAction
*
- * Asynchronous operations are broken up into two separate operations
- * which are chained together by a #GAsyncReadyCallback. To begin
- * an asynchronous operation, provide a #GAsyncReadyCallback to the
- * asynchronous function. This callback will be triggered when the
- * operation has completed, and will be passed a #GAsyncResult instance
- * filled with the details of the operation's success or failure, the
- * object the asynchronous function was started for and any error codes
- * returned. The asynchronous callback function is then expected to call
- * the corresponding "_finish()" function, passing the object the
- * function was called for, the #GAsyncResult instance, and (optionally)
- * an @error to grab any error conditions that may have occurred.
+ * Requests a hint about the valid range of values for the state of
+ * @action.
*
- * The "_finish()" function for an operation takes the generic result
- * (of type #GAsyncResult) and returns the specific result that the
- * operation in question yields (e.g. a #GFileEnumerator for a
- * "enumerate children" operation). If the result or error status of the
- * operation is not needed, there is no need to call the "_finish()"
- * function; GIO will take care of cleaning up the result and error
- * information after the #GAsyncReadyCallback returns. You can pass
- * %NULL for the #GAsyncReadyCallback if you don't need to take any
- * action at all after the operation completes. Applications may also
- * take a reference to the #GAsyncResult and call "_finish()" later;
- * however, the "_finish()" function may be called at most once.
+ * If %NULL is returned it either means that the action is not stateful
+ * or that there is no hint about the valid range of values for the
+ * state of the action.
*
- * Example of a typical asynchronous operation flow:
- * |[
- * void _theoretical_frobnitz_async (Theoretical *t,
- * GCancellable *c,
- * GAsyncReadyCallback *cb,
- * gpointer u);
+ * If a #GVariant array is returned then each item in the array is a
+ * possible value for the state. If a #GVariant pair (ie: two-tuple) is
+ * returned then the tuple specifies the inclusive lower and upper bound
+ * of valid values for the state.
*
- * gboolean _theoretical_frobnitz_finish (Theoretical *t,
- * GAsyncResult *res,
- * GError **e);
+ * In any case, the information is merely a hint. It may be possible to
+ * have a state value outside of the hinted range and setting a value
+ * within the range may fail.
*
- * static void
- * frobnitz_result_func (GObject *source_object,
- * GAsyncResult *res,
- * gpointer user_data)
- * {
- * gboolean success = FALSE;
+ * The return value (if non-%NULL) should be freed with
+ * g_variant_unref() when it is no longer required.
*
- * success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ * Returns: (nullable) (transfer full): the state range hint
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_get_state_type:
+ * @action: a #GAction
*
- * if (success)
- * g_printf ("Hurray!\n");
- * else
- * g_printf ("Uh oh!\n");
+ * Queries the type of the state of @action.
*
- * /<!-- -->* ... *<!-- -->/
+ * If the action is stateful (e.g. created with
+ * g_simple_action_new_stateful()) then this function returns the
+ * #GVariantType of the state. This is the type of the initial value
+ * given as the state. All calls to g_action_change_state() must give a
+ * #GVariant of this type and g_action_get_state() will return a
+ * #GVariant of the same type.
*
- * }
+ * If the action is not stateful (e.g. created with g_simple_action_new())
+ * then this function will return %NULL. In that case, g_action_get_state()
+ * will return %NULL and you must not call g_action_change_state().
*
- * int main (int argc, void *argv[])
- * {
- * /<!-- -->* ... *<!-- -->/
+ * Returns: (allow-none): the state type, if the action is stateful
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_group_action_added:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
*
- * _theoretical_frobnitz_async (theoretical_data,
- * NULL,
- * frobnitz_result_func,
- * NULL);
+ * Emits the #GActionGroup::action-added signal on @action_group.
*
- * /<!-- -->* ... *<!-- -->/
- * }
- * ]|
+ * This function should only be called by #GActionGroup implementations.
*
- * 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.
+ * Since: 2.28
*/
/**
- * SECTION:gbufferedinputstream
- * @short_description: Buffered Input Stream
- * @include: gio/gio.h
- * @see_also: #GFilterInputStream, #GInputStream
- *
- * Buffered input stream implements #GFilterInputStream and provides
- * for buffered reads.
+ * g_action_group_action_enabled_changed:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
+ * @enabled: whether or not the action is now enabled
*
- * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
+ * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
*
- * To create a buffered input stream, use g_buffered_input_stream_new(),
- * or g_buffered_input_stream_new_sized() to specify the buffer's size at
- * construction.
+ * This function should only be called by #GActionGroup implementations.
*
- * To get the size of a buffer within a buffered input stream, use
- * g_buffered_input_stream_get_buffer_size(). To change the size of a
- * buffered input stream's buffer, use
- * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
- * cannot be reduced below the size of the data within the buffer.
+ * Since: 2.28
*/
/**
- * SECTION:gbufferedoutputstream
- * @short_description: Buffered Output Stream
- * @include: gio/gio.h
- * @see_also: #GFilterOutputStream, #GOutputStream
+ * g_action_group_action_removed:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
*
- * Buffered output stream implements #GFilterOutputStream and provides
- * for buffered writes.
+ * Emits the #GActionGroup::action-removed signal on @action_group.
*
- * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
+ * This function should only be called by #GActionGroup implementations.
*
- * To create a buffered output stream, use g_buffered_output_stream_new(),
- * or g_buffered_output_stream_new_sized() to specify the buffer's size
- * at construction.
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_group_action_state_changed:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
+ * @state: the new state of the named action
*
- * To get the size of a buffer within a buffered input stream, use
- * g_buffered_output_stream_get_buffer_size(). To change the size of a
- * buffered output stream's buffer, use
- * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
- * size cannot be reduced below the size of the data within the buffer.
+ * Emits the #GActionGroup::action-state-changed signal on @action_group.
+ *
+ * This function should only be called by #GActionGroup implementations.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gcancellable
- * @short_description: Thread-safe Operation Cancellation Stack
- * @include: gio/gio.h
+ * g_action_group_activate_action:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to activate
+ * @parameter: (allow-none): parameters to the activation
*
- * GCancellable is a thread-safe operation cancellation stack used
- * throughout GIO to allow for cancellation of synchronous and
- * asynchronous operations.
+ * Activate the named action within @action_group.
+ *
+ * If the action is expecting a parameter, then the correct type of
+ * parameter must be given as @parameter. If the action is expecting no
+ * parameters then @parameter must be %NULL. See
+ * g_action_group_get_action_parameter_type().
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gcharsetconverter
- * @short_description: Convert between charsets
- * @include: gio/gio.h
+ * g_action_group_change_action_state:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to request the change on
+ * @value: the new state
*
- * #GCharsetConverter is an implementation of #GConverter based on
- * GIConv.
+ * Request for the state of the named action within @action_group to be
+ * changed to @value.
+ *
+ * The action must be stateful and @value must be of the correct type.
+ * See g_action_group_get_action_state_type().
+ *
+ * This call merely requests a change. The action may refuse to change
+ * its state or may change its state to something other than @value.
+ * See g_action_group_get_action_state_hint().
+ *
+ * If the @value GVariant is floating, it is consumed.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gcontenttype
- * @short_description: Platform-specific content typing
- * @include: gio/gio.h
+ * g_action_group_get_action_enabled:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
+ *
+ * Checks if the named action within @action_group is currently enabled.
+ *
+ * An action must be enabled in order to be activated or in order to
+ * have its state changed from outside callers.
*
- * 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".
- * 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.
+ * Returns: whether or not the action is currently enabled
+ * Since: 2.28
*/
/**
- * SECTION:gconverter
- * @short_description: Data conversion interface
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
+ * g_action_group_get_action_parameter_type:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * #GConverter is implemented by objects that convert
- * binary data in various ways. The conversion can be
- * stateful and may fail at any place.
+ * Queries the type of the parameter that must be given when activating
+ * the named action within @action_group.
*
- * Some example conversions are: character set conversion,
- * compression, decompression and regular expression
- * replace.
+ * When activating the action using g_action_group_activate_action(),
+ * the #GVariant given to that function must be of the type returned
+ * by this function.
*
- * Since: 2.24
+ * In the case that this function returns %NULL, you must not give any
+ * #GVariant, but %NULL instead.
+ *
+ * The parameter type of a particular action will never change but it is
+ * 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: (nullable): the parameter type
+ * Since: 2.28
*/
/**
- * SECTION:gconverterinputstream
- * @short_description: Converter Input Stream
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GConverter
+ * g_action_group_get_action_state:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * Converter input stream implements #GInputStream and allows
- * conversion of data of various types during reading.
+ * Queries the current state of the named action within @action_group.
+ *
+ * If the action is not stateful then %NULL will be returned. If the
+ * action is stateful then the type of the return value is the type
+ * given by g_action_group_get_action_state_type().
+ *
+ * The return value (if non-%NULL) should be freed with
+ * g_variant_unref() when it is no longer required.
+ *
+ * Returns: (nullable): the current state of the action
+ * Since: 2.28
*/
/**
- * SECTION:gconverteroutputstream
- * @short_description: Converter Output Stream
- * @include: gio/gio.h
- * @see_also: #GOutputStream, #GConverter
+ * g_action_group_get_action_state_hint:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * Converter output stream implements #GOutputStream and allows
- * conversion of data of various types during reading.
+ * Requests a hint about the valid range of values for the state of the
+ * named action within @action_group.
+ *
+ * If %NULL is returned it either means that the action is not stateful
+ * or that there is no hint about the valid range of values for the
+ * state of the action.
+ *
+ * If a #GVariant array is returned then each item in the array is a
+ * possible value for the state. If a #GVariant pair (ie: two-tuple) is
+ * returned then the tuple specifies the inclusive lower and upper bound
+ * of valid values for the state.
+ *
+ * In any case, the information is merely a hint. It may be possible to
+ * have a state value outside of the hinted range and setting a value
+ * within the range may fail.
+ *
+ * The return value (if non-%NULL) should be freed with
+ * g_variant_unref() when it is no longer required.
+ *
+ * Returns: (nullable) (transfer full): the state range hint
+ * Since: 2.28
*/
/**
- * SECTION:gcredentials
- * @short_description: An object containing credentials
- * @include: gio/gio.h
- *
- * The #GCredentials type is a reference-counted wrapper for native
- * credentials. This information is typically used for identifying,
- * authenticating and authorizing other processes.
+ * g_action_group_get_action_state_type:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * Some operating systems supports looking up the credentials of the
- * remote peer of a communication endpoint - see e.g.
- * g_socket_get_credentials().
+ * Queries the type of the state of the named action within
+ * @action_group.
*
- * Some operating systems supports securely sending and receiving
- * credentials over a Unix Domain Socket, see
- * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
- * g_unix_connection_receive_credentials() for details.
+ * If the action is stateful then this function returns the
+ * #GVariantType of the state. All calls to
+ * g_action_group_change_action_state() must give a #GVariant of this
+ * type and g_action_group_get_action_state() will return a #GVariant
+ * of the same type.
*
- * 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
- * %G_CREDENTIALS_TYPE_LINUX_UCRED.
+ * If the action is not stateful then this function will return %NULL.
+ * In that case, g_action_group_get_action_state() will return %NULL
+ * and you must not call g_action_group_change_action_state().
*
- * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>.
- * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
+ * The state type of a particular action will never change but it is
+ * possible for an action to be removed and for a new action to be added
+ * with the same name but a different state type.
*
- * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
- * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
+ * Returns: (nullable) (transfer full): the state type, if the action
+ * is stateful
+ * Since: 2.28
*/
/**
- * SECTION:gdatainputstream
- * @short_description: Data Input Stream
- * @include: gio/gio.h
- * @see_also: #GInputStream
+ * g_action_group_has_action:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to check for
*
- * Data input stream implements #GInputStream and includes functions for
- * reading structured data directly from a binary input stream.
+ * Checks if the named action exists within @action_group.
+ *
+ * Returns: whether the named action exists
+ * Since: 2.28
*/
/**
- * SECTION:gdataoutputstream
- * @short_description: Data Output Stream
- * @include: gio/gio.h
- * @see_also: #GOutputStream
+ * g_action_group_list_actions:
+ * @action_group: a #GActionGroup
*
- * Data output stream implements #GOutputStream and includes functions for
- * writing data directly to an output stream.
+ * Lists the actions contained within @action_group.
+ *
+ * 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
+ * Since: 2.28
*/
/**
- * SECTION:gdbusactiongroup
- * @title: GDBusActionGroup
- * @short_description: A D-Bus GActionGroup implementation
- * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
+ * g_action_group_query_action:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
+ * @enabled: (out): if the action is presently enabled
+ * @parameter_type: (out) (allow-none): the parameter type, or %NULL if none needed
+ * @state_type: (out) (allow-none): the state type, or %NULL if stateless
+ * @state_hint: (out) (allow-none): the state hint, or %NULL if none
+ * @state: (out) (allow-none): the current state, or %NULL if stateless
*
- * #GDBusActionGroup is an implementation of the #GActionGroup
- * interface that can be used as a proxy for an action group
- * that is exported over D-Bus with g_dbus_connection_export_action_group().
+ * Queries all aspects of the named action within an @action_group.
+ *
+ * This function acquires the information available from
+ * g_action_group_has_action(), g_action_group_get_action_enabled(),
+ * g_action_group_get_action_parameter_type(),
+ * g_action_group_get_action_state_type(),
+ * g_action_group_get_action_state_hint() and
+ * g_action_group_get_action_state() with a single function call.
+ *
+ * This provides two main benefits.
+ *
+ * The first is the improvement in efficiency that comes with not having
+ * to perform repeated lookups of the action in order to discover
+ * different things about it. The second is that implementing
+ * #GActionGroup can now be done by only overriding this one virtual
+ * function.
+ *
+ * The interface provides a default implementation of this function that
+ * calls the individual functions, as required, to fetch the
+ * information. The interface also provides default implementations of
+ * those functions that call this function. All implementations,
+ * therefore, must override either this function or all of the others.
+ *
+ * If the action exists, %TRUE is returned and any of the requested
+ * fields (as indicated by having a non-%NULL reference passed in) are
+ * filled. If the action doesn't exist, %FALSE is returned and the
+ * fields may or may not have been modified.
+ *
+ * Returns: %TRUE if the action exists, else %FALSE
+ * Since: 2.32
*/
/**
- * SECTION:gdbusaddress
- * @title: D-Bus Addresses
- * @short_description: D-Bus connection endpoints
- * @include: gio/gio.h
+ * g_action_map_add_action:
+ * @action_map: a #GActionMap
+ * @action: a #GAction
*
- * 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>.
+ * Adds an action to the @action_map.
+ *
+ * If the action map already contains an action with the same name
+ * as @action then the old action is dropped from the action map.
+ *
+ * The action map takes its own reference on @action.
+ *
+ * Since: 2.32
*/
/**
- * SECTION:gdbusauthobserver
- * @short_description: Object used for authenticating connections
- * @include: gio/gio.h
+ * g_action_map_add_action_entries:
+ * @action_map: a #GActionMap
+ * @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
*
- * The #GDBusAuthObserver type provides a mechanism for participating
- * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
- * peers. Simply instantiate a #GDBusAuthObserver and connect to the
- * signals you are interested in. Note that new signals may be added
- * in the future
+ * A convenience function for creating multiple #GSimpleAction instances
+ * and adding them to a #GActionMap.
*
- * For example, if you only want to allow D-Bus connections from
- * processes owned by the same uid as the server, you would use a
- * signal handler like the following:
- * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
- * static gboolean
- * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
- * GIOStream *stream,
- * GCredentials *credentials,
- * gpointer user_data)
+ * Each action is constructed as per one #GActionEntry.
+ *
+ * |[<!-- language="C" -->
+ * static void
+ * activate_quit (GSimpleAction *simple,
+ * GVariant *parameter,
+ * gpointer user_data)
* {
- * gboolean authorized;
+ * exit (0);
+ * }
*
- * authorized = FALSE;
- * if (credentials != NULL)
+ * static void
+ * activate_print_string (GSimpleAction *simple,
+ * GVariant *parameter,
+ * gpointer user_data)
* {
- * GCredentials *own_credentials;
- * own_credentials = g_credentials_new ();
- * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
- * authorized = TRUE;
- * g_object_unref (own_credentials);
+ * g_print ("%s\n", g_variant_get_string (parameter, NULL));
* }
*
- * return authorized;
+ * static GActionGroup *
+ * create_action_group (void)
+ * {
+ * const GActionEntry entries[] = {
+ * { "quit", activate_quit },
+ * { "print-string", activate_print_string, "s" }
+ * };
+ * GSimpleActionGroup *group;
+ *
+ * group = g_simple_action_group_new ();
+ * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+ *
+ * return G_ACTION_GROUP (group);
* }
- * </programlisting></example>
+ * ]|
+ *
+ * Since: 2.32
*/
/**
- * SECTION:gdbusconnection
- * @short_description: D-Bus Connections
- * @include: gio/gio.h
+ * g_action_map_lookup_action:
+ * @action_map: a #GActionMap
+ * @action_name: the name of an action
*
- * The #GDBusConnection type is used for D-Bus connections to remote
- * peers such as a message buses. It is a low-level API that offers a
- * lot of flexibility. For instance, it lets you establish a connection
- * over any transport that can by represented as an #GIOStream.
+ * Looks up the action with the name @action_name in @action_map.
*
- * 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(),
- * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
+ * If no such action exists, returns %NULL.
+ *
+ * Returns: (transfer none): a #GAction, or %NULL
+ * Since: 2.32
+ */
+
+
+/**
+ * g_action_map_remove_action:
+ * @action_map: a #GActionMap
+ * @action_name: the name of the action
*
- * 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>.
+ * Removes the named action from the action map.
*
- * Most of the ways to obtain a #GDBusConnection automatically initialize it
- * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
- * g_bus_get(), and the synchronous versions of those methods, give you an
- * initialized connection. Language bindings for GIO should use
- * g_initable_new() or g_async_initable_new(), which also initialize the
- * connection.
+ * If no action of this name is in the map then nothing happens.
*
- * If you construct an uninitialized #GDBusConnection, such as via
- * g_object_new(), you must initialize it via g_initable_init() or
- * g_async_initable_init() before using its methods or properties. Calling
- * methods or accessing properties on a #GDBusConnection that has not completed
- * initialization successfully is considered to be invalid, and leads to
- * undefined behaviour. In particular, if initialization fails with a #GError,
- * the only valid thing you can do with that #GDBusConnection is to free it
- * with g_object_unref().
+ * Since: 2.32
+ */
+
+
+/**
+ * g_action_name_is_valid:
+ * @action_name: an potential action name
*
- * <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>
+ * Checks if @action_name is valid.
*
- * <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>
+ * @action_name is valid if it consists only of alphanumeric characters,
+ * plus '-' and '.'. The empty string is not a valid action name.
*
- * <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>
+ * It is an error to call this function with a non-utf8 @action_name.
+ * @action_name must not be %NULL.
*
- * <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>
+ * Returns: %TRUE if @action_name is valid
+ * Since: 2.38
*/
/**
- * SECTION:gdbuserror
- * @title: GDBusError
- * @short_description: Mapping D-Bus errors to and from GError
- * @include: gio/gio.h
+ * 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
*
- * All facilities that return errors from remote methods (such as
- * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
- * errors (e.g. errors returned from the other peer) and locally
- * in-process generated errors.
+ * Parses a detailed action name into its separate name and target
+ * components.
*
- * To check if a returned #GError is an error from a remote peer, use
- * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
- * use g_dbus_error_get_remote_error(). Before presenting an error,
- * always use g_dbus_error_strip_remote_error().
+ * Detailed action names can have three formats.
*
- * In addition, facilities used to return errors to a remote peer also
- * use #GError. See g_dbus_method_invocation_return_error() for
- * discussion about how the D-Bus error name is set.
+ * 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".
*
- * Applications can associate a #GError error domain with a set of D-Bus errors in order to
- * 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: *<!-- -->/
+ * 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".
*
- * #define FOO_BAR_ERROR (foo_bar_error_quark ())
- * GQuark foo_bar_error_quark (void);
+ * 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 '.'.
*
- * typedef enum
- * {
- * FOO_BAR_ERROR_FAILED,
- * FOO_BAR_ERROR_ANOTHER_ERROR,
- * FOO_BAR_ERROR_SOME_THIRD_ERROR,
- * } FooBarError;
+ * 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
*
- * /<!-- -->* foo-bar-error.c: *<!-- -->/
+ * Formats a detailed action name from @action_name and @target_value.
*
- * static const GDBusErrorEntry foo_bar_error_entries[] =
- * {
- * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
- * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
- * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
- * };
+ * It is an error to call this function with an invalid action name.
*
- * GQuark
- * foo_bar_error_quark (void)
- * {
- * static volatile gsize quark_volatile = 0;
- * g_dbus_error_register_error_domain ("foo-bar-error-quark",
- * &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
- * 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().
+ * 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.
*
- * Note that errors in the %G_DBUS_ERROR error domain is intended only
- * for returning errors from a remote message bus process. Errors
- * generated locally in-process by e.g. #GDBusConnection is from the
- * %G_IO_ERROR domain.
+ * See that function for the types of strings that will be printed by
+ * this function.
+ *
+ * Returns: a detailed format string
+ * Since: 2.38
*/
/**
- * SECTION:gdbusinterface
- * @short_description: Base type for D-Bus interfaces
- * @include: gio/gio.h
+ * g_app_info_add_supports_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: a string.
+ * @error: a #GError.
*
- * The #GDBusInterface type is the base type for D-Bus interfaces both
- * on the service side (see #GDBusInterfaceSkeleton) and client side
- * (see #GDBusProxy).
+ * 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.
*/
/**
- * SECTION:gdbusinterfaceskeleton
- * @short_description: Service-side D-Bus interface
- * @include: gio/gio.h
+ * g_app_info_can_delete:
+ * @appinfo: a #GAppInfo
*
- * Abstract base class for D-Bus interfaces on the service side.
+ * Obtains the information whether the #GAppInfo can be deleted.
+ * See g_app_info_delete().
+ *
+ * Returns: %TRUE if @appinfo can be deleted
+ * Since: 2.20
*/
/**
- * SECTION:gdbusintrospection
- * @title: D-Bus Introspection Data
- * @short_description: Node and interface description data structures
- * @include: gio/gio.h
+ * g_app_info_can_remove_supports_type:
+ * @appinfo: a #GAppInfo.
*
- * Various data structures and convenience routines to parse and
- * generate D-Bus introspection XML. Introspection information is
- * used when registering objects with g_dbus_connection_register_object().
+ * Checks if a supported content type can be removed from an application.
*
- * 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>.
+ * Returns: %TRUE if it is possible to remove supported
+ * content types from a given @appinfo, %FALSE if not.
*/
/**
- * SECTION:gdbusmenumodel
- * @title: GDBusMenuModel
- * @short_description: A D-Bus GMenuModel implementation
- * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
+ * g_app_info_create_from_commandline:
+ * @commandline: the commandline to use
+ * @application_name: (allow-none): the application name, or %NULL to use @commandline
+ * @flags: flags that can specify details of the created #GAppInfo
+ * @error: a #GError location to store the error occurring, %NULL to ignore.
*
- * #GDBusMenuModel is an implementation of #GMenuModel that can be used
- * as a proxy for a menu model that is exported over D-Bus with
- * g_dbus_connection_export_menu_model().
+ * Creates a new #GAppInfo from the given information.
+ *
+ * Note that for @commandline, the quoting rules of the Exec key of the
+ * [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.
+ *
+ * Returns: (transfer full): new #GAppInfo for given command.
*/
/**
- * SECTION:gdbusmessage
- * @short_description: D-Bus Message
- * @include: gio/gio.h
+ * g_app_info_delete: (virtual do_delete)
+ * @appinfo: a #GAppInfo
*
- * A type for representing D-Bus messages that can be sent or received
- * on a #GDBusConnection.
+ * Tries to delete a #GAppInfo.
+ *
+ * On some platforms, there may be a difference between user-defined
+ * #GAppInfos which can be deleted, and system-wide ones which cannot.
+ * See g_app_info_can_delete().
+ *
+ * Returns: %TRUE if @appinfo has been deleted
+ * Since: 2.20
*/
/**
- * SECTION:gdbusmethodinvocation
- * @short_description: Object for handling remote calls
- * @include: gio/gio.h
+ * g_app_info_dup:
+ * @appinfo: a #GAppInfo.
*
- * Instances of the #GDBusMethodInvocation class are used when
- * handling D-Bus method calls. It provides a way to asynchronously
- * return results and errors.
+ * Creates a duplicate of a #GAppInfo.
*
- * The normal way to obtain a #GDBusMethodInvocation object is to receive
- * it as an argument to the handle_method_call() function in a
- * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
+ * Returns: (transfer full): a duplicate of @appinfo.
*/
/**
- * SECTION:gdbusnameowning
- * @title: Owning Bus Names
- * @short_description: Simple API for owning bus names
- * @include: gio/gio.h
+ * g_app_info_equal:
+ * @appinfo1: the first #GAppInfo.
+ * @appinfo2: the second #GAppInfo.
*
- * Convenience API for owning bus names.
+ * Checks if two #GAppInfos are equal.
*
- * <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>
+ * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
*/
/**
- * SECTION:gdbusnamewatching
- * @title: Watching Bus Names
- * @short_description: Simple API for watching bus names
- * @include: gio/gio.h
+ * g_app_info_get_all:
*
- * Convenience API for watching bus names.
+ * Gets a list of all of the applications currently registered
+ * on this system.
+ *
+ * For desktop files, this includes applications that have
+ * `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 `Hidden` key set.
*
- * <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>
+ * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos.
*/
/**
- * SECTION:gdbusobject
- * @short_description: Base type for D-Bus objects
- * @include: gio/gio.h
+ * g_app_info_get_all_for_type:
+ * @content_type: the content type to find a #GAppInfo for
*
- * The #GDBusObject type is the base type for D-Bus objects on both
- * the service side (see #GDBusObjectSkeleton) and the client side
- * (see #GDBusObjectProxy). It is essentially just a container of
- * interfaces.
+ * Gets a list of all #GAppInfos for a given content type,
+ * including the recommended and fallback #GAppInfos. See
+ * 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.
*/
/**
- * SECTION:gdbusobjectmanager
- * @short_description: Base type for D-Bus object managers
- * @include: gio/gio.h
+ * g_app_info_get_commandline:
+ * @appinfo: a #GAppInfo
*
- * 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>
- * interface.
+ * Gets the commandline with which the application will be
+ * started.
*
- * See #GDBusObjectManagerClient for the client-side implementation
- * and #GDBusObjectManagerServer for the service-side implementation.
+ * Returns: a string containing the @appinfo's commandline,
+ * or %NULL if this information is not available
+ * Since: 2.20
*/
/**
- * SECTION:gdbusobjectmanagerclient
- * @short_description: Client-side object manager
- * @include: gio/gio.h
- *
- * #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>
- * interface).
- *
- * Once an instance of this type has been created, you can connect to
- * the #GDBusObjectManager::object-added and
- * #GDBusObjectManager::object-removed signals and inspect the
- * #GDBusObjectProxy objects returned by
- * g_dbus_object_manager_get_objects().
- *
- * If the name for a #GDBusObjectManagerClient is not owned by anyone at
- * object construction time, the default behavior is to request the
- * message bus to launch an owner for the name. This behavior can be
- * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
- * flag. It's also worth noting that this only works if the name of
- * interest is activatable in the first place. E.g. in some cases it
- * is not possible to launch an owner for the requested name. In this
- * case, #GDBusObjectManagerClient object construction still succeeds but
- * there will be no object proxies
- * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
- * the #GDBusObjectManagerClient:name-owner property is %NULL.
- *
- * The owner of the requested name can come and go (for example
- * consider a system service being restarted) – #GDBusObjectManagerClient
- * handles this case too; simply connect to the #GObject::notify
- * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
- * property. When the name owner vanishes, the behavior is that
- * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
- * emission of the #GObject::notify signal) and then
- * #GDBusObjectManager::object-removed signals are synthesized
- * for all currently existing object proxies. Since
- * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
- * use this information to disambiguate a synthesized signal from a
- * genuine signal caused by object removal on the remote
- * #GDBusObjectManager. Similarly, when a new name owner appears,
- * #GDBusObjectManager::object-added signals are synthesized
- * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
- * object proxies have been added, the #GDBusObjectManagerClient:name-owner
- * 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
- * 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.
- *
- * To avoid having the application connect to signals on the returned
- * #GDBusObjectProxy and #GDBusProxy objects, the
- * #GDBusObject::interface-added,
- * #GDBusObject::interface-removed,
- * #GDBusProxy::g-properties-changed and
- * #GDBusProxy::g-signal signals
- * are also emitted on the #GDBusObjectManagerClient instance managing these
- * objects. The signals emitted are
- * #GDBusObjectManager::interface-added,
- * #GDBusObjectManager::interface-removed,
- * #GDBusObjectManagerClient::interface-proxy-properties-changed and
- * #GDBusObjectManagerClient::interface-proxy-signal.
+ * 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
*
- * Note that all callbacks and signals are emitted in the
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
- * that the #GDBusObjectManagerClient object was constructed
- * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
- * originating from the #GDBusObjectManagerClient object will be created in
- * the same context and, consequently, will deliver signals in the
- * same main loop.
+ * Gets the default #GAppInfo for a given content type.
+ *
+ * Returns: (transfer full): #GAppInfo for given @content_type or
+ * %NULL on error.
*/
/**
- * SECTION:gdbusobjectmanagerserver
- * @short_description: Service-side object manager
- * @include: gio/gio.h
+ * g_app_info_get_default_for_uri_scheme:
+ * @uri_scheme: a string containing a URI scheme.
*
- * #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>
- * 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
- * clients can keep caches up to date by only listening to D-Bus
- * signals.
+ * Gets the default application for handling URIs with
+ * the given URI scheme. A URI scheme is the initial part
+ * of the URI, up to but not including the ':', e.g. "http",
+ * "ftp" or "sip".
*
- * See #GDBusObjectManagerClient for the client-side code that is
- * intended to be used with #GDBusObjectManagerServer or any D-Bus
- * object implementing the org.freedesktop.DBus.ObjectManager
- * interface.
+ * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
*/
/**
- * SECTION:gdbusobjectproxy
- * @short_description: Client-side D-Bus object
- * @include: gio/gio.h
+ * g_app_info_get_description:
+ * @appinfo: a #GAppInfo.
*
- * A #GDBusObjectProxy is an object used to represent a remote object
- * with one or more D-Bus interfaces. Normally, you don't instantiate
- * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
- * is used to obtain it.
+ * Gets a human-readable description of an installed application.
*
- * Since: 2.30
+ * Returns: a string containing a description of the
+ * application @appinfo, or %NULL if none.
*/
/**
- * SECTION:gdbusobjectskeleton
- * @short_description: Service-side D-Bus object
- * @include: gio/gio.h
+ * g_app_info_get_display_name:
+ * @appinfo: a #GAppInfo.
*
- * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
- * interfaces. The set of exported interfaces on the object may be
- * dynamic and change at runtime.
+ * Gets the display name of the application. The display name is often more
+ * descriptive to the user than the name itself.
*
- * This type is intended to be used with #GDBusObjectManager.
+ * Returns: the display name of the application for @appinfo, or the name if
+ * no display name is available.
+ * Since: 2.24
*/
/**
- * SECTION:gdbusproxy
- * @short_description: Client-side D-Bus interface proxy
- * @include: gio/gio.h
+ * g_app_info_get_executable:
+ * @appinfo: a #GAppInfo
*
- * #GDBusProxy is a base class used for proxies to access a D-Bus
- * interface on a remote object. A #GDBusProxy can be constructed for
- * both well-known and unique names.
+ * Gets the executable's name for the installed application.
*
- * By default, #GDBusProxy will cache all properties (and listen to
- * changes) of the remote object, and proxy all signals that gets
- * emitted. This behaviour can be changed by passing suitable
- * #GDBusProxyFlags when the proxy is created. If the proxy is for a
- * well-known name, the property cache is flushed when the name owner
- * vanishes and reloaded when a name owner appears.
+ * Returns: a string containing the @appinfo's application
+ * binaries name
+ */
+
+
+/**
+ * g_app_info_get_fallback_for_type:
+ * @content_type: the content type to find a #GAppInfo for
*
- * If a #GDBusProxy is used for a well-known name, the owner of the
- * name is tracked and can be read from
- * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
- * get notified of changes. Additionally, only signals and property
- * changes emitted from the current name owner are considered and
- * calls are always sent to the current name owner. This avoids a
- * number of race conditions when the name is lost by one owner and
- * claimed by another. However, if no name owner currently exists,
- * then calls will be sent to the well-known name which may result in
- * the message bus launching an owner (unless
- * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
+ * Gets a list of fallback #GAppInfos for a given content type, i.e.
+ * those applications which claim to support the given content type
+ * by MIME type subclassing and not directly.
*
- * 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.
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * for given @content_type or %NULL on error.
+ * Since: 2.28
+ */
+
+
+/**
+ * g_app_info_get_icon:
+ * @appinfo: a #GAppInfo.
*
- * 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>
- * of the thread where the instance was constructed.
+ * Gets the icon for the application.
*
- * <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>
+ * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
+ * if there is no default icon.
*/
/**
- * SECTION:gdbusserver
- * @short_description: Helper for accepting connections
- * @include: gio/gio.h
+ * g_app_info_get_id:
+ * @appinfo: a #GAppInfo.
*
- * #GDBusServer is a helper for listening to and accepting D-Bus
- * connections. This can be used to create a new D-Bus server, allowing two
- * peers to use the D-Bus protocol for their own specialized communication.
- * A server instance provided in this way will not perform message routing or
- * implement the org.freedesktop.DBus interface.
+ * Gets the ID of an application. An id is a string that
+ * identifies the application. The exact format of the id is
+ * platform dependent. For instance, on Unix this is the
+ * desktop file id from the xdg menu specification.
*
- * 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().
+ * Note that the returned ID may be %NULL, depending on how
+ * the @appinfo has been constructed.
*
- * <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>
+ * Returns: a string containing the application's ID.
*/
/**
- * SECTION:gdbusutils
- * @title: D-Bus Utilities
- * @short_description: Various utilities related to D-Bus.
- * @include: gio/gio.h
+ * g_app_info_get_name:
+ * @appinfo: a #GAppInfo.
*
- * Various utility routines related to D-Bus.
+ * Gets the installed name of the application.
+ *
+ * Returns: the name of the application for @appinfo.
*/
/**
- * SECTION:gdesktopappinfo
- * @title: GDesktopAppInfo
- * @short_description: Application information from desktop files
- * @include: gio/gdesktopappinfo.h
+ * g_app_info_get_recommended_for_type:
+ * @content_type: the content type to find a #GAppInfo for
*
- * #GDesktopAppInfo is an implementation of #GAppInfo based on
- * desktop files.
+ * Gets a list of recommended #GAppInfos for a given content type, i.e.
+ * those applications which claim to support the given content type exactly,
+ * and not by MIME type subclassing.
+ * Note that the first application of the list is the last used one, i.e.
+ * the last one for which g_app_info_set_as_last_used_for_type() has been
+ * called.
*
- * 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.
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * for given @content_type or %NULL on error.
+ * Since: 2.28
*/
/**
- * SECTION:gdrive
- * @short_description: Drive management
- * @include: gio/gio.h
- *
- * #GDrive - this represent a piece of hardware connected to the machine.
- * It's generally only created for removable hardware or hardware with
- * removable media.
- *
- * #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
- * automatically detected and ejecting the media.
- *
- * If the #GDrive reports that media isn't automatically detected, one
- * can poll for media; typically one should not do this periodically
- * as a poll for media operation is potententially expensive and may
- * spin up the drive creating noise.
+ * g_app_info_get_supported_types:
+ * @appinfo: a #GAppInfo that can handle files
*
- * #GDrive supports starting and stopping drives with authentication
- * support for the former. This can be used to support a diverse set
- * of use cases including connecting/disconnecting iSCSI devices,
- * powering down external disk enclosures and starting/stopping
- * multi-disk devices such as RAID devices. Note that the actual
- * semantics and side-effects of starting/stopping a #GDrive may vary
- * according to implementation. To choose the correct verbs in e.g. a
- * file manager, use g_drive_get_start_stop_type().
+ * Retrieves the list of content types that @app_info claims to support.
+ * If this information is not provided by the environment, this function
+ * will return %NULL.
+ * This function does not take in consideration associations added with
+ * g_app_info_add_supports_type(), but only those exported directly by
+ * the application.
*
- * For porting from GnomeVFS note that there is no equivalent of
- * #GDrive in that API.
+ * Returns: (transfer none) (array zero-terminated=1) (element-type utf8):
+ * a list of content types.
+ * Since: 2.34
*/
/**
- * SECTION:gemblem
- * @short_description: An object for emblems
- * @include: gio/gio.h
- * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
+ * g_app_info_launch:
+ * @appinfo: a #GAppInfo
+ * @files: (allow-none) (element-type GFile): a #GList of #GFile objects
+ * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
+ * @error: a #GError
*
- * #GEmblem is an implementation of #GIcon that supports
- * having an emblem, which is an icon with additional properties.
- * It can than be added to a #GEmblemedIcon.
+ * Launches the application. Passes @files to the launched application
+ * as arguments, using the optional @launch_context to get information
+ * about the details of the launcher (like what screen it is on).
+ * On error, @error will be set accordingly.
*
- * Currently, only metainformation about the emblem's origin is
- * supported. More may be added in the future.
+ * To launch the application without arguments pass a %NULL @files list.
+ *
+ * Note that even if the launch is successful the application launched
+ * can fail to start if it runs into problems during startup. There is
+ * no way to detect this.
+ *
+ * Some URIs can be changed when passed through a GFile (for instance
+ * unsupported URIs with strange formats like mailto:), so if you have
+ * a textual URI you want to pass in as argument, consider using
+ * 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().
+ *
+ * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+ * environment variable with the path of the launched desktop file and
+ * `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.
*/
/**
- * SECTION:gemblemedicon
- * @short_description: Icon with emblems
- * @include: gio/gio.h
- * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
+ * g_app_info_launch_default_for_uri:
+ * @uri: the uri to show
+ * @launch_context: (allow-none): an optional #GAppLaunchContext.
+ * @error: a #GError.
*
- * #GEmblemedIcon is an implementation of #GIcon that supports
- * adding an emblem to an icon. Adding multiple emblems to an
- * icon is ensured via g_emblemed_icon_add_emblem().
+ * Utility function that launches the default application
+ * registered to handle the specified uri. Synchronous I/O
+ * is done on the uri to detect the type of the file if
+ * required.
*
- * Note that #GEmblemedIcon allows no control over the position
- * of the emblems. See also #GEmblem for more information.
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * SECTION:gfile
- * @short_description: File and Directory Handling
- * @include: gio/gio.h
- * @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).
- *
- * 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
- * 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
- * %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
- * %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.
+ * g_app_info_launch_uris:
+ * @appinfo: a #GAppInfo
+ * @uris: (allow-none) (element-type utf8): a #GList containing URIs to launch.
+ * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
+ * @error: a #GError
*
- * Many #GFile operations have both synchronous and asynchronous versions
- * to suit your application. Asynchronous versions of synchronous functions
- * simply have _async() appended to their function names. The asynchronous
- * I/O functions call a #GAsyncReadyCallback which is then used to finalize
- * the operation, producing a GAsyncResult which is then passed to the
- * function's matching _finish() operation.
+ * Launches the application. This passes the @uris to the launched application
+ * as arguments, using the optional @launch_context to get information
+ * about the details of the launcher (like what screen it is on).
+ * On error, @error will be set accordingly.
*
- * 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.
+ * To launch the application without arguments pass a %NULL @uris list.
*
- * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
- * One notable feature of #GFile<!-- -->s 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>
- * for HTTP Etag headers, which are a very similar concept.
- * </para>
+ * Note that even if the launch is successful the application launched
+ * can fail to start if it runs into problems during startup. There is
+ * no way to detect this.
+ *
+ * Returns: %TRUE on successful launch, %FALSE otherwise.
*/
/**
- * SECTION:gfileattribute
- * @short_description: Key-Value Paired File Attributes
- * @include: gio/gio.h
- * @see_also: #GFile, #GFileInfo
- *
- * File attributes in GIO consist of a list of key-value pairs.
+ * g_app_info_monitor_get:
*
- * 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
- * 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.
- *
- * Values are stored within the list in #GFileAttributeValue structures.
- * Values can store different types, listed in the enum #GFileAttributeType.
- * Upon creation of a #GFileAttributeValue, the type will be set to
- * %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ * Gets the #GAppInfoMonitor for the current thread-default main
+ * context.
*
- * The list of possible attributes for a filesystem (pointed to by a #GFile) is
- * available as a #GFileAttributeInfoList. This list is queryable by key names
- * as indicated earlier.
+ * 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.
*
- * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
- * install default keys and values for their given file system, architecture,
- * 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).
+ * You must only call g_object_unref() on the return value from under
+ * the same main context as you created it.
*
- * <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>
+ * Returns: (transfer full): a reference to a #GAppInfoMonitor
+ * Since: 2.40
+ */
+
+
+/**
+ * g_app_info_remove_supports_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: a string.
+ * @error: a #GError.
*
- * Please note that these are not all of the possible namespaces.
- * More namespaces can be added from GIO modules or by individual applications.
- * For more information about writing GIO modules, see #GIOModule.
+ * Removes a supported type from an application, if possible.
*
- * <!-- TODO: Implementation note about using extended attributes on supported
- * file systems -->
+ * Returns: %TRUE on success, %FALSE on error.
+ */
+
+
+/**
+ * g_app_info_reset_type_associations:
+ * @content_type: a content type
*
- * <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_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>
+ * Removes all changes to the type associations done by
+ * g_app_info_set_as_default_for_type(),
+ * g_app_info_set_as_default_for_extension(),
+ * g_app_info_add_supports_type() or
+ * g_app_info_remove_supports_type().
*
- * Note that there are no predefined keys in the "xattr" and "xattr-sys"
- * namespaces. Keys for the "xattr" namespace are constructed by stripping
- * away the "user." prefix from the extended user attribute, and prepending
- * "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>.
+ * Since: 2.20
*/
/**
- * SECTION:gfiledescriptorbased
- * @short_description: Interface for file descriptor based IO
- * @include: gio/gfiledescriptorbased.h
- * @see_also: #GInputStream, #GOutputStream
- *
- * #GFileDescriptorBased is implemented by streams (implementations of
- * #GInputStream or #GOutputStream) that are based on file descriptors.
+ * g_app_info_set_as_default_for_extension:
+ * @appinfo: a #GAppInfo.
+ * @extension: a string containing the file extension (without the dot).
+ * @error: a #GError.
*
- * 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.
+ * Sets the application as the default handler for the given file extension.
*
- * Since: 2.24
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * SECTION:gfileenumerator
- * @short_description: Enumerated Files Routines
- * @include: gio/gio.h
- *
- * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
- * 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).
+ * g_app_info_set_as_default_for_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: the content type.
+ * @error: a #GError.
*
- * 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
- * synchronous will only return the next file in the enumerator.
+ * Sets the application as the default handler for a given type.
*
- * 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
- * on it, and it should be freed with g_object_unref().
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * SECTION:gfileicon
- * @short_description: Icons pointing to an image file
- * @include: gio/gio.h
- * @see_also: #GIcon, #GLoadableIcon
+ * g_app_info_set_as_last_used_for_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: the content type.
+ * @error: a #GError.
*
- * #GFileIcon specifies an icon by pointing to an image file
- * to be used as icon.
+ * Sets the application as the last used application for a given type.
+ * This will make the application appear as first in the list returned
+ * by g_app_info_get_recommended_for_type(), regardless of the default
+ * application for that content type.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * SECTION:gfileinfo
- * @short_description: File Information and Attributes
- * @include: gio/gio.h
- * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
+ * g_app_info_should_show:
+ * @appinfo: a #GAppInfo.
*
- * 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.
+ * Checks if the application info should be shown in menus that
+ * list available applications.
*
- * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
- * information on how GIO handles file attributes.
+ * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
+ */
+
+
+/**
+ * g_app_info_supports_files:
+ * @appinfo: a #GAppInfo.
*
- * 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
- * stream, use g_file_input_stream_query_info() or
- * g_file_output_stream_query_info() (or their async variants).
+ * Checks if the application accepts files as arguments.
*
- * To change the actual attributes of a file, you should then set the
- * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
- * or g_file_set_attributes_async() on a GFile.
+ * Returns: %TRUE if the @appinfo supports files.
+ */
+
+
+/**
+ * g_app_info_supports_uris:
+ * @appinfo: a #GAppInfo.
*
- * However, not all attributes can be changed in the file. For instance,
- * the actual size of a file cannot be changed via g_file_info_set_size().
- * You may call g_file_query_settable_attributes() and
- * g_file_query_writable_namespaces() to discover the settable attributes
- * of a particular file at runtime.
+ * Checks if the application supports reading files and directories from URIs.
*
- * #GFileAttributeMatcher allows for searching through a #GFileInfo for
- * attributes.
+ * Returns: %TRUE if the @appinfo supports URIs.
*/
/**
- * SECTION:gfileinputstream
- * @short_description: File input streaming operations
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GDataInputStream, #GSeekable
+ * g_app_launch_context_get_display:
+ * @context: a #GAppLaunchContext
+ * @info: a #GAppInfo
+ * @files: (element-type GFile): a #GList of #GFile objects
*
- * GFileInputStream provides input streams that take their
- * content from a file.
+ * 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 `DISPLAY` environment variable.
*
- * GFileInputStream implements #GSeekable, which allows the input
- * stream to jump to arbitrary positions in the file, provided the
- * filesystem of the file allows it. To find the position of a file
- * input stream, use g_seekable_tell(). To find out if a file input
- * stream supports seeking, use g_seekable_stream_can_seek().
- * To position a file input stream, use g_seekable_seek().
+ * Returns: a display string for the display.
*/
/**
- * SECTION:gfileiostream
- * @short_description: File read and write streaming operations
- * @include: gio/gio.h
- * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
- *
- * GFileIOStream provides io streams that both read and write to the same
- * file handle.
+ * g_app_launch_context_get_environment:
+ * @context: a #GAppLaunchContext
*
- * GFileIOStream implements #GSeekable, which allows the io
- * stream to jump to arbitrary positions in the file and to truncate
- * the file, provided the filesystem of the file supports these
- * operations.
+ * 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 `KEY=VALUE`.
*
- * To find the position of a file io stream, use
- * g_seekable_tell().
+ * Returns: (array zero-terminated=1) (transfer full): the
+ * child's environment
+ * Since: 2.32
+ */
+
+
+/**
+ * g_app_launch_context_get_startup_notify_id:
+ * @context: a #GAppLaunchContext
+ * @info: a #GAppInfo
+ * @files: (element-type GFile): a #GList of of #GFile objects
*
- * To find out if a file io stream supports seeking, use g_seekable_can_seek().
- * To position a file io stream, use g_seekable_seek().
- * To find out if a file io stream supports truncating, use
- * g_seekable_can_truncate(). To truncate a file io
- * stream, use g_seekable_truncate().
+ * Initiates startup notification for the application and returns the
+ * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
*
- * The default implementation of all the #GFileIOStream operations
- * and the implementation of #GSeekable just call into the same operations
- * on the output stream.
+ * Startup notification IDs are defined in the
+ * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
*
- * Since: 2.22
+ * Returns: a startup notification ID for the application, or %NULL if
+ * not supported.
*/
/**
- * SECTION:gfilemonitor
- * @short_description: File Monitor
- * @include: gio/gio.h
- *
- * Monitors a file or directory for changes.
- *
- * To obtain a #GFileMonitor for a file or directory, use
- * g_file_monitor(), g_file_monitor_file(), or
- * g_file_monitor_directory().
+ * g_app_launch_context_launch_failed:
+ * @context: a #GAppLaunchContext.
+ * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
*
- * 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
- * (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).
+ * Called when an application has failed to launch, so that it can cancel
+ * the application startup notification started in g_app_launch_context_get_startup_notify_id().
*/
/**
- * SECTION:gfilenamecompleter
- * @short_description: Filename Completer
- * @include: gio/gio.h
+ * g_app_launch_context_new:
*
- * Completes partial file and directory names given a partial string by
- * looking in the file system for clues. Can return a list of possible
- * completion strings for widget implementations.
+ * Creates a new application launch context. This is not normally used,
+ * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
+ *
+ * Returns: a #GAppLaunchContext.
*/
/**
- * SECTION:gfileoutputstream
- * @short_description: File output streaming operations
- * @include: gio/gio.h
- * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
+ * g_app_launch_context_setenv:
+ * @context: a #GAppLaunchContext
+ * @variable: the environment variable to set
+ * @value: the value for to set the variable to.
*
- * GFileOutputStream provides output streams that write their
- * content to a file.
+ * Arranges for @variable to be set to @value in the child's
+ * environment when @context is used to launch an application.
*
- * GFileOutputStream implements #GSeekable, which allows the output
- * stream to jump to arbitrary positions in the file and to truncate
- * the file, provided the filesystem of the file supports these
- * operations.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_app_launch_context_unsetenv:
+ * @context: a #GAppLaunchContext
+ * @variable: the environment variable to remove
*
- * To find the position of a file output stream, use g_seekable_tell().
- * To find out if a file output stream supports seeking, use
- * g_seekable_can_seek().To position a file output stream, use
- * g_seekable_seek(). To find out if a file output stream supports
- * truncating, use g_seekable_can_truncate(). To truncate a file output
- * stream, use g_seekable_truncate().
+ * Arranges for @variable to be unset in the child's environment
+ * when @context is used to launch an application.
+ *
+ * Since: 2.32
*/
/**
- * SECTION:gfilterinputstream
- * @short_description: Filter Input Stream
- * @include: gio/gio.h
+ * g_application_activate:
+ * @application: a #GApplication
*
- * Base class for input stream implementations that perform some
- * kind of filtering operation on a base stream. Typical examples
- * of filtering operations are character set conversion, compression
- * and byte order flipping.
+ * Activates the application.
+ *
+ * In essence, this results in the #GApplication::activate signal being
+ * emitted in the primary instance.
+ *
+ * The application must be registered before calling this function.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gfilteroutputstream
- * @short_description: Filter Output Stream
- * @include: gio/gio.h
+ * 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
*
- * Base class for output stream implementations that perform some
- * kind of filtering operation on a base stream. Typical examples
- * of filtering operations are character set conversion, compression
- * and byte order flipping.
+ * 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
*/
/**
- * SECTION:gicon
- * @short_description: Interface for icons
- * @include: gio/gio.h
+ * g_application_add_main_option_entries:
+ * @application: a #GApplication
+ * @entries: (array zero-terminated=1) (element-type GOptionEntry): a
+ * %NULL-terminated list of #GOptionEntrys
*
- * #GIcon is a very minimal interface for icons. It provides functions
- * for checking the equality of two icons, hashing of icons and
- * serializing an icon to and from strings.
+ * Adds main option entries to be handled by @application.
*
- * #GIcon does not provide the actual pixmap for the icon as this is out
- * of GIO's scope, however implementations of #GIcon may contain the name
- * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
+ * This function is comparable to g_option_context_add_main_entries().
*
- * To obtain a hash of a #GIcon, see g_icon_hash().
+ * 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.
*
- * To check if two #GIcons are equal, see g_icon_equal().
+ * 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).
*
- * For serializing a #GIcon, use g_icon_to_string() and
- * g_icon_new_for_string().
+ * 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.
*
- * 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().
+ * 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
*/
/**
- * SECTION:ginetaddress
- * @short_description: An IPv4/IPv6 address
+ * g_application_add_option_group:
+ * @application: the #GApplication
+ * @group: a #GOptionGroup
*
- * #GInetAddress represents an IPv4 or IPv6 internet address. Use
- * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
- * look up the #GInetAddress for a hostname. Use
- * g_resolver_lookup_by_address() or
- * g_resolver_lookup_by_address_async() to look up the hostname for a
- * #GInetAddress.
+ * Adds a #GOptionGroup to the commandline handling of @application.
*
- * To actually connect to a remote host, you will need a
- * #GInetSocketAddress (which includes a #GInetAddress as well as a
- * port number).
+ * 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
*/
/**
- * SECTION:ginetaddressmask
- * @short_description: An IPv4/IPv6 address mask
+ * g_application_bind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
*
- * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
- * described by a base address and a length indicating how many bits
- * of the base address are relevant for matching purposes. These are
- * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
+ * 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
*/
/**
- * SECTION:ginetsocketaddress
- * @short_description: Internet GSocketAddress
+ * g_application_command_line_create_file_for_arg:
+ * @cmdline: a #GApplicationCommandLine
+ * @arg: an argument from @cmdline
*
- * An IPv4 or IPv6 socket address; that is, the combination of a
- * #GInetAddress and a port number.
+ * 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
*/
/**
- * SECTION:ginitable
- * @short_description: Failable object initialization interface
- * @include: gio/gio.h
- * @see_also: #GAsyncInitable
+ * g_application_command_line_get_arguments:
+ * @cmdline: a #GApplicationCommandLine
+ * @argc: (out) (allow-none): the length of the arguments array, or %NULL
*
- * #GInitable is implemented by objects that can fail during
- * initialization. If an object implements this interface then
- * it must be initialized as the first thing after construction,
- * either via g_initable_init() or g_async_initable_init_async()
- * (the latter is only available if it also implements #GAsyncInitable).
+ * Gets the list of arguments that was passed on the command line.
*
- * 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. They will often fail with g_critical() or g_warning(), but
- * this must not be relied on.
+ * 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.
*
- * Users of objects implementing this are not intended to use
- * the interface method directly, instead it will be used automatically
- * in various ways. For C applications you generally just call
- * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
- * This will call g_initable_init() under the cover, returning %NULL and
- * setting a #GError on failure (at which point the instance is
- * unreferenced).
+ * If you wish to use the return value with #GOptionContext, you must
+ * use g_option_context_parse_strv().
*
- * For bindings in languages where the native constructor supports
- * exceptions the binding could check for objects implemention %GInitable
- * during normal construction and automatically initialize them, throwing
- * an exception on failure.
+ * 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)
+ * Since: 2.28
*/
/**
- * SECTION:ginputstream
- * @short_description: Base class for implementing streaming input
- * @include: gio/gio.h
+ * g_application_command_line_get_cwd:
+ * @cmdline: a #GApplicationCommandLine
*
- * GInputStream has functions to read from a stream (g_input_stream_read()),
- * to close a stream (g_input_stream_close()) and to skip some content
- * (g_input_stream_skip()).
+ * Gets the working directory of the command line invocation.
+ * The string may contain non-utf8 data.
*
- * To copy the content of an input stream to an output stream without
- * manually handling the reads and writes, use g_output_stream_splice().
+ * It is possible that the remote application did not send a working
+ * directory, so this may be %NULL.
*
- * All of these functions have async variants too.
+ * The return value should not be modified or freed and is valid for as
+ * long as @cmdline exists.
+ *
+ * Returns: the current directory, or %NULL
+ * Since: 2.28
*/
/**
- * SECTION:gioerror
- * @short_description: Error helper functions
- * @include: gio/gio.h
+ * g_application_command_line_get_environ:
+ * @cmdline: a #GApplicationCommandLine
*
- * Contains helper functions for reporting errors to the user.
+ * Gets the contents of the 'environ' variable of the command line
+ * invocation, as would be returned by g_get_environ(), ie as a
+ * %NULL-terminated list of strings in the form 'NAME=VALUE'.
+ * The strings may contain non-utf8 data.
+ *
+ * The remote application usually does not send an environment. Use
+ * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
+ * set it is possible that the environment is still not available (due
+ * to invocation messages from other applications).
+ *
+ * The return value should not be modified or freed and is valid for as
+ * long as @cmdline exists.
+ *
+ * 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
+ * Since: 2.28
*/
/**
- * SECTION:giomodule
- * @short_description: Loadable GIO Modules
- * @include: gio/gio.h
+ * g_application_command_line_get_exit_status:
+ * @cmdline: a #GApplicationCommandLine
*
- * Provides an interface and default functions for loading and unloading
- * modules. This is used internally to make GIO extensible, but can also
- * be used by others to implement module loading.
+ * Gets the exit status of @cmdline. See
+ * g_application_command_line_set_exit_status() for more information.
+ *
+ * Returns: the exit status
+ * Since: 2.28
*/
/**
- * SECTION:gioscheduler
- * @short_description: I/O Scheduler
- * @include: gio/gio.h
+ * g_application_command_line_get_is_remote:
+ * @cmdline: a #GApplicationCommandLine
*
- * Schedules asynchronous I/O operations. #GIOScheduler integrates
- * into the main event loop (#GMainLoop) and uses threads.
+ * Determines if @cmdline represents a remote invocation.
*
- * <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>
+ * Returns: %TRUE if the invocation was remote
+ * Since: 2.28
*/
/**
- * SECTION:giostream
- * @short_description: Base class for implementing read/write streams
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
- *
- * GIOStream represents an object that has both read and write streams.
- * Generally the two streams acts as separate input and output streams,
- * but they share some common resources and state. For instance, for
- * seekable streams they may use the same position in both streams.
- *
- * Examples of #GIOStream objects are #GSocketConnection which represents
- * a two-way network connection, and #GFileIOStream which represent a
- * file handle opened in read-write mode.
+ * g_application_command_line_get_options_dict:
+ * @cmdline: a #GApplicationCommandLine
*
- * To do the actual reading and writing you need to get the substreams
- * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
+ * Gets the options there were passed to g_application_command_line().
*
- * The #GIOStream object owns the input and the output streams, not the other
- * way around, so keeping the substreams alive will not keep the #GIOStream
- * object alive. If the #GIOStream object is freed it will be closed, thus
- * closing the substream, so even if the substreams stay alive they will
- * always just return a %G_IO_ERROR_CLOSED for all operations.
+ * 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.
*
- * 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.
+ * If no options were sent then an empty dictionary is returned so that
+ * you don't need to check for %NULL.
*
- * Since: 2.22
+ * Returns: (transfer none): a #GVariantDict with the options
+ * Since: 2.40
*/
/**
- * SECTION:gloadableicon
- * @short_description: Loadable Icons
- * @include: gio/gio.h
- * @see_also: #GIcon, #GThemedIcon
+ * g_application_command_line_get_platform_data:
+ * @cmdline: #GApplicationCommandLine
*
- * Extends the #GIcon interface and adds the ability to
- * load icons from streams.
+ * Gets the platform data associated with the invocation of @cmdline.
+ *
+ * This is a #GVariant dictionary containing information about the
+ * context in which the invocation occurred. It typically contains
+ * information like the current working directory and the startup
+ * notification ID.
+ *
+ * For local invocation, it will be %NULL.
+ *
+ * Returns: (nullable): the platform data, or %NULL
+ * Since: 2.28
*/
/**
- * SECTION:gmemoryinputstream
- * @short_description: Streaming input operations on memory chunks
- * @include: gio/gio.h
- * @see_also: #GMemoryOutputStream
+ * g_application_command_line_get_stdin:
+ * @cmdline: a #GApplicationCommandLine
*
- * #GMemoryInputStream is a class for using arbitrary
- * memory chunks as input for GIO streaming input operations.
+ * 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
*/
/**
- * SECTION:gmemoryoutputstream
- * @short_description: Streaming output operations on memory chunks
- * @include: gio/gio.h
- * @see_also: #GMemoryInputStream
+ * g_application_command_line_getenv:
+ * @cmdline: a #GApplicationCommandLine
+ * @name: the environment variable to get
+ *
+ * Gets the value of a particular environment variable of the command
+ * line invocation, as would be returned by g_getenv(). The strings may
+ * contain non-utf8 data.
+ *
+ * The remote application usually does not send an environment. Use
+ * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
+ * set it is possible that the environment is still not available (due
+ * to invocation messages from other applications).
*
- * #GMemoryOutputStream is a class for using arbitrary
- * memory chunks as output for GIO streaming output operations.
+ * The return value should not be modified or freed and is valid for as
+ * long as @cmdline exists.
+ *
+ * Returns: the value of the variable, or %NULL if unset or unsent
+ * Since: 2.28
*/
/**
- * SECTION:gmenu
- * @title: GMenu
- * @short_description: A simple implementation of GMenuModel
+ * g_application_command_line_print:
+ * @cmdline: a #GApplicationCommandLine
+ * @format: a printf-style format string
+ * @...: arguments, as per @format
*
- * #GMenu is a simple implementation of #GMenuModel.
- * You populate a #GMenu by adding #GMenuItem instances to it.
+ * Formats a message and prints it using the stdout print handler in the
+ * invoking process.
*
- * There are some convenience functions to allow you to directly
- * add items (avoiding #GMenuItem) for the common cases. To add
- * a regular item, use g_menu_insert(). To add a section, use
- * g_menu_insert_section(). To add a submenu, use
- * g_menu_insert_submenu().
+ * If @cmdline is a local invocation then this is exactly equivalent to
+ * g_print(). If @cmdline is remote then this is equivalent to calling
+ * g_print() in the invoking process.
*
- * Often it is more convenient to create a #GMenu from an XML
- * fragment, using <link linkend="gio-GMenu-Markup">GMenu Markup</link>.
+ * Since: 2.28
*/
/**
- * SECTION:gmenuexporter
- * @title: GMenuModel exporter
- * @short_description: Export GMenuModels on D-Bus
- * @see_also: #GMenuModel, #GDBusMenuModel
+ * g_application_command_line_printerr:
+ * @cmdline: a #GApplicationCommandLine
+ * @format: a printf-style format string
+ * @...: arguments, as per @format
*
- * These functions support exporting a #GMenuModel on D-Bus.
- * The D-Bus interface that is used is a private implementation
- * detail.
+ * Formats a message and prints it using the stderr print handler in the
+ * invoking process.
*
- * To access an exported #GMenuModel remotely, use
- * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
+ * If @cmdline is a local invocation then this is exactly equivalent to
+ * g_printerr(). If @cmdline is remote then this is equivalent to
+ * calling g_printerr() in the invoking process.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gmenumarkup
- * @title: GMenu Markup
- * @short_description: parsing and printing GMenuModel XML
+ * g_application_command_line_set_exit_status:
+ * @cmdline: a #GApplicationCommandLine
+ * @exit_status: the exit status
*
- * The functions here allow to instantiate #GMenuModels by parsing
- * fragments of an XML document.
- * * The XML format for #GMenuModel consists of a toplevel
- * <tag class="starttag">menu</tag> element, which contains one or more
- * <tag class="starttag">item</tag> elements. Each <tag class="starttag">item</tag>
- * element contains <tag class="starttag">attribute</tag> and <tag class="starttag">link</tag>
- * elements with a mandatory name attribute.
- * <tag class="starttag">link</tag> elements have the same content
- * model as <tag class="starttag">menu</tag>.
+ * Sets the exit status that will be used when the invoking process
+ * exits.
*
- * Here is the XML for <xref linkend="menu-example"/>:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/menumarkup2.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ * The return value of the #GApplication::command-line signal is
+ * passed to this function when the handler returns. This is the usual
+ * way of setting the exit status.
*
- * The parser also understands a somewhat less verbose format, in which
- * attributes are encoded as actual XML attributes of <tag class="starttag">item</tag>
- * elements, and <tag class="starttag">link</tag> elements are replaced by
- * <tag class="starttag">section</tag> and <tag class="starttag">submenu</tag> elements.
+ * In the event that you want the remote invocation to continue running
+ * and want to decide on the exit status in the future, you can use this
+ * call. For the case of a remote invocation, the remote process will
+ * typically exit when the last reference is dropped on @cmdline. The
+ * exit status of the remote process will be equal to the last value
+ * that was set with this function.
*
- * Here is how the example looks in this format:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/menumarkup.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ * In the case that the commandline invocation is local, the situation
+ * is slightly more complicated. If the commandline invocation results
+ * in the mainloop running (ie: because the use-count of the application
+ * increased to a non-zero value) then the application is considered to
+ * have been 'successful' in a certain sense, and the exit status is
+ * always zero. If the application use count is zero, though, the exit
+ * status of the local #GApplicationCommandLine is used.
*
- * The parser can obtaing translations for attribute values using gettext.
- * To make use of this, the <tag class="starttag">menu</tag> element must
- * have a domain attribute which specifies the gettext domain to use, and
- * <tag class="starttag">attribute</tag> elements can be marked for translation
- * with a <literal>translatable="yes"</literal> attribute. It is also possible
- * to specify message context and translator comments, using the context
- * and comments attributes.
+ * Since: 2.28
+ */
+
+
+/**
+ * g_application_get_application_id:
+ * @application: a #GApplication
*
- * The following DTD describes the XML format approximately:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/menumarkup.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ * Gets the unique identifier for @application.
*
- * To serialize a #GMenuModel into an XML fragment, use
- * g_menu_markup_print_string().
+ * Returns: the identifier for @application, owned by @application
+ * Since: 2.28
*/
/**
- * SECTION:gmenumodel
- * @title: GMenuModel
- * @short_description: An abstract class representing the contents of a menu
- * @see_also: #GActionGroup
+ * g_application_get_dbus_connection:
+ * @application: a #GApplication
*
- * #GMenuModel represents the contents of a menu -- an ordered list of
- * menu items. The items are associated with actions, which can be
- * activated through them. Items can be grouped in sections, and may
- * have submenus associated with them. Both items and sections usually
- * have some representation data, such as labels or icons. The type of
- * the associated action (ie whether it is stateful, and what kind of
- * state it has) can influence the representation of the item.
+ * Gets the #GDBusConnection being used by the application, or %NULL.
*
- * The conceptual model of menus in #GMenuModel is hierarchical:
- * sections and submenus are again represented by #GMenuModels.
- * Menus themselves do not define their own roles. Rather, the role
- * of a particular #GMenuModel is defined by the item that references
- * it (or, in the case of the 'root' menu, is defined by the context
- * in which it is used).
+ * If #GApplication is using its D-Bus backend then this function will
+ * return the #GDBusConnection being used for uniqueness and
+ * communication with the desktop environment and other instances of the
+ * application.
*
- * As an example, consider the visible portions of the menu in
- * <xref linkend="menu-example"/>.
+ * If #GApplication is not using D-Bus then this function will return
+ * %NULL. This includes the situation where the D-Bus backend would
+ * normally be in use but we were unable to connect to the bus.
*
- * <figure id="menu-example">
- * <title>An example menu</title>
- * <graphic fileref="menu-example.png" format="PNG"></graphic>
- * </figure>
+ * This function must not be called before the application has been
+ * registered. See g_application_get_is_registered().
*
- * 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
- * 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.
+ * Returns: (transfer none): a #GDBusConnection, or %NULL
+ * Since: 2.34
+ */
+
+
+/**
+ * g_application_get_dbus_object_path:
+ * @application: a #GApplication
*
- * <figure id="menu-model">
- * <title>A menu model</title>
- * <graphic fileref="menu-model.png" format="PNG"></graphic>
- * </figure>
+ * Gets the D-Bus object path being used by the application, or %NULL.
*
- * Notice that the separators visible in <xref linkend="menu-example"/>
- * appear nowhere in <xref linkend="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,
- * a display system may show a section header instead of a separator.
+ * If #GApplication is using its D-Bus backend then this function will
+ * return the D-Bus object path that #GApplication is using. If the
+ * application is the primary instance then there is an object published
+ * at this path. If the application is not the primary instance then
+ * the result of this function is undefined.
*
- * The motivation for this abstract model of application controls is
- * that modern user interfaces tend to make these controls available
- * 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
- * #GDBusMenuModel.
+ * If #GApplication is not using D-Bus then this function will return
+ * %NULL. This includes the situation where the D-Bus backend would
+ * normally be in use but we were unable to connect to the bus.
*
- * The API of #GMenuModel is very generic, with iterators for the
- * attributes and links of an item, see g_menu_model_iterate_item_attributes()
- * and g_menu_model_iterate_item_links(). The 'standard' attributes and
- * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
- * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
- * and %G_MENU_LINK_SUBMENU.
+ * This function must not be called before the application has been
+ * registered. See g_application_get_is_registered().
*
- * Items in a #GMenuModel represent active controls if they refer to
- * an action that can get activated when the user interacts with the
- * menu item. The reference to the action is encoded by the string id
- * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
- * identifies an action in an action group. Which action group(s) provide
- * actions depends on the context in which the menu model is used.
- * E.g. when the model is exported as the application menu of a
- * #GtkApplication, actions can be application-wide or window-specific
- * (and thus come from two different action groups). By convention, the
- * application-wide actions have names that start with "app.", while the
- * names of window-specific actions start with "win.".
+ * Returns: the object path, or %NULL
+ * Since: 2.34
+ */
+
+
+/**
+ * g_application_get_default:
*
- * 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>
- * 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>
+ * Returns the default #GApplication instance for this process.
*
- * <formalpara><title>Boolean State</title>
- * <para>
- * 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>
+ * Normally there is only one #GApplication per process and it becomes
+ * the default when it is created. You can exercise more control over
+ * this by using g_application_set_default().
*
- * <formalpara><title>String Parameter and State</title>
- * <para>
- * 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>
+ * If there is no default application then %NULL is returned.
+ *
+ * Returns: (transfer none): the default application for this process, or %NULL
+ * Since: 2.32
*/
/**
- * SECTION:gmount
- * @short_description: Mount management
- * @include: gio/gio.h
- * @see_also: GVolume, GUnixMount
+ * g_application_get_flags:
+ * @application: a #GApplication
*
- * The #GMount interface represents user-visible mounts. Note, when
- * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
+ * Gets the flags for @application.
*
- * #GMount is a "mounted" filesystem that you can access. Mounted is in
- * quotes because it's not the same as a unix mount, it might be a gvfs
- * mount, but you can still access the files on it if you use GIO. Might or
- * might not be related to a volume object.
+ * See #GApplicationFlags.
*
- * Unmounting a #GMount instance is an asynchronous operation. For
- * more information about asynchronous operations, see #GAsyncReady
- * and #GSimpleAsyncReady. 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
- * #GAsyncReady structure will be passed to the callback. That
- * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
- * and the #GAsyncReady data to see if the operation was completed
- * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
- * is called, then it will be filled with any error information.
+ * Returns: the flags for @application
+ * Since: 2.28
*/
/**
- * SECTION:gmountoperation
- * @short_description: Object used for authentication and user interaction
- * @include: gio/gio.h
+ * g_application_get_inactivity_timeout:
+ * @application: a #GApplication
*
- * #GMountOperation provides a mechanism for interacting with the user.
- * It can be used for authenticating mountable operations, such as loop
- * mounting files, hard drive partitions or server locations. It can
- * also be used to ask the user questions or show a list of applications
- * preventing unmount or eject operations from completing.
+ * Gets the current inactivity timeout for the application.
*
- * Note that #GMountOperation is used for more than just #GMount
- * objects – for example it is also used in g_drive_start() and
- * g_drive_stop().
+ * This is the amount of time (in milliseconds) after the last call to
+ * g_application_release() before the application stops running.
*
- * Users should instantiate a subclass of this that implements all the
- * various callbacks to show the required dialogs, such as
- * #GtkMountOperation. If no user interaction is desired (for example
- * when automounting filesystems at login time), usually %NULL can be
- * passed, see each method taking a #GMountOperation for details.
+ * Returns: the timeout, in milliseconds
+ * Since: 2.28
*/
/**
- * SECTION:gnetworkaddress
- * @short_description: A GSocketConnectable for resolving hostnames
- * @include: gio/gio.h
+ * g_application_get_is_busy:
+ * @application: a #GApplication
*
- * #GNetworkAddress provides an easy way to resolve a hostname and
- * then attempt to connect to that host, handling the possibility of
- * multiple IP addresses and multiple address families.
+ * Gets the application's current busy state, as set through
+ * g_application_mark_busy() or g_application_bind_busy_property().
*
- * See #GSocketConnectable for and example of using the connectable
- * interface.
+ * Returns: %TRUE if @application is currenty marked as busy
+ * Since: 2.44
*/
/**
- * SECTION:gnetworkmonitor
- * @title: GNetworkMonitor
- * @short_description: Network status monitor
- * @include: gio/gio.h
+ * g_application_get_is_registered:
+ * @application: a #GApplication
+ *
+ * Checks if @application is registered.
*
+ * An application is registered if g_application_register() has been
+ * successfully called.
*
+ * Returns: %TRUE if @application is registered
+ * Since: 2.28
*/
/**
- * SECTION:gnetworkservice
- * @short_description: A GSocketConnectable for resolving SRV records
- * @include: gio/gio.h
+ * g_application_get_is_remote:
+ * @application: a #GApplication
*
- * Like #GNetworkAddress does with hostnames, #GNetworkService
- * provides an easy way to resolve a SRV record, and then attempt to
- * connect to one of the hosts that implements that service, handling
- * service priority/weighting, multiple IP addresses, and multiple
- * address families.
+ * Checks if @application is remote.
+ *
+ * If @application is remote then it means that another instance of
+ * application already exists (the 'primary' instance). Calls to
+ * perform actions on @application will result in the actions being
+ * performed by the primary instance.
+ *
+ * The value of this property cannot be accessed before
+ * g_application_register() has been called. See
+ * g_application_get_is_registered().
*
- * See #GSrvTarget for more information about SRV records, and see
- * #GSocketConnectable for and example of using the connectable
- * interface.
+ * Returns: %TRUE if @application is remote
+ * Since: 2.28
*/
/**
- * SECTION:goutputstream
- * @short_description: Base class for implementing streaming output
- * @include: gio/gio.h
+ * g_application_get_resource_base_path:
+ * @application: a #GApplication
*
- * GOutputStream has functions to write to a stream (g_output_stream_write()),
- * to close a stream (g_output_stream_close()) and to flush pending writes
- * (g_output_stream_flush()).
+ * Gets the resource base path of @application.
*
- * To copy the content of an input stream to an output stream without
- * manually handling the reads and writes, use g_output_stream_splice().
+ * See g_application_set_resource_base_path() for more information.
*
- * All of these functions have async variants too.
+ * Returns: (nullable): the base resource path, if one is set
+ * Since: 2.42
*/
/**
- * SECTION:gpermission
- * @title: GPermission
- * @short_description: An object representing the permission to perform a certain action
- *
- * A #GPermission represents the status of the caller's permission to
- * perform a certain action.
+ * g_application_hold:
+ * @application: a #GApplication
*
- * You can query if the action is currently allowed and if it is
- * possible to acquire the permission so that the action will be allowed
- * in the future.
+ * Increases the use count of @application.
*
- * There is also an API to actually acquire the permission and one to
- * release it.
+ * Use this function to indicate that the application has a reason to
+ * continue to run. For example, g_application_hold() is called by GTK+
+ * when a toplevel window is on the screen.
*
- * As an example, a #GPermission might represent the ability for the
- * user to write to a #GSettings object. This #GPermission object could
- * then be used to decide if it is appropriate to show a "Click here to
- * unlock" button in a dialog and to provide the mechanism to invoke
- * when that button is clicked.
+ * To cancel the hold, call g_application_release().
*/
/**
- * SECTION:gpollableinputstream
- * @short_description: Interface for pollable input streams
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
+ * g_application_id_is_valid:
+ * @application_id: a potential application identifier
*
- * #GPollableInputStream is implemented by #GInputStream<!-- -->s 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.
+ * Checks if @application_id is a valid application identifier.
*
- * Since: 2.28
- */
-
-
-/**
- * SECTION:gpollableoutputstream
- * @short_description: Interface for pollable output streams
- * @include: gio/gio.h
- * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
+ * A valid ID is required for calls to g_application_new() and
+ * g_application_set_application_id().
*
- * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s 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.
+ * For convenience, the restrictions on application identifiers are
+ * reproduced here:
*
- * Since: 2.28
+ * - 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
*/
/**
- * SECTION:gproxy
- * @short_description: Interface for proxy handling
+ * g_application_mark_busy:
+ * @application: a #GApplication
*
- * A #GProxy handles connecting to a remote host via a given type of
- * proxy server. It is implemented by the 'gio-proxy' extension point.
- * The extensions are named after their proxy protocol name. As an
- * example, a SOCKS5 proxy implementation can be retrieved with the
- * name 'socks5' using the function
- * g_io_extension_point_get_extension_by_name().
+ * Increases the busy count of @application.
*
- * Since: 2.26
+ * 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
*/
/**
- * SECTION:gproxyaddress
- * @short_description: An internet address with proxy information
+ * g_application_new:
+ * @application_id: (allow-none): the application id
+ * @flags: the application flags
*
- * Support for proxied #GInetSocketAddress.
+ * Creates a new #GApplication instance.
+ *
+ * If non-%NULL, the application id must be valid. See
+ * g_application_id_is_valid().
+ *
+ * If no application ID is given then some features of #GApplication
+ * (most notably application uniqueness) will be disabled.
+ *
+ * Returns: a new #GApplication instance
*/
/**
- * SECTION:gproxyresolver
- * @short_description: Asynchronous and cancellable network proxy resolver
- * @include: gio/gio.h
+ * g_application_open:
+ * @application: a #GApplication
+ * @files: (array length=n_files): an array of #GFiles to open
+ * @n_files: the length of the @files array
+ * @hint: a hint (or ""), but never %NULL
*
- * #GProxyResolver provides synchronous and asynchronous network proxy
- * resolution. #GProxyResolver is used within #GSocketClient through
- * the method g_socket_connectable_proxy_enumerate().
+ * Opens the given files.
+ *
+ * In essence, this results in the #GApplication::open signal being emitted
+ * in the primary instance.
+ *
+ * @n_files must be greater than zero.
+ *
+ * @hint is simply passed through to the ::open signal. It is
+ * intended to be used by applications that have multiple modes for
+ * opening files (eg: "view" vs "edit", etc). Unless you have a need
+ * for this functionality, you should use "".
+ *
+ * The application must be registered before calling this function
+ * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gremoteactiongroup
- * @title: GRemoteActionGroup
- * @short_description: a #GActionGroup that interacts with other processes
+ * g_application_quit:
+ * @application: a #GApplication
*
- * 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.
+ * Immediately quits the application.
*
- * The interface has <literal>_full</literal> 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
- * "platform data" #GVariant to be specified: a dictionary providing
- * context for the action invocation (for example: timestamps, startup
- * notification IDs, etc).
+ * Upon return to the mainloop, g_application_run() will return,
+ * calling only the 'shutdown' function before doing so.
*
- * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
- * mechanism to send platform data for action invocations over D-Bus.
+ * The hold count is ignored.
*
- * 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
- * provides a mechanism by which to receive platform data for action
- * invocations that arrive by way of D-Bus.
+ * The result of calling g_application_run() again after it returns is
+ * unspecified.
*
* Since: 2.32
*/
/**
- * SECTION:gresolver
- * @short_description: Asynchronous and cancellable DNS resolver
- * @include: gio/gio.h
+ * g_application_register:
+ * @application: a #GApplication
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a pointer to a NULL #GError, or %NULL
*
- * #GResolver provides cancellable synchronous and asynchronous DNS
- * resolution, for hostnames (g_resolver_lookup_by_address(),
- * g_resolver_lookup_by_name() and their async variants) and SRV
- * (service) records (g_resolver_lookup_service()).
+ * Attempts registration of the application.
*
- * #GNetworkAddress and #GNetworkService provide wrappers around
- * #GResolver functionality that also implement #GSocketConnectable,
- * making it easy to connect to a remote host/service.
+ * This is the point at which the application discovers if it is the
+ * primary instance or merely acting as a remote for an already-existing
+ * primary instance. This is implemented by attempting to acquire the
+ * application identifier as a unique bus name on the session bus using
+ * GDBus.
+ *
+ * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was
+ * given, then this process will always become the primary instance.
+ *
+ * Due to the internal architecture of GDBus, method calls can be
+ * dispatched at any time (even if a main loop is not running). For
+ * this reason, you must ensure that any object paths that you wish to
+ * register are registered before calling this function.
+ *
+ * If the application has already been registered then %TRUE is
+ * returned with no work performed.
+ *
+ * The #GApplication::startup signal is emitted if registration succeeds
+ * and @application is the primary instance (including the non-unique
+ * case).
+ *
+ * In the event of an error (such as @cancellable being cancelled, or a
+ * failure to connect to the session bus), %FALSE is returned and @error
+ * is set appropriately.
+ *
+ * Note: the return value of this function is not an indicator that this
+ * instance is or is not the primary instance of the application. See
+ * g_application_get_is_remote() for that.
+ *
+ * Returns: %TRUE if registration succeeded
+ * Since: 2.28
*/
/**
- * SECTION:gseekable
- * @short_description: Stream seeking interface
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
+ * g_application_release:
+ * @application: a #GApplication
*
- * #GSeekable is implemented by streams (implementations of
- * #GInputStream or #GOutputStream) that support seeking.
+ * Decrease the use count of @application.
+ *
+ * When the use count reaches zero, the application will stop running.
+ *
+ * Never call this function except to cancel the effect of a previous
+ * call to g_application_hold().
*/
/**
- * SECTION:gsettings
- * @short_description: High-level API for application settings
+ * g_application_run:
+ * @application: a #GApplication
+ * @argc: the argc from main() (or 0 if @argv is %NULL)
+ * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
*
- * The #GSettings class provides a convenient API for storing and retrieving
- * application settings.
+ * Runs the application.
*
- * Reads and writes can be considered to be non-blocking. Reading
- * settings with #GSettings is typically extremely fast: on
- * approximately the same order of magnitude (but slower than) a
- * #GHashTable lookup. Writing settings is also extremely fast in terms
- * of time to return to your application, but can be extremely expensive
- * for other threads and other processes. Many settings backends
- * (including dconf) have lazy initialisation which means in the common
- * case of the user using their computer without modifying any settings
- * a lot of work can be avoided. For dconf, the D-Bus service doesn't
- * even need to be started in this case. For this reason, you should
- * only ever modify #GSettings keys in response to explicit user action.
- * Particular care should be paid to ensure that modifications are not
- * made during startup -- for example, when setting the initial value
- * of preferences widgets. The built-in g_settings_bind() functionality
- * is careful not to write settings in response to notify signals as a
- * result of modifications that it makes to widgets.
+ * This function is intended to be run from main() and its return value
+ * 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. 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.
*
- * When creating a GSettings instance, you have to specify a schema
- * that describes the keys in your settings and their types and default
- * values, as well as some other information.
+ * 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
+ * [gapplication-example-cmdline2.c][gapplication-example-cmdline2]
+ * for an example.
*
- * Normally, a schema has as fixed path that determines where the settings
- * are stored in the conceptual global tree of settings. However, schemas
- * can also be 'relocatable', i.e. not equipped with a fixed path. This is
- * useful e.g. when the schema describes an 'account', and you want to be
- * able to store a arbitrary number of accounts.
+ * 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.
*
- * Unlike other configuration systems (like GConf), GSettings does not
- * restrict keys to basic types like strings and numbers. GSettings stores
- * values as #GVariant, and allows any #GVariantType for keys. Key names
- * are restricted to lowercase characters, numbers and '-'. Furthermore,
- * the names must begin with a lowercase character, must not end
- * with a '-', and must not contain consecutive dashes.
+ * 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.
*
- * 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.
+ * 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
*
- * 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[
- * <schemalist>
- * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
+ * 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.
*
- * <key name="greeting" type="s">
- * <default l10n="messages">"Hello, earthlings"</default>
- * <summary>A greeting</summary>
- * <description>
- * Greeting of the invading martians
- * </description>
- * </key>
+ * Notifications may persist after the application exits. It will be
+ * D-Bus-activated when the notification or one of its actions is
+ * activated.
*
- * <key name="box" type="(ii)">
- * <default>(20,30)</default>
- * </key>
+ * Modifying @notification after this call has no effect. However, the
+ * object can be reused for a later call to this function.
*
- * </schema>
- * </schemalist>
- * ]]></programlisting></example>
+ * @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.
*
- * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
- * <programlisting><![CDATA[
- * <schemalist>
+ * 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.
*
- * <enum id="org.gtk.Test.myenum">
- * <value nick="first" value="1"/>
- * <value nick="second" value="2"/>
- * </enum>
- *
- * <flags id="org.gtk.Test.myflags">
- * <value nick="flag1" value="1"/>
- * <value nick="flag2" value="2"/>
- * <value nick="flag3" value="4"/>
- * </flags>
- *
- * <schema id="org.gtk.Test">
- *
- * <key name="key-with-range" type="i">
- * <range min="1" max="100"/>
- * <default>10</default>
- * </key>
- *
- * <key name="key-with-choices" type="s">
- * <choices>
- * <choice value='Elisabeth'/>
- * <choice value='Annabeth'/>
- * <choice value='Joe'/>
- * </choices>
- * <aliases>
- * <alias value='Anna' target='Annabeth'/>
- * <alias value='Beth' target='Elisabeth'/>
- * </aliases>
- * <default>'Joe'</default>
- * </key>
- *
- * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
- * <default>'first'</default>
- * </key>
- *
- * <key name='flags-key' flags='org.gtk.Test.myflags'>
- * <default>["flag1",flag2"]</default>
- * </key>
- * </schema>
- * </schemalist>
- * ]]></programlisting></example>
+ * @id may be %NULL, but it is impossible to replace or withdraw
+ * notifications without an id.
*
- * <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>
- * [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>
+ * If @notification is no longer relevant, it can be withdrawn with
+ * g_application_withdraw_notification().
*
- * <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>
+ * Since: 2.40
*/
/**
- * SECTION:gsettingsbackend
- * @title: GSettingsBackend
- * @short_description: Interface for settings backend implementations
- * @include: gio/gsettingsbackend.h
- * @see_also: #GSettings, #GIOExtensionPoint
- *
- * The #GSettingsBackend interface defines a generic interface for
- * non-strictly-typed data that is stored in a hierarchy. To implement
- * an alternative storage backend for #GSettings, you need to implement
- * the #GSettingsBackend interface and then make it implement the
- * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
- *
- * The interface defines methods for reading and writing values, a
- * method for determining if writing of certain values will fail
- * (lockdown) and a change notification mechanism.
- *
- * The semantics of the interface are very precisely defined and
- * implementations must carefully adhere to the expectations of
- * callers that are documented on each of the interface methods.
+ * g_application_set_action_group:
+ * @application: a #GApplication
+ * @action_group: (allow-none): a #GActionGroup, or %NULL
*
- * Some of the GSettingsBackend functions accept or return a #GTree.
- * These trees always have strings as keys and #GVariant as values.
- * g_settings_backend_create_tree() is a convenience function to create
- * suitable trees.
+ * This used to be how actions were associated with a #GApplication.
+ * Now there is #GActionMap for that.
*
- * <note><para>
- * 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>
+ * 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.
*/
/**
- * SECTION:gsettingsschema
- * @short_description: introspecting and controlling the loading of #GSettings schemas
+ * g_application_set_application_id:
+ * @application: a #GApplication
+ * @application_id: (allow-none): the identifier for @application
*
- * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
- * mechanism for advanced control over the loading of schemas and a
- * mechanism for introspecting their content.
+ * Sets the unique identifier for @application.
*
- * Plugin loading systems that wish to provide plugins a way to access
- * settings face the problem of how to make the schemas for these
- * settings visible to GSettings. Typically, a plugin will want to ship
- * the schema along with itself and it won't be installed into the
- * standard system directories for schemas.
+ * The application id can only be modified if @application has not yet
+ * been registered.
*
- * #GSettingsSchemaSource provides a mechanism for dealing with this by
- * allowing the creation of a new 'schema source' from which schemas can
- * be acquired. This schema source can then become part of the metadata
- * associated with the plugin and queried whenever the plugin requires
- * access to some settings.
+ * If non-%NULL, the application id must be valid. See
+ * g_application_id_is_valid().
*
- * Consider the following example:
+ * Since: 2.28
+ */
+
+
+/**
+ * g_application_set_default:
+ * @application: (allow-none): the application to set as default, or %NULL
*
- * |[
- * typedef struct
- * {
- * ...
- * GSettingsSchemaSource *schema_source;
- * ...
- * } Plugin;
+ * Sets or unsets the default application for the process, as returned
+ * by g_application_get_default().
*
- * Plugin *
- * initialise_plugin (const gchar *dir)
- * {
- * Plugin *plugin;
+ * This function does not take its own reference on @application. If
+ * @application is destroyed then the default application will revert
+ * back to %NULL.
*
- * ...
+ * Since: 2.32
+ */
+
+
+/**
+ * g_application_set_flags:
+ * @application: a #GApplication
+ * @flags: the flags for @application
*
- * plugin->schema_source =
- * g_settings_new_schema_source_from_directory (dir,
- * g_settings_schema_source_get_default (), FALSE, NULL);
+ * Sets the flags for @application.
*
- * ...
+ * The flags can only be modified if @application has not yet been
+ * registered.
*
- * return plugin;
- * }
+ * See #GApplicationFlags.
*
- * ...
+ * Since: 2.28
+ */
+
+
+/**
+ * g_application_set_inactivity_timeout:
+ * @application: a #GApplication
+ * @inactivity_timeout: the timeout, in milliseconds
*
- * GSettings *
- * plugin_get_settings (Plugin *plugin,
- * const gchar *schema_id)
- * {
- * GSettingsSchema *schema;
+ * Sets the current inactivity timeout for the application.
*
- * if (schema_id == NULL)
- * schema_id = plugin->identifier;
+ * This is the amount of time (in milliseconds) after the last call to
+ * g_application_release() before the application stops running.
*
- * schema = g_settings_schema_source_lookup (plugin->schema_source,
- * schema_id, FALSE);
+ * This call has no side effects of its own. The value set here is only
+ * used for next time g_application_release() drops the use count to
+ * zero. Any timeouts currently in progress are not impacted.
*
- * if (schema == NULL)
- * {
- * ... disable the plugin or abort, etc ...
- * }
+ * Since: 2.28
+ */
+
+
+/**
+ * g_application_set_resource_base_path:
+ * @application: a #GApplication
+ * @resource_path: (nullable): the resource path to use
*
- * return g_settings_new_full (schema, NULL, NULL);
- * }
- * ]|
+ * Sets (or unsets) the base resource path of @application.
*
- * The code above shows how hooks should be added to the code that
- * initialises (or enables) the plugin to create the schema source and
- * how an API can be added to the plugin system to provide a convenient
- * way for the plugin to access its settings, using the schemas that it
- * ships.
+ * 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.
*
- * From the standpoint of the plugin, it would need to ensure that it
- * ships a gschemas.compiled file as part of itself, and then simply do
- * the following:
+ * 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.
*
- * |[
- * {
- * GSettings *settings;
- * gint some_value;
+ * 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".
*
- * settings = plugin_get_settings (self, NULL);
- * some_value = g_settings_get_int (settings, "some-value");
- * ...
- * }
- * ]|
+ * See #GResource for more information about adding resources to your
+ * application.
*
- * It's also possible that the plugin system expects the schema source
- * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
- * In that case, the plugin loading system must compile the schemas for
- * itself before attempting to create the settings source.
+ * You can disable automatic resource loading functionality by setting
+ * the path to %NULL.
*
- * Since: 2.32
+ * 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
*/
/**
- * SECTION:gsimpleaction
- * @title: GSimpleAction
- * @short_description: A simple GAction implementation
+ * g_application_unbind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
*
- * A #GSimpleAction is the obvious simple implementation of the #GAction
- * interface. This is the easiest way to create an action for purposes of
- * adding it to a #GSimpleActionGroup.
+ * Destroys a binding between @property and the busy state of
+ * @application that was previously created with
+ * g_application_bind_busy_property().
*
- * See also #GtkAction.
+ * Since: 2.44
*/
/**
- * SECTION:gsimpleactiongroup
- * @title: GSimpleActionGroup
- * @short_description: A simple GActionGroup implementation
+ * g_application_unmark_busy:
+ * @application: a #GApplication
*
- * #GSimpleActionGroup is a hash table filled with #GAction objects,
- * implementing the #GActionGroup and #GActionMap interfaces.
+ * 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
*/
/**
- * SECTION:gsimpleasyncresult
- * @short_description: Simple asynchronous results implementation
- * @include: gio/gio.h
- * @see_also: #GAsyncResult
- *
- * 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.
- *
- * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, 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
- * asynchronously, a boolean value for checking the success or failure
- * of an operation, or a #gssize for operations which return the number
- * of bytes modified by the operation; all of the simple return cases
- * are covered.
- *
- * Most of the time, an application will not need to know of the details
- * of this API; it is handled transparently, and any necessary operations
- * are handled by #GAsyncResult's interface. However, if implementing a
- * new GIO module, for writing language bindings, or for complex
- * applications that need better control of how asynchronous operations
- * are completed, it is important to understand this functionality.
- *
- * GSimpleAsyncResults are tagged with the calling function to ensure
- * that asynchronous functions and their finishing functions are used
- * together correctly.
- *
- * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
- * If the result needs to be created for a #GError, use
- * g_simple_async_result_new_from_error() or
- * g_simple_async_result_new_take_error(). If a #GError is not available
- * (e.g. the asynchronous operation's doesn't take a #GError argument),
- * but the result still needs to be created for an error condition, use
- * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
- * if your application or binding requires passing a variable argument list
- * directly), and the error can then be propagated through the use of
- * g_simple_async_result_propagate_error().
- *
- * An asynchronous operation can be made to ignore a cancellation event by
- * calling g_simple_async_result_set_handle_cancellation() with a
- * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
- * operations that are dangerous to cancel, such as close (which would
- * cause a leak if cancelled before being run).
- *
- * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
- * or it can use #GThread<!-- -->s.
- * 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
- * job in a separate thread and then deliver the result to the
- * thread-default main context.
- *
- * To set the results of an asynchronous function,
- * g_simple_async_result_set_op_res_gpointer(),
- * g_simple_async_result_set_op_res_gboolean(), and
- * g_simple_async_result_set_op_res_gssize()
- * are provided, setting the operation's result to a gpointer, gboolean, or
- * gssize, respectively.
- *
- * Likewise, to get the result of an asynchronous function,
- * g_simple_async_result_get_op_res_gpointer(),
- * g_simple_async_result_get_op_res_gboolean(), and
- * g_simple_async_result_get_op_res_gssize() are
- * provided, getting the operation's result as a gpointer, gboolean, and
- * gssize, respectively.
+ * g_application_withdraw_notification:
+ * @application: a #GApplication
+ * @id: id of a previously sent notification
*
- * For the details of the requirements implementations must respect, see
- * #GAsyncResult. A typical implementation of an asynchronous operation
- * using GSimpleAsyncResult looks something like this:
+ * Withdraws a notification that was sent with
+ * g_application_send_notification().
*
- * |[
- * 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.
- * */
- * GSimpleAsyncResult *result = user_data;
- *
- * if (cake == NULL)
- * g_simple_async_result_set_error (result,
- * BAKER_ERRORS,
- * BAKER_ERROR_NO_FLOUR,
- * "Go to the supermarket");
- * else
- * g_simple_async_result_set_op_res_gpointer (result,
- * g_object_ref (cake),
- * 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().
- * */
- * g_simple_async_result_complete (result);
- * g_object_unref (result);
- * }
+ * This call does nothing if a notification with @id doesn't exist or
+ * the notification was never sent.
*
- * void
- * baker_bake_cake_async (Baker *self,
- * guint radius,
- * GAsyncReadyCallback callback,
- * gpointer user_data)
- * {
- * GSimpleAsyncResult *simple;
- * Cake *cake;
+ * 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.
*
- * if (radius < 3)
- * {
- * g_simple_async_report_error_in_idle (G_OBJECT (self),
- * callback,
- * user_data,
- * BAKER_ERRORS,
- * BAKER_ERROR_TOO_SMALL,
- * "%ucm radius cakes are silly",
- * radius);
- * return;
- * }
+ * 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.
*
- * simple = g_simple_async_result_new (G_OBJECT (self),
- * callback,
- * user_data,
- * baker_bake_cake_async);
- * cake = _baker_get_cached_cake (self, radius);
+ * Since: 2.40
+ */
+
+
+/**
+ * g_async_initable_init_async:
+ * @initable: a #GAsyncInitable.
+ * @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
*
- * if (cake != NULL)
- * {
- * g_simple_async_result_set_op_res_gpointer (simple,
- * g_object_ref (cake),
- * 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.
- * */
- * g_object_unref (cake);
- * return;
- * }
+ * Starts asynchronous initialization of the object implementing the
+ * interface. This must be done before any real use of the object after
+ * initial construction. If the object also implements #GInitable you can
+ * optionally call g_initable_init() instead.
*
- * _baker_prepare_cake (self, radius, baked_cb, simple);
- * }
+ * When the initialization is finished, @callback will be called. You can
+ * then call g_async_initable_init_finish() to get the result of the
+ * initialization.
*
- * Cake *
- * baker_bake_cake_finish (Baker *self,
- * GAsyncResult *result,
- * GError **error)
- * {
- * GSimpleAsyncResult *simple;
- * Cake *cake;
+ * Implementations may also support cancellation. If @cancellable is not
+ * %NULL, then initialization 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, and
+ * the object doesn't support cancellable initialization, the error
+ * %G_IO_ERROR_NOT_SUPPORTED will be returned.
*
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (self),
- * baker_bake_cake_async),
- * NULL);
+ * As with #GInitable, 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. They will often fail with g_critical() or
+ * g_warning(), but this must not be relied on.
*
- * simple = (GSimpleAsyncResult *) result;
+ * Implementations of this method must be idempotent: i.e. multiple calls
+ * to this function with the same argument should return the same results.
+ * Only the first call initializes the object; further calls return the result
+ * of the first call. This is so that it's safe to implement the singleton
+ * pattern in the GObject constructor function.
*
- * if (g_simple_async_result_propagate_error (simple, error))
- * return NULL;
+ * For classes that also support the #GInitable interface, the default
+ * implementation of this method will run the g_initable_init() function
+ * in a thread, so if you want to support asynchronous initialization via
+ * threads, just implement the #GAsyncInitable interface without overriding
+ * any interface methods.
*
- * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
- * return g_object_ref (cake);
- * }
- * ]|
+ * Since: 2.22
*/
/**
- * SECTION:gsimplepermission
- * @title: GSimplePermission
- * @short_description: A GPermission that doesn't change value
+ * g_async_initable_init_finish:
+ * @initable: a #GAsyncInitable.
+ * @res: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * #GSimplePermission is a trivial implementation of #GPermission that
- * represents a permission that is either always or never allowed. The
- * value is given at construction and doesn't change.
+ * Finishes asynchronous initialization and returns the result.
+ * See g_async_initable_init_async().
*
- * Calling request or release will result in errors.
+ * Returns: %TRUE if successful. If an error has occurred, this function
+ * will return %FALSE and set @error appropriately if present.
+ * Since: 2.22
*/
/**
- * SECTION:gsocket
- * @short_description: Low-level socket object
- * @include: gio/gio.h
- * @see_also: #GInitable
- *
- * 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.
- * It supports both the UNIX socket implementations and winsock2 on Windows.
+ * g_async_initable_new_async:
+ * @object_type: a #GType supporting #GAsyncInitable.
+ * @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
+ * @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.
*
- * #GSocket is the platform independent base upon which the higher level
- * network primitives are based. Applications are not typically meant to
- * use it directly, but rather through classes like #GSocketClient,
- * #GSocketService and #GSocketConnection. However there may be cases where
- * direct use of #GSocket is useful.
+ * Helper function for constructing #GAsyncInitable object. This is
+ * similar to g_object_new() but also initializes the object asynchronously.
*
- * #GSocket implements the #GInitable interface, so if it is manually constructed
- * by e.g. g_object_new() you must call g_initable_init() and check the
- * results before using the object. This is done automatically in
- * g_socket_new() and g_socket_new_from_fd(), so these functions can return
- * %NULL.
+ * When the initialization is finished, @callback will be called. You can
+ * then call g_async_initable_new_finish() to get the new object and check
+ * for any errors.
*
- * Sockets operate in two general modes, blocking or non-blocking. When
- * in blocking mode all operations block until the requested operation
- * is finished or there is an error. In non-blocking mode all calls that
- * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
- * To know when a call would successfully run you can call g_socket_condition_check(),
- * or g_socket_condition_wait(). You can also use g_socket_create_source() and
- * attach it to a #GMainContext to get callbacks when I/O is possible.
- * Note that all sockets are always set to non blocking mode in the system, and
- * blocking mode is emulated in GSocket.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_async_initable_new_finish:
+ * @initable: the #GAsyncInitable from the callback
+ * @res: the #GAsyncResult from the callback
+ * @error: return location for errors, or %NULL to ignore
*
- * When working in non-blocking mode applications should always be able to
- * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
- * function said that I/O was possible. This can easily happen in case
- * of a race condition in the application, but it can also happen for other
- * reasons. For instance, on Windows a socket is always seen as writable
- * until a write returns %G_IO_ERROR_WOULD_BLOCK.
+ * Finishes the async construction for the various g_async_initable_new
+ * calls, returning the created object or %NULL on error.
*
- * #GSocket<!-- -->s 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
- * specified or received in each I/O operation.
+ * 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.
+ * @var_args: The var args list generated from @first_property_name.
+ * @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
+ * @user_data: the data to pass to callback function
*
- * All socket file descriptors are set to be close-on-exec.
+ * Helper function for constructing #GAsyncInitable object. This is
+ * similar to g_object_new_valist() but also initializes the object
+ * asynchronously.
*
- * Note that creating a #GSocket causes the signal %SIGPIPE to be
- * ignored for the remainder of the program. If you are writing a
- * command-line utility that uses #GSocket, you may need to take into
- * account the fact that your program will not automatically be killed
- * if it tries to write to %stdout after it has been closed.
+ * When the initialization is finished, @callback will be called. You can
+ * then call g_async_initable_new_finish() to get the new object and check
+ * for any errors.
*
* Since: 2.22
*/
/**
- * SECTION:gsocketaddress
- * @short_description: Abstract base class representing endpoints for socket communication
+ * g_async_initable_newv_async:
+ * @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 [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
+ * @user_data: the data to pass to callback function
*
- * #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.
+ * Helper function for constructing #GAsyncInitable object. This is
+ * similar to g_object_newv() but also initializes the object asynchronously.
+ *
+ * When the initialization is finished, @callback will be called. You can
+ * then call g_async_initable_new_finish() to get the new object and check
+ * for any errors.
+ *
+ * Since: 2.22
*/
/**
- * SECTION:gsocketclient
- * @short_description: Helper for connecting to a network service
- * @include: gio/gio.h
- * @see_also: #GSocketConnection, #GSocketListener
+ * g_async_result_get_source_object:
+ * @res: a #GAsyncResult
*
- * #GSocketClient is a high-level utility class for connecting to a
- * network host using a connection oriented socket type.
+ * Gets the source object from a #GAsyncResult.
*
- * You create a #GSocketClient object, set any options you want, and then
- * call a sync or async connect operation, which returns a #GSocketConnection
- * subclass on success.
+ * Returns: (transfer full): a new reference to the source object for the @res,
+ * or %NULL if there is none.
+ */
+
+
+/**
+ * g_async_result_get_user_data:
+ * @res: a #GAsyncResult.
*
- * The type of the #GSocketConnection object returned depends on the type of
- * the underlying socket that is in use. For instance, for a TCP/IP connection
- * it will be a #GTcpConnection.
+ * Gets the user data from a #GAsyncResult.
*
- * Since: 2.22
+ * Returns: (transfer full): the user data for @res.
*/
/**
- * SECTION:gsocketconnectable
- * @short_description: Interface for potential socket endpoints
- *
- * Objects that describe one or more potential socket endpoints
- * implement #GSocketConnectable. Callers can then use
- * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
- * to try out each socket address in turn until one succeeds, as shown
- * in the sample code below.
+ * g_async_result_is_tagged:
+ * @res: a #GAsyncResult
+ * @source_tag: an application-defined tag
*
- * |[
- * MyConnectionType *
- * connect_to_host (const char *hostname,
- * guint16 port,
- * GCancellable *cancellable,
- * GError **error)
- * {
- * MyConnection *conn = NULL;
- * GSocketConnectable *addr;
- * GSocketAddressEnumerator *enumerator;
- * GSocketAddress *sockaddr;
- * GError *conn_error = NULL;
- *
- * addr = g_network_address_new ("www.gnome.org", 80);
- * 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).
- * *<!-- -->/
- * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
- * {
- * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
- * g_object_unref (sockaddr);
- * }
- * g_object_unref (enumerator);
+ * Checks if @res has the given @source_tag (generally a function
+ * pointer indicating the function @res was created by).
*
- * if (conn)
- * {
- * if (conn_error)
- * {
- * /<!-- -->* 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.
- * *<!-- -->/
- * if (conn_error)
- * g_error_free (conn_error);
- * return NULL;
- * }
- * else
- * {
- * g_error_propagate (error, conn_error);
- * return NULL;
- * }
- * }
- * ]|
+ * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if
+ * not.
+ * Since: 2.34
*/
/**
- * SECTION:gsocketconnection
- * @short_description: A socket connection
- * @include: gio/gio.h
- * @see_also: #GIOStream, #GSocketClient, #GSocketListener
- *
- * #GSocketConnection is a #GIOStream for a connected socket. They
- * can be created either by #GSocketClient when connecting to a host,
- * or by #GSocketListener when accepting a new client.
+ * g_async_result_legacy_propagate_error:
+ * @res: a #GAsyncResult
+ * @error: (out): a location to propagate the error to.
*
- * The type of the #GSocketConnection object returned from these calls
- * depends on the type of the underlying socket that is in use. For
- * instance, for a TCP/IP connection it will be a #GTcpConnection.
+ * If @res is a #GSimpleAsyncResult, this is equivalent to
+ * g_simple_async_result_propagate_error(). Otherwise it returns
+ * %FALSE.
*
- * Choosing what type of object to construct is done with the socket
- * connection factory, and it is possible for 3rd parties to register
- * custom socket connection types for specific combination of socket
- * family/type/protocol using g_socket_connection_factory_register_type().
+ * 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.
*
- * Since: 2.22
+ * Returns: %TRUE if @error is has been filled in with an error from
+ * @res, %FALSE if not.
+ * Since: 2.34
*/
/**
- * SECTION:gsocketcontrolmessage
- * @title: GSocketControlMessage
- * @short_description: A GSocket control message
- * @see_also: #GSocket.
+ * g_buffered_input_stream_fill:
+ * @stream: a #GBufferedInputStream
+ * @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
*
- * A #GSocketControlMessage is a special-purpose utility message that
- * can be sent to or received from a #GSocket. These types of
- * messages are often called "ancillary data".
+ * Tries to read @count bytes from the stream into the buffer.
+ * Will block during this read.
*
- * 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
- * a UNIX socket).
+ * If @count is zero, returns zero and does nothing. A value of @count
+ * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
*
- * These messages are sent with g_socket_send_message() and received
- * with g_socket_receive_message().
+ * On success, the number of bytes read into the buffer is returned.
+ * It is not an error if this is not the same as the requested size, as it
+ * 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.
*
- * To extend the set of control message that can be sent, subclass this
- * class and override the get_size, get_level, get_type and serialize
- * methods.
+ * If @count is -1 then the attempted read size is equal to the number of
+ * bytes that are required to fill the buffer.
*
- * To extend the set of control messages that can be received, subclass
- * this class and implement the deserialize method. Also, make sure your
- * class is registered with the GType typesystem before calling
- * g_socket_receive_message() to read such a message.
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+ * operation was partially finished when the operation was cancelled the
+ * partial result will be returned, without an error.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * For the asynchronous, non-blocking, version of this function, see
+ * g_buffered_input_stream_fill_async().
*
- * Since: 2.22
+ * Returns: the number of bytes read into @stream's buffer, up to @count,
+ * or -1 on error.
*/
/**
- * SECTION:gsocketlistener
- * @title: GSocketListener
- * @short_description: Helper for accepting network client connections
- * @see_also: #GThreadedSocketService, #GSocketService.
- *
- * A #GSocketListener is an object that keeps track of a set
- * of server sockets and helps you accept sockets from any of the
- * socket, either sync or async.
+ * g_buffered_input_stream_fill_async:
+ * @stream: a #GBufferedInputStream
+ * @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
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): a #gpointer
*
- * If you want to implement a network server, also look at #GSocketService
- * and #GThreadedSocketService which are subclass of #GSocketListener
- * that makes this even easier.
+ * Reads data into @stream's buffer asynchronously, up to @count size.
+ * @io_priority can be used to prioritize reads. For the synchronous
+ * version of this function, see g_buffered_input_stream_fill().
*
- * Since: 2.22
+ * If @count is -1 then the attempted read size is equal to the number
+ * of bytes that are required to fill the buffer.
*/
/**
- * SECTION:gsocketservice
- * @title: GSocketService
- * @short_description: Make it easy to implement a network service
- * @see_also: #GThreadedSocketService, #GSocketListener.
+ * g_buffered_input_stream_fill_finish:
+ * @stream: a #GBufferedInputStream
+ * @result: a #GAsyncResult
+ * @error: a #GError
*
- * A #GSocketService is an object that represents a service that
- * is provided to the network or over local sockets. When a new
- * connection is made to the service the #GSocketService::incoming
- * signal is emitted.
+ * Finishes an asynchronous read.
*
- * A #GSocketService is a subclass of #GSocketListener and you need
- * to add the addresses you want to accept connections on with the
- * #GSocketListener APIs.
+ * Returns: a #gssize of the read stream, or %-1 on an error.
+ */
+
+
+/**
+ * g_buffered_input_stream_get_available:
+ * @stream: #GBufferedInputStream
*
- * There are two options for implementing a network service based on
- * #GSocketService. The first is to create the service using
- * g_socket_service_new() and to connect to the #GSocketService::incoming
- * signal. The second is to subclass #GSocketService and override the
- * default signal handler implementation.
+ * Gets the size of the available data within the stream.
*
- * In either case, the handler must immediately return, or else it
- * will block additional incoming connections from being serviced.
- * If you are interested in writing connection handlers that contain
- * blocking code then see #GThreadedSocketService.
+ * Returns: size of the available stream.
+ */
+
+
+/**
+ * g_buffered_input_stream_get_buffer_size:
+ * @stream: a #GBufferedInputStream
*
- * 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
- * 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.
+ * Gets the size of the input buffer.
*
- * Since: 2.22
+ * Returns: the current buffer size.
*/
/**
- * SECTION:gsrvtarget
- * @short_description: DNS SRV record target
- * @include: gio/gio.h
+ * g_buffered_input_stream_new:
+ * @base_stream: a #GInputStream
*
- * SRV (service) records are used by some network protocols to provide
- * service-specific aliasing and load-balancing. For example, XMPP
- * (Jabber) uses SRV records to locate the XMPP server for a domain;
- * rather than connecting directly to "example.com" or assuming a
- * specific server hostname like "xmpp.example.com", an XMPP client
- * would look up the "xmpp-client" SRV record for "example.com", and
- * then connect to whatever host was pointed to by that record.
+ * Creates a new #GInputStream from the given @base_stream, with
+ * a buffer set to the default size (4 kilobytes).
*
- * You can use g_resolver_lookup_service() or
- * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
- * 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
- * #GSrvTarget at all.
+ * Returns: a #GInputStream for the given @base_stream.
*/
/**
- * SECTION:gtcpconnection
- * @title: GTcpConnection
- * @short_description: A TCP GSocketConnection
- * @see_also: #GSocketConnection.
+ * g_buffered_input_stream_new_sized:
+ * @base_stream: a #GInputStream
+ * @size: a #gsize
*
- * This is the subclass of #GSocketConnection that is created
- * for TCP/IP sockets.
+ * Creates a new #GBufferedInputStream from the given @base_stream,
+ * with a buffer set to @size.
*
- * Since: 2.22
+ * Returns: a #GInputStream.
*/
/**
- * SECTION:gtcpwrapperconnection
- * @title: GTcpWrapperConnection
- * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
- * @see_also: #GSocketConnection.
+ * g_buffered_input_stream_peek:
+ * @stream: a #GBufferedInputStream
+ * @buffer: (array length=count) (element-type guint8): a pointer to
+ * an allocated chunk of memory
+ * @offset: a #gsize
+ * @count: a #gsize
*
- * 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
- * always return a #GSocketConnection, even when the connection it has
- * actually created is not directly a #GSocketConnection.
+ * Peeks in the buffer, copying data of size @count into @buffer,
+ * offset @offset bytes.
*
- * Since: 2.28
+ * Returns: a #gsize of the number of bytes peeked, or -1 on error.
*/
/**
- * SECTION:gthemedicon
- * @short_description: Icon theming support
- * @include: gio/gio.h
- * @see_also: #GIcon, #GLoadableIcon
+ * g_buffered_input_stream_peek_buffer:
+ * @stream: a #GBufferedInputStream
+ * @count: (out): a #gsize to get the number of bytes available in the buffer
*
- * #GThemedIcon is an implementation of #GIcon that supports icon themes.
- * #GThemedIcon contains a list of all of the icons present in an icon
- * theme, so that icons can be looked up quickly. #GThemedIcon does
- * not provide actual pixmaps for icons, just the icon names.
- * Ideally something like gtk_icon_theme_choose_icon() should be used to
- * resolve the list of names so that fallback icons work nicely with
- * themes that inherit other themes.
+ * Returns the buffer with the currently available bytes. The returned
+ * 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
*/
/**
- * SECTION:gthreadedsocketservice
- * @title: GThreadedSocketService
- * @short_description: A threaded GSocketService
- * @see_also: #GSocketService.
+ * g_buffered_input_stream_read_byte:
+ * @stream: a #GBufferedInputStream
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * A #GThreadedSocketService is a simple subclass of #GSocketService
- * that handles incoming connections by creating a worker thread and
- * dispatching the connection to it by emitting the
- * #GThreadedSocketService::run signal in the new thread.
+ * Tries to read a single byte from the stream or the buffer. Will block
+ * during this read.
*
- * The signal handler may perform blocking IO and need not return
- * until the connection is closed.
+ * On success, the byte read from the stream is returned. On end of stream
+ * -1 is returned but it's not an exceptional error and @error is not set.
*
- * The service is implemented using a thread pool, so there is a
- * limited amount of threads available to serve incoming requests.
- * The service automatically stops the #GSocketService from accepting
- * new connections when all threads are busy.
+ * 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.
*
- * As with #GSocketService, you may connect to #GThreadedSocketService::run,
- * or subclass and override the default handler.
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Returns: the byte read from the @stream, or -1 on end of stream or error.
*/
/**
- * SECTION:gtls
- * @title: TLS Overview
- * @short_description: TLS (aka SSL) support for GSocketConnection
- * @include: gio/gio.h
+ * g_buffered_input_stream_set_buffer_size:
+ * @stream: a #GBufferedInputStream
+ * @size: a #gsize
*
- * #GTlsConnection and related classes provide TLS (Transport Layer
- * Security, previously known as SSL, Secure Sockets Layer) support for
- * gio-based network streams.
+ * Sets the size of the internal buffer of @stream to @size, or to the
+ * size of the contents of the buffer. The buffer can never be resized
+ * smaller than its current contents.
+ */
+
+
+/**
+ * g_buffered_output_stream_get_auto_grow:
+ * @stream: a #GBufferedOutputStream.
*
- * In the simplest case, for a client connection, you can just set the
- * #GSocketClient:tls flag on a #GSocketClient, and then any
- * connections created by that client will have TLS negotiated
- * automatically, using appropriate default settings, and rejecting
- * any invalid or self-signed certificates (unless you change that
- * default by setting the #GSocketClient:tls-validation-flags
- * property). The returned object will be a #GTcpWrapperConnection,
- * which wraps the underlying #GTlsClientConnection.
+ * Checks if the buffer automatically grows as data is added.
*
- * For greater control, you can create your own #GTlsClientConnection,
- * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
- * pollable input and output streams) and then connect to its signals,
- * such as #GTlsConnection::accept-certificate, before starting the
- * handshake.
+ * Returns: %TRUE if the @stream's buffer automatically grows,
+ * %FALSE otherwise.
+ */
+
+
+/**
+ * g_buffered_output_stream_get_buffer_size:
+ * @stream: a #GBufferedOutputStream.
*
- * Server-side TLS is similar, using #GTlsServerConnection. At the
- * moment, there is no support for automatically wrapping server-side
- * connections in the way #GSocketClient does for client-side
- * connections.
+ * Gets the size of the buffer in the @stream.
+ *
+ * Returns: the current size of the buffer.
*/
/**
- * SECTION:gtlsbackend
- * @title: GTlsBackend
- * @short_description: TLS backend implementation
- * @include: gio/gio.h
+ * g_buffered_output_stream_new:
+ * @base_stream: a #GOutputStream.
*
+ * Creates a new buffered output stream for a base stream.
*
+ * Returns: a #GOutputStream for the given @base_stream.
*/
/**
- * SECTION:gtlscertificate
- * @title: GTlsCertificate
- * @short_description: TLS certificate
- * @see_also: #GTlsConnection
+ * g_buffered_output_stream_new_sized:
+ * @base_stream: a #GOutputStream.
+ * @size: a #gsize.
*
- * A certificate used for TLS authentication and encryption.
- * This can represent either a public key 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
- * #GTlsServerConnection).
+ * Creates a new buffered output stream with a given buffer size.
*
- * Since: 2.28
+ * Returns: a #GOutputStream with an internal buffer set to @size.
*/
/**
- * SECTION:gtlsclientconnection
- * @short_description: TLS client-side connection
- * @include: gio/gio.h
+ * g_buffered_output_stream_set_auto_grow:
+ * @stream: a #GBufferedOutputStream.
+ * @auto_grow: a #gboolean.
+ *
+ * Sets whether or not the @stream's buffer should automatically grow.
+ * If @auto_grow is true, then each write will just make the buffer
+ * larger, and you must manually flush the buffer to actually write out
+ * the data to the underlying stream.
+ */
+
+
+/**
+ * g_buffered_output_stream_set_buffer_size:
+ * @stream: a #GBufferedOutputStream.
+ * @size: a #gsize.
*
- * #GTlsClientConnection is the client-side subclass of
- * #GTlsConnection, representing a client-side TLS connection.
+ * Sets the size of the internal buffer to @size.
*/
/**
- * SECTION:gtlsconnection
- * @short_description: TLS connection type
- * @include: gio/gio.h
+ * 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
*
- * #GTlsConnection is the base TLS connection class type, which wraps
- * a #GIOStream and provides TLS encryption on top of it. Its
- * subclasses, #GTlsClientConnection and #GTlsServerConnection,
- * implement client-side and server-side TLS, respectively.
+ * Asynchronously connects to the message bus specified by @bus_type.
*
- * Since: 2.28
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_bus_get_finish() to get the result of the operation.
+ *
+ * This is a asynchronous failable function. See g_bus_get_sync() for
+ * the synchronous version.
+ *
+ * Since: 2.26
*/
/**
- * SECTION:gtlsdatabase
- * @short_description: TLS database type
- * @include: gio/gio.h
+ * g_bus_get_finish:
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ * to g_bus_get()
+ * @error: return location for error or %NULL
*
- * #GTlsDatabase is used to lookup certificates and other information
- * from a certificate or key store. It is an abstract base class which
- * TLS library specific subtypes override.
+ * Finishes an operation started with g_bus_get().
*
- * Most common client applications will not directly interact with
- * #GTlsDatabase. It is used internally by #GTlsConnection.
+ * The returned object is a singleton, that is, shared with other
+ * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
+ * event that you need a private message bus connection, use
+ * g_dbus_address_get_for_bus_sync() and
+ * g_dbus_connection_new_for_address().
*
- * Since: 2.30
+ * 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().
+ * Since: 2.26
*/
/**
- * SECTION:gtlsfiledatabase
- * @short_description: TLS file based database type
- * @include: gio/gio.h
+ * g_bus_get_sync:
+ * @bus_type: a #GBusType
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
*
- * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
- * their certificate information from a file. It is in interface which
- * TLS library specific subtypes implement.
+ * Synchronously connects to the message bus specified by @bus_type.
+ * Note that the returned object may shared with other callers,
+ * e.g. if two separate parts of a process calls this function with
+ * the same @bus_type, they will share the same object.
*
- * Since: 2.30
+ * This is a synchronous failable function. See g_bus_get() and
+ * g_bus_get_finish() for the asynchronous version.
+ *
+ * The returned object is a singleton, that is, shared with other
+ * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
+ * event that you need a private message bus connection, use
+ * g_dbus_address_get_for_bus_sync() and
+ * g_dbus_connection_new_for_address().
+ *
+ * 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().
+ * Since: 2.26
*/
/**
- * SECTION:gtlsinteraction
- * @short_description: Interaction with the user during TLS operations.
- * @include: gio/gio.h
+ * 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
*
- * #GTlsInteraction provides a mechanism for the TLS connection and database
- * code to interact with the user. It can be used to ask the user for passwords.
+ * 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
+ * [thread-default main context][g-main-context-push-thread-default]
+ * of the thread you are calling this function from.
*
- * To use a #GTlsInteraction with a TLS connection use
- * g_tls_connection_set_interaction().
+ * 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:
*
- * Callers should instantiate a derived class that implements the various
- * interaction methods to show the required dialogs.
+ * - @name_lost_handler with a %NULL connection (if a connection to the bus
+ * can't be made).
*
- * Callers should use the 'invoke' functions like
- * g_tls_interaction_invoke_ask_password() to run interaction methods. These
- * functions make sure that the interaction is invoked in the main loop
- * and not in the current thread, if the current thread is not running the
- * main loop.
+ * - @bus_acquired_handler then @name_lost_handler (if the name can't be
+ * obtained)
*
- * Derived classes can choose to implement whichever interactions methods they'd
- * like to support by overriding those virtual methods in their class
- * initialization function. Any interactions not implemented will return
- * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
- * it must also implement the corresponding finish method.
+ * - @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.
+ *
+ * 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
+ * will work.
+ *
+ * Another guarantee is that invocations of @name_acquired_handler
+ * and @name_lost_handler are guaranteed to alternate; that
+ * is, if @name_acquired_handler is invoked then you are
+ * guaranteed that the next time one of the handlers is invoked, it
+ * will be @name_lost_handler. The reverse is also true.
+ *
+ * If you plan on exporting objects (using e.g.
+ * g_dbus_connection_register_object()), note that it is generally too late
+ * to export the objects in @name_acquired_handler. Instead, you can do this
+ * in @bus_acquired_handler since you are guaranteed that this will run
+ * before @name is requested from the bus.
+ *
+ * This behavior makes it very simple to write applications that wants
+ * 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.
+ * Since: 2.26
*/
/**
- * SECTION:gtlspassword
- * @title: GTlsPassword
- * @short_description: TLS Passwords for prompting
- * @include: gio/gio.h
+ * 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
*
- * Holds a password used in TLS.
+ * 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
+ * Since: 2.26
*/
/**
- * SECTION:gtlsserverconnection
- * @short_description: TLS server-side connection
- * @include: gio/gio.h
+ * 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
*
- * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
- * representing a server-side TLS connection.
+ * Version of g_bus_own_name_on_connection() using closures instead of
+ * callbacks for easier binding in other languages.
*
- * Since: 2.28
+ * Returns: an identifier (never 0) that an be used with
+ * g_bus_unown_name() to stop owning the name.
+ * Since: 2.26
*/
/**
- * SECTION:gunixconnection
- * @title: GUnixConnection
- * @short_description: A UNIX domain GSocketConnection
- * @include: gio/gunixconnection.h
- * @see_also: #GSocketConnection.
+ * 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
*
- * This is the subclass of #GSocketConnection that is created
- * for UNIX domain sockets.
+ * Version of g_bus_own_name() using closures instead of callbacks for
+ * easier binding in other languages.
*
- * It contains functions to do some of the UNIX socket specific
- * functionality like passing file descriptors.
+ * 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()
*
- * 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.
+ * Stops owning a name.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * SECTION:gunixcredentialsmessage
- * @title: GUnixCredentialsMessage
- * @short_description: A GSocketControlMessage containing credentials
- * @include: gio/gunixcredentialsmessage.h
- * @see_also: #GUnixConnection, #GSocketControlMessage
+ * g_bus_unwatch_name:
+ * @watcher_id: An identifier obtained from g_bus_watch_name()
*
- * This #GSocketControlMessage contains a #GCredentials instance. It
- * may be sent using g_socket_send_message() and received using
- * g_socket_receive_message() over UNIX sockets (ie: sockets in the
- * %G_SOCKET_FAMILY_UNIX family).
+ * Stops watching a name.
*
- * For an easier way to send and receive credentials over
- * stream-oriented UNIX sockets, see
- * g_unix_connection_send_credentials() and
- * g_unix_connection_receive_credentials(). To receive credentials of
- * a foreign process connected to a socket, use
- * g_socket_get_credentials().
+ * Since: 2.26
*/
/**
- * SECTION:gunixfdlist
- * @title: GUnixFDList
- * @short_description: An object containing a set of UNIX file descriptors
- * @include: gio/gunixfdlist.h
- * @see_also: #GUnixFDMessage
+ * 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_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
+ * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
+ * @user_data: User data to pass to handlers.
+ * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
*
- * A #GUnixFDList contains a list of file descriptors. It owns the file
- * descriptors that it contains, closing them when finalized.
+ * 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
+ * [thread-default main context][g-main-context-push-thread-default]
+ * of the thread you are calling this function from.
*
- * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
- * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
- * and received using g_socket_receive_message().
+ * You are guaranteed that one of the handlers will be invoked after
+ * calling this function. When you are done watching the name, just
+ * call g_bus_unwatch_name() with the watcher id this function
+ * returns.
+ *
+ * If the name vanishes or appears (for example the application owning
+ * the name could restart), the handlers are also invoked. If the
+ * #GDBusConnection that is used for watching the name disconnects, then
+ * @name_vanished_handler is invoked since it is no longer
+ * possible to access the name.
+ *
+ * Another guarantee is that invocations of @name_appeared_handler
+ * and @name_vanished_handler are guaranteed to alternate; that
+ * is, if @name_appeared_handler is invoked then you are
+ * guaranteed that the next time one of the handlers is invoked, it
+ * will be @name_vanished_handler. The reverse is also true.
*
- * 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.
+ * 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.
+ * Since: 2.26
*/
/**
- * SECTION:gunixfdmessage
- * @title: GUnixFDMessage
- * @short_description: A GSocketControlMessage containing a GUnixFDList
- * @include: gio/gunixfdmessage.h
- * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
- *
- * This #GSocketControlMessage contains a #GUnixFDList.
- * It may be sent using g_socket_send_message() and received using
- * g_socket_receive_message() over UNIX sockets (ie: sockets in the
- * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
- * between processes by the kernel.
+ * 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_handler: (allow-none): Handler to invoke when @name is known to exist or %NULL.
+ * @name_vanished_handler: (allow-none): Handler to invoke when @name is known to not exist or %NULL.
+ * @user_data: User data to pass to handlers.
+ * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
*
- * For an easier way to send and receive file descriptors over
- * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
- * g_unix_connection_receive_fd().
+ * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
+ * #GBusType.
*
- * 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.
+ * Returns: An identifier (never 0) that an be used with
+ * g_bus_unwatch_name() to stop watching the name.
+ * Since: 2.26
*/
/**
- * SECTION:gunixinputstream
- * @short_description: Streaming input operations for UNIX file descriptors
- * @include: gio/gunixinputstream.h
- * @see_also: #GInputStream
+ * 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.
*
- * #GUnixInputStream implements #GInputStream for reading from a UNIX
- * file descriptor, including asynchronous operations. (If the file
- * descriptor refers to a socket or pipe, this will use poll() to do
- * asynchronous I/O. If it refers to a regular file, it will fall back
- * to doing asynchronous I/O in another thread.)
+ * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
+ * easier binding in other languages.
*
- * 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.
+ * Returns: An identifier (never 0) that an be used with
+ * g_bus_unwatch_name() to stop watching the name.
+ * Since: 2.26
*/
/**
- * SECTION:gunixmounts
- * @include: gio/gunixmounts.h
- * @short_description: UNIX mounts
+ * 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.
*
- * Routines for managing mounted UNIX mount points and paths.
+ * Version of g_bus_watch_name() using closures instead of callbacks for
+ * easier binding in other languages.
*
- * 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.
+ * Returns: An identifier (never 0) that an be used with
+ * g_bus_unwatch_name() to stop watching the name.
+ * Since: 2.26
*/
/**
- * SECTION:gunixoutputstream
- * @short_description: Streaming output operations for UNIX file descriptors
- * @include: gio/gunixoutputstream.h
- * @see_also: #GOutputStream
+ * g_bytes_icon_get_bytes:
+ * @icon: a #GIcon.
*
- * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
- * file descriptor, including asynchronous operations. (If the file
- * descriptor refers to a socket or pipe, this will use poll() to do
- * asynchronous I/O. If it refers to a regular file, it will fall back
- * to doing asynchronous I/O in another thread.)
+ * Gets the #GBytes associated with the given @icon.
*
- * 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.
+ * Returns: (transfer none): a #GBytes, or %NULL.
+ * Since: 2.38
*/
/**
- * SECTION:gunixsocketaddress
- * @short_description: UNIX GSocketAddress
- * @include: gio/gunixsocketaddress.h
- *
- * Support for UNIX-domain (also known as local) sockets.
+ * g_bytes_icon_new:
+ * @bytes: a #GBytes.
*
- * UNIX domain sockets are generally visible in the filesystem.
- * However, some systems support abstract socket names which are not
- * visible in the filesystem and not affected by the filesystem
- * permissions, visibility, etc. Currently this is only supported
- * under Linux. If you attempt to use abstract sockets on other
- * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
- * errors. You can use g_unix_socket_address_abstract_names_supported()
- * to see if abstract names are supported.
+ * Creates a new icon for a bytes.
*
- * 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.
+ * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given
+ * @bytes, or %NULL on error.
+ * Since: 2.38
*/
/**
- * SECTION:gvfs
- * @short_description: Virtual File System
- * @include: gio/gio.h
+ * g_cancellable_cancel:
+ * @cancellable: (nullable): a #GCancellable object.
*
- * Entry point for using GIO functionality.
+ * 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.
+ *
+ * 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
+ * the application returns to the main loop.
*/
/**
- * SECTION:gvolume
- * @short_description: Volume management
- * @include: gio/gio.h
+ * g_cancellable_connect:
+ * @cancellable: A #GCancellable.
+ * @callback: The #GCallback to connect.
+ * @data: Data to pass to @callback.
+ * @data_destroy_func: (allow-none): Free function for @data or %NULL.
*
- * The #GVolume interface represents user-visible objects that can be
- * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
- * equivalent of #GnomeVFSDrive.
+ * Convenience function to connect to the #GCancellable::cancelled
+ * signal. Also handles the race condition that may happen
+ * if the cancellable is cancelled right before connecting.
*
- * Mounting a #GVolume instance is an asynchronous operation. For more
- * information about asynchronous operations, see #GAsyncReady and
- * #GSimpleAsyncReady. To mount a #GVolume, first call
- * g_volume_mount() with (at least) the #GVolume instance, optionally
- * a #GMountOperation object and a #GAsyncReadyCallback.
+ * @callback is called at most once, either directly at the
+ * time of the connect if @cancellable is already cancelled,
+ * or when @cancellable is cancelled in some thread.
*
- * Typically, one will only want to pass %NULL for the
- * #GMountOperation if automounting all volumes when a desktop session
- * starts since it's not desirable to put up a lot of dialogs asking
- * for credentials.
+ * @data_destroy_func will be called when the handler is
+ * disconnected, or immediately if the cancellable is already
+ * cancelled.
*
- * The callback will be fired when the operation has resolved (either
- * with success or failure), and a #GAsyncReady structure will be
- * passed to the callback. That callback should then call
- * g_volume_mount_finish() with the #GVolume instance and the
- * #GAsyncReady data to see if the operation was completed
- * successfully. If an @error is present when g_volume_mount_finish()
- * is called, then it will be filled with any error information.
+ * See #GCancellable::cancelled for details on how to use this.
*
- * <para id="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>
+ * 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().
*
- * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
- * when the gvfs hal volume monitor is in use. Other volume monitors
- * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
- * identifier, which can be used to obtain a hal device by means of
- * libhal_manger_find_device_string_match().
+ * Returns: The id of the signal handler or 0 if @cancellable has already
+ * been cancelled.
+ * Since: 2.22
*/
/**
- * SECTION:gvolumemonitor
- * @short_description: Volume Monitor
- * @include: gio/gio.h
- * @see_also: #GFileMonitor
+ * g_cancellable_disconnect:
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @handler_id: Handler id of the handler to be disconnected, or %0.
*
- * #GVolumeMonitor is for listing the user interesting devices and volumes
- * on the computer. In other words, what a file selector or file manager
- * would show in a sidebar.
+ * Disconnects a handler from a cancellable instance similar to
+ * g_signal_handler_disconnect(). Additionally, in the event that a
+ * signal handler is currently running, this call will block until the
+ * handler has finished. Calling this function from a
+ * #GCancellable::cancelled signal handler will therefore result in a
+ * deadlock.
*
- * #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.
- */
-
-
-/**
- * SECTION:gwin32inputstream
- * @short_description: Streaming input operations for Windows file handles
- * @include: gio/gwin32inputstream.h
- * @see_also: #GInputStream
+ * This avoids a race condition where a thread cancels at the
+ * same time as the cancellable operation is finished and the
+ * signal handler is removed. See #GCancellable::cancelled for
+ * details on how to use this.
*
- * #GWin32InputStream implements #GInputStream for reading from a
- * Windows file handle.
+ * If @cancellable is %NULL or @handler_id is %0 this function does
+ * nothing.
*
- * 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.
+ * Since: 2.22
*/
/**
- * SECTION:gwin32outputstream
- * @short_description: Streaming output operations for Windows file handles
- * @include: gio/gwin32outputstream.h
- * @see_also: #GOutputStream
+ * g_cancellable_get_current:
*
- * #GWin32OutputStream implements #GOutputStream for writing to a
- * Windows file handle.
+ * Gets the top cancellable from the stack.
*
- * 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.
+ * Returns: (nullable) (transfer none): a #GCancellable from the top
+ * of the stack, or %NULL if the stack is empty.
*/
/**
- * SECTION:gzcompressor
- * @short_description: Zlib compressor
- * @include: gio/gio.h
+ * g_cancellable_get_fd:
+ * @cancellable: a #GCancellable.
*
- * #GZlibCompressor is an implementation of #GConverter that
- * compresses data using zlib.
+ * Gets the file descriptor for a cancellable job. This can be used to
+ * implement cancellable operations on Unix systems. The returned fd will
+ * turn readable when @cancellable is cancelled.
+ *
+ * You are not supposed to read from the fd yourself, just check for
+ * readable status. Reading to unset the readable status is done
+ * with g_cancellable_reset().
+ *
+ * After a successful return from this function, you should use
+ * g_cancellable_release_fd() to free up resources allocated for
+ * the returned file descriptor.
+ *
+ * See also g_cancellable_make_pollfd().
+ *
+ * Returns: A valid file descriptor. %-1 if the file descriptor
+ * is not supported, or on errors.
*/
/**
- * SECTION:gzdecompressor
- * @short_description: Zlib decompressor
- * @include: gio/gio.h
+ * g_cancellable_is_cancelled:
+ * @cancellable: (allow-none): a #GCancellable or %NULL
*
- * #GZlibDecompressor is an implementation of #GConverter that
- * decompresses data compressed with zlib.
+ * 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.
*/
/**
- * The string info map is an efficient data structure designed to be:
- *
- * 1) Implement <choices> with a list of valid strings
- *
- * 2) Implement <alias> by mapping one string to another
- *
- * 3) Implement enumerated types by mapping strings to integer values
- * (and back).
- *
- * The map is made out of an array of uint32s. Each entry in the array
- * is an integer value, followed by a specially formatted string value:
- *
- * The string starts with the byte 0xff or 0xfe, followed by the
- * content of the string, followed by a nul byte, followed by
- * additional nul bytes for padding, followed by a 0xff byte.
- *
- * Padding is added so that the entire formatted string takes up a
- * multiple of 4 bytes, and not less than 8 bytes. The requirement
- * for a string to take up 8 bytes is so that the scanner doesn't lose
- * synch and mistake a string for an integer value.
- *
- * The first byte of the formatted string depends on if the integer is
- * an enum value (0xff) or an alias (0xfe). If it is an alias then the
- * number refers to the word offset within the info map at which the
- * integer corresponding to the "target" value is stored.
- *
- * For example, consider the case of the string info map representing an
- * enumerated type of 'foo' (value 1) and 'bar' (value 2) and 'baz'
- * (alias for 'bar'). Note that string info maps are always little
- * endian.
- *
- * x01 x00 x00 x00 xff 'f' 'o' 'o' x00 x00 x00 xff x02 x00 x00 x00
- * xff 'b' 'a' 'r' x00 x00 x00 xff x03 x00 x00 x00 xfe 'b' 'a' 'z'
- * x00 x00 x00 xff
- *
- *
- * The operations that someone may want to perform with the map:
- *
- * - lookup if a string is valid (and not an alias)
- * - lookup the integer value for a enum 'nick'
- * - lookup the integer value for the target of an alias
- * - lookup an alias and convert it to its target string
- * - lookup the enum nick for a given value
- *
- * In order to lookup if a string is valid, it is padded on either side
- * (as described) and scanned for in the array. For example, you might
- * look for "foo":
- *
- * xff 'f' 'o' 'o' x00 x00 x00 xff
- *
- * In order to lookup the integer value for a nick, the string is padded
- * on either side and scanned for in the array, as above. Instead of
- * merely succeeding, we look at the integer value to the left of the
- * match. This is the enum value.
- *
- * In order to lookup an alias and convert it to its target enum value,
- * the string is padded on either side (as described, with 0xfe) and
- * scanned for. For example, you might look for "baz":
+ * g_cancellable_make_pollfd:
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @pollfd: a pointer to a #GPollFD
*
- * xfe 'b' 'a' 'z' x00 x00 x00 xff
+ * Creates a #GPollFD corresponding to @cancellable; this can be passed
+ * to g_poll() and used to poll for cancellation. This is useful both
+ * for unix systems without a native poll and for portability to
+ * windows.
*
- * The integer immediately preceding the match then contains the offset
- * of the integer value of the target. In our example, that's '3'.
- * This index is dereferenced to find the enum value of '2'.
+ * When this function returns %TRUE, you should use
+ * g_cancellable_release_fd() to free up resources allocated for the
+ * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
*
- * To convert the alias to its target string, 5 bytes just need to be
- * added past the start of the integer value to find the start of the
- * string.
+ * If this function returns %FALSE, either no @cancellable was given or
+ * resource limits prevent this function from allocating the necessary
+ * structures for polling. (On Linux, you will likely have reached
+ * the maximum number of file descriptors.) The suggested way to handle
+ * these cases is to ignore the @cancellable.
*
- * To lookup the enum nick for a given value, the value is searched for
- * in the array. To ensure that the value isn't matching the inside of a
- * string, we must check that it is either the first item in the array or
- * immediately preceded by the byte 0xff. It must also be immediately
- * followed by the byte 0xff.
+ * You are not supposed to read from the fd yourself, just check for
+ * readable status. Reading to unset the readable status is done
+ * with g_cancellable_reset().
*
- * Because strings always take up a minimum of 2 words, because 0xff or
- * 0xfe never appear inside of a utf-8 string and because no two integer
- * values ever appear in sequence, the only way we can have the
- * sequence:
+ * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
+ * failure to prepare the cancellable.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_cancellable_new:
*
- * xff __ __ __ __ xff (or 0xfe)
+ * Creates a new #GCancellable object.
*
- * is in the event of an integer nested between two strings.
+ * Applications that want to start one or more operations
+ * that should be cancellable should create a #GCancellable
+ * and pass it to the operations.
*
- * For implementation simplicity/efficiency, strings may not be more
- * than 65 characters in length (ie: 17 32bit words after padding).
+ * One #GCancellable can be used in multiple consecutive
+ * operations or in multiple concurrent operations.
*
- * In the event that we are doing <choices> (ie: not an enum type) then
- * the value of each choice is set to zero and ignored.
+ * Returns: a #GCancellable.
*/
/**
- * _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.
- *
- * Retrieves the default object 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.
+ * g_cancellable_pop_current:
+ * @cancellable: a #GCancellable object
*
- * If an extension point implementation implements #GInitable, then
- * that implementation will only be used if it initializes
- * successfully. Otherwise, if @verify_func is not %NULL, then it will
- * be called on each candidate implementation after construction, to
- * check if it is actually usable or not.
+ * Pops @cancellable off the cancellable stack (verifying that @cancellable
+ * is on the top of the stack).
+ */
+
+
+/**
+ * g_cancellable_push_current:
+ * @cancellable: a #GCancellable object
*
- * The result is cached after it is generated the first time, and
- * the function is thread-safe.
+ * Pushes @cancellable onto the cancellable stack. The current
+ * cancellable can then be received using g_cancellable_get_current().
*
- * @extension_point, or %NULL if there are no usable
- * implementations.
+ * This is useful when implementing cancellable operations in
+ * code that does not allow you to pass down the cancellable object.
*
- * Returns: (transfer none): an object implementing
+ * This is typically called automatically by e.g. #GFile operations,
+ * so you rarely have to call this yourself.
*/
/**
- * g_action_activate:
- * @action: a #GAction
- * @parameter: (allow-none): the parameter to the activation
+ * g_cancellable_release_fd:
+ * @cancellable: a #GCancellable
*
- * Activates the action.
+ * Releases a resources previously allocated by g_cancellable_get_fd()
+ * or g_cancellable_make_pollfd().
*
- * @parameter must be the correct type of parameter for the action (ie:
- * the parameter type given at construction time). If the parameter
- * type was %NULL then @parameter must also be %NULL.
+ * For compatibility reasons with older releases, calling this function
+ * is not strictly required, the resources will be automatically freed
+ * when the @cancellable is finalized. However, the @cancellable will
+ * block scarce file descriptors until it is finalized if this function
+ * is not called. This can cause the application to run out of file
+ * descriptors when many #GCancellables are used at the same time.
*
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * g_action_change_state:
- * @action: a #GAction
- * @value: the new state
+ * g_cancellable_reset:
+ * @cancellable: a #GCancellable object.
*
- * Request for the state of @action to be changed to @value.
+ * Resets @cancellable to its uncancelled state.
*
- * The action must be stateful and @value must be of the correct type.
- * See g_action_get_state_type().
+ * If cancellable is currently in use by any cancellable operation
+ * then the behavior of this function is undefined.
*
- * This call merely requests a change. The action may refuse to change
- * its state or may change its state to something other than @value.
- * See g_action_get_state_hint().
+ * 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.
+ */
+
+
+/**
+ * g_cancellable_set_error_if_cancelled:
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: #GError to append error state to
*
- * If the @value GVariant is floating, it is consumed.
+ * If the @cancellable is cancelled, sets the error to notify
+ * that the operation was cancelled.
*
- * Since: 2.30
+ * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
*/
/**
- * g_action_get_enabled:
- * @action: a #GAction
+ * g_cancellable_source_new: (skip)
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
*
- * Checks if @action is currently enabled.
+ * Creates a source that triggers if @cancellable is cancelled and
+ * calls its callback of type #GCancellableSourceFunc. This is
+ * primarily useful for attaching to another (non-cancellable) source
+ * with g_source_add_child_source() to add cancellability to it.
*
- * An action must be enabled in order to be activated or in order to
- * have its state changed from outside callers.
+ * For convenience, you can call this with a %NULL #GCancellable,
+ * in which case the source will never trigger.
*
- * Returns: whether the action is enabled
+ * The new #GSource will hold a reference to the #GCancellable.
+ *
+ * Returns: (transfer full): the new #GSource.
* Since: 2.28
*/
/**
- * g_action_get_name:
- * @action: a #GAction
+ * g_charset_converter_get_num_fallbacks:
+ * @converter: a #GCharsetConverter
*
- * Queries the name of @action.
+ * Gets the number of fallbacks that @converter has applied so far.
*
- * Returns: the name of the action
- * Since: 2.28
+ * Returns: the number of fallbacks that @converter has applied
+ * Since: 2.24
*/
/**
- * g_action_get_parameter_type:
- * @action: a #GAction
- *
- * Queries the type of the parameter that must be given when activating
- * @action.
- *
- * When activating the action using g_action_activate(), the #GVariant
- * given to that function must be of the type returned by this function.
+ * g_charset_converter_get_use_fallback:
+ * @converter: a #GCharsetConverter
*
- * In the case that this function returns %NULL, you must not give any
- * #GVariant, but %NULL instead.
+ * Gets the #GCharsetConverter:use-fallback property.
*
- * Returns: (allow-none): the parameter type
- * Since: 2.28
+ * Returns: %TRUE if fallbacks are used by @converter
+ * Since: 2.24
*/
/**
- * g_action_get_state:
- * @action: a #GAction
- *
- * Queries the current state of @action.
- *
- * If the action is not stateful then %NULL will be returned. If the
- * action is stateful then the type of the return value is the type
- * given by g_action_get_state_type().
+ * g_charset_converter_new:
+ * @to_charset: destination charset
+ * @from_charset: source charset
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * The return value (if non-%NULL) should be freed with
- * g_variant_unref() when it is no longer required.
+ * Creates a new #GCharsetConverter.
*
- * Returns: (transfer full): the current state of the action
- * Since: 2.28
+ * Returns: a new #GCharsetConverter or %NULL on error.
+ * Since: 2.24
*/
/**
- * g_action_get_state_hint:
- * @action: a #GAction
+ * g_charset_converter_set_use_fallback:
+ * @converter: a #GCharsetConverter
+ * @use_fallback: %TRUE to use fallbacks
*
- * Requests a hint about the valid range of values for the state of
- * @action.
+ * Sets the #GCharsetConverter:use-fallback property.
*
- * If %NULL is returned it either means that the action is not stateful
- * or that there is no hint about the valid range of values for the
- * state of the action.
+ * Since: 2.24
+ */
+
+
+/**
+ * g_content_type_can_be_executable:
+ * @type: a content type string
*
- * If a #GVariant array is returned then each item in the array is a
- * possible value for the state. If a #GVariant pair (ie: two-tuple) is
- * returned then the tuple specifies the inclusive lower and upper bound
- * of valid values for the state.
+ * 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).
*
- * In any case, the information is merely a hint. It may be possible to
- * have a state value outside of the hinted range and setting a value
- * within the range may fail.
+ * Returns: %TRUE if the file type corresponds to a type that
+ * can be executable, %FALSE otherwise.
+ */
+
+
+/**
+ * g_content_type_equals:
+ * @type1: a content type string
+ * @type2: a content type string
*
- * The return value (if non-%NULL) should be freed with
- * g_variant_unref() when it is no longer required.
+ * Compares two content types for equality.
*
- * Returns: (transfer full): the state range hint
- * Since: 2.28
+ * Returns: %TRUE if the two strings are identical or equivalent,
+ * %FALSE otherwise.
*/
/**
- * g_action_get_state_type:
- * @action: a #GAction
+ * g_content_type_from_mime_type:
+ * @mime_type: a mime type string
*
- * Queries the type of the state of @action.
+ * Tries to find a content type based on the mime type name.
*
- * If the action is stateful (e.g. created with
- * g_simple_action_new_stateful()) then this function returns the
- * #GVariantType of the state. This is the type of the initial value
- * given as the state. All calls to g_action_change_state() must give a
- * #GVariant of this type and g_action_get_state() will return a
- * #GVariant of the same type.
+ * Returns: (nullable): Newly allocated string with content type or
+ * %NULL. Free with g_free()
+ * Since: 2.18
+ */
+
+
+/**
+ * g_content_type_get_description:
+ * @type: a content type string
*
- * If the action is not stateful (e.g. created with g_simple_action_new())
- * then this function will return %NULL. In that case, g_action_get_state()
- * will return %NULL and you must not call g_action_change_state().
+ * Gets the human readable description of the content type.
*
- * Returns: (allow-none): the state type, if the action is stateful
- * Since: 2.28
+ * Returns: a short description of the content type @type. Free the
+ * returned string with g_free()
*/
/**
- * g_action_group_action_added:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
+ * g_content_type_get_generic_icon_name:
+ * @type: a content type string
*
- * Emits the #GActionGroup::action-added signal on @action_group.
+ * Gets the generic icon name for a content type.
*
- * This function should only be called by #GActionGroup implementations.
+ * See the
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+ * specification for more on the generic icon name.
*
- * Since: 2.28
+ * Returns: (allow-none): the registered generic icon name for the given @type,
+ * or %NULL if unknown. Free with g_free()
+ * Since: 2.34
*/
/**
- * g_action_group_action_enabled_changed:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
- * @enabled: whether or not the action is now enabled
- *
- * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
+ * g_content_type_get_icon:
+ * @type: a content type string
*
- * This function should only be called by #GActionGroup implementations.
+ * Gets the icon for a content type.
*
- * Since: 2.28
+ * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
+ * object with g_object_unref()
*/
/**
- * g_action_group_action_removed:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
- *
- * Emits the #GActionGroup::action-removed signal on @action_group.
+ * g_content_type_get_mime_type:
+ * @type: a content type string
*
- * This function should only be called by #GActionGroup implementations.
+ * Gets the mime type for the content type, if one is registered.
*
- * Since: 2.28
+ * Returns: (nullable): the registered mime type for the given @type,
+ * or %NULL if unknown.
*/
/**
- * g_action_group_action_state_changed:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
- * @state: the new state of the named action
- *
- * Emits the #GActionGroup::action-state-changed signal on @action_group.
+ * g_content_type_get_symbolic_icon:
+ * @type: a content type string
*
- * This function should only be called by #GActionGroup implementations.
+ * Gets the symbolic icon for a content type.
*
- * Since: 2.28
+ * Returns: (transfer full): symbolic #GIcon corresponding to the content type.
+ * Free the returned object with g_object_unref()
+ * Since: 2.34
*/
/**
- * g_action_group_activate_action:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to activate
- * @parameter: (allow-none): parameters to the activation
- *
- * Activate the named action within @action_group.
+ * g_content_type_guess:
+ * @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
*
- * If the action is expecting a parameter, then the correct type of
- * parameter must be given as @parameter. If the action is expecting no
- * parameters then @parameter must be %NULL. See
- * g_action_group_get_action_parameter_type().
+ * 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.
*
- * Since: 2.28
+ * Returns: a string indicating a guessed content type for the
+ * given data. Free with g_free()
*/
/**
- * g_action_group_change_action_state:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to request the change on
- * @value: the new state
- *
- * Request for the state of the named action within @action_group to be
- * changed to @value.
+ * g_content_type_guess_for_tree:
+ * @root: the root of the tree to guess a type for
*
- * The action must be stateful and @value must be of the correct type.
- * See g_action_group_get_action_state_type().
+ * Tries to guess the type of the tree with root @root, by
+ * looking at the files it contains. The result is an array
+ * of content types, with the best guess coming first.
*
- * This call merely requests a change. The action may refuse to change
- * its state or may change its state to something other than @value.
- * See g_action_group_get_action_state_hint().
+ * 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
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+ * specification for more on x-content types.
*
- * If the @value GVariant is floating, it is consumed.
+ * This function is useful in the implementation of
+ * g_mount_guess_content_type().
*
- * Since: 2.28
+ * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
+ * array of zero or more content types. Free with g_strfreev()
+ * Since: 2.18
*/
/**
- * g_action_group_get_action_enabled:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
- *
- * Checks if the named action within @action_group is currently enabled.
+ * g_content_type_is_a:
+ * @type: a content type string
+ * @supertype: a content type string
*
- * An action must be enabled in order to be activated or in order to
- * have its state changed from outside callers.
+ * Determines if @type is a subset of @supertype.
*
- * Returns: whether or not the action is currently enabled
- * Since: 2.28
+ * Returns: %TRUE if @type is a kind of @supertype,
+ * %FALSE otherwise.
*/
/**
- * g_action_group_get_action_parameter_type:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
- *
- * Queries the type of the parameter that must be given when activating
- * the named action within @action_group.
- *
- * When activating the action using g_action_group_activate_action(),
- * the #GVariant given to that function must be of the type returned
- * by this function.
- *
- * In the case that this function returns %NULL, you must not give any
- * #GVariant, but %NULL instead.
+ * g_content_type_is_unknown:
+ * @type: a content type string
*
- * The parameter type of a particular action will never change but it is
- * possible for an action to be removed and for a new action to be added
- * with the same name but a different parameter type.
+ * Checks if the content type is the generic "unknown" type.
+ * On UNIX this is the "application/octet-stream" mimetype,
+ * while on win32 it is "*".
*
- * Returns: the parameter type
- * Since: 2.28
+ * Returns: %TRUE if the type is the unknown type.
*/
/**
- * g_action_group_get_action_state:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
- *
- * Queries the current state of the named action within @action_group.
- *
- * If the action is not stateful then %NULL will be returned. If the
- * action is stateful then the type of the return value is the type
- * given by g_action_group_get_action_state_type().
+ * g_content_types_get_registered:
*
- * The return value (if non-%NULL) should be freed with
- * g_variant_unref() when it is no longer required.
+ * Gets a list of strings containing all the registered content types
+ * known to the system. The list and its data should be freed using
+ * g_list_free_full (list, g_free).
*
- * Returns: (allow-none): the current state of the action
- * Since: 2.28
+ * Returns: (element-type utf8) (transfer full): list of the registered
+ * content types
*/
/**
- * g_action_group_get_action_state_hint:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
+ * g_converter_convert:
+ * @converter: a #GConverter.
+ * @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
+ * @flags: a #GConverterFlags controlling the conversion details
+ * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
+ * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Requests a hint about the valid range of values for the state of the
- * named action within @action_group.
+ * This is the main operation used when converting data. It is to be called
+ * multiple times in a loop, and each time it will do some work, i.e.
+ * producing some output (in @outbuf) or consuming some input (from @inbuf) or
+ * both. If its not possible to do any work an error is returned.
*
- * If %NULL is returned it either means that the action is not stateful
- * or that there is no hint about the valid range of values for the
- * state of the action.
+ * Note that a single call may not consume all input (or any input at all).
+ * Also a call may produce output even if given no input, due to state stored
+ * in the converter producing output.
*
- * If a #GVariant array is returned then each item in the array is a
- * possible value for the state. If a #GVariant pair (ie: two-tuple) is
- * returned then the tuple specifies the inclusive lower and upper bound
- * of valid values for the state.
+ * If any data was either produced or consumed, and then an error happens, then
+ * only the successful conversion is reported and the error is returned on the
+ * next call.
*
- * In any case, the information is merely a hint. It may be possible to
- * have a state value outside of the hinted range and setting a value
- * within the range may fail.
+ * A full conversion loop involves calling this method repeatedly, each time
+ * giving it new input and space output space. When there is no more input
+ * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+ * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+ * each time until all data is consumed and all output is produced, then
+ * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+ * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+ * in a decompression converter where the end of data is detectable from the
+ * data (and there might even be other data after the end of the compressed data).
*
- * The return value (if non-%NULL) should be freed with
- * g_variant_unref() when it is no longer required.
+ * When some data has successfully been converted @bytes_read and is set to
+ * the number of bytes read from @inbuf, and @bytes_written is set to indicate
+ * how many bytes was written to @outbuf. If there are more data to output
+ * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+ * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+ * then %G_CONVERTER_FINISHED is returned.
*
- * Returns: (transfer full): the state range hint
- * Since: 2.28
- */
-
-
-/**
- * g_action_group_get_action_state_type:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
+ * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
+ * Some errors need special handling:
*
- * Queries the type of the state of the named action within
- * @action_group.
+ * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
+ * to write the resulting converted data, the application should
+ * call the function again with a larger @outbuf to continue.
*
- * If the action is stateful then this function returns the
- * #GVariantType of the state. All calls to
- * g_action_group_change_action_state() must give a #GVariant of this
- * type and g_action_group_get_action_state() will return a #GVariant
- * of the same type.
+ * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+ * input to fully determine what the conversion should produce,
+ * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+ * example with an incomplete multibyte sequence when converting text,
+ * or when a regexp matches up to the end of the input (and may match
+ * further input). It may also happen when @inbuf_size is zero and
+ * there is no more data to produce.
*
- * If the action is not stateful then this function will return %NULL.
- * In that case, g_action_group_get_action_state() will return %NULL
- * and you must not call g_action_group_change_action_state().
+ * When this happens the application should read more input and then
+ * call the function again. If further input shows that there is no
+ * more data call the function again with the same data but with
+ * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+ * to finish as e.g. in the regexp match case (or, to fail again with
+ * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+ * input is actually partial).
*
- * The state type of a particular action will never change but it is
- * possible for an action to be removed and for a new action to be added
- * with the same name but a different state type.
+ * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+ * converter object is in an invalid state where its not allowed
+ * to call g_converter_convert() anymore. At this time you can only
+ * free the object or call g_converter_reset() to reset it to the
+ * initial state.
*
- * Returns: (transfer full): the state type, if the action is stateful
- * Since: 2.28
+ * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+ * to try to write out all internal state to the output. The application
+ * has to call the function multiple times with the flag set, and when
+ * the available input has been consumed and all internal state has
+ * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+ * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+ * This is somewhat similar to what happens at the end of the input stream,
+ * but done in the middle of the data.
+ *
+ * This has different meanings for different conversions. For instance
+ * in a compression converter it would mean that we flush all the
+ * compression state into output such that if you uncompress the
+ * compressed data you get back all the input data. Doing this may
+ * make the final file larger due to padding though. Another example
+ * is a regexp conversion, where if you at the end of the flushed data
+ * have a match, but there is also a potential longer match. In the
+ * non-flushed case we would ask for more input, but when flushing we
+ * treat this as the end of input and do the match.
+ *
+ * Flushing is not always possible (like if a charset converter flushes
+ * at a partial multibyte sequence). Converters are supposed to try
+ * to produce as much output as possible and then return an error
+ * (typically %G_IO_ERROR_PARTIAL_INPUT).
+ *
+ * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
+ * Since: 2.24
*/
/**
- * g_action_group_has_action:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to check for
+ * g_converter_input_stream_get_converter:
+ * @converter_stream: a #GConverterInputStream
*
- * Checks if the named action exists within @action_group.
+ * Gets the #GConverter that is used by @converter_stream.
*
- * Returns: whether the named action exists
- * Since: 2.28
+ * Returns: (transfer none): the converter of the converter input stream
+ * Since: 2.24
*/
/**
- * g_action_group_list_actions:
- * @action_group: a #GActionGroup
+ * g_converter_input_stream_new:
+ * @base_stream: a #GInputStream
+ * @converter: a #GConverter
*
- * Lists the actions contained within @action_group.
+ * Creates a new converter input stream for the @base_stream.
*
- * The caller is responsible for freeing the list with g_strfreev() when
- * it is no longer required.
+ * Returns: a new #GInputStream.
+ */
+
+
+/**
+ * g_converter_output_stream_get_converter:
+ * @converter_stream: a #GConverterOutputStream
*
- * actions in the groupb
+ * Gets the #GConverter that is used by @converter_stream.
*
- * Returns: (transfer full): a %NULL-terminated array of the names of the
- * Since: 2.28
+ * Returns: (transfer none): the converter of the converter output stream
+ * Since: 2.24
*/
/**
- * g_action_group_query_action:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
- * @enabled: (out): if the action is presently enabled
- * @parameter_type: (out): the parameter type, or %NULL if none needed
- * @state_type: (out): the state type, or %NULL if stateless
- * @state_hint: (out): the state hint, or %NULL if none
- * @state: (out): the current state, or %NULL if stateless
+ * g_converter_output_stream_new:
+ * @base_stream: a #GOutputStream
+ * @converter: a #GConverter
*
- * Queries all aspects of the named action within an @action_group.
+ * Creates a new converter output stream for the @base_stream.
*
- * This function acquires the information available from
- * g_action_group_has_action(), g_action_group_get_action_enabled(),
- * g_action_group_get_action_parameter_type(),
- * g_action_group_get_action_state_type(),
- * g_action_group_get_action_state_hint() and
- * g_action_group_get_state() with a single function call.
+ * Returns: a new #GOutputStream.
+ */
+
+
+/**
+ * g_converter_reset:
+ * @converter: a #GConverter.
*
- * This provides two main benefits.
+ * Resets all internal state in the converter, making it behave
+ * as if it was just created. If the converter has any internal
+ * state that would produce output then that output is lost.
*
- * The first is the improvement in efficiency that comes with not having
- * to perform repeated lookups of the action in order to discover
- * different things about it. The second is that implementing
- * #GActionGroup can now be done by only overriding this one virtual
- * function.
+ * Since: 2.24
+ */
+
+
+/**
+ * g_credentials_get_native: (skip)
+ * @credentials: A #GCredentials.
+ * @native_type: The type of native credentials to get.
*
- * The interface provides a default implementation of this function that
- * calls the individual functions, as required, to fetch the
- * information. The interface also provides default implementations of
- * those functions that call this function. All implementations,
- * therefore, must override either this function or all of the others.
+ * Gets a pointer to native credentials of type @native_type from
+ * @credentials.
*
- * If the action exists, %TRUE is returned and any of the requested
- * fields (as indicated by having a non-%NULL reference passed in) are
- * filled. If the action doesn't exist, %FALSE is returned and the
- * fields may or may not have been modified.
+ * It is a programming error (which will cause an warning to be
+ * 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: %TRUE if the action exists, else %FALSE
- * Since: 2.32
+ * 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_action_map_add_action:
- * @action_map: a #GActionMap
- * @action: a #GAction
- *
- * Adds an action to the @action_map.
+ * g_credentials_get_unix_pid:
+ * @credentials: A #GCredentials
+ * @error: Return location for error or %NULL.
*
- * If the action map already contains an action with the same name
- * as @action then the old action is dropped from the action map.
+ * Tries to get the UNIX process identifier from @credentials. This
+ * method is only available on UNIX platforms.
*
- * The action map takes its own reference on @action.
+ * 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.
*
- * Since: 2.32
+ * Returns: The UNIX process ID, or -1 if @error is set.
+ * Since: 2.36
*/
/**
- * g_action_map_add_action_entries:
- * @action_map: a #GActionMap
- * @entries: 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
- *
- * A convenience function for creating multiple #GSimpleAction instances
- * and adding them to a #GActionMap.
- *
- * Each action is constructed as per one #GActionEntry.
+ * g_credentials_get_unix_user:
+ * @credentials: A #GCredentials
+ * @error: Return location for error or %NULL.
*
- * <example>
- * <title>Using g_action_map_add_action_entries()</title>
- * <programlisting>
- * static void
- * activate_quit (GSimpleAction *simple,
- * GVariant *parameter,
- * gpointer user_data)
- * {
- * exit (0);
- * }
+ * Tries to get the UNIX user identifier from @credentials. This
+ * method is only available on UNIX platforms.
*
- * static void
- * activate_print_string (GSimpleAction *simple,
- * GVariant *parameter,
- * gpointer user_data)
- * {
- * g_print ("%s\n", g_variant_get_string (parameter, NULL));
- * }
+ * 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.
*
- * static GActionGroup *
- * create_action_group (void)
- * {
- * const GActionEntry entries[] = {
- * { "quit", activate_quit },
- * { "print-string", activate_print_string, "s" }
- * };
- * GSimpleActionGroup *group;
+ * Returns: The UNIX user identifier or -1 if @error is set.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_credentials_is_same_user:
+ * @credentials: A #GCredentials.
+ * @other_credentials: A #GCredentials.
+ * @error: Return location for error or %NULL.
*
- * group = g_simple_action_group_new ();
- * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+ * Checks if @credentials and @other_credentials is the same user.
*
- * return G_ACTION_GROUP (group);
- * }
- * </programlisting>
- * </example>
+ * This operation can fail if #GCredentials is not supported on the
+ * the OS.
*
- * Since: 2.32
+ * Returns: %TRUE if @credentials and @other_credentials has the same
+ * user, %FALSE otherwise or if @error is set.
+ * Since: 2.26
*/
/**
- * g_action_map_lookup_action:
- * @action_map: a #GActionMap
- * @action_name: the name of an action
- *
- * Looks up the action with the name @action_name in @action_map.
+ * g_credentials_new:
*
- * If no such action exists, returns %NULL.
+ * Creates a new #GCredentials object with credentials matching the
+ * the current process.
*
- * Returns: (transfer none): a #GAction, or %NULL
- * Since: 2.32
+ * Returns: A #GCredentials. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_action_map_remove_action:
- * @action_map: a #GActionMap
- * @action_name: the name of the action
+ * g_credentials_set_native:
+ * @credentials: A #GCredentials.
+ * @native_type: The type of native credentials to set.
+ * @native: A pointer to native credentials.
*
- * Removes the named action from the action map.
+ * Copies the native credentials of type @native_type from @native
+ * into @credentials.
*
- * If no action of this name is in the map then nothing happens.
+ * It is a programming error (which will cause an warning to be
+ * logged) to use this method if there is no #GCredentials support for
+ * the OS or if @native_type isn't supported by the OS.
*
- * Since: 2.32
+ * Since: 2.26
*/
/**
- * g_alloca:
- * @size: number of bytes to allocate.
- *
- * Allocates @size bytes on the stack; these bytes will be freed when the current
- * stack frame is cleaned up. This macro essentially just wraps the alloca()
- * function present on most UNIX variants.
- * Thus it provides the same advantages and pitfalls as alloca():
- * <variablelist>
- * <varlistentry><term></term><listitem><para>
- * + alloca() is very fast, as on most systems it's implemented by just adjusting
- * the stack pointer register.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
- * blocks just build up and are released together at function end.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation sizes have to fit into the current stack frame. For instance in a
- * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
- * so be sparse with alloca() uses.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation failure due to insufficient stack space is not indicated with a %NULL
- * return like e.g. with malloc(). Instead, most systems probably handle it the same
- * way as out of stack space situations from infinite function recursion, i.e.
- * with a segmentation fault.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
- * Stack space allocated with alloca() in the same scope as a variable sized array
- * will be freed together with the variable sized array upon exit of that scope, and
- * not upon exit of the enclosing function scope.
- * </para></listitem></varlistentry>
- * </variablelist>
- *
- * Returns: space for @size bytes, allocated on the stack
+ * g_credentials_set_unix_user:
+ * @credentials: A #GCredentials.
+ * @uid: The UNIX user identifier to set.
+ * @error: Return location for error or %NULL.
+ *
+ * Tries to set the UNIX user identifier on @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 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
*/
/**
- * g_app_info_add_supports_type:
- * @appinfo: a #GAppInfo.
- * @content_type: a string.
- * @error: a #GError.
+ * g_credentials_to_string:
+ * @credentials: A #GCredentials object.
*
- * Adds a content type to the application information to indicate the
- * application is capable of opening files with the given content type.
+ * Creates a human-readable textual representation of @credentials
+ * that can be used in logging and debug messages. The format of the
+ * returned string may change in future GLib release.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: A string that should be freed with g_free().
+ * Since: 2.26
*/
/**
- * g_app_info_can_delete:
- * @appinfo: a #GAppInfo
+ * g_data_input_stream_get_byte_order:
+ * @stream: a given #GDataInputStream.
*
- * Obtains the information whether the #GAppInfo can be deleted.
- * See g_app_info_delete().
+ * Gets the byte order for the data input stream.
*
- * Returns: %TRUE if @appinfo can be deleted
- * Since: 2.20
+ * Returns: the @stream's current #GDataStreamByteOrder.
*/
/**
- * g_app_info_can_remove_supports_type:
- * @appinfo: a #GAppInfo.
- *
- * Checks if a supported content type can be removed from an application.
+ * g_data_input_stream_get_newline_type:
+ * @stream: a given #GDataInputStream.
*
- * content types from a given @appinfo, %FALSE if not.
+ * Gets the current newline type for the @stream.
*
- * Returns: %TRUE if it is possible to remove supported
+ * Returns: #GDataStreamNewlineType for the given @stream.
*/
/**
- * g_app_info_create_from_commandline:
- * @commandline: the commandline to use
- * @application_name: (allow-none): the application name, or %NULL to use @commandline
- * @flags: flags that can specify details of the created #GAppInfo
- * @error: a #GError location to store the error occurring, %NULL to ignore.
+ * g_data_input_stream_new:
+ * @base_stream: a #GInputStream.
*
- * Creates a new #GAppInfo from the given information.
+ * Creates a new data input stream for the @base_stream.
*
- * Returns: (transfer full): new #GAppInfo for given command.
+ * Returns: a new #GDataInputStream.
*/
/**
- * g_app_info_delete:
- * @appinfo: a #GAppInfo
- *
- * Tries to delete a #GAppInfo.
+ * g_data_input_stream_read_byte:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * 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().
+ * Reads an unsigned 8-bit/1-byte value from @stream.
*
- * Virtual: do_delete
- * Returns: %TRUE if @appinfo has been deleted
- * Since: 2.20
+ * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
+ * if an error occurred.
*/
/**
- * g_app_info_dup:
- * @appinfo: a #GAppInfo.
+ * g_data_input_stream_read_int16:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Creates a duplicate of a #GAppInfo.
+ * Reads a 16-bit/2-byte value from @stream.
*
- * Returns: (transfer full): a duplicate of @appinfo.
+ * 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.
*/
/**
- * g_app_info_equal:
- * @appinfo1: the first #GAppInfo.
- * @appinfo2: the second #GAppInfo.
+ * g_data_input_stream_read_int32:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
+ *
+ * Reads a signed 32-bit/4-byte value from @stream.
*
- * Checks if two #GAppInfo<!-- -->s are equal.
+ * 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: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
+ * 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 signed 32-bit/4-byte value read from the @stream or %0 if
+ * an error occurred.
*/
/**
- * g_app_info_get_all:
+ * g_data_input_stream_read_int64:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Gets a list of all of the applications currently registered
- * on this system.
+ * Reads a 64-bit/8-byte value from @stream.
*
- * 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().
- * The returned list does not include applications which have
- * the <literal>Hidden</literal> key set.
+ * 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().
+ *
+ * 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: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
+ * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
+ * an error occurred.
*/
/**
- * g_app_info_get_all_for_type:
- * @content_type: the content type to find a #GAppInfo for
+ * g_data_input_stream_read_line:
+ * @stream: a given #GDataInputStream.
+ * @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.
*
- * Gets a list of all #GAppInfos for a given content type,
- * including the recommended and fallback #GAppInfos. See
- * g_app_info_get_recommended_for_type() and
- * g_app_info_get_fallback_for_type().
+ * Reads a line from the data input stream. Note that no encoding
+ * checks or conversion is performed; the input is not guaranteed to
+ * be UTF-8, and may in fact have embedded NUL characters.
*
- * for given @content_type or %NULL on 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.
*
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * 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_app_info_get_commandline:
- * @appinfo: a #GAppInfo
+ * g_data_input_stream_read_line_async:
+ * @stream: a given #GDataInputStream.
+ * @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.
*
- * Gets the commandline with which the application will be
- * started.
+ * The asynchronous version of g_data_input_stream_read_line(). It is
+ * an error to have two outstanding calls to this function.
*
- * or %NULL if this information is not available
+ * When the operation is finished, @callback will be called. You
+ * can then call g_data_input_stream_read_line_finish() to get
+ * the result of the operation.
*
- * Returns: a string containing the @appinfo's commandline,
* 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
- *
- * Gets the default #GAppInfo for a given content type.
+ * g_data_input_stream_read_line_finish:
+ * @stream: a given #GDataInputStream.
+ * @result: the #GAsyncResult that was provided to the callback.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @error: #GError for error reporting.
*
- * %NULL on error.
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_line_async(). Note the warning about
+ * string encoding in g_data_input_stream_read_line() applies here as
+ * well.
*
- * Returns: (transfer full): #GAppInfo for given @content_type or
+ * 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
*/
/**
- * g_app_info_get_default_for_uri_scheme:
- * @uri_scheme: a string containing a URI scheme.
+ * g_data_input_stream_read_line_finish_utf8:
+ * @stream: a given #GDataInputStream.
+ * @result: the #GAsyncResult that was provided to the callback.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @error: #GError for error reporting.
*
- * Gets the default application for handling URIs with
- * the given URI scheme. A URI scheme is the initial part
- * of the URI, up to but not including the ':', e.g. "http",
- * "ftp" or "sip".
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_line_async().
*
- * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
+ * 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
*/
/**
- * g_app_info_get_description:
- * @appinfo: a #GAppInfo.
+ * g_data_input_stream_read_line_utf8:
+ * @stream: a given #GDataInputStream.
+ * @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.
*
- * Gets a human-readable description of an installed application.
+ * Reads a UTF-8 encoded line from the data input stream.
*
- * application @appinfo, or %NULL if none.
+ * 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 string containing a description of the
+ * 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
*/
/**
- * g_app_info_get_display_name:
- * @appinfo: a #GAppInfo.
+ * g_data_input_stream_read_uint16:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Gets the display name of the application. The display name is often more
- * descriptive to the user than the name itself.
+ * Reads an unsigned 16-bit/2-byte value from @stream.
*
- * no display name is available.
+ * 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: the display name of the application for @appinfo, or the name if
- * Since: 2.24
+ * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
+ * an error occurred.
*/
/**
- * g_app_info_get_executable:
- * @appinfo: a #GAppInfo
+ * g_data_input_stream_read_uint32:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Gets the executable's name for the installed application.
+ * Reads an unsigned 32-bit/4-byte value from @stream.
*
- * binaries name
+ * 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 string containing the @appinfo's application
+ * 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: an unsigned 32-bit/4-byte value read from the @stream or %0 if
+ * an error occurred.
*/
/**
- * g_app_info_get_fallback_for_type:
- * @content_type: the content type to find a #GAppInfo for
+ * g_data_input_stream_read_uint64:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Gets a list of fallback #GAppInfos for a given content type, i.e.
- * those applications which claim to support the given content type
- * by MIME type subclassing and not directly.
+ * Reads an unsigned 64-bit/8-byte value from @stream.
*
- * for given @content_type or %NULL on error.
+ * In order to get the correct byte order for this read operation,
+ * see g_data_input_stream_get_byte_order().
*
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
- * Since: 2.28
+ * 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: an unsigned 64-bit/8-byte read from @stream or %0 if
+ * an error occurred.
*/
/**
- * g_app_info_get_icon:
- * @appinfo: a #GAppInfo.
+ * g_data_input_stream_read_until:
+ * @stream: a given #GDataInputStream.
+ * @stop_chars: characters to terminate the read.
+ * @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.
*
- * Gets the icon for the application.
+ * Reads a string from the data input stream, up to the first
+ * occurrence of any of the stop characters.
*
- * if there is no default icon.
+ * Note that, in contrast to g_data_input_stream_read_until_async(),
+ * this function consumes the stop character that it finds.
*
- * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
+ * Don't use this function in new code. Its functionality is
+ * inconsistent with g_data_input_stream_read_until_async(). Both
+ * functions will be marked as deprecated in a future release. Use
+ * 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.
*/
/**
- * g_app_info_get_id:
- * @appinfo: a #GAppInfo.
+ * g_data_input_stream_read_until_async:
+ * @stream: a given #GDataInputStream.
+ * @stop_chars: characters to terminate the read.
+ * @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.
*
- * Gets the ID of an application. An id is a string that
- * identifies the application. The exact format of the id is
- * platform dependent. For instance, on Unix this is the
- * desktop file id from the xdg menu specification.
+ * The asynchronous version of g_data_input_stream_read_until().
+ * It is an error to have two outstanding calls to this function.
*
- * Note that the returned ID may be %NULL, depending on how
- * the @appinfo has been constructed.
+ * Note that, in contrast to g_data_input_stream_read_until(),
+ * this function does not consume the stop character that it finds. You
+ * must read it for yourself.
*
- * Returns: a string containing the application's ID.
- */
-
-
-/**
- * g_app_info_get_name:
- * @appinfo: a #GAppInfo.
+ * When the operation is finished, @callback will be called. You
+ * can then call g_data_input_stream_read_until_finish() to get
+ * the result of the operation.
*
- * Gets the installed name of the application.
+ * Don't use this function in new code. Its functionality is
+ * inconsistent with g_data_input_stream_read_until(). Both functions
+ * will be marked as deprecated in a future release. Use
+ * g_data_input_stream_read_upto_async() instead.
*
- * Returns: the name of the application for @appinfo.
+ * Since: 2.20
*/
/**
- * g_app_info_get_recommended_for_type:
- * @content_type: the content type to find a #GAppInfo for
- *
- * Gets a list of recommended #GAppInfos for a given content type, i.e.
- * those applications which claim to support the given content type exactly,
- * and not by MIME type subclassing.
- * Note that the first application of the list is the last used one, i.e.
- * the last one for which g_app_info_set_as_last_used_for_type() has been
- * called.
+ * g_data_input_stream_read_until_finish:
+ * @stream: a given #GDataInputStream.
+ * @result: the #GAsyncResult that was provided to the callback.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @error: #GError for error reporting.
*
- * for given @content_type or %NULL on error.
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_until_async().
*
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
- * Since: 2.28
+ * 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.
*/
/**
- * g_app_info_launch:
- * @appinfo: a #GAppInfo
- * @files: (element-type GFile): a #GList of #GFile objects
- * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
- * @error: a #GError
- *
- * Launches the application. Passes @files to the launched application
- * as arguments, using the optional @launch_context to get information
- * about the details of the launcher (like what screen it is on).
- * On error, @error will be set accordingly.
- *
- * To launch the application without arguments pass a %NULL @files list.
- *
- * Note that even if the launch is successful the application launched
- * can fail to start if it runs into problems during startup. There is
- * no way to detect this.
+ * 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
+ * @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
*
- * Some URIs can be changed when passed through a GFile (for instance
- * unsupported URIs with strange formats like mailto:), so if you have
- * a textual URI you want to pass in as argument, consider using
- * g_app_info_launch_uris() instead.
+ * Reads a string from the data input stream, up to the first
+ * occurrence of any of the stop characters.
*
- * 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().
+ * In contrast to g_data_input_stream_read_until(), 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() again.
*
- * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
- * 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.
+ * Note that @stop_chars may contain '\0' if @stop_chars_len is
+ * specified.
*
- * Returns: %TRUE on successful launch, %FALSE otherwise.
+ * 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_app_info_launch_default_for_uri:
- * @uri: the uri to show
- * @launch_context: (allow-none): an optional #GAppLaunchContext.
- * @error: a #GError.
+ * 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 [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
*
- * Utility function that launches the default application
- * registered to handle the specified uri. Synchronous I/O
- * is done on the uri to detect the type of the file if
- * required.
+ * The asynchronous version of g_data_input_stream_read_upto().
+ * It is an error to have two outstanding calls to this function.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * In contrast to g_data_input_stream_read_until(), 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() again.
+ *
+ * Note that @stop_chars may contain '\0' if @stop_chars_len is
+ * specified.
+ *
+ * When the operation is finished, @callback will be called. You
+ * can then call g_data_input_stream_read_upto_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.26
*/
/**
- * g_app_info_launch_uris:
- * @appinfo: a #GAppInfo
- * @uris: (element-type utf8): a #GList containing URIs to launch.
- * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
- * @error: a #GError
- *
- * Launches the application. This passes the @uris to the launched application
- * as arguments, using the optional @launch_context to get information
- * about the details of the launcher (like what screen it is on).
- * On error, @error will be set accordingly.
+ * g_data_input_stream_read_upto_finish:
+ * @stream: a #GDataInputStream
+ * @result: the #GAsyncResult that was provided to the callback
+ * @length: (out): a #gsize to get the length of the data read in
+ * @error: #GError for error reporting
*
- * To launch the application without arguments pass a %NULL @uris list.
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_upto_async().
*
- * Note that even if the launch is successful the application launched
- * can fail to start if it runs into problems during startup. There is
- * no way to detect this.
+ * 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: %TRUE on successful launch, %FALSE otherwise.
+ * 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_app_info_remove_supports_type:
- * @appinfo: a #GAppInfo.
- * @content_type: a string.
- * @error: a #GError.
- *
- * Removes a supported type from an application, if possible.
+ * g_data_input_stream_set_byte_order:
+ * @stream: a given #GDataInputStream.
+ * @order: a #GDataStreamByteOrder to set.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * This function sets the byte order for the given @stream. All subsequent
+ * reads from the @stream will be read in the given @order.
*/
/**
- * g_app_info_reset_type_associations:
- * @content_type: a content type
+ * g_data_input_stream_set_newline_type:
+ * @stream: a #GDataInputStream.
+ * @type: the type of new line return as #GDataStreamNewlineType.
*
- * Removes all changes to the type associations done by
- * g_app_info_set_as_default_for_type(),
- * g_app_info_set_as_default_for_extension(),
- * g_app_info_add_supports_type() or
- * g_app_info_remove_supports_type().
+ * Sets the newline type for the @stream.
*
- * Since: 2.20
+ * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
+ * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
+ * "CR LF", and this might block if there is no more data available.
*/
/**
- * g_app_info_set_as_default_for_extension:
- * @appinfo: a #GAppInfo.
- * @extension: a string containing the file extension (without the dot).
- * @error: a #GError.
+ * g_data_output_stream_get_byte_order:
+ * @stream: a #GDataOutputStream.
*
- * Sets the application as the default handler for the given file extension.
+ * Gets the byte order for the stream.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: the #GDataStreamByteOrder for the @stream.
*/
/**
- * g_app_info_set_as_default_for_type:
- * @appinfo: a #GAppInfo.
- * @content_type: the content type.
- * @error: a #GError.
+ * g_data_output_stream_new:
+ * @base_stream: a #GOutputStream.
*
- * Sets the application as the default handler for a given type.
+ * Creates a new data output stream for @base_stream.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: #GDataOutputStream.
*/
/**
- * g_app_info_set_as_last_used_for_type:
- * @appinfo: a #GAppInfo.
- * @content_type: the content type.
- * @error: a #GError.
+ * g_data_output_stream_put_byte:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guchar.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Sets the application as the last used application for a given type.
- * This will make the application appear as first in the list returned
- * by g_app_info_get_recommended_for_type(), regardless of the default
- * application for that content type.
+ * Puts a byte into the output stream.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_app_info_should_show:
- * @appinfo: a #GAppInfo.
+ * g_data_output_stream_put_int16:
+ * @stream: a #GDataOutputStream.
+ * @data: a #gint16.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Checks if the application info should be shown in menus that
- * list available applications.
+ * Puts a signed 16-bit integer into the output stream.
*
- * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_app_info_supports_files:
- * @appinfo: a #GAppInfo.
+ * g_data_output_stream_put_int32:
+ * @stream: a #GDataOutputStream.
+ * @data: a #gint32.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Checks if the application accepts files as arguments.
+ * Puts a signed 32-bit integer into the output stream.
*
- * Returns: %TRUE if the @appinfo supports files.
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_app_info_supports_uris:
- * @appinfo: a #GAppInfo.
+ * g_data_output_stream_put_int64:
+ * @stream: a #GDataOutputStream.
+ * @data: a #gint64.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Checks if the application supports reading files and directories from URIs.
+ * Puts a signed 64-bit integer into the stream.
*
- * Returns: %TRUE if the @appinfo supports URIs.
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_app_launch_context_get_display:
- * @context: a #GAppLaunchContext
- * @info: a #GAppInfo
- * @files: (element-type GFile): a #GList of #GFile objects
+ * g_data_output_stream_put_string:
+ * @stream: a #GDataOutputStream.
+ * @str: a string.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * 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.
+ * Puts a string into the output stream.
*
- * Returns: a display string for the display.
+ * Returns: %TRUE if @string was successfully added to the @stream.
*/
/**
- * g_app_launch_context_get_environment:
- * @context: a #GAppLaunchContext
- *
- * 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>.
+ * g_data_output_stream_put_uint16:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guint16.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * child's environment
+ * Puts an unsigned 16-bit integer into the output stream.
*
- * Returns: (array zero-terminated=1) (transfer full): the
- * Since: 2.32
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_app_launch_context_get_startup_notify_id:
- * @context: a #GAppLaunchContext
- * @info: a #GAppInfo
- * @files: (element-type GFile): a #GList of of #GFile objects
+ * g_data_output_stream_put_uint32:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guint32.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Initiates startup notification for the application and returns the
- * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
- * if supported.
+ * Puts an unsigned 32-bit integer into the stream.
*
- * 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>.
+ * Returns: %TRUE if @data was successfully added to the @stream.
+ */
+
+
+/**
+ * g_data_output_stream_put_uint64:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guint64.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * not supported.
+ * Puts an unsigned 64-bit integer into the stream.
*
- * Returns: a startup notification ID for the application, or %NULL if
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_app_launch_context_launch_failed:
- * @context: a #GAppLaunchContext.
- * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
+ * g_data_output_stream_set_byte_order:
+ * @stream: a #GDataOutputStream.
+ * @order: a %GDataStreamByteOrder.
*
- * Called when an application has failed to launch, so that it can cancel
- * the application startup notification started in g_app_launch_context_get_startup_notify_id().
+ * Sets the byte order of the data output stream to @order.
*/
/**
- * g_app_launch_context_new:
+ * g_dbus_action_group_get:
+ * @connection: A #GDBusConnection
+ * @bus_name: the bus name which exports the action group
+ * @object_path: the object path at which the action group is exported
*
- * Creates a new application launch context. This is not normally used,
- * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
+ * Obtains a #GDBusActionGroup for the action group which is exported at
+ * the given @bus_name and @object_path.
*
- * Returns: a #GAppLaunchContext.
+ * The thread default main context is taken at the time of this call.
+ * All signals on the menu model (and any linked models) are reported
+ * with respect to this context. All calls on the returned menu model
+ * (and linked models) must also originate from this same context, with
+ * the thread default main context unchanged.
+ *
+ * This call is non-blocking. The returned action group may or may not
+ * already be filled in. The correct thing to do is connect the signals
+ * for the action group to monitor for changes and then to call
+ * g_action_group_list_actions() to get the initial list.
+ *
+ * Returns: (transfer full): a #GDBusActionGroup
+ * Since: 2.32
*/
/**
- * g_app_launch_context_setenv:
- * @context: a #GAppLaunchContext
- * @variable: the environment variable to set
- * @value: the value for to set the variable to.
+ * 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
*
- * Arranges for @variable to be set to @value in the child's
- * environment when @context is used to launch an application.
+ * Escape @string so it can appear in a D-Bus address as the value
+ * part of a key-value pair.
*
- * Since: 2.32
+ * 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_app_launch_context_unsetenv:
- * @context: a #GAppLaunchContext
- * @variable: the environment variable to remove
+ * 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
*
- * Arranges for @variable to be unset in the child's environment
- * when @context is used to launch an application.
+ * 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.
*
- * Since: 2.32
+ * Returns: a valid D-Bus address string for @bus_type or %NULL if
+ * @error is set
+ * Since: 2.26
*/
/**
- * g_application_activate:
- * @application: a #GApplication
+ * g_dbus_address_get_stream:
+ * @address: A valid D-Bus address.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: Data to pass to @callback.
*
- * Activates the application.
+ * Asynchronously connects to an endpoint specified by @address and
+ * sets up the connection so it is in a state to run the client-side
+ * of the D-Bus authentication conversation.
*
- * In essence, this results in the #GApplication::activate() signal being
- * emitted in the primary instance.
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_dbus_address_get_stream_finish() to get the result of
+ * the operation.
*
- * The application must be registered before calling this function.
+ * This is an asynchronous failable function. See
+ * g_dbus_address_get_stream_sync() for the synchronous version.
*
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * g_application_command_line_get_arguments:
- * @cmdline: a #GApplicationCommandLine
- * @argc: (out): the length of the arguments array, or %NULL
+ * g_dbus_address_get_stream_finish:
+ * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
+ * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
+ * @error: Return location for error or %NULL.
*
- * Gets the list of arguments that was passed on the command line.
+ * Finishes an operation started with g_dbus_address_get_stream().
*
- * The strings in the array may contain non-utf8 data.
+ * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_address_get_stream_sync:
+ * @address: A valid D-Bus address.
+ * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * The return value is %NULL-terminated and should be freed using
- * g_strfreev().
+ * Synchronously connects to an endpoint specified by @address and
+ * sets up the connection so it is in a state to run the client-side
+ * of the D-Bus authentication conversation.
*
- * containing the arguments (the argv)
+ * This is a synchronous failable function. See
+ * g_dbus_address_get_stream() for the asynchronous version.
*
- * Returns: (array length=argc) (transfer full): the string array
- * Since: 2.28
+ * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
+ * Since: 2.26
*/
/**
- * g_application_command_line_get_cwd:
- * @cmdline: a #GApplicationCommandLine
- *
- * Gets the working directory of the command line invocation.
- * The string may contain non-utf8 data.
+ * g_dbus_annotation_info_lookup:
+ * @annotations: (array zero-terminated=1) (allow-none): A %NULL-terminated array of annotations or %NULL.
+ * @name: The name of the annotation to look up.
*
- * It is possible that the remote application did not send a working
- * directory, so this may be %NULL.
+ * Looks up the value of an annotation.
*
- * The return value should not be modified or freed and is valid for as
- * long as @cmdline exists.
+ * The cost of this function is O(n) in number of annotations.
*
- * Returns: the current directory, or %NULL
- * Since: 2.28
+ * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
+ * Since: 2.26
*/
/**
- * g_application_command_line_get_environ:
- * @cmdline: a #GApplicationCommandLine
- *
- * Gets the contents of the 'environ' variable of the command line
- * invocation, as would be returned by g_get_environ(), ie as a
- * %NULL-terminated list of strings in the form 'NAME=VALUE'.
- * The strings may contain non-utf8 data.
- *
- * The remote application usually does not send an environment. Use
- * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
- * set it is possible that the environment is still not available (due
- * to invocation messages from other applications).
- *
- * The return value should not be modified or freed and is valid for as
- * long as @cmdline exists.
- *
- * See g_application_command_line_getenv() if you are only interested
- * in the value of a single environment variable.
+ * g_dbus_annotation_info_ref:
+ * @info: A #GDBusNodeInfo
*
- * strings, or %NULL if they were not sent
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: (array zero-terminated=1) (transfer none): the environment
- * Since: 2.28
+ * Returns: The same @info.
+ * Since: 2.26
*/
/**
- * g_application_command_line_get_exit_status:
- * @cmdline: a #GApplicationCommandLine
+ * g_dbus_annotation_info_unref:
+ * @info: A #GDBusAnnotationInfo.
*
- * Gets the exit status of @cmdline. See
- * g_application_command_line_set_exit_status() for more information.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: the exit status
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * g_application_command_line_get_is_remote:
- * @cmdline: a #GApplicationCommandLine
+ * g_dbus_arg_info_ref:
+ * @info: A #GDBusArgInfo
*
- * Determines if @cmdline represents a remote invocation.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: %TRUE if the invocation was remote
- * Since: 2.28
+ * Returns: The same @info.
+ * Since: 2.26
*/
/**
- * g_application_command_line_get_platform_data:
- * @cmdline: #GApplicationCommandLine
- *
- * Gets the platform data associated with the invocation of @cmdline.
- *
- * This is a #GVariant dictionary containing information about the
- * context in which the invocation occurred. It typically contains
- * information like the current working directory and the startup
- * notification ID.
+ * g_dbus_arg_info_unref:
+ * @info: A #GDBusArgInfo.
*
- * For local invocation, it will be %NULL.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: the platform data, or %NULL
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * g_application_command_line_getenv:
- * @cmdline: a #GApplicationCommandLine
- * @name: the environment variable to get
+ * g_dbus_auth_observer_allow_mechanism:
+ * @observer: A #GDBusAuthObserver.
+ * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
*
- * Gets the value of a particular environment variable of the command
- * line invocation, as would be returned by g_getenv(). The strings may
- * contain non-utf8 data.
+ * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
*
- * The remote application usually does not send an environment. Use
- * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
- * set it is possible that the environment is still not available (due
- * to invocation messages from other applications).
+ * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
+ * Since: 2.34
+ */
+
+
+/**
+ * g_dbus_auth_observer_authorize_authenticated_peer:
+ * @observer: A #GDBusAuthObserver.
+ * @stream: A #GIOStream for the #GDBusConnection.
+ * @credentials: (allow-none): Credentials received from the peer or %NULL.
*
- * The return value should not be modified or freed and is valid for as
- * long as @cmdline exists.
+ * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
*
- * Returns: the value of the variable, or %NULL if unset or unsent
- * Since: 2.28
+ * Returns: %TRUE if the peer is authorized, %FALSE if not.
+ * Since: 2.26
*/
/**
- * g_application_command_line_print:
- * @cmdline: a #GApplicationCommandLine
- * @format: a printf-style format string
- * @...: arguments, as per @format
- *
- * Formats a message and prints it using the stdout print handler in the
- * invoking process.
+ * g_dbus_auth_observer_new:
*
- * If @cmdline is a local invocation then this is exactly equivalent to
- * g_print(). If @cmdline is remote then this is equivalent to calling
- * g_print() in the invoking process.
+ * Creates a new #GDBusAuthObserver object.
*
- * Since: 2.28
+ * Returns: A #GDBusAuthObserver. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_application_command_line_printerr:
- * @cmdline: a #GApplicationCommandLine
- * @format: a printf-style format string
- * @...: arguments, as per @format
+ * 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
*
- * Formats a message and prints it using the stderr print handler in the
- * invoking process.
+ * Adds a message filter. Filters are handlers that are run on all
+ * incoming and outgoing messages, prior to standard dispatch. Filters
+ * are run in the order that they were added. The same handler can be
+ * added as a filter more than once, in which case it will be run more
+ * than once. Filters added during a filter callback won't be run on
+ * the message being processed. Filter functions are allowed to modify
+ * and even drop messages.
*
- * If @cmdline is a local invocation then this is exactly equivalent to
- * g_printerr(). If @cmdline is remote then this is equivalent to
- * calling g_printerr() in the invoking process.
+ * Note that filters are run in a dedicated message handling thread so
+ * they can't block and, generally, can't do anything but signal a
+ * worker thread. Also note that filters are rarely needed - use API
+ * such as g_dbus_connection_send_message_with_reply(),
+ * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
*
- * Since: 2.28
+ * If a filter consumes an incoming message the message is not
+ * dispatched anywhere else - not even the standard dispatch machinery
+ * (that API such as g_dbus_connection_signal_subscribe() and
+ * g_dbus_connection_send_message_with_reply() relies on) will see the
+ * 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()
+ * Since: 2.26
*/
/**
- * g_application_command_line_set_exit_status:
- * @cmdline: a #GApplicationCommandLine
- * @exit_status: the exit status
+ * 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
*
- * Sets the exit status that will be used when the invoking process
- * exits.
+ * Asynchronously invokes the @method_name method on the
+ * @interface_name D-Bus interface on the remote object at
+ * @object_path owned by @bus_name.
*
- * The return value of the #GApplication::command-line signal is
- * passed to this function when the handler returns. This is the usual
- * way of setting the exit status.
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
+ * not compatible with the D-Bus protocol, the operation fails with
+ * %G_IO_ERROR_INVALID_ARGUMENT.
*
- * In the event that you want the remote invocation to continue running
- * and want to decide on the exit status in the future, you can use this
- * call. For the case of a remote invocation, the remote process will
- * typically exit when the last reference is dropped on @cmdline. The
- * exit status of the remote process will be equal to the last value
- * that was set with this function.
+ * If @reply_type is non-%NULL then the reply will be checked for having this type and an
+ * error will be raised if it does not match. Said another way, if you give a @reply_type
+ * then any non-%NULL return value will be of this type.
*
- * In the case that the commandline invocation is local, the situation
- * is slightly more complicated. If the commandline invocation results
- * in the mainloop running (ie: because the use-count of the application
- * increased to a non-zero value) then the application is considered to
- * have been 'successful' in a certain sense, and the exit status is
- * always zero. If the application use count is zero, though, the exit
- * status of the local #GApplicationCommandLine is used.
+ * 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",
+ * "org.freedesktop.StringThings",
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * NULL,
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * (GAsyncReadyCallback) two_strings_done,
+ * NULL);
+ * ]|
*
- * Since: 2.28
+ * 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
+ * function.
+ *
+ * If @callback is %NULL then the D-Bus method call message will be sent with
+ * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
+ *
+ * Since: 2.26
*/
/**
- * g_application_get_application_id:
- * @application: a #GApplication
+ * 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
*
- * Gets the unique identifier for @application.
+ * Finishes an operation started with g_dbus_connection_call().
*
- * Returns: the identifier for @application, owned by @application
- * Since: 2.28
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
+ * Since: 2.26
*/
/**
- * g_application_get_default:
- * @returns: (transfer none): the default application for this process, or %NULL
+ * g_dbus_connection_call_sync:
+ * @connection: a #GDBusConnection
+ * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
+ * @connection is not a message bus connection
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to invoke method on
+ * @method_name: the name of the method to invoke
+ * @parameters: (allow-none): a #GVariant tuple with parameters for the method
+ * or %NULL if not passing parameters
+ * @reply_type: (allow-none): the expected type of the reply, or %NULL
+ * @flags: flags from the #GDBusCallFlags enumeration
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ * timeout or %G_MAXINT for no timeout
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
*
- * Returns the default #GApplication instance for this process.
+ * Synchronously invokes the @method_name method on the
+ * @interface_name D-Bus interface on the remote object at
+ * @object_path owned by @bus_name.
*
- * Normally there is only one #GApplication per process and it becomes
- * the default when it is created. You can exercise more control over
- * this by using g_application_set_default().
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
+ * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
+ * contains a value not compatible with the D-Bus protocol, the operation
+ * fails with %G_IO_ERROR_INVALID_ARGUMENT.
*
- * If there is no default application then %NULL is returned.
+ * If @reply_type is non-%NULL then the reply will be checked for having
+ * this type and an error will be raised if it does not match. Said
+ * another way, if you give a @reply_type then any non-%NULL return
+ * value will be of this type.
*
- * Since: 2.32
+ * 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",
+ * "org.freedesktop.StringThings",
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * NULL,
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * &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().
+ * Since: 2.26
*/
-/**
- * g_application_get_flags:
- * @application: a #GApplication
+/**
+ * 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
+ * @user_data: The data to pass to @callback.
*
- * Gets the flags for @application.
+ * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
*
- * See #GApplicationFlags.
+ * This method is only available on UNIX.
*
- * Returns: the flags for @application
- * Since: 2.28
+ * Since: 2.30
*/
/**
- * g_application_get_inactivity_timeout:
- * @application: a #GApplication
- *
- * Gets the current inactivity timeout for the application.
+ * 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
*
- * This is the amount of time (in milliseconds) after the last call to
- * g_application_release() before the application stops running.
+ * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
*
- * Returns: the timeout, in milliseconds
- * Since: 2.28
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
+ * Since: 2.30
*/
/**
- * g_application_get_is_registered:
- * @application: a #GApplication
+ * g_dbus_connection_call_with_unix_fd_list_sync:
+ * @connection: a #GDBusConnection
+ * @bus_name: (allow-none): a unique or well-known bus name or %NULL
+ * if @connection is not a message bus connection
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to invoke method on
+ * @method_name: the name of the method to invoke
+ * @parameters: (allow-none): a #GVariant tuple with parameters for
+ * the method or %NULL if not passing parameters
+ * @reply_type: (allow-none): the expected type of the reply, or %NULL
+ * @flags: flags from the #GDBusCallFlags enumeration
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ * timeout or %G_MAXINT for no timeout
+ * @fd_list: (allow-none): a #GUnixFDList or %NULL
+ * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
*
- * Checks if @application is registered.
+ * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
*
- * An application is registered if g_application_register() has been
- * successfully called.
+ * This method is only available on UNIX.
*
- * Returns: %TRUE if @application is registered
- * Since: 2.28
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
+ * Since: 2.30
*/
/**
- * g_application_get_is_remote:
- * @application: a #GApplication
+ * 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
*
- * Checks if @application is remote.
+ * Closes @connection. Note that this never causes the process to
+ * exit (this might only happen if the other end of a shared message
+ * bus connection disconnects, see #GDBusConnection:exit-on-close).
*
- * If @application is remote then it means that another instance of
- * application already exists (the 'primary' instance). Calls to
- * perform actions on @application will result in the actions being
- * performed by the primary instance.
+ * Once the connection is closed, operations such as sending a message
+ * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
+ * will not automatically flush the connection so queued messages may
+ * be lost. Use g_dbus_connection_flush() if you need such guarantees.
*
- * The value of this property cannot be accessed before
- * g_application_register() has been called. See
- * g_application_get_is_registered().
+ * If @connection is already closed, this method fails with
+ * %G_IO_ERROR_CLOSED.
*
- * Returns: %TRUE if @application is remote
- * Since: 2.28
+ * When @connection has been closed, the #GDBusConnection::closed
+ * 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
+ * [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
+ * version.
+ *
+ * Since: 2.26
*/
/**
- * g_application_hold:
- * @application: a #GApplication
- *
- * Increases the use count of @application.
+ * 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
*
- * Use this function to indicate that the application has a reason to
- * continue to run. For example, g_application_hold() is called by GTK+
- * when a toplevel window is on the screen.
+ * Finishes an operation started with g_dbus_connection_close().
*
- * To cancel the hold, call g_application_release().
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
+ * Since: 2.26
*/
/**
- * g_application_id_is_valid:
- * @application_id: a potential application identifier
- *
- * Checks if @application_id is a valid application identifier.
- *
- * A valid ID is required for calls to g_application_new() and
- * g_application_set_application_id().
+ * g_dbus_connection_close_sync:
+ * @connection: a #GDBusConnection
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
*
- * 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>
+ * 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 @application_id is valid
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
+ * Since: 2.26
*/
/**
- * g_application_new:
- * @application_id: the application id
- * @flags: the application flags
+ * 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
*
- * Creates a new #GApplication instance.
+ * Emits a signal.
*
- * This function calls g_type_init() for you.
+ * If the parameters GVariant is floating, it is consumed.
*
- * The application id must be valid. See g_application_id_is_valid().
+ * This can only fail if @parameters is not compatible with the D-Bus protocol.
*
- * Returns: a new #GApplication instance
+ * Returns: %TRUE unless @error is set
+ * Since: 2.26
*/
/**
- * g_application_open:
- * @application: a #GApplication
- * @files: (array length=n_files): an array of #GFiles to open
- * @n_files: the length of the @files array
- * @hint: a hint (or ""), but never %NULL
+ * g_dbus_connection_export_action_group:
+ * @connection: a #GDBusConnection
+ * @object_path: a D-Bus object path
+ * @action_group: a #GActionGroup
+ * @error: a pointer to a %NULL #GError, or %NULL
*
- * Opens the given files.
+ * Exports @action_group on @connection at @object_path.
*
- * In essence, this results in the #GApplication::open signal being emitted
- * in the primary instance.
+ * The implemented D-Bus API should be considered private. It is
+ * subject to change in the future.
*
- * @n_files must be greater than zero.
+ * A given object path can only have one action group exported on it.
+ * If this constraint is violated, the export will fail and 0 will be
+ * returned (with @error set accordingly).
*
- * @hint is simply passed through to the ::open signal. It is
- * intended to be used by applications that have multiple modes for
- * opening files (eg: "view" vs "edit", etc). Unless you have a need
- * for this functionality, you should use "".
+ * You can unexport the action group using
+ * g_dbus_connection_unexport_action_group() with the return value of
+ * this function.
*
- * The application must be registered before calling this function
- * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
+ * The thread default main context is taken at the time of this call.
+ * All incoming action activations and state change requests are
+ * reported from this context. Any changes on the action group that
+ * cause it to emit signals must also come from this same context.
+ * Since incoming action activations and state change requests are
+ * rather likely to cause changes on the action group, this effectively
+ * limits a given action group to being exported from only one main
+ * context.
*
- * Since: 2.28
+ * Returns: the ID of the export (never zero), or 0 in case of failure
+ * Since: 2.32
*/
/**
- * g_application_register:
- * @application: a #GApplication
- * @cancellable: a #GCancellable, or %NULL
- * @error: a pointer to a NULL #GError, or %NULL
- *
- * Attempts registration of the application.
- *
- * This is the point at which the application discovers if it is the
- * primary instance or merely acting as a remote for an already-existing
- * primary instance. This is implemented by attempting to acquire the
- * application identifier as a unique bus name on the session bus using
- * GDBus.
- *
- * Due to the internal architecture of GDBus, method calls can be
- * dispatched at any time (even if a main loop is not running). For
- * this reason, you must ensure that any object paths that you wish to
- * register are registered before calling this function.
+ * g_dbus_connection_export_menu_model:
+ * @connection: a #GDBusConnection
+ * @object_path: a D-Bus object path
+ * @menu: a #GMenuModel
+ * @error: return location for an error, or %NULL
*
- * If the application has already been registered then %TRUE is
- * returned with no work performed.
+ * Exports @menu on @connection at @object_path.
*
- * The #GApplication::startup signal is emitted if registration succeeds
- * and @application is the primary instance.
+ * The implemented D-Bus API should be considered private.
+ * It is subject to change in the future.
*
- * In the event of an error (such as @cancellable being cancelled, or a
- * failure to connect to the session bus), %FALSE is returned and @error
- * is set appropriately.
+ * 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).
*
- * Note: the return value of this function is not an indicator that this
- * instance is or is not the primary instance of the application. See
- * g_application_get_is_remote() for that.
+ * You can unexport the menu model using
+ * g_dbus_connection_unexport_menu_model() with the return value of
+ * this function.
*
- * Returns: %TRUE if registration succeeded
- * Since: 2.28
+ * Returns: the ID of the export (never zero), or 0 in case of failure
+ * Since: 2.32
*/
/**
- * g_application_release:
- * @application: a #GApplication
+ * 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
*
- * Decrease the use count of @application.
+ * 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 guaranteed that the message has
+ * been sent to the networking buffers in the OS kernel.
*
- * When the use count reaches zero, the application will stop running.
+ * 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_flush_finish() to get the result of the
+ * operation. See g_dbus_connection_flush_sync() for the synchronous
+ * version.
*
- * Never call this function except to cancel the effect of a previous
- * call to g_application_hold().
+ * Since: 2.26
*/
/**
- * g_application_run:
- * @application: a #GApplication
- * @argc: the argc from main() (or 0 if @argv is %NULL)
- * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
- *
- * Runs the application.
+ * 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
*
- * This function is intended to be run from main() and its return value
- * 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.
+ * Finishes an operation started with g_dbus_connection_flush().
*
- * 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_HANDLED_COMMAND_LINE and
- * process the commandline arguments in your #GApplication::command-line
- * signal handler, either manually or using the #GOptionContext API.
+ * 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
*
- * 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.
+ * 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.
*
- * 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.
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_connection_get_capabilities:
+ * @connection: a #GDBusConnection
*
- * 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).
+ * Gets the capabilities negotiated with the remote peer
*
- * Returns: the exit status
- * Since: 2.28
+ * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration
+ * Since: 2.26
*/
/**
- * g_application_set_action_group:
- * @application: a #GApplication
- * @action_group: (allow-none): a #GActionGroup, or %NULL
- *
- * This used to be how actions were associated with a #GApplication.
- * Now there is #GActionMap for that.
- *
+ * g_dbus_connection_get_exit_on_close:
+ * @connection: a #GDBusConnection
*
- * 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.
+ * Gets whether the process is terminated when @connection is
+ * closed by the remote peer. See
+ * #GDBusConnection:exit-on-close for more details.
*
- * Since: 2.28
+ * Returns: whether the process is terminated when @connection is
+ * closed by the remote peer
+ * Since: 2.26
*/
/**
- * g_application_set_application_id:
- * @application: a #GApplication
- * @application_id: the identifier for @application
+ * g_dbus_connection_get_guid:
+ * @connection: a #GDBusConnection
*
- * Sets the unique identifier for @application.
+ * The GUID of the peer performing the role of server when
+ * authenticating. See #GDBusConnection:guid for more details.
*
- * The application id can only be modified if @application has not yet
- * been registered.
+ * 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
*
- * The application id must be valid. See g_application_id_is_valid().
+ * Retrieves the last serial number assigned to a #GDBusMessage on
+ * the current thread. This includes messages sent via both low-level
+ * API such as g_dbus_connection_send_message() as well as
+ * high-level API such as g_dbus_connection_emit_signal(),
+ * g_dbus_connection_call() or g_dbus_proxy_call().
*
- * Since: 2.28
+ * Returns: the last used serial or zero when no message has been sent
+ * within the current thread
+ * Since: 2.34
*/
/**
- * g_application_set_default:
- * @application: the application to set as default, or %NULL
+ * g_dbus_connection_get_peer_credentials:
+ * @connection: a #GDBusConnection
*
- * Sets or unsets the default application for the process, as returned
- * by g_application_get_default().
+ * Gets the credentials of the authenticated peer. This will always
+ * return %NULL unless @connection acted as a server
+ * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
+ * when set up and the client passed credentials as part of the
+ * authentication process.
*
- * This function does not take its own reference on @application. If
- * @application is destroyed then the default application will revert
- * back to %NULL.
+ * In a message bus setup, the message bus is always the server and
+ * each application is a client. So this method will always return
+ * %NULL for message bus clients.
*
- * Since: 2.32
+ * Returns: (transfer none): a #GCredentials or %NULL if not available.
+ * Do not free this object, it is owned by @connection.
+ * Since: 2.26
*/
/**
- * g_application_set_flags:
- * @application: a #GApplication
- * @flags: the flags for @application
- *
- * Sets the flags for @application.
+ * g_dbus_connection_get_stream:
+ * @connection: a #GDBusConnection
*
- * The flags can only be modified if @application has not yet been
- * registered.
+ * Gets the underlying stream used for IO.
*
- * See #GApplicationFlags.
+ * While the #GDBusConnection is active, it will interact with this
+ * stream from a worker thread, so it is not safe to interact with
+ * the stream directly.
*
- * Since: 2.28
+ * Returns: (transfer none): the stream used for IO
+ * Since: 2.26
*/
/**
- * g_application_set_inactivity_timeout:
- * @application: a #GApplication
- * @inactivity_timeout: the timeout, in milliseconds
+ * g_dbus_connection_get_unique_name:
+ * @connection: a #GDBusConnection
*
- * Sets the current inactivity timeout for the application.
+ * 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.
*
- * This is the amount of time (in milliseconds) after the last call to
- * g_application_release() before the application stops running.
+ * 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
*
- * This call has no side effects of its own. The value set here is only
- * used for next time g_application_release() drops the use count to
- * zero. Any timeouts currently in progress are not impacted.
+ * Gets whether @connection is closed.
*
- * Since: 2.28
+ * Returns: %TRUE if the connection is closed, %FALSE otherwise
+ * Since: 2.26
*/
/**
- * g_async_initable_init_async:
- * @initable: a #GAsyncInitable.
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * 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 function
+ * @user_data: the data to pass to @callback
*
- * Starts asynchronous initialization of the object implementing the
- * interface. This must be done before any real use of the object after
- * initial construction. If the object also implements #GInitable you can
- * optionally call g_initable_init() instead.
+ * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
+ * with the end represented by @stream.
*
- * When the initialization is finished, @callback will be called. You can
- * then call g_async_initable_init_finish() to get the result of the
- * initialization.
+ * If @stream is a #GSocketConnection, then the corresponding #GSocket
+ * will be put into non-blocking mode.
*
- * Implementations may also support cancellation. If @cancellable is not
- * %NULL, then initialization 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, and
- * the object doesn't support cancellable initialization, the error
- * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+ * The D-Bus connection will interact with @stream from a worker thread.
+ * As a result, the caller should not interact with @stream after this
+ * method has been called, except by calling g_object_unref() on it.
*
- * As with #GInitable, 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. They will often fail with g_critical() or
- * g_warning(), but this must not be relied on.
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
*
- * Implementations of this method must be idempotent: i.e. multiple calls
- * to this function with the same argument should return the same results.
- * Only the first call initializes the object; further calls return the result
- * of the first call. This is so that it's safe to implement the singleton
- * pattern in the GObject constructor function.
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_dbus_connection_new_finish() to get the result of the
+ * operation.
*
- * For classes that also support the #GInitable interface, the default
- * implementation of this method will run the g_initable_init() function
- * in a thread, so if you want to support asynchronous initialization via
- * threads, just implement the #GAsyncInitable interface without overriding
- * any interface methods.
+ * This is a asynchronous failable constructor. See
+ * g_dbus_connection_new_sync() for the synchronous
+ * version.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * g_async_initable_init_finish:
- * @initable: a #GAsyncInitable.
- * @res: a #GAsyncResult.
- * @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().
+ * 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
*
- * will return %FALSE and set @error appropriately if present.
+ * Finishes an operation started with g_dbus_connection_new().
*
- * Returns: %TRUE if successful. If an error has occurred, this function
- * Since: 2.22
+ * Returns: a #GDBusConnection or %NULL if @error is set. Free
+ * with g_object_unref().
+ * Since: 2.26
*/
/**
- * 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.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the initialization is finished
- * @user_data: the data to pass to callback function
- * @first_property_name: 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.
+ * 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
*
- * Helper function for constructing #GAsyncInitable object. This is
- * similar to g_object_new() but also initializes the object asynchronously.
+ * Asynchronously connects and sets up a D-Bus client connection for
+ * exchanging D-Bus messages with an endpoint specified by @address
+ * which must be in the D-Bus address format.
*
- * When the initialization is finished, @callback will be called. You can
- * then call g_async_initable_new_finish() to get the new object and check
- * for any errors.
+ * This constructor can only be used to initiate client-side
+ * connections - use g_dbus_connection_new() if you need to act as the
+ * server. In particular, @flags cannot contain the
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
*
- * Since: 2.22
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_dbus_connection_new_finish() to get the result of the
+ * operation.
+ *
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
+ *
+ * This is a asynchronous failable constructor. See
+ * g_dbus_connection_new_for_address_sync() for the synchronous
+ * version.
+ *
+ * Since: 2.26
*/
/**
- * g_async_initable_new_finish:
- * @initable: the #GAsyncInitable from the callback
- * @res: the #GAsyncResult from the callback
- * @error: return location for errors, or %NULL to ignore
+ * 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
*
- * Finishes the async construction for the various g_async_initable_new
- * calls, returning the created object or %NULL on error.
+ * 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().
+ * 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
*
- * Free with g_object_unref().
+ * Synchronously connects and sets up a D-Bus client connection for
+ * exchanging D-Bus messages with an endpoint specified by @address
+ * which must be in the D-Bus address format.
*
- * Returns: (transfer full): a newly created #GObject, or %NULL on error.
- * Since: 2.22
+ * This constructor can only be used to initiate client-side
+ * connections - use g_dbus_connection_new_sync() if you need to act
+ * as the server. In particular, @flags cannot contain the
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+ *
+ * This is a synchronous failable constructor. See
+ * g_dbus_connection_new_for_address() for the asynchronous version.
+ *
+ * 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().
+ * Since: 2.26
*/
/**
- * 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.
- * @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.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the initialization is finished
- * @user_data: the data to pass to callback function
+ * 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
*
- * Helper function for constructing #GAsyncInitable object. This is
- * similar to g_object_new_valist() but also initializes the object
- * asynchronously.
+ * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
+ * with the end represented by @stream.
*
- * When the initialization is finished, @callback will be called. You can
- * then call g_async_initable_new_finish() to get the new object and check
- * for any errors.
+ * If @stream is a #GSocketConnection, then the corresponding #GSocket
+ * will be put into non-blocking mode.
+ *
+ * The D-Bus connection will interact with @stream from a worker thread.
+ * As a result, the caller should not interact with @stream after this
+ * method has been called, except by calling g_object_unref() on it.
+ *
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
+ *
+ * This is a synchronous failable constructor. See
+ * g_dbus_connection_new() for the asynchronous version.
*
- * Since: 2.22
+ * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_async_initable_newv_async:
- * @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.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the initialization is finished
- * @user_data: the data to pass to callback function
+ * 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
*
- * Helper function for constructing #GAsyncInitable object. This is
- * similar to g_object_newv() but also initializes the object asynchronously.
+ * Registers callbacks for exported objects at @object_path with the
+ * D-Bus interface that is described in @interface_info.
*
- * When the initialization is finished, @callback will be called. You can
- * then call g_async_initable_new_finish() to get the new object and check
- * for any errors.
+ * 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.
*
- * Since: 2.22
- */
-
-
-/**
- * g_async_result_get_source_object:
- * @res: a #GAsyncResult
+ * 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 `org.freedesktop.DBus.Error.InvalidArgs`
+ * is returned to the remote caller.
*
- * Gets the source object from a #GAsyncResult.
+ * Additionally, if the remote caller attempts to invoke methods or
+ * access properties not mentioned in @interface_info the
+ * `org.freedesktop.DBus.Error.UnknownMethod` resp.
+ * `org.freedesktop.DBus.Error.InvalidArgs` errors
+ * are returned to the caller.
*
- * or %NULL if there is none.
+ * It is considered a programming error if the
+ * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
+ * #GVariant of incorrect type.
*
- * Returns: (transfer full): a new reference to the source object for the @res,
- */
-
-
-/**
- * g_async_result_get_user_data:
- * @res: a #GAsyncResult.
+ * If an existing callback is already registered at @object_path and
+ * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
*
- * Gets the user data from a #GAsyncResult.
+ * 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 can implement org.freedesktop.DBus.Properties
+ * yourself, e.g. to handle getting and setting of properties asynchronously.
*
- * Returns: (transfer full): the user data for @res.
+ * 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 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()
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_fill:
- * @stream: a #GBufferedInputStream
- * @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
+ * 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
*
- * Tries to read @count bytes from the stream into the buffer.
- * Will block during this read.
+ * Registers a whole subtree of dynamic objects.
*
- * If @count is zero, returns zero and does nothing. A value of @count
- * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ * The @enumerate and @introspection functions in @vtable are used to
+ * convey, to remote callers, what nodes exist in the subtree rooted
+ * by @object_path.
*
- * On success, the number of bytes read into the buffer is returned.
- * It is not an error if this is not the same as the requested size, as it
- * 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.
+ * When handling remote calls into any node in the subtree, first the
+ * @enumerate function is used to check if the node exists. If the node exists
+ * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
+ * the @introspection function is used to check if the node supports the
+ * requested method. If so, the @dispatch function is used to determine
+ * where to dispatch the call. The collected #GDBusInterfaceVTable and
+ * #gpointer will be used to call into the interface vtable for processing
+ * the request.
*
- * If @count is -1 then the attempted read size is equal to the number of
- * bytes that are required to fill the buffer.
+ * 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 @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.
+ * If an existing subtree is already registered at @object_path or
+ * then @error is set to #G_IO_ERROR_EXISTS.
*
- * On error -1 is returned and @error is set accordingly.
+ * Note that it is valid to register regular objects (using
+ * 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 fallback handler for object paths not
+ * registered via g_dbus_connection_register_object() or other bindings.
*
- * For the asynchronous, non-blocking, version of this function, see
- * g_buffered_input_stream_fill_async().
+ * Note that @vtable will be copied so you cannot change it after
+ * registration.
*
- * or -1 on error.
+ * See this [server][gdbus-subtree-server] for an example of how to use
+ * this method.
*
- * Returns: the number of bytes read into @stream's buffer, up to @count,
+ * 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_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
- * @cancellable: (allow-none): optional #GCancellable object
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): a #gpointer
+ * g_dbus_connection_remove_filter:
+ * @connection: a #GDBusConnection
+ * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
*
- * Reads data into @stream's buffer asynchronously, up to @count size.
- * @io_priority can be used to prioritize reads. For the synchronous
- * version of this function, see g_buffered_input_stream_fill().
+ * Removes a filter.
*
- * If @count is -1 then the attempted read size is equal to the number
- * of bytes that are required to fill the buffer.
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_fill_finish:
- * @stream: a #GBufferedInputStream
- * @result: a #GAsyncResult
- * @error: a #GError
+ * 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
*
- * Finishes an asynchronous read.
+ * Asynchronously sends @message to the peer represented by @connection.
*
- * Returns: a #gssize of the read stream, or %-1 on an error.
- */
-
-
-/**
- * g_buffered_input_stream_get_available:
- * @stream: #GBufferedInputStream
+ * Unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+ * will be assigned by @connection and set on @message via
+ * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+ * serial number used will be written to this location prior to
+ * submitting the message to the underlying transport.
*
- * Gets the size of the available data within the stream.
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
*
- * Returns: size of the available stream.
- */
-
-
-/**
- * g_buffered_input_stream_get_buffer_size:
- * @stream: a #GBufferedInputStream
+ * 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.
*
- * Gets the size of the input buffer.
+ * Note that @message must be unlocked, unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
*
- * Returns: the current buffer size.
+ * Returns: %TRUE if the message was well-formed and queued for
+ * transmission, %FALSE if @error is set
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_new:
- * @base_stream: a #GInputStream
+ * 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
*
- * Creates a new #GInputStream from the given @base_stream, with
- * a buffer set to the default size (4 kilobytes).
+ * Asynchronously sends @message to the peer represented by @connection.
*
- * Returns: a #GInputStream for the given @base_stream.
+ * Unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+ * will be assigned by @connection and set on @message via
+ * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+ * serial number used will be written to this location prior to
+ * submitting the message to the underlying transport.
+ *
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * 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
+ * [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 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_buffered_input_stream_new_sized:
- * @base_stream: a #GInputStream
- * @size: a #gsize
+ * 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: teturn location for error or %NULL
*
- * Creates a new #GBufferedInputStream from the given @base_stream,
- * with a buffer set to @size.
+ * Finishes an operation started with g_dbus_connection_send_message_with_reply().
*
- * Returns: a #GInputStream.
+ * Note that @error is only set if a local in-process error
+ * occurred. That is to say that the returned #GDBusMessage object may
+ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
+ * g_dbus_message_to_gerror() to transcode this to a #GError.
+ *
+ * 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
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_peek:
- * @stream: a #GBufferedInputStream
- * @buffer: a pointer to an allocated chunk of memory
- * @offset: a #gsize
- * @count: a #gsize
+ * 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
*
- * Peeks in the buffer, copying data of size @count into @buffer,
- * offset @offset bytes.
+ * Synchronously sends @message to the peer represented by @connection
+ * and blocks the calling thread until a reply is received or the
+ * timeout is reached. See g_dbus_connection_send_message_with_reply()
+ * for the asynchronous version of this method.
*
- * Returns: a #gsize of the number of bytes peeked, or -1 on error.
+ * Unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+ * will be assigned by @connection and set on @message via
+ * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+ * serial number used will be written to this location prior to
+ * submitting the message to the underlying transport.
+ *
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * Note that @error is only set if a local in-process error
+ * occurred. That is to say that the returned #GDBusMessage object may
+ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
+ * g_dbus_message_to_gerror() to transcode this to a #GError.
+ *
+ * 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
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_peek_buffer:
- * @stream: a #GBufferedInputStream
- * @count: (out): a #gsize to get the number of bytes available in the buffer
+ * 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
*
- * Returns the buffer with the currently available bytes. The returned
- * buffer must not be modified and will become invalid when reading from
- * the stream or filling the buffer.
+ * Sets whether the process should be terminated when @connection is
+ * closed by the remote peer. See #GDBusConnection:exit-on-close for
+ * more details.
*
- * read-only buffer
+ * Note that this function should be used with care. Most modern UNIX
+ * desktops tie the notion of a user session the session bus, and expect
+ * all of a users applications to quit when their bus connection goes away.
+ * If you are setting @exit_on_close to %FALSE for the shared session
+ * bus connection, you should make sure that your application exits
+ * when the user session ends.
*
- * Returns: (array length=count) (element-type guint8) (transfer none):
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_read_byte:
- * @stream: a #GBufferedInputStream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: location to store the error occurring, or %NULL to ignore
+ * 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
*
- * Tries to read a single byte from the stream or the buffer. Will block
- * during this read.
+ * 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.
*
- * On success, the byte read from the stream is returned. On end of stream
- * -1 is returned but it's not an exceptional error and @error is not set.
+ * If @connection is not a message bus connection, @sender must be
+ * %NULL.
*
- * 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.
+ * If @sender is a well-known name note that @callback is invoked with
+ * the unique name for the owner of @sender, not the well-known name
+ * as one would expect. This is because the message bus rewrites the
+ * name. As such, to avoid certain race conditions, users should be
+ * tracking the name owner of the well-known name and use that when
+ * processing the received signal.
*
- * On error -1 is returned and @error is set accordingly.
+ * 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: the byte read from the @stream, or -1 on end of stream or error.
+ * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
+ * Since: 2.26
*/
/**
- * g_buffered_input_stream_set_buffer_size:
- * @stream: a #GBufferedInputStream
- * @size: a #gsize
+ * g_dbus_connection_signal_unsubscribe:
+ * @connection: a #GDBusConnection
+ * @subscription_id: a subscription id obtained from
+ * g_dbus_connection_signal_subscribe()
*
- * Sets the size of the internal buffer of @stream to @size, or to the
- * size of the contents of the buffer. The buffer can never be resized
- * smaller than its current contents.
+ * Unsubscribes from signals.
+ *
+ * Since: 2.26
*/
/**
- * g_buffered_output_stream_get_auto_grow:
- * @stream: a #GBufferedOutputStream.
- *
- * Checks if the buffer automatically grows as data is added.
+ * g_dbus_connection_start_message_processing:
+ * @connection: a #GDBusConnection
*
- * %FALSE otherwise.
+ * If @connection was created with
+ * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
+ * starts processing messages. Does nothing on if @connection wasn't
+ * created with this flag or if the method has already been called.
*
- * Returns: %TRUE if the @stream's buffer automatically grows,
+ * Since: 2.26
*/
/**
- * g_buffered_output_stream_get_buffer_size:
- * @stream: a #GBufferedOutputStream.
+ * g_dbus_connection_unexport_action_group:
+ * @connection: a #GDBusConnection
+ * @export_id: the ID from g_dbus_connection_export_action_group()
*
- * Gets the size of the buffer in the @stream.
+ * Reverses the effect of a previous call to
+ * g_dbus_connection_export_action_group().
*
- * Returns: the current size of the buffer.
+ * It is an error to call this function with an ID that wasn't returned
+ * from g_dbus_connection_export_action_group() or to call it with the
+ * same ID more than once.
+ *
+ * Since: 2.32
*/
/**
- * g_buffered_output_stream_new:
- * @base_stream: a #GOutputStream.
+ * g_dbus_connection_unexport_menu_model:
+ * @connection: a #GDBusConnection
+ * @export_id: the ID from g_dbus_connection_export_menu_model()
*
- * Creates a new buffered output stream for a base stream.
+ * Reverses the effect of a previous call to
+ * g_dbus_connection_export_menu_model().
*
- * Returns: a #GOutputStream for the given @base_stream.
+ * It is an error to call this function with an ID that wasn't returned
+ * from g_dbus_connection_export_menu_model() or to call it with the
+ * same ID more than once.
+ *
+ * Since: 2.32
*/
/**
- * g_buffered_output_stream_new_sized:
- * @base_stream: a #GOutputStream.
- * @size: a #gsize.
+ * g_dbus_connection_unregister_object:
+ * @connection: a #GDBusConnection
+ * @registration_id: a registration id obtained from
+ * g_dbus_connection_register_object()
*
- * Creates a new buffered output stream with a given buffer size.
+ * Unregisters an object.
*
- * Returns: a #GOutputStream with an internal buffer set to @size.
+ * Returns: %TRUE if the object was unregistered, %FALSE otherwise
+ * Since: 2.26
*/
/**
- * g_buffered_output_stream_set_auto_grow:
- * @stream: a #GBufferedOutputStream.
- * @auto_grow: a #gboolean.
+ * g_dbus_connection_unregister_subtree:
+ * @connection: a #GDBusConnection
+ * @registration_id: a subtree registration id obtained from
+ * g_dbus_connection_register_subtree()
*
- * Sets whether or not the @stream's buffer should automatically grow.
- * If @auto_grow is true, then each write will just make the buffer
- * larger, and you must manually flush the buffer to actually write out
- * the data to the underlying stream.
- */
-
-
-/**
- * g_buffered_output_stream_set_buffer_size:
- * @stream: a #GBufferedOutputStream.
- * @size: a #gsize.
+ * Unregisters a subtree.
*
- * Sets the size of the internal buffer to @size.
+ * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise
+ * Since: 2.26
*/
/**
- * g_bus_get:
- * @bus_type: A #GBusType.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * g_dbus_error_encode_gerror:
+ * @error: A #GError.
*
- * Asynchronously connects to the message bus specified by @bus_type.
+ * Creates a D-Bus error name to use for @error. If @error matches
+ * a registered error (cf. g_dbus_error_register_error()), the corresponding
+ * D-Bus error name will be returned.
*
- * When the operation is finished, @callback will be invoked. You can
- * then call g_bus_get_finish() to get the result of the operation.
+ * Otherwise the a name of the form
+ * `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().
*
- * This is a asynchronous failable function. See g_bus_get_sync() for
- * the synchronous version.
+ * This function is typically only used in object mappings to put a
+ * #GError on the wire. Regular applications should not use it.
*
+ * Returns: A D-Bus error name (never %NULL). Free with g_free().
* Since: 2.26
*/
/**
- * g_bus_get_finish:
- * @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().
+ * g_dbus_error_get_remote_error:
+ * @error: a #GError
*
- * The returned object is a singleton, that is, shared with other
- * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
- * event that you need a private message bus connection, use
- * g_dbus_address_get_for_bus_sync() and
- * g_dbus_connection_new_for_address().
+ * Gets the D-Bus error name used for @error, if any.
*
- * Note that the returned #GDBusConnection object will (usually) have
- * the #GDBusConnection:exit-on-close property set to %TRUE.
+ * This function is guaranteed to return a D-Bus error name for all
+ * #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: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: an allocated string or %NULL if the D-Bus error name
+ * could not be found. Free with g_free().
* Since: 2.26
*/
/**
- * g_bus_get_sync:
- * @bus_type: A #GBusType.
- * @cancellable: 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,
- * e.g. if two separate parts of a process calls this function with
- * the same @bus_type, they will share the same object.
- *
- * This is a synchronous failable function. See g_bus_get() and
- * g_bus_get_finish() for the asynchronous version.
- *
- * The returned object is a singleton, that is, shared with other
- * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
- * event that you need a private message bus connection, use
- * g_dbus_address_get_for_bus_sync() and
- * g_dbus_connection_new_for_address().
+ * g_dbus_error_is_remote_error:
+ * @error: A #GError.
*
- * Note that the returned #GDBusConnection object will (usually) have
- * the #GDBusConnection:exit-on-close property set to %TRUE.
+ * 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: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: %TRUE if @error represents an error from a remote peer,
+ * %FALSE otherwise.
* 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: Handler to invoke when connected to the bus of type @bus_type or %NULL.
- * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
- * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_dbus_error_new_for_dbus_error:
+ * @dbus_error_name: D-Bus error name.
+ * @dbus_error_message: D-Bus error message.
*
- * 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.
+ * Creates a #GError based on the contents of @dbus_error_name and
+ * @dbus_error_message.
*
- * 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>
- * When you are done owning the name, just call g_bus_unown_name()
- * with the owner id this function returns.
+ * Errors registered with g_dbus_error_register_error() will be looked
+ * up using @dbus_error_name and if a match is found, the error domain
+ * and code is used. Applications can use g_dbus_error_get_remote_error()
+ * to recover @dbus_error_name.
*
- * 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.
+ * If a match against a registered error is not found and the D-Bus
+ * error name is in a form as returned by g_dbus_error_encode_gerror()
+ * the error domain and code encoded in the name is used to
+ * create the #GError. Also, @dbus_error_name is added to the error message
+ * such that it can be recovered with g_dbus_error_get_remote_error().
*
- * 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
- * will work.
+ * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
+ * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
+ * added to the error message such that it can be recovered with
+ * g_dbus_error_get_remote_error().
*
- * Another guarantee is that invocations of @name_acquired_handler
- * and @name_lost_handler are guaranteed to alternate; that
- * is, if @name_acquired_handler is invoked then you are
- * guaranteed that the next time one of the handlers is invoked, it
- * will be @name_lost_handler. The reverse is also true.
+ * In all three cases, @dbus_error_name can always be recovered from the
+ * returned #GError using the g_dbus_error_get_remote_error() function
+ * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
*
- * If you plan on exporting objects (using e.g.
- * g_dbus_connection_register_object()), note that it is generally too late
- * to export the objects in @name_acquired_handler. Instead, you can do this
- * in @bus_acquired_handler since you are guaranteed that this will run
- * before @name is requested from the bus.
+ * This function is typically only used in object mappings to prepare
+ * #GError instances for applications. Regular applications should not use
+ * it.
*
- * This behavior makes it very simple to write applications that wants
- * to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
- * Simply register objects to be exported in @bus_acquired_handler and
- * unregister the objects (if any) in @name_lost_handler.
+ * Returns: An allocated #GError. Free with g_error_free().
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_error_register_error:
+ * @error_domain: A #GQuark for a error domain.
+ * @error_code: An error code.
+ * @dbus_error_name: A D-Bus error name.
+ *
+ * Creates an association to map between @dbus_error_name and
+ * #GErrors specified by @error_domain and @error_code.
*
- * g_bus_unown_name() to stop owning the name.
+ * This is typically done in the routine that returns the #GQuark for
+ * an error domain.
*
- * Returns: An identifier (never 0) that an be used with
+ * Returns: %TRUE if the association was created, %FALSE if it already
+ * exists.
* 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: Handler to invoke when @name is acquired or %NULL.
- * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_dbus_error_register_error_domain:
+ * @error_domain_quark_name: The error domain name.
+ * @quark_volatile: A pointer where to store the #GQuark.
+ * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
+ * @num_entries: Number of items to register.
*
- * Like g_bus_own_name() but takes a #GDBusConnection instead of a
- * #GBusType.
+ * Helper function for associating a #GError error domain with D-Bus error names.
+ *
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_error_set_dbus_error:
+ * @error: A pointer to a #GError or %NULL.
+ * @dbus_error_name: D-Bus error name.
+ * @dbus_error_message: D-Bus error message.
+ * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
+ * @...: Arguments for @format.
*
- * g_bus_unown_name() to stop owning the name.
+ * Does nothing if @error is %NULL. Otherwise sets *@error to
+ * a new #GError created with g_dbus_error_new_for_dbus_error()
+ * with @dbus_error_message prepend with @format (unless %NULL).
*
- * Returns: An identifier (never 0) that an be used with
* 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.
- *
- * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
- * easier binding in other languages.
+ * g_dbus_error_set_dbus_error_valist:
+ * @error: A pointer to a #GError or %NULL.
+ * @dbus_error_name: D-Bus error name.
+ * @dbus_error_message: D-Bus error message.
+ * @format: (allow-none): printf()-style format to prepend to @dbus_error_message or %NULL.
+ * @var_args: Arguments for @format.
*
- * g_bus_unown_name() to stop owning the name.
+ * Like g_dbus_error_set_dbus_error() but intended for language bindings.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_own_name_on_connection
* 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_dbus_error_strip_remote_error:
+ * @error: A #GError.
*
- * Version of g_bus_own_name() using closures instead of callbacks for
- * easier binding in other languages.
+ * Looks for extra information in the error message used to recover
+ * the D-Bus error name and strips it if found. If stripped, the
+ * message field in @error will correspond exactly to what was
+ * received on the wire.
*
- * g_bus_unown_name() to stop owning the name.
+ * This is typically used when presenting errors to the end user.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_own_name
+ * Returns: %TRUE if information was stripped, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_bus_unown_name:
- * @owner_id: An identifier obtained from g_bus_own_name()
+ * g_dbus_error_unregister_error:
+ * @error_domain: A #GQuark for a error domain.
+ * @error_code: An error code.
+ * @dbus_error_name: A D-Bus error name.
*
- * Stops owning a name.
+ * Destroys an association previously set up with g_dbus_error_register_error().
*
+ * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
* Since: 2.26
*/
/**
- * g_bus_unwatch_name:
- * @watcher_id: An identifier obtained from g_bus_watch_name()
+ * g_dbus_generate_guid:
*
- * Stops watching a name.
+ * Generate a D-Bus GUID that can be used with
+ * e.g. g_dbus_connection_new().
+ *
+ * See the D-Bus specification regarding what strings are valid D-Bus
+ * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
*
+ * Returns: A valid D-Bus GUID. Free with g_free().
* Since: 2.26
*/
/**
- * 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_handler: Handler to invoke when @name is known to exist or %NULL.
- * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_dbus_gvalue_to_gvariant:
+ * @gvalue: A #GValue to convert to a #GVariant
+ * @type: A #GVariantType
*
- * 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.
+ * Converts a #GValue to a #GVariant of the type indicated by the @type
+ * parameter.
*
- * You are guaranteed that one of the handlers will be invoked after
- * calling this function. When you are done watching the name, just
- * call g_bus_unwatch_name() with the watcher id this function
- * returns.
+ * The conversion is using the following rules:
*
- * If the name vanishes or appears (for example the application owning
- * the name could restart), the handlers are also invoked. If the
- * #GDBusConnection that is used for watching the name disconnects, then
- * @name_vanished_handler is invoked since it is no longer
- * possible to access the name.
+ * - #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
*
- * Another guarantee is that invocations of @name_appeared_handler
- * and @name_vanished_handler are guaranteed to alternate; that
- * is, if @name_appeared_handler is invoked then you are
- * guaranteed that the next time one of the handlers is invoked, it
- * will be @name_vanished_handler. The reverse is also true.
+ * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
+ * 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.
*
- * 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.
+ * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
+ * %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).
*
- * g_bus_unwatch_name() to stop watching the name.
+ * See the g_dbus_gvariant_to_gvalue() function for how to convert a
+ * #GVariant to a #GValue.
*
- * Returns: An identifier (never 0) that an be used with
- * Since: 2.26
+ * 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_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_handler: Handler to invoke when @name is known to exist or %NULL.
- * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_dbus_gvariant_to_gvalue:
+ * @value: A #GVariant.
+ * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue.
*
- * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
- * #GBusType.
+ * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
*
- * g_bus_unwatch_name() to stop watching the name.
+ * The rules specified in the g_dbus_gvalue_to_gvariant() function are
+ * used - this function is essentially its reverse form.
*
- * Returns: An identifier (never 0) that an be used with
- * Since: 2.26
+ * The conversion never fails - a valid #GValue is always returned in
+ * @out_gvalue.
+ *
+ * Since: 2.30
*/
/**
- * g_bus_watch_name_on_connection_with_closures:
- * @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.
- *
- * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
- * easier binding in other languages.
+ * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object)
+ * @interface_: An exported D-Bus interface.
*
- * g_bus_unwatch_name() to stop watching the name.
+ * Gets the #GDBusObject that @interface_ belongs to, if any.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_watch_name_on_connection
- * Since: 2.26
+ * Returns: (transfer full): A #GDBusObject or %NULL. The returned
+ * reference should be freed with g_object_unref().
+ * Since: 2.32
*/
/**
- * g_bus_watch_name_with_closures:
- * @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.
- *
- * Version of g_bus_watch_name() using closures instead of callbacks for
- * easier binding in other languages.
+ * g_dbus_interface_get_info:
+ * @interface_: An exported D-Bus interface.
*
- * g_bus_unwatch_name() to stop watching the name.
+ * Gets D-Bus introspection information for the D-Bus interface
+ * implemented by @interface_.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_watch_name
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
+ * Since: 2.30
*/
/**
- * g_cancellable_cancel:
- * @cancellable: a #GCancellable object.
+ * g_dbus_interface_get_object: (skip)
+ * @interface_: An exported D-Bus interface
*
- * 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 #GDBusObject that @interface_ belongs to, if any.
*
- * 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.
+ * 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.
*
- * 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
- * the application returns to the main loop.
+ * Returns: (transfer none): A #GDBusObject or %NULL. The returned
+ * reference belongs to @interface_ and should not be freed.
+ * Since: 2.30
*/
/**
- * g_cancellable_connect:
- * @cancellable: A #GCancellable.
- * @callback: The #GCallback to connect.
- * @data: Data to pass to @callback.
- * @data_destroy_func: Free function for @data or %NULL.
+ * g_dbus_interface_info_cache_build:
+ * @info: A #GDBusInterfaceInfo.
*
- * Convenience function to connect to the #GCancellable::cancelled
- * signal. Also handles the race condition that may happen
- * if the cancellable is cancelled right before connecting.
+ * Builds a lookup-cache to speed up
+ * g_dbus_interface_info_lookup_method(),
+ * g_dbus_interface_info_lookup_signal() and
+ * g_dbus_interface_info_lookup_property().
*
- * @callback is called at most once, either directly at the
- * time of the connect if @cancellable is already cancelled,
- * or when @cancellable is cancelled in some thread.
+ * If this has already been called with @info, the existing cache is
+ * used and its use count is increased.
*
- * @data_destroy_func will be called when the handler is
- * disconnected, or immediately if the cancellable is already
- * cancelled.
+ * Note that @info cannot be modified until
+ * g_dbus_interface_info_cache_release() is called.
*
- * See #GCancellable::cancelled for details on how to use this.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_dbus_interface_info_cache_release:
+ * @info: A GDBusInterfaceInfo
*
- * been cancelled.
+ * Decrements the usage count for the cache for @info built by
+ * g_dbus_interface_info_cache_build() (if any) and frees the
+ * resources used by the cache if the usage count drops to zero.
*
- * Returns: The id of the signal handler or 0 if @cancellable has already
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * g_cancellable_disconnect:
- * @cancellable: A #GCancellable or %NULL.
- * @handler_id: Handler id of the handler to be disconnected, or %0.
- *
- * Disconnects a handler from a cancellable instance similar to
- * g_signal_handler_disconnect(). Additionally, in the event that a
- * signal handler is currently running, this call will block until the
- * handler has finished. Calling this function from a
- * #GCancellable::cancelled signal handler will therefore result in a
- * deadlock.
+ * g_dbus_interface_info_generate_xml:
+ * @info: A #GDBusNodeInfo
+ * @indent: Indentation level.
+ * @string_builder: (out): A #GString to to append XML data to.
*
- * This avoids a race condition where a thread cancels at the
- * same time as the cancellable operation is finished and the
- * signal handler is removed. See #GCancellable::cancelled for
- * details on how to use this.
+ * Appends an XML representation of @info (and its children) to @string_builder.
*
- * If @cancellable is %NULL or @handler_id is %0 this function does
- * nothing.
+ * This function is typically used for generating introspection XML
+ * documents at run-time for handling the
+ * `org.freedesktop.DBus.Introspectable.Introspect`
+ * method.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * g_cancellable_get_current:
+ * g_dbus_interface_info_lookup_method:
+ * @info: A #GDBusInterfaceInfo.
+ * @name: A D-Bus method name (typically in CamelCase)
*
- * Gets the top cancellable from the stack.
+ * Looks up information about a method.
*
- * if the stack is empty.
+ * 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 #GCancellable from the top of the stack, or %NULL
+ * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Since: 2.26
*/
/**
- * g_cancellable_get_fd:
- * @cancellable: a #GCancellable.
+ * g_dbus_interface_info_lookup_property:
+ * @info: A #GDBusInterfaceInfo.
+ * @name: A D-Bus property name (typically in CamelCase).
*
- * Gets the file descriptor for a cancellable job. This can be used to
- * implement cancellable operations on Unix systems. The returned fd will
- * turn readable when @cancellable is cancelled.
+ * Looks up information about a property.
*
- * You are not supposed to read from the fd yourself, just check for
- * readable status. Reading to unset the readable status is done
- * with g_cancellable_reset().
+ * The cost of this function is O(n) in number of properties unless
+ * g_dbus_interface_info_cache_build() has been used on @info.
*
- * After a successful return from this function, you should use
- * g_cancellable_release_fd() to free up resources allocated for
- * the returned file descriptor.
+ * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_interface_info_lookup_signal:
+ * @info: A #GDBusInterfaceInfo.
+ * @name: A D-Bus signal name (typically in CamelCase)
*
- * See also g_cancellable_make_pollfd().
+ * Looks up information about a signal.
*
- * is not supported, or on errors.
+ * 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.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_interface_info_ref:
+ * @info: A #GDBusInterfaceInfo
+ *
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: A valid file descriptor. %-1 if the file descriptor
+ * Returns: The same @info.
+ * Since: 2.26
*/
/**
- * g_cancellable_is_cancelled:
- * @cancellable: (allow-none): a #GCancellable or %NULL
- *
- * Checks if a cancellable job has been cancelled.
+ * g_dbus_interface_info_unref:
+ * @info: A #GDBusInterfaceInfo.
*
- * FALSE if called with %NULL or if item is not cancelled.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: %TRUE if @cancellable is cancelled,
+ * Since: 2.26
*/
/**
- * g_cancellable_make_pollfd:
- * @cancellable: a #GCancellable or %NULL
- * @pollfd: a pointer to a #GPollFD
- *
- * Creates a #GPollFD corresponding to @cancellable; this can be passed
- * to g_poll() and used to poll for cancellation. This is useful both
- * for unix systems without a native poll and for portability to
- * windows.
- *
- * When this function returns %TRUE, you should use
- * g_cancellable_release_fd() to free up resources allocated for the
- * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
- *
- * If this function returns %FALSE, either no @cancellable was given or
- * resource limits prevent this function from allocating the necessary
- * structures for polling. (On Linux, you will likely have reached
- * the maximum number of file descriptors.) The suggested way to handle
- * these cases is to ignore the @cancellable.
+ * g_dbus_interface_set_object:
+ * @interface_: An exported D-Bus interface.
+ * @object: (allow-none): A #GDBusObject or %NULL.
*
- * You are not supposed to read from the fd yourself, just check for
- * readable status. Reading to unset the readable status is done
- * with g_cancellable_reset().
+ * Sets the #GDBusObject for @interface_ to @object.
*
- * failure to prepare the cancellable.
+ * Note that @interface_ will hold a weak reference to @object.
*
- * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
- * Since: 2.22
+ * Since: 2.30
*/
/**
- * g_cancellable_new:
+ * g_dbus_interface_skeleton_export:
+ * @interface_: The D-Bus interface to export.
+ * @connection: A #GDBusConnection to export @interface_ on.
+ * @object_path: The path to export the interface at.
+ * @error: Return location for error or %NULL.
*
- * Creates a new #GCancellable object.
+ * Exports @interface_ at @object_path on @connection.
*
- * Applications that want to start one or more operations
- * that should be cancellable should create a #GCancellable
- * and pass it to the operations.
+ * This can be called multiple times to export the same @interface_
+ * onto multiple connections however the @object_path provided must be
+ * the same for all connections.
*
- * One #GCancellable can be used in multiple consecutive
- * operations or in multiple concurrent operations.
+ * Use g_dbus_interface_skeleton_unexport() to unexport the object.
*
- * Returns: a #GCancellable.
+ * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
+ * @error set.
+ * Since: 2.30
*/
/**
- * g_cancellable_pop_current:
- * @cancellable: a #GCancellable object
+ * g_dbus_interface_skeleton_flush:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Pops @cancellable off the cancellable stack (verifying that @cancellable
- * is on the top of the stack).
+ * If @interface_ has outstanding changes, request for these changes to be
+ * emitted immediately.
+ *
+ * For example, an exported D-Bus interface may queue up property
+ * changes and emit the
+ * `org.freedesktop.DBus.Properties::Propert``
+ * signal later (e.g. in an idle handler). This technique is useful
+ * for collapsing multiple property changes into one.
+ *
+ * Since: 2.30
*/
/**
- * g_cancellable_push_current:
- * @cancellable: a #GCancellable object
- *
- * Pushes @cancellable onto the cancellable stack. The current
- * cancellable can then be received using g_cancellable_get_current().
+ * g_dbus_interface_skeleton_get_connection:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * This is useful when implementing cancellable operations in
- * code that does not allow you to pass down the cancellable object.
+ * Gets the first connection that @interface_ is exported on, if any.
*
- * This is typically called automatically by e.g. #GFile operations,
- * so you rarely have to call this yourself.
+ * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
+ * not exported anywhere. Do not free, the object belongs to @interface_.
+ * Since: 2.30
*/
/**
- * g_cancellable_release_fd:
- * @cancellable: a #GCancellable
- *
- * Releases a resources previously allocated by g_cancellable_get_fd()
- * or g_cancellable_make_pollfd().
+ * g_dbus_interface_skeleton_get_connections:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * For compatibility reasons with older releases, calling this function
- * is not strictly required, the resources will be automatically freed
- * when the @cancellable is finalized. However, the @cancellable will
- * block scarce file descriptors until it is finalized if this function
- * is not called. This can cause the application to run out of file
- * descriptors when many #GCancellables are used at the same time.
+ * Gets a list of the connections that @interface_ is exported on.
*
- * Since: 2.22
+ * 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
*/
/**
- * g_cancellable_reset:
- * @cancellable: a #GCancellable object.
+ * g_dbus_interface_skeleton_get_flags:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Resets @cancellable to its uncancelled state.
+ * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
+ * of @interface_
*
- * If cancellable is currently in use by any cancellable operation
- * then the behavior of this function is undefined.
+ * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
+ * Since: 2.30
*/
/**
- * g_cancellable_set_error_if_cancelled:
- * @cancellable: (allow-none): a #GCancellable or %NULL
- * @error: #GError to append error state to
+ * g_dbus_interface_skeleton_get_info:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * If the @cancellable is cancelled, sets the error to notify
- * that the operation was cancelled.
+ * Gets D-Bus introspection information for the D-Bus interface
+ * implemented by @interface_.
*
- * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
+ * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
+ * Since: 2.30
*/
/**
- * g_cancellable_source_new: (skip)
- * @cancellable: a #GCancellable, or %NULL
- *
- * Creates a source that triggers if @cancellable is cancelled and
- * calls its callback of type #GCancellableSourceFunc. This is
- * primarily useful for attaching to another (non-cancellable) source
- * with g_source_add_child_source() to add cancellability to it.
+ * g_dbus_interface_skeleton_get_object_path:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * For convenience, you can call this with a %NULL #GCancellable,
- * in which case the source will never trigger.
+ * Gets the object path that @interface_ is exported on, if any.
*
- * Returns: (transfer full): the new #GSource.
- * Since: 2.28
+ * 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
*/
/**
- * g_charset_converter_get_num_fallbacks:
- * @converter: a #GCharsetConverter
+ * g_dbus_interface_skeleton_get_properties:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Gets the number of fallbacks that @converter has applied so far.
+ * Gets all D-Bus properties for @interface_.
*
- * Returns: the number of fallbacks that @converter has applied
- * Since: 2.24
+ * Returns: (transfer full): A #GVariant of type
+ * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
+ * Free with g_variant_unref().
+ * Since: 2.30
*/
/**
- * g_charset_converter_get_use_fallback:
- * @converter: a #GCharsetConverter
+ * g_dbus_interface_skeleton_get_vtable: (skip)
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Gets the #GCharsetConverter:use-fallback property.
+ * Gets the interface vtable for the D-Bus interface implemented by
+ * @interface_. The returned function pointers should expect @interface_
+ * itself to be passed as @user_data.
*
- * Returns: %TRUE if fallbacks are used by @converter
- * Since: 2.24
+ * Returns: A #GDBusInterfaceVTable (never %NULL).
+ * Since: 2.30
*/
/**
- * g_charset_converter_new:
- * @to_charset: destination charset
- * @from_charset: source charset
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_dbus_interface_skeleton_has_connection:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ * @connection: A #GDBusConnection.
*
- * Creates a new #GCharsetConverter.
+ * Checks if @interface_ is exported on @connection.
*
- * Returns: a new #GCharsetConverter or %NULL on error.
- * Since: 2.24
+ * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
+ * Since: 2.32
*/
/**
- * g_charset_converter_set_use_fallback:
- * @converter: a #GCharsetConverter
- * @use_fallback: %TRUE to use fallbacks
+ * g_dbus_interface_skeleton_set_flags:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
*
- * Sets the #GCharsetConverter:use-fallback property.
+ * Sets flags describing what the behavior of @skeleton should be.
*
- * Since: 2.24
+ * Since: 2.30
*/
/**
- * g_content_type_can_be_executable:
- * @type: a content type string
+ * g_dbus_interface_skeleton_unexport:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * 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).
+ * Stops exporting @interface_ on all connections it is exported on.
*
- * can be executable, %FALSE otherwise.
+ * To unexport @interface_ from only a single connection, use
+ * g_dbus_interface_skeleton_unexport_from_connection()
*
- * Returns: %TRUE if the file type corresponds to a type that
+ * Since: 2.30
*/
/**
- * g_content_type_equals:
- * @type1: a content type string
- * @type2: a content type string
+ * g_dbus_interface_skeleton_unexport_from_connection:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ * @connection: A #GDBusConnection.
*
- * Compares two content types for equality.
+ * Stops exporting @interface_ on @connection.
*
- * %FALSE otherwise.
+ * To stop exporting on all connections the interface is exported on,
+ * use g_dbus_interface_skeleton_unexport().
*
- * Returns: %TRUE if the two strings are identical or equivalent,
+ * Since: 2.32
*/
/**
- * g_content_type_from_mime_type:
- * @mime_type: a mime type string
+ * g_dbus_is_address:
+ * @string: A string.
*
- * Tries to find a content type based on the mime type name.
+ * Checks if @string is a D-Bus address.
*
- * or %NULL. Free with g_free()
+ * This doesn't check if @string is actually supported by #GDBusServer
+ * or #GDBusConnection - use g_dbus_is_supported_address() to do more
+ * checks.
*
- * Returns: (allow-none): Newly allocated string with content type
- * Since: 2.18
+ * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_content_type_get_description:
- * @type: a content type string
+ * g_dbus_is_guid:
+ * @string: The string to check.
*
- * Gets the human readable description of the content type.
+ * Checks if @string is a D-Bus GUID.
*
- * returned string with g_free()
+ * See the D-Bus specification regarding what strings are valid D-Bus
+ * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
*
- * Returns: a short description of the content type @type. Free the
+ * Returns: %TRUE if @string is a guid, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_content_type_get_icon:
- * @type: a content type string
- *
- * Gets the icon for a content type.
+ * g_dbus_is_interface_name:
+ * @string: The string to check.
*
- * object with g_object_unref()
+ * Checks if @string is a valid D-Bus interface name.
*
- * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
+ * Returns: %TRUE if valid, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_content_type_get_mime_type:
- * @type: a content type string
- *
- * Gets the mime type for the content type, if one is registered.
+ * g_dbus_is_member_name:
+ * @string: The string to check.
*
- * or %NULL if unknown.
+ * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
*
- * Returns: (allow-none): the registered mime type for the given @type,
+ * Returns: %TRUE if valid, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_content_type_guess:
- * @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
- *
- * 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.
+ * g_dbus_is_name:
+ * @string: The string to check.
*
- * given data. Free with g_free()
+ * Checks if @string is a valid D-Bus bus name (either unique or well-known).
*
- * Returns: a string indicating a guessed content type for the
+ * Returns: %TRUE if valid, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_content_type_guess_for_tree:
- * @root: the root of the tree to guess a type for
- *
- * Tries to guess the type of the tree with root @root, by
- * looking at the files it contains. The result is an array
- * of content types, with the best guess coming first.
- *
- * 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>
- * specification for more on x-content types.
- *
- * This function is useful in the implementation of
- * g_mount_guess_content_type().
+ * g_dbus_is_supported_address:
+ * @string: A string.
+ * @error: Return location for error or %NULL.
*
- * array of zero or more content types, or %NULL. Free with g_strfreev()
+ * Like g_dbus_is_address() but also checks if the library suppors the
+ * transports in @string and that key/value pairs for each transport
+ * are valid.
*
- * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
- * Since: 2.18
+ * Returns: %TRUE if @string is a valid D-Bus address that is
+ * supported by this library, %FALSE if @error is set.
+ * Since: 2.26
*/
/**
- * g_content_type_is_a:
- * @type: a content type string
- * @supertype: a content type string
- *
- * Determines if @type is a subset of @supertype.
+ * g_dbus_is_unique_name:
+ * @string: The string to check.
*
- * %FALSE otherwise.
+ * Checks if @string is a valid D-Bus unique bus name.
*
- * Returns: %TRUE if @type is a kind of @supertype,
+ * Returns: %TRUE if valid, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_content_type_is_unknown:
- * @type: a content type string
+ * g_dbus_menu_model_get:
+ * @connection: a #GDBusConnection
+ * @bus_name: the bus name which exports the menu model
+ * @object_path: the object path at which the menu model is exported
*
- * Checks if the content type is the generic "unknown" type.
- * On UNIX this is the "application/octet-stream" mimetype,
- * while on win32 it is "*".
+ * Obtains a #GDBusMenuModel for the menu model which is exported
+ * at the given @bus_name and @object_path.
*
- * Returns: %TRUE if the type is the unknown type.
+ * The thread default main context is taken at the time of this call.
+ * All signals on the menu model (and any linked models) are reported
+ * with respect to this context. All calls on the returned menu model
+ * (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().
+ * Since: 2.32
*/
/**
- * g_content_types_get_registered:
+ * g_dbus_message_bytes_needed:
+ * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
+ * @blob_len: The length of @blob (must be at least 16).
+ * @error: Return location for error or %NULL.
*
- * 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_foreach (list, g_free, NULL);
- * g_list_free (list);
- * </programlisting>
+ * Utility function to calculate how many bytes are needed to
+ * completely deserialize the D-Bus message stored at @blob.
*
- * Returns: (element-type utf8) (transfer full): #GList of the registered content types
+ * 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
*/
/**
- * g_converter_convert:
- * @converter: a #GConverter.
- * @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
- * @flags: a #GConvertFlags controlling the conversion details
- * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
- * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
- * @error: location to store the error occurring, or %NULL to ignore
- *
- * This is the main operation used when converting data. It is to be called
- * multiple times in a loop, and each time it will do some work, i.e.
- * producing some output (in @outbuf) or consuming some input (from @inbuf) or
- * both. If its not possible to do any work an error is returned.
- *
- * Note that a single call may not consume all input (or any input at all).
- * Also a call may produce output even if given no input, due to state stored
- * in the converter producing output.
- *
- * If any data was either produced or consumed, and then an error happens, then
- * only the successful conversion is reported and the error is returned on the
- * next call.
- *
- * A full conversion loop involves calling this method repeatedly, each time
- * giving it new input and space output space. When there is no more input
- * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
- * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
- * each time until all data is consumed and all output is produced, then
- * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
- * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
- * in a decompression converter where the end of data is detectable from the
- * data (and there might even be other data after the end of the compressed data).
- *
- * When some data has successfully been converted @bytes_read and is set to
- * the number of bytes read from @inbuf, and @bytes_written is set to indicate
- * how many bytes was written to @outbuf. If there are more data to output
- * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
- * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
- * then %G_CONVERTER_FINISHED is returned.
- *
- * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
- * Some errors need special handling:
- *
- * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
- * to write the resulting converted data, the application should
- * call the function again with a larger @outbuf to continue.
- *
- * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
- * input to fully determine what the conversion should produce,
- * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
- * example with an incomplete multibyte sequence when converting text,
- * or when a regexp matches up to the end of the input (and may match
- * further input). It may also happen when @inbuf_size is zero and
- * there is no more data to produce.
- *
- * When this happens the application should read more input and then
- * call the function again. If further input shows that there is no
- * more data call the function again with the same data but with
- * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
- * to finish as e.g. in the regexp match case (or, to fail again with
- * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
- * input is actually partial).
- *
- * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
- * converter object is in an invalid state where its not allowed
- * to call g_converter_convert() anymore. At this time you can only
- * free the object or call g_converter_reset() to reset it to the
- * initial state.
- *
- * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
- * to try to write out all internal state to the output. The application
- * has to call the function multiple times with the flag set, and when
- * the available input has been consumed and all internal state has
- * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
- * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
- * This is somewhat similar to what happens at the end of the input stream,
- * but done in the middle of the data.
+ * g_dbus_message_copy:
+ * @message: A #GDBusMessage.
+ * @error: Return location for error or %NULL.
*
- * This has different meanings for different conversions. For instance
- * in a compression converter it would mean that we flush all the
- * compression state into output such that if you uncompress the
- * compressed data you get back all the input data. Doing this may
- * make the final file larger due to padding though. Another example
- * is a regexp conversion, where if you at the end of the flushed data
- * have a match, but there is also a potential longer match. In the
- * non-flushed case we would ask for more input, but when flushing we
- * treat this as the end of input and do the match.
+ * Copies @message. The copy is a deep copy and the returned
+ * #GDBusMessage is completely identical except that it is guaranteed
+ * to not be locked.
*
- * Flushing is not always possible (like if a charset converter flushes
- * at a partial multibyte sequence). Converters are supposed to try
- * to produce as much output as possible and then return an error
- * (typically %G_IO_ERROR_PARTIAL_INPUT).
+ * This operation can fail if e.g. @message contains file descriptors
+ * and the per-process or system-wide open files limit is reached.
*
- * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
- * Since: 2.24
+ * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
+ * Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_converter_input_stream_get_converter:
- * @converter_stream: a #GConverterInputStream
+ * g_dbus_message_get_arg0:
+ * @message: A #GDBusMessage.
*
- * Gets the #GConverter that is used by @converter_stream.
+ * Convenience to get the first item in the body of @message.
*
- * Returns: (transfer none): the converter of the converter input stream
- * Since: 2.24
+ * Returns: The string item or %NULL if the first item in the body of
+ * @message is not a string.
+ * Since: 2.26
*/
/**
- * g_converter_input_stream_new:
- * @base_stream: a #GInputStream
- * @converter: a #GConverter
+ * g_dbus_message_get_body:
+ * @message: A #GDBusMessage.
*
- * Creates a new converter input stream for the @base_stream.
+ * Gets the body of a message.
*
- * Returns: a new #GInputStream.
+ * Returns: (transfer none): A #GVariant or %NULL if the body is
+ * empty. Do not free, it is owned by @message.
+ * Since: 2.26
*/
/**
- * g_converter_output_stream_get_converter:
- * @converter_stream: a #GConverterOutputStream
+ * g_dbus_message_get_byte_order:
+ * @message: A #GDBusMessage.
*
- * Gets the #GConverter that is used by @converter_stream.
+ * Gets the byte order of @message.
*
- * Returns: (transfer none): the converter of the converter output stream
- * Since: 2.24
+ * Returns: The byte order.
*/
/**
- * g_converter_output_stream_new:
- * @base_stream: a #GOutputStream
- * @converter: a #GConverter
+ * g_dbus_message_get_destination:
+ * @message: A #GDBusMessage.
*
- * Creates a new converter output stream for the @base_stream.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
*
- * Returns: a new #GOutputStream.
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_converter_reset:
- * @converter: a #GConverter.
+ * g_dbus_message_get_error_name:
+ * @message: A #GDBusMessage.
*
- * Resets all internal state in the converter, making it behave
- * as if it was just created. If the converter has any internal
- * state that would produce output then that output is lost.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
*
- * Since: 2.24
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_credentials_get_native: (skip)
- * @credentials: A #GCredentials.
- * @native_type: The type of native credentials to get.
- *
- * Gets a pointer to native credentials of type @native_type from
- * @credentials.
- *
- * It is a programming error (which will cause an warning to be
- * logged) to use this method if there is no #GCredentials support for
- * the OS or if @native_type isn't supported by the OS.
+ * g_dbus_message_get_flags:
+ * @message: A #GDBusMessage.
*
- * 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.
+ * Gets the flags for @message.
*
- * Returns: The pointer to native credentials or %NULL if the
+ * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
* Since: 2.26
*/
/**
- * g_credentials_get_unix_user:
- * @credentials: A #GCredentials
- * @error: Return location for error or %NULL.
- *
- * Tries to get the UNIX user identifier from @credentials. This
- * method is only available on UNIX platforms.
+ * g_dbus_message_get_header:
+ * @message: A #GDBusMessage.
+ * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
*
- * 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.
+ * Gets a header field on @message.
*
- * Returns: The UNIX user identifier or -1 if @error is set.
+ * Returns: A #GVariant with the value if the header was found, %NULL
+ * otherwise. Do not free, it is owned by @message.
* Since: 2.26
*/
/**
- * g_credentials_is_same_user:
- * @credentials: A #GCredentials.
- * @other_credentials: A #GCredentials.
- * @error: Return location for error or %NULL.
- *
- * Checks if @credentials and @other_credentials is the same user.
- *
- * This operation can fail if #GCredentials is not supported on the
- * the OS.
+ * g_dbus_message_get_header_fields:
+ * @message: A #GDBusMessage.
*
- * user, %FALSE otherwise or if @error is set.
+ * Gets an array of all header fields on @message that are set.
*
- * Returns: %TRUE if @credentials and @other_credentials has the same
+ * 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
*/
/**
- * g_credentials_new:
+ * g_dbus_message_get_interface:
+ * @message: A #GDBusMessage.
*
- * Creates a new #GCredentials object with credentials matching the
- * the current process.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
*
- * Returns: A #GCredentials. Free with g_object_unref().
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_credentials_set_native:
- * @credentials: A #GCredentials.
- * @native_type: The type of native credentials to set.
- * @native: A pointer to native credentials.
- *
- * Copies the native credentials of type @native_type from @native
- * into @credentials.
+ * g_dbus_message_get_locked:
+ * @message: A #GDBusMessage.
*
- * It is a programming error (which will cause an warning to be
- * logged) to use this method if there is no #GCredentials support for
- * the OS or if @native_type isn't supported by the OS.
+ * Checks whether @message is locked. To monitor changes to this
+ * value, conncet to the #GObject::notify signal to listen for changes
+ * on the #GDBusMessage:locked property.
*
+ * Returns: %TRUE if @message is locked, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_credentials_set_unix_user:
- * @credentials: A #GCredentials.
- * @uid: The UNIX user identifier to set.
- * @error: Return location for error or %NULL.
- *
- * Tries to set the UNIX user identifier on @credentials. This method
- * is only available on UNIX platforms.
+ * g_dbus_message_get_member:
+ * @message: A #GDBusMessage.
*
- * 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.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
*
- * Returns: %TRUE if @uid was set, %FALSE if error is set.
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_credentials_to_string:
- * @credentials: A #GCredentials object.
+ * g_dbus_message_get_message_type:
+ * @message: A #GDBusMessage.
*
- * Creates a human-readable textual representation of @credentials
- * that can be used in logging and debug messages. The format of the
- * returned string may change in future GLib release.
+ * Gets the type of @message.
*
- * Returns: A string that should be freed with g_free().
+ * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
* Since: 2.26
*/
/**
- * g_data_input_stream_get_byte_order:
- * @stream: a given #GDataInputStream.
+ * g_dbus_message_get_num_unix_fds:
+ * @message: A #GDBusMessage.
*
- * Gets the byte order for the data input stream.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
*
- * Returns: the @stream's current #GDataStreamByteOrder.
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_get_newline_type:
- * @stream: a given #GDataInputStream.
+ * g_dbus_message_get_path:
+ * @message: A #GDBusMessage.
*
- * Gets the current newline type for the @stream.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
*
- * Returns: #GDataStreamNewlineType for the given @stream.
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_new:
- * @base_stream: a #GInputStream.
+ * g_dbus_message_get_reply_serial:
+ * @message: A #GDBusMessage.
*
- * Creates a new data input stream for the @base_stream.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
*
- * Returns: a new #GDataInputStream.
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_byte:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Reads an unsigned 8-bit/1-byte value from @stream.
+ * g_dbus_message_get_sender:
+ * @message: A #GDBusMessage.
*
- * if an error occurred.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
*
- * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_int16:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Reads a 16-bit/2-byte value from @stream.
- *
- * 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().
+ * g_dbus_message_get_serial:
+ * @message: A #GDBusMessage.
*
- * an error occurred.
+ * Gets the serial for @message.
*
- * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
+ * Returns: A #guint32.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_int32:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Reads a signed 32-bit/4-byte value from @stream.
- *
- * 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().
- *
- * 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_dbus_message_get_signature:
+ * @message: A #GDBusMessage.
*
- * an error occurred.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
*
- * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_int64:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_message_get_unix_fd_list:
+ * @message: A #GDBusMessage.
*
- * Reads a 64-bit/8-byte value from @stream.
+ * Gets the UNIX file descriptors associated with @message, if any.
*
- * 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().
+ * This method is only available on UNIX.
*
- * 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 none): A #GUnixFDList or %NULL if no file descriptors are
+ * associated. Do not free, this object is owned by @message.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_message_lock:
+ * @message: A #GDBusMessage.
*
- * an error occurred.
+ * If @message is locked, does nothing. Otherwise locks the message.
*
- * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line:
- * @stream: a given #GDataInputStream.
- * @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.
+ * g_dbus_message_new:
*
- * Reads a line from the data input stream. Note that no encoding
- * checks or conversion is performed; the input is not guaranteed to
- * be UTF-8, and may in fact have embedded NUL characters.
+ * Creates a new empty #GDBusMessage.
*
- * 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 #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_message_new_from_blob:
+ * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
+ * @blob_len: The length of @blob.
+ * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
+ * @error: Return location for error or %NULL.
*
- * 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.
+ * Creates a new #GDBusMessage from the data stored at @blob. The byte
+ * order that the message was in can be retrieved using
+ * g_dbus_message_get_byte_order().
*
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
+ * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
+ * g_object_unref().
+ * Since: 2.26
*/
/**
- * 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.
- * @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.
- *
- * The asynchronous version of g_data_input_stream_read_line(). It is
- * an error to have two outstanding calls to this function.
+ * g_dbus_message_new_method_call:
+ * @name: (allow-none): A valid D-Bus name or %NULL.
+ * @path: A valid object path.
+ * @interface_: (allow-none): A valid D-Bus interface name or %NULL.
+ * @method: A valid method name.
*
- * When the operation is finished, @callback will be called. You
- * can then call g_data_input_stream_read_line_finish() to get
- * the result of the operation.
+ * Creates a new #GDBusMessage for a method call.
*
- * Since: 2.20
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line_finish:
- * @stream: a given #GDataInputStream.
- * @result: the #GAsyncResult that was provided to the callback.
- * @length: (out): a #gsize to get the length of the data read in.
- * @error: #GError for error reporting.
- *
- * Finish an asynchronous call started by
- * g_data_input_stream_read_line_async(). Note the warning about
- * string encoding in g_data_input_stream_read_line() applies here as
- * well.
+ * 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.
+ * @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.
*
- * 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.
+ * Creates a new #GDBusMessage that is an error reply to @method_call_message.
*
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
- * Since: 2.20
+ * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line_finish_utf8:
- * @stream: a given #GDataInputStream.
- * @result: the #GAsyncResult that was provided to the callback.
- * @length: (out): a #gsize to get the length of the data read in.
- * @error: #GError for error reporting.
- *
- * Finish an asynchronous call started by
- * g_data_input_stream_read_line_async().
+ * 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.
+ * @error_name: A valid D-Bus error name.
+ * @error_message: The D-Bus error message.
*
- * (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.
+ * Creates a new #GDBusMessage that is an error reply to @method_call_message.
*
- * Returns: (transfer full): a string with the line that was read in
- * Since: 2.30
+ * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line_utf8:
- * @stream: a given #GDataInputStream.
- * @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.
- *
- * Reads a UTF-8 encoded line from the data input stream.
- *
- * 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_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.
+ * @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.
*
- * 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.
+ * Like g_dbus_message_new_method_error() but intended for language bindings.
*
- * Returns: (transfer full): a NUL terminated UTF-8 string with the
- * Since: 2.30
+ * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_uint16:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Reads an unsigned 16-bit/2-byte value from @stream.
- *
- * 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().
+ * 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.
*
- * an error occurred.
+ * Creates a new #GDBusMessage that is a reply to @method_call_message.
*
- * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
+ * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_uint32:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Reads an unsigned 32-bit/4-byte value from @stream.
- *
- * 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().
- *
- * 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_dbus_message_new_signal:
+ * @path: A valid object path.
+ * @interface_: A valid D-Bus interface name.
+ * @signal: A valid signal name.
*
- * an error occurred.
+ * Creates a new #GDBusMessage for a signal emission.
*
- * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: A #GDBusMessage. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_uint64:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
- *
- * Reads an unsigned 64-bit/8-byte value from @stream.
- *
- * In order to get the correct byte order for this read operation,
- * see g_data_input_stream_get_byte_order().
+ * g_dbus_message_print: (type method-return)
+ * @message: A #GDBusMessage.
+ * @indent: Indentation level.
*
- * 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.
+ * Produces a human-readable multi-line description of @message.
*
- * an error occurred.
+ * 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:
+ * |[
+ * Flags: none
+ * Version: 0
+ * Serial: 4
+ * Headers:
+ * path -> objectpath '/org/gtk/GDBus/TestObject'
+ * interface -> 'org.gtk.GDBus.TestInterface'
+ * member -> 'GimmeStdout'
+ * destination -> ':1.146'
+ * Body: ()
+ * UNIX File Descriptors:
+ * (none)
+ * ]|
+ * or
+ * |[
+ * 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:
+ * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
+ * ]|
*
- * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
+ * Returns: A string that should be freed with g_free().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_until:
- * @stream: a given #GDataInputStream.
- * @stop_chars: characters to terminate the read.
- * @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.
- *
- * Reads a string from the data input stream, up to the first
- * occurrence of any of the stop characters.
- *
- * Note that, in contrast to g_data_input_stream_read_until_async(),
- * this function consumes the stop character that it finds.
+ * g_dbus_message_set_body:
+ * @message: A #GDBusMessage.
+ * @body: Either %NULL or a #GVariant that is a tuple.
*
- * Don't use this function in new code. Its functionality is
- * inconsistent with g_data_input_stream_read_until_async(). Both
- * functions will be marked as deprecated in a future release. Use
- * g_data_input_stream_read_upto() instead, but note that that function
- * does not consume the stop character.
+ * Sets the body @message. As a side-effect the
+ * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
+ * type string of @body (or cleared if @body is %NULL).
*
- * 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.
+ * If @body is floating, @message assumes ownership of @body.
*
- * Returns: (transfer full): a string with the data that was read
+ * Since: 2.26
*/
/**
- * 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.
- * @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.
- *
- * The asynchronous version of g_data_input_stream_read_until().
- * It is an error to have two outstanding calls to this function.
- *
- * Note that, in contrast to g_data_input_stream_read_until(),
- * this function does not consume the stop character that it finds. You
- * must read it for yourself.
- *
- * When the operation is finished, @callback will be called. You
- * can then call g_data_input_stream_read_until_finish() to get
- * the result of the operation.
- *
- * Don't use this function in new code. Its functionality is
- * inconsistent with g_data_input_stream_read_until(). Both functions
- * will be marked as deprecated in a future release. Use
- * g_data_input_stream_read_upto_async() instead.
+ * g_dbus_message_set_byte_order:
+ * @message: A #GDBusMessage.
+ * @byte_order: The byte order.
*
- * Since: 2.20
+ * Sets the byte order of @message.
*/
/**
- * g_data_input_stream_read_until_finish:
- * @stream: a given #GDataInputStream.
- * @result: the #GAsyncResult that was provided to the callback.
- * @length: (out): a #gsize to get the length of the data read in.
- * @error: #GError for error reporting.
- *
- * Finish an asynchronous call started by
- * g_data_input_stream_read_until_async().
- *
+ * g_dbus_message_set_destination:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * 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.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
*
- * Since: 2.20
- * Returns: (transfer full): a string with the data that was read
+ * Since: 2.26
*/
/**
- * 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
- * @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
- *
- * Reads a string from the data input stream, up to the first
- * 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
- * g_data_input_stream_read_upto() again.
- *
- * Note that @stop_chars may contain '\0' if @stop_chars_len is
- * specified.
+ * g_dbus_message_set_error_name:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * 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
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
*
- * Returns: (transfer full): a string with the data that was read
* 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.
- * @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
- *
- * The asynchronous version of g_data_input_stream_read_upto().
- * 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
- * g_data_input_stream_read_upto() again.
- *
- * Note that @stop_chars may contain '\0' if @stop_chars_len is
- * specified.
+ * g_dbus_message_set_flags:
+ * @message: A #GDBusMessage.
+ * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags
+ * enumeration bitwise ORed together).
*
- * When the operation is finished, @callback will be called. You
- * can then call g_data_input_stream_read_upto_finish() to get
- * the result of the operation.
+ * Sets the flags to set on @message.
*
* Since: 2.26
*/
/**
- * g_data_input_stream_read_upto_finish:
- * @stream: a #GDataInputStream
- * @result: the #GAsyncResult that was provided to the callback
- * @length: (out): a #gsize to get the length of the data read in
- * @error: #GError for error reporting
- *
- * Finish an asynchronous call started by
- * g_data_input_stream_read_upto_async().
+ * g_dbus_message_set_header:
+ * @message: A #GDBusMessage.
+ * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+ * @value: (allow-none): A #GVariant to set the header field or %NULL to clear the header field.
*
- * 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.
+ * Sets a header field on @message.
*
- * 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.
+ * If @value is floating, @message assumes ownership of @value.
*
- * Returns: (transfer full): a string with the data that was read
- * Since: 2.24
+ * Since: 2.26
*/
/**
- * g_data_input_stream_set_byte_order:
- * @stream: a given #GDataInputStream.
- * @order: a #GDataStreamByteOrder to set.
+ * g_dbus_message_set_interface:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * This function sets the byte order for the given @stream. All subsequent
- * reads from the @stream will be read in the given @order.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ *
+ * Since: 2.26
*/
/**
- * g_data_input_stream_set_newline_type:
- * @stream: a #GDataInputStream.
- * @type: the type of new line return as #GDataStreamNewlineType.
+ * g_dbus_message_set_member:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Sets the newline type for the @stream.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
*
- * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
- * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
- * "CR LF", and this might block if there is no more data available.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_get_byte_order:
- * @stream: a #GDataOutputStream.
+ * g_dbus_message_set_message_type:
+ * @message: A #GDBusMessage.
+ * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
*
- * Gets the byte order for the stream.
+ * Sets @message to be of @type.
*
- * Returns: the #GDataStreamByteOrder for the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_new:
- * @base_stream: a #GOutputStream.
+ * g_dbus_message_set_num_unix_fds:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Creates a new data output stream for @base_stream.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
*
- * Returns: #GDataOutputStream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_byte:
- * @stream: a #GDataOutputStream.
- * @data: a #guchar.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_set_path:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Puts a byte into the output stream.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_int16:
- * @stream: a #GDataOutputStream.
- * @data: a #gint16.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_set_reply_serial:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Puts a signed 16-bit integer into the output stream.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_int32:
- * @stream: a #GDataOutputStream.
- * @data: a #gint32.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_set_sender:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Puts a signed 32-bit integer into the output stream.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_int64:
- * @stream: a #GDataOutputStream.
- * @data: a #gint64.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_set_serial:
+ * @message: A #GDBusMessage.
+ * @serial: A #guint32.
*
- * Puts a signed 64-bit integer into the stream.
+ * Sets the serial for @message.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_string:
- * @stream: a #GDataOutputStream.
- * @str: a string.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_set_signature:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Puts a string into the output stream.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
*
- * Returns: %TRUE if @string was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_uint16:
- * @stream: a #GDataOutputStream.
- * @data: a #guint16.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_set_unix_fd_list:
+ * @message: A #GDBusMessage.
+ * @fd_list: (allow-none): A #GUnixFDList or %NULL.
*
- * Puts an unsigned 16-bit integer into the output stream.
+ * Sets the UNIX file descriptors associated with @message. As a
+ * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
+ * field is set to the number of fds in @fd_list (or cleared if
+ * @fd_list is %NULL).
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * This method is only available on UNIX.
+ *
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_uint32:
- * @stream: a #GDataOutputStream.
- * @data: a #guint32.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_to_blob:
+ * @message: A #GDBusMessage.
+ * @out_size: Return location for size of generated blob.
+ * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
+ * @error: Return location for error.
*
- * Puts an unsigned 32-bit integer into the stream.
+ * Serializes @message to a blob. The byte order returned by
+ * g_dbus_message_get_byte_order() will be used.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * 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
*/
/**
- * g_data_output_stream_put_uint64:
- * @stream: a #GDataOutputStream.
- * @data: a #guint64.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_message_to_gerror:
+ * @message: A #GDBusMessage.
+ * @error: The #GError to set.
*
- * Puts an unsigned 64-bit integer into the stream.
+ * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
+ * nothing and returns %FALSE.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Otherwise this method encodes the error in @message as a #GError
+ * using g_dbus_error_set_dbus_error() using the information in the
+ * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
+ * well as the first string item in @message's body.
+ *
+ * Returns: %TRUE if @error was set, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_set_byte_order:
- * @stream: a #GDataOutputStream.
- * @order: a %GDataStreamByteOrder.
+ * g_dbus_method_info_ref:
+ * @info: A #GDBusMethodInfo
*
- * Sets the byte order of the data output stream to @order.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
+ *
+ * Returns: The same @info.
+ * Since: 2.26
*/
/**
- * g_dbus_action_group_get:
- * @connection: A #GDBusConnection
- * @bus_name: the bus name which exports the action group
- * @object_path: the object path at which the action group is exported
- *
- * Obtains a #GDBusActionGroup for the action group which is exported at
- * the given @bus_name and @object_path.
- *
- * The thread default main context is taken at the time of this call.
- * All signals on the menu model (and any linked models) are reported
- * with respect to this context. All calls on the returned menu model
- * (and linked models) must also originate from this same context, with
- * the thread default main context unchanged.
+ * g_dbus_method_info_unref:
+ * @info: A #GDBusMethodInfo.
*
- * This call is non-blocking. The returned action group may or may not
- * already be filled in. The correct thing to do is connect the signals
- * for the action group to monitor for changes and then to call
- * g_action_group_list_actions() to get the initial list.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: (transfer full): a #GDBusActionGroup
- * Since: 2.32
+ * Since: 2.26
*/
/**
- * g_dbus_address_get_for_bus_sync:
- * @bus_type: A #GBusType.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_method_invocation_get_connection:
+ * @invocation: A #GDBusMethodInvocation.
*
- * 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.
+ * Gets the #GDBusConnection the method was invoked on.
*
- * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
+ * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_address_get_stream:
- * @address: A valid D-Bus address.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: Data to pass to @callback.
- *
- * Asynchronously connects to an endpoint specified by @address and
- * sets up the connection so it is in a state to run the client-side
- * of the D-Bus authentication conversation.
+ * g_dbus_method_invocation_get_interface_name:
+ * @invocation: A #GDBusMethodInvocation.
*
- * When the operation is finished, @callback will be invoked. You can
- * then call g_dbus_address_get_stream_finish() to get the result of
- * the operation.
+ * Gets the name of the D-Bus interface the method was invoked on.
*
- * This is an asynchronous failable function. See
- * g_dbus_address_get_stream_sync() for the synchronous version.
+ * 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
*/
/**
- * g_dbus_address_get_stream_finish:
- * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
- * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
- * @error: Return location for error or %NULL.
+ * g_dbus_method_invocation_get_message:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Finishes an operation started with g_dbus_address_get_stream().
+ * Gets the #GDBusMessage for the method invocation. This is useful if
+ * you need to use low-level protocol features, such as UNIX file
+ * descriptor passing, that cannot be properly expressed in the
+ * #GVariant API.
*
- * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
+ * 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
*/
/**
- * g_dbus_address_get_stream_sync:
- * @address: A valid D-Bus address.
- * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_method_invocation_get_method_info:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Synchronously connects to an endpoint specified by @address and
- * sets up the connection so it is in a state to run the client-side
- * of the D-Bus authentication conversation.
+ * Gets information about the method call, if any.
*
- * This is a synchronous failable function. See
- * g_dbus_address_get_stream() for the asynchronous version.
+ * 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: (transfer full): A #GIOStream or %NULL if @error is set.
+ * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_annotation_info_lookup:
- * @annotations: A %NULL-terminated array of annotations or %NULL.
- * @name: The name of the annotation to look up.
- *
- * Looks up the value of an annotation.
+ * g_dbus_method_invocation_get_method_name:
+ * @invocation: A #GDBusMethodInvocation.
*
- * This cost of this function is O(n) in number of annotations.
+ * Gets the name of the method that was invoked.
*
- * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_annotation_info_ref:
- * @info: A #GDBusNodeInfo
+ * g_dbus_method_invocation_get_object_path:
+ * @invocation: A #GDBusMethodInvocation.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Gets the object path the method was invoked on.
*
- * Returns: The same @info.
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_annotation_info_unref:
- * @info: A #GDBusAnnotationInfo.
+ * g_dbus_method_invocation_get_parameters:
+ * @invocation: A #GDBusMethodInvocation.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Gets the parameters of the method invocation. If there are no input
+ * parameters then this will return a GVariant with 0 children rather than NULL.
*
+ * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_arg_info_ref:
- * @info: A #GDBusArgInfo
+ * g_dbus_method_invocation_get_property_info:
+ * @invocation: A #GDBusMethodInvocation
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Gets information about the property that this method call is for, if
+ * any.
*
- * Returns: The same @info.
- * Since: 2.26
+ * 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_arg_info_unref:
- * @info: A #GDBusArgInfo.
+ * g_dbus_method_invocation_get_sender:
+ * @invocation: A #GDBusMethodInvocation.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Gets the bus name that invoked the method.
*
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_auth_observer_authorize_authenticated_peer:
- * @observer: A #GDBusAuthObserver.
- * @stream: A #GIOStream for the #GDBusConnection.
- * @credentials: Credentials received from the peer or %NULL.
+ * g_dbus_method_invocation_get_user_data: (skip)
+ * @invocation: A #GDBusMethodInvocation.
*
- * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
+ * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
*
- * Returns: %TRUE if the peer is authorized, %FALSE if not.
+ * Returns: A #gpointer.
* Since: 2.26
*/
/**
- * g_dbus_auth_observer_new:
+ * g_dbus_method_invocation_return_dbus_error:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @error_name: A valid D-Bus error name.
+ * @error_message: A valid D-Bus error message.
*
- * Creates a new #GDBusAuthObserver object.
+ * Finishes handling a D-Bus method call by returning an error.
+ *
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: A #GDBusAuthObserver. Free with g_object_unref().
* Since: 2.26
*/
/**
- * 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.
+ * g_dbus_method_invocation_return_error:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @domain: A #GQuark for the #GError error domain.
+ * @code: The error code.
+ * @format: printf()-style format.
+ * @...: Parameters for @format.
*
- * Adds a message filter. Filters are handlers that are run on all
- * incoming and outgoing messages, prior to standard dispatch. Filters
- * are run in the order that they were added. The same handler can be
- * added as a filter more than once, in which case it will be run more
- * than once. Filters added during a filter callback won't be run on
- * the message being processed. Filter functions are allowed to modify
- * and even drop messages.
+ * Finishes handling a D-Bus method call by returning an error.
*
- * Note that filters are run in a dedicated message handling thread so
- * they can't block and, generally, can't do anything but signal a
- * worker thread. Also note that filters are rarely needed - use API
- * such as g_dbus_connection_send_message_with_reply(),
- * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
+ * See g_dbus_error_encode_gerror() for details about what error name
+ * 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
+ * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
+ * transparent mapping of #GError between applications using GDBus.
*
- * If a filter consumes an incoming message the message is not
- * dispatched anywhere else - not even the standard dispatch machinery
- * (that API such as g_dbus_connection_signal_subscribe() and
- * g_dbus_connection_send_message_with_reply() relies on) will see the
- * message. Similary, if a filter consumes an outgoing message, the
- * message will not be sent to the other peer.
+ * If you are writing an application intended to be portable,
+ * always register errors with g_dbus_error_register_error()
+ * or use g_dbus_method_invocation_return_dbus_error().
*
- * g_dbus_connection_remove_filter().
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: A filter identifier that can be used with
* 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: 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.
+ * g_dbus_method_invocation_return_error_literal:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @domain: A #GQuark for the #GError error domain.
+ * @code: The error code.
+ * @message: The error message.
*
- * Asynchronously invokes the @method_name method on the
- * @interface_name D-Bus interface on the remote object at
- * @object_path owned by @bus_name.
+ * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
*
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
- * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
- * not compatible with the D-Bus protocol, the operation fails with
- * %G_IO_ERROR_INVALID_ARGUMENT.
+ * This method will free @invocation, you cannot use it afterwards.
*
- * If @reply_type is non-%NULL then the reply will be checked for having this type and an
- * error will be raised if it does not match. Said another way, if you give a @reply_type
- * then any non-%NULL return value will be of this type.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_method_invocation_return_error_valist:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @domain: A #GQuark for the #GError error domain.
+ * @code: The error code.
+ * @format: printf()-style format.
+ * @var_args: #va_list of parameters for @format.
*
- * If the @parameters #GVariant is floating, it is consumed. This allows
- * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
- * g_dbus_connection_call (connection,
- * "org.freedesktop.StringThings",
- * "/org/freedesktop/StringThings",
- * "org.freedesktop.StringThings",
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * NULL,
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * (GAsyncReadyCallback) two_strings_done,
- * NULL);
- * ]|
+ * Like g_dbus_method_invocation_return_error() but intended for
+ * language bindings.
*
- * 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 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
- * function.
+ * This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
*/
/**
- * 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.
+ * g_dbus_method_invocation_return_gerror:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @error: A #GError.
*
- * Finishes an operation started with g_dbus_connection_call().
+ * Like g_dbus_method_invocation_return_error() but takes a #GError
+ * instead of the error domain, error code and message.
*
- * return values. Free with g_variant_unref().
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
* 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: 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
- * @object_path owned by @bus_name.
- *
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
- * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
- * contains a value not compatible with the D-Bus protocol, the operation
- * fails with %G_IO_ERROR_INVALID_ARGUMENT.
- * If @reply_type is non-%NULL then the reply will be checked for having
- * this type and an error will be raised if it does not match. Said
- * another way, if you give a @reply_type then any non-%NULL return
- * value will be of this type.
+ * g_dbus_method_invocation_return_value:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
*
- * If the @parameters #GVariant is floating, it is consumed.
- * This allows convenient 'inline' use of g_variant_new(), e.g.:
- * |[
- * g_dbus_connection_call_sync (connection,
- * "org.freedesktop.StringThings",
- * "/org/freedesktop/StringThings",
- * "org.freedesktop.StringThings",
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * NULL,
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * &error);
- * ]|
+ * Finishes handling a D-Bus method call by returning @parameters.
+ * If the @parameters GVariant is floating, it is consumed.
*
- * The calling thread is blocked until a reply is received. See
- * g_dbus_connection_call() for the asynchronous version of
- * this method.
+ * It is an error if @parameters is not of the right format.
*
- * return values. Free with g_variant_unref().
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
* 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.
+ * g_dbus_method_invocation_return_value_with_unix_fd_list:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
* @fd_list: (allow-none): A #GUnixFDList or %NULL.
- * @cancellable: 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.
+ * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
*
* This method is only available on UNIX.
*
+ * This method will free @invocation, you cannot use it afterwards.
+ *
* Since: 2.30
*/
/**
- * g_dbus_connection_call_with_unix_fd_list_finish:
- * @connection: A #GDBusConnection.
- * @out_fd_list: (out): 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.
+ * g_dbus_method_invocation_take_error: (skip)
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @error: (transfer full): A #GError.
*
- * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
+ * Like g_dbus_method_invocation_return_gerror() but takes ownership
+ * of @error so the caller does not need to free it.
*
- * return values. Free with g_variant_unref().
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
* 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): Return location for a #GUnixFDList or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
- *
- * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
+ * g_dbus_node_info_generate_xml:
+ * @info: A #GDBusNodeInfo.
+ * @indent: Indentation level.
+ * @string_builder: (out): A #GString to to append XML data to.
*
- * This method is only available on UNIX.
+ * Appends an XML representation of @info (and its children) to @string_builder.
*
- * return values. Free with g_variant_unref().
+ * This function is typically used for generating introspection XML documents at run-time for
+ * handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_connection_close:
- * @connection: A #GDBusConnection.
- * @cancellable: 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.
+ * g_dbus_node_info_lookup_interface:
+ * @info: A #GDBusNodeInfo.
+ * @name: A D-Bus interface name.
*
- * Closes @connection. Note that this never causes the process to
- * exit (this might only happen if the other end of a shared message
- * bus connection disconnects, see #GDBusConnection:exit-on-close).
+ * Looks up information about an interface.
*
- * Once the connection is closed, operations such as sending a message
- * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
- * will not automatically flush the connection so queued messages may
- * be lost. Use g_dbus_connection_flush() if you need such guarantees.
+ * The cost of this function is O(n) in number of interfaces.
*
- * If @connection is already closed, this method fails with
- * %G_IO_ERROR_CLOSED.
+ * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_node_info_new_for_xml:
+ * @xml_data: Valid D-Bus introspection XML.
+ * @error: Return location for error.
*
- * 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.
+ * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
*
- * 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
- * then call g_dbus_connection_close_finish() to get the result of the
- * operation. See g_dbus_connection_close_sync() for the synchronous
- * version.
+ * The introspection XML must contain exactly one top-level
+ * <node> element.
+ *
+ * Note that this routine is using a
+ * [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().
* 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.
+ * g_dbus_node_info_ref:
+ * @info: A #GDBusNodeInfo
*
- * Finishes an operation started with g_dbus_connection_close().
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: The same @info.
* Since: 2.26
*/
/**
- * g_dbus_connection_close_sync:
- * @connection: A #GDBusConnection.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_node_info_unref:
+ * @info: A #GDBusNodeInfo.
*
- * 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.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * 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.
- *
- * Emits a signal.
- *
- * If the parameters GVariant is floating, it is consumed.
+ * g_dbus_object_get_interface:
+ * @object: A #GDBusObject.
+ * @interface_name: A D-Bus interface name.
*
- * This can only fail if @parameters is not compatible with the D-Bus protocol.
+ * Gets the D-Bus interface with name @interface_name associated with
+ * @object, if any.
*
- * Returns: %TRUE unless @error is set.
- * Since: 2.26
+ * Returns: (transfer full): %NULL if not found, otherwise a
+ * #GDBusInterface that must be freed with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_export_action_group:
- * @connection: a #GDBusConnection
- * @object_path: a D-Bus object path
- * @action_group: a #GActionGroup
- * @error: a pointer to a %NULL #GError, or %NULL
- *
- * Exports @action_group on @connection at @object_path.
- *
- * The implemented D-Bus API should be considered private. It is
- * subject to change in the future.
- *
- * A given object path can only have one action group exported on it.
- * If this constraint is violated, the export will fail and 0 will be
- * returned (with @error set accordingly).
- *
- * You can unexport the action group using
- * g_dbus_connection_unexport_action_group() with the return value of
- * this function.
+ * g_dbus_object_get_interfaces:
+ * @object: A #GDBusObject.
*
- * The thread default main context is taken at the time of this call.
- * All incoming action activations and state change requests are
- * reported from this context. Any changes on the action group that
- * cause it to emit signals must also come from this same context.
- * Since incoming action activations and state change requests are
- * rather likely to cause changes on the action group, this effectively
- * limits a given action group to being exported from only one main
- * context.
+ * Gets the D-Bus interfaces associated with @object.
*
- * Returns: the ID of the export (never zero), or 0 in case of failure
- * Since: 2.32
+ * 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
*/
/**
- * g_dbus_connection_export_menu_model:
- * @connection: a #GDBusConnection
- * @object_path: a D-Bus object path
- * @menu: a #GMenuModel
- * @error: return location for an error, or %NULL
- *
- * Exports @menu on @connection at @object_path.
- *
- * 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
- * constraint is violated, the export will fail and 0 will be
- * returned (with @error set accordingly).
+ * g_dbus_object_get_object_path:
+ * @object: A #GDBusObject.
*
- * You can unexport the menu model using
- * g_dbus_connection_unexport_menu_model() with the return value of
- * this function.
+ * Gets the object path for @object.
*
- * Returns: the ID of the export (never zero), or 0 in case of failure
- * Since: 2.32
+ * Returns: A string owned by @object. Do not free.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_flush:
- * @connection: A #GDBusConnection.
- * @cancellable: 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.
+ * g_dbus_object_manager_client_get_connection:
+ * @manager: A #GDBusObjectManagerClient
*
- * 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
- * then call g_dbus_connection_flush_finish() to get the result of the
- * operation. See g_dbus_connection_flush_sync() for the synchronous
- * version.
+ * Gets the #GDBusConnection used by @manager.
*
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusConnection object. Do not free,
+ * the object belongs to @manager.
+ * Since: 2.30
*/
/**
- * 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.
+ * g_dbus_object_manager_client_get_flags:
+ * @manager: A #GDBusObjectManagerClient
*
- * Finishes an operation started with g_dbus_connection_flush().
+ * Gets the flags that @manager was constructed with.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
- * Since: 2.26
+ * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
+ * enumeration.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_flush_sync:
- * @connection: A #GDBusConnection.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_object_manager_client_get_name:
+ * @manager: A #GDBusObjectManagerClient
*
- * 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.
+ * Gets the name that @manager is for, or %NULL if not a message bus
+ * connection.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
- * Since: 2.26
+ * Returns: A unique or well-known name. Do not free, the string
+ * belongs to @manager.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_capabilities:
- * @connection: A #GDBusConnection.
+ * g_dbus_object_manager_client_get_name_owner:
+ * @manager: A #GDBusObjectManagerClient.
*
- * Gets the capabilities negotiated with the remote peer
+ * The unique name that owns the name that @manager is for or %NULL if
+ * no-one currently owns that name. You can connect to the
+ * #GObject::notify signal to track changes to the
+ * #GDBusObjectManagerClient:name-owner property.
*
- * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
- * Since: 2.26
+ * Returns: (nullable): The name owner or %NULL if no name owner
+ * exists. Free with g_free().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_exit_on_close:
+ * g_dbus_object_manager_client_new:
* @connection: A #GDBusConnection.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @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.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data 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.
*
- * Gets whether the process is terminated when @connection is
- * closed by the remote peer. See
- * #GDBusConnection:exit-on-close for more details.
+ * Asynchronously creates a new #GDBusObjectManagerClient object.
*
- * closed by the remote peer.
+ * This is an asynchronous failable constructor. When the result is
+ * ready, @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_object_manager_client_new_finish() to get the result. See
+ * g_dbus_object_manager_client_new_sync() for the synchronous version.
*
- * Returns: Whether the process is terminated when @connection is
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_guid:
- * @connection: A #GDBusConnection.
- *
- * The GUID of the peer performing the role of server when
- * authenticating. See #GDBusConnection:guid for more details.
+ * g_dbus_object_manager_client_new_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
+ * @error: Return location for error or %NULL.
*
- * @connection.
+ * Finishes an operation started with g_dbus_object_manager_client_new().
*
- * Returns: The GUID. Do not free this string, it is owned by
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_peer_credentials:
- * @connection: A #GDBusConnection.
- *
- * Gets the credentials of the authenticated peer. This will always
- * return %NULL unless @connection acted as a server
- * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
- * when set up and the client passed credentials as part of the
- * authentication process.
+ * g_dbus_object_manager_client_new_for_bus:
+ * @bus_type: A #GBusType.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @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.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data 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.
*
- * In a message bus setup, the message bus is always the server and
- * each application is a client. So this method will always return
- * %NULL for message bus clients.
+ * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
+ * #GDBusConnection.
*
- * this object, it is owned by @connection.
+ * This is an asynchronous failable constructor. When the result is
+ * ready, @callback will be invoked in the
+ * [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.
*
- * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_stream:
- * @connection: a #GDBusConnection
- *
- * Gets the underlying stream used for IO.
+ * g_dbus_object_manager_client_new_for_bus_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
+ * @error: Return location for error or %NULL.
*
- * While the #GDBusConnection is active, it will interact with this
- * stream from a worker thread, so it is not safe to interact with
- * the stream directly.
+ * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
*
- * Returns: (transfer none): the stream used for IO
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_unique_name:
- * @connection: A #GDBusConnection.
+ * g_dbus_object_manager_client_new_for_bus_sync:
+ * @bus_type: A #GBusType.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @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.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
+ * @cancellable: (allow-none): A #GCancellable or %NULL
+ * @error: Return location for error or %NULL.
*
- * 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.
+ * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
+ * of a #GDBusConnection.
*
- * bus connection. Do not free this string, it is owned by
- * @connection.
+ * This is a synchronous failable constructor - the calling thread is
+ * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
+ * for the asynchronous version.
*
- * Returns: The unique name or %NULL if @connection is not a message
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_is_closed:
+ * g_dbus_object_manager_client_new_sync:
* @connection: A #GDBusConnection.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @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.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
+ * @cancellable: (allow-none): A #GCancellable or %NULL
+ * @error: Return location for error or %NULL.
*
- * Gets whether @connection is closed.
+ * Creates a new #GDBusObjectManagerClient object.
*
- * Returns: %TRUE if the connection is closed, %FALSE otherwise.
- * Since: 2.26
+ * This is a synchronous failable constructor - the calling thread is
+ * 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().
+ * Since: 2.30
*/
/**
- * 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: 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.
- *
- * If @stream is a #GSocketConnection, then the corresponding #GSocket
- * will be put into non-blocking mode.
- *
- * The D-Bus connection will interact with @stream from a worker thread.
- * As a result, the caller should not interact with @stream after this
- * method has been called, except by calling g_object_unref() on it.
- *
- * If @observer is not %NULL it may be used to control the
- * authentication process.
- *
- * When the operation is finished, @callback will be invoked. You can
- * then call g_dbus_connection_new_finish() to get the result of the
- * operation.
+ * g_dbus_object_manager_get_interface:
+ * @manager: A #GDBusObjectManager.
+ * @object_path: Object path to lookup.
+ * @interface_name: D-Bus interface name to lookup.
*
- * This is a asynchronous failable constructor. See
- * g_dbus_connection_new_sync() for the synchronous
- * version.
+ * Gets the interface proxy for @interface_name at @object_path, if
+ * any.
*
- * Since: 2.26
+ * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
+ * with g_object_unref().
+ * Since: 2.30
*/
/**
- * 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.
+ * g_dbus_object_manager_get_object:
+ * @manager: A #GDBusObjectManager.
+ * @object_path: Object path to lookup.
*
- * Finishes an operation started with g_dbus_connection_new().
+ * Gets the #GDBusObjectProxy at @object_path, if any.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: (transfer full): A #GDBusObject or %NULL. Free with
+ * g_object_unref().
+ * Since: 2.30
*/
/**
- * 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: 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
- * which must be in the D-Bus address format.
- *
- * This constructor can only be used to initiate client-side
- * connections - use g_dbus_connection_new() if you need to act as the
- * server. In particular, @flags cannot contain the
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
- *
- * When the operation is finished, @callback will be invoked. You can
- * then call g_dbus_connection_new_finish() to get the result of the
- * operation.
- *
- * If @observer is not %NULL it may be used to control the
- * authentication process.
+ * g_dbus_object_manager_get_object_path:
+ * @manager: A #GDBusObjectManager.
*
- * This is a asynchronous failable constructor. See
- * g_dbus_connection_new_for_address_sync() for the synchronous
- * version.
+ * Gets the object path that @manager is for.
*
- * Since: 2.26
+ * Returns: A string owned by @manager. Do not free.
+ * Since: 2.30
*/
/**
- * 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.
+ * g_dbus_object_manager_get_objects:
+ * @manager: A #GDBusObjectManager.
*
- * Finishes an operation started with g_dbus_connection_new_for_address().
+ * Gets all #GDBusObject objects known to @manager.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * 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
*/
/**
- * 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: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_object_manager_server_export:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object: A #GDBusObjectSkeleton.
*
- * Synchronously connects and sets up a D-Bus client connection for
- * exchanging D-Bus messages with an endpoint specified by @address
- * which must be in the D-Bus address format.
+ * Exports @object on @manager.
*
- * This constructor can only be used to initiate client-side
- * connections - use g_dbus_connection_new_sync() if you need to act
- * as the server. In particular, @flags cannot contain the
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+ * If there is already a #GDBusObject exported at the object path,
+ * then the old object is removed.
*
- * This is a synchronous failable constructor. See
- * g_dbus_connection_new_for_address() for the asynchronous version.
+ * The object path for @object must be in the hierarchy rooted by the
+ * object path for @manager.
*
- * If @observer is not %NULL it may be used to control the
- * authentication process.
+ * Note that @manager will take a reference on @object for as long as
+ * it is exported.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * 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: 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.
- *
- * If @stream is a #GSocketConnection, then the corresponding #GSocket
- * will be put into non-blocking mode.
- *
- * The D-Bus connection will interact with @stream from a worker thread.
- * As a result, the caller should not interact with @stream after this
- * method has been called, except by calling g_object_unref() on it.
- *
- * If @observer is not %NULL it may be used to control the
- * authentication process.
+ * g_dbus_object_manager_server_export_uniquely:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object: An object.
*
- * This is a synchronous failable constructor. See
- * g_dbus_connection_new() for the asynchronous version.
+ * Like g_dbus_object_manager_server_export() but appends a string of
+ * 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.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * 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.
- *
- * 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.
- *
- * 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>
- * 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
- * are returned to the caller.
- *
- * It is considered a programming error if the
- * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
- * #GVariant of incorrect type.
- *
- * If an existing callback is already registered at @object_path and
- * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
- *
- * 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.
- *
- * 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.
+ * g_dbus_object_manager_server_get_connection:
+ * @manager: A #GDBusObjectManagerServer
*
- * that can be used with g_dbus_connection_unregister_object() .
+ * Gets the #GDBusConnection used by @manager.
*
- * Returns: 0 if @error is set, otherwise a registration id (never 0)
- * Since: 2.26
+ * 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
*/
/**
- * 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.
- *
- * Registers a whole subtree of <quote>dynamic</quote> objects.
- *
- * The @enumerate and @introspection functions in @vtable are used to
- * convey, to remote callers, what nodes exist in the subtree rooted
- * by @object_path.
- *
- * When handling remote calls into any node in the subtree, first the
- * @enumerate function is used to check if the node exists. If the node exists
- * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
- * the @introspection function is used to check if the node supports the
- * requested method. If so, the @dispatch function is used to determine
- * where to dispatch the call. The collected #GDBusInterfaceVTable and
- * #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.
- *
- * If an existing subtree is already registered at @object_path or
- * then @error is set to #G_IO_ERROR_EXISTS.
- *
- * Note that it is valid to register regular objects (using
- * 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.
- *
- * 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.
+ * g_dbus_object_manager_server_is_exported:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object: An object.
*
- * that can be used with g_dbus_connection_unregister_subtree() .
+ * Returns whether @object is currently exported on @manager.
*
- * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
- * Since: 2.26
+ * Returns: %TRUE if @object is exported
+ * Since: 2.34
*/
/**
- * g_dbus_connection_remove_filter:
- * @connection: a #GDBusConnection
- * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
+ * g_dbus_object_manager_server_new:
+ * @object_path: The object path to export the manager object at.
*
- * Removes a filter.
+ * Creates a new #GDBusObjectManagerServer object.
*
- * Since: 2.26
+ * The returned server isn't yet exported on any connection. To do so,
+ * use g_dbus_object_manager_server_set_connection(). Normally you
+ * want to export all of your objects before doing so to avoid <ulink
+ * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
+ * signals being emitted.
+ *
+ * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
+ * Since: 2.30
*/
/**
- * 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.
- *
- * Asynchronously sends @message to the peer represented by @connection.
- *
- * Unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
- * will be assigned by @connection and set on @message via
- * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
- * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
- *
- * If @connection is closed then the operation will fail with
- * %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.
- *
- * Note that @message must be unlocked, unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
- *
- * transmission, %FALSE if @error is set.
+ * g_dbus_object_manager_server_set_connection:
+ * @manager: A #GDBusObjectManagerServer.
+ * @connection: (allow-none): A #GDBusConnection or %NULL.
*
- * Returns: %TRUE if the message was well-formed and queued for
- * Since: 2.26
+ * Exports all objects managed by @manager on @connection. If
+ * @connection is %NULL, stops exporting objects.
*/
/**
- * 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: 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.
- *
- * Unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
- * will be assigned by @connection and set on @message via
- * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
- * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
+ * g_dbus_object_manager_server_unexport:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object_path: An object path.
*
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
- * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
- * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ * If @manager has an object at @path, removes the object. Otherwise
+ * does nothing.
*
- * 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 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 @object_path must be in the hierarchy rooted by the
+ * object path for @manager.
*
- * Note that @message must be unlocked, unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_dbus_object_proxy_get_connection:
+ * @proxy: a #GDBusObjectProxy
*
- * 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.
+ * Gets the connection that @proxy is for.
*
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusConnection. Do not free, the
+ * object is owned by @proxy.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_send_message_with_reply_finish:
+ * g_dbus_object_proxy_new:
* @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.
- *
- * Finishes an operation started with g_dbus_connection_send_message_with_reply().
- *
- * Note that @error is only set if a local in-process error
- * occurred. That is to say that the returned #GDBusMessage object may
- * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
- * g_dbus_message_to_gerror() to transcode this to a #GError.
+ * @object_path: the object path
*
- * 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.
+ * Creates a new #GDBusObjectProxy for the given connection and
+ * object path.
*
- * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
- * Since: 2.26
+ * Returns: a new #GDBusObjectProxy
+ * Since: 2.30
*/
/**
- * 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: 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
- * timeout is reached. See g_dbus_connection_send_message_with_reply()
- * for the asynchronous version of this method.
- *
- * Unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
- * will be assigned by @connection and set on @message via
- * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
- * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
- *
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
- * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
- * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ * g_dbus_object_skeleton_add_interface:
+ * @object: A #GDBusObjectSkeleton.
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Note that @error is only set if a local in-process error
- * occurred. That is to say that the returned #GDBusMessage object may
- * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
- * g_dbus_message_to_gerror() to transcode this to a #GError.
+ * Adds @interface_ to @object.
*
- * 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.
+ * If @object already contains a #GDBusInterfaceSkeleton with the same
+ * interface name, it is removed before @interface_ is added.
*
- * Note that @message must be unlocked, unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ * Note that @object takes its own reference on @interface_ and holds
+ * it until removed.
*
- * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * 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.
- *
- * Sets whether the process should be terminated when @connection is
- * closed by the remote peer. See #GDBusConnection:exit-on-close for
- * more details.
+ * g_dbus_object_skeleton_flush:
+ * @object: A #GDBusObjectSkeleton.
*
- * Note that this function should be used with care. Most modern UNIX
- * desktops tie the notion of a user session the session bus, and expect
- * all of a users applications to quit when their bus connection goes away.
- * If you are setting @exit_on_close to %FALSE for the shared session
- * bus connection, you should make sure that your application exits
- * when the user session ends.
+ * This method simply calls g_dbus_interface_skeleton_flush() on all
+ * interfaces belonging to @object. See that method for when flushing
+ * is useful.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * 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.
- *
- * 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.
- *
- * If @connection is not a message bus connection, @sender must be
- * %NULL.
+ * g_dbus_object_skeleton_new:
+ * @object_path: An object path.
*
- * If @sender is a well-known name note that @callback is invoked with
- * the unique name for the owner of @sender, not the well-known name
- * as one would expect. This is because the message bus rewrites the
- * name. As such, to avoid certain race conditions, users should be
- * tracking the name owner of the well-known name and use that when
- * processing the received signal.
+ * Creates a new #GDBusObjectSkeleton.
*
- * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
- * Since: 2.26
+ * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_signal_unsubscribe:
- * @connection: A #GDBusConnection.
- * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
+ * g_dbus_object_skeleton_remove_interface:
+ * @object: A #GDBusObjectSkeleton.
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Unsubscribes from signals.
+ * Removes @interface_ from @object.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_start_message_processing:
- * @connection: A #GDBusConnection.
+ * g_dbus_object_skeleton_remove_interface_by_name:
+ * @object: A #GDBusObjectSkeleton.
+ * @interface_name: A D-Bus interface name.
*
- * If @connection was created with
- * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
- * starts processing messages. Does nothing on if @connection wasn't
- * created with this flag or if the method has already been called.
+ * Removes the #GDBusInterface with @interface_name from @object.
*
- * Since: 2.26
+ * If no D-Bus interface of the given interface exists, this function
+ * does nothing.
+ *
+ * Since: 2.30
*/
/**
- * g_dbus_connection_unexport_action_group:
- * @connection: a #GDBusConnection
- * @export_id: the ID from g_dbus_connection_export_action_group()
- *
- * Reverses the effect of a previous call to
- * g_dbus_connection_export_action_group().
+ * g_dbus_object_skeleton_set_object_path:
+ * @object: A #GDBusObjectSkeleton.
+ * @object_path: A valid D-Bus object path.
*
- * It is an error to call this function with an ID that wasn't returned
- * from g_dbus_connection_export_action_group() or to call it with the
- * same ID more than once.
+ * Sets the object path for @object.
*
- * Since: 2.32
+ * Since: 2.30
*/
/**
- * g_dbus_connection_unexport_menu_model:
- * @connection: a #GDBusConnection
- * @export_id: the ID from g_dbus_connection_export_menu_model()
- *
- * Reverses the effect of a previous call to
- * g_dbus_connection_export_menu_model().
+ * g_dbus_property_info_ref:
+ * @info: A #GDBusPropertyInfo
*
- * It is an error to call this function with an ID that wasn't returned
- * from g_dbus_connection_export_menu_model() or to call it with the
- * same ID more than once.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Since: 2.32
+ * Returns: The same @info.
+ * Since: 2.26
*/
/**
- * g_dbus_connection_unregister_object:
- * @connection: A #GDBusConnection.
- * @registration_id: A registration id obtained from g_dbus_connection_register_object().
+ * g_dbus_property_info_unref:
+ * @info: A #GDBusPropertyInfo.
*
- * Unregisters an object.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * 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().
+ * g_dbus_proxy_call:
+ * @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.
+ * @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.
+ * @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.
*
- * Unregisters a subtree.
+ * Asynchronously invokes the @method_name method on @proxy.
+ *
+ * If @method_name contains any dots, then @name is split into interface and
+ * method name parts. This allows using @proxy for invoking methods on
+ * other interfaces.
+ *
+ * If the #GDBusConnection associated with @proxy is closed then
+ * the operation will fail with %G_IO_ERROR_CLOSED. If
+ * @cancellable is canceled, the operation will fail with
+ * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
+ * compatible with the D-Bus protocol, the operation fails with
+ * %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * 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)",
+ * "Thing One",
+ * "Thing Two"),
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * (GAsyncReadyCallback) two_strings_done,
+ * &data);
+ * ]|
+ *
+ * If @proxy has an expected interface (see
+ * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
+ * then the return value is checked against the return type.
+ *
+ * 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_proxy_call_finish() to get the result of
+ * the operation. See g_dbus_proxy_call_sync() for the synchronous
+ * version of this method.
+ *
+ * If @callback is %NULL then the D-Bus method call message will be sent with
+ * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
*
- * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_error_encode_gerror:
- * @error: A #GError.
- *
- * Creates a D-Bus error name to use for @error. If @error matches
- * a registered error (cf. g_dbus_error_register_error()), the corresponding
- * 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>
- * 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_proxy_call_finish:
+ * @proxy: A #GDBusProxy.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
+ * @error: Return location for error or %NULL.
*
- * This function is typically only used in object mappings to put a
- * #GError on the wire. Regular applications should not use it.
+ * Finishes an operation started with g_dbus_proxy_call().
*
- * Returns: A D-Bus error name (never %NULL). Free with g_free().
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
* Since: 2.26
*/
/**
- * g_dbus_error_get_remote_error:
- * @error: A #GError.
+ * 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.
+ * @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.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Gets the D-Bus error name used for @error, if any.
+ * Synchronously invokes the @method_name method on @proxy.
*
- * 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
- * g_dbus_error_strip_remote_error() has been used on @error.
+ * If @method_name contains any dots, then @name is split into interface and
+ * method name parts. This allows using @proxy for invoking methods on
+ * other interfaces.
+ *
+ * If the #GDBusConnection associated with @proxy is disconnected then
+ * the operation will fail with %G_IO_ERROR_CLOSED. If
+ * @cancellable is canceled, the operation will fail with
+ * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
+ * compatible with the D-Bus protocol, the operation fails with
+ * %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * 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)",
+ * "Thing One",
+ * "Thing Two"),
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * &error);
+ * ]|
+ *
+ * The calling thread is blocked until a reply is received. See
+ * g_dbus_proxy_call() for the asynchronous version of this
+ * method.
+ *
+ * If @proxy has an expected interface (see
+ * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
+ * then the return value is checked against the return type.
*
- * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
* Since: 2.26
*/
/**
- * g_dbus_error_is_remote_error:
- * @error: A #GError.
+ * g_dbus_proxy_call_with_unix_fd_list:
+ * @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.
+ * @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.
+ * @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.
*
- * 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.
+ * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
*
- * %FALSE otherwise.
+ * This method is only available on UNIX.
*
- * Returns: %TRUE if @error represents an error from a remote peer,
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_error_new_for_dbus_error:
- * @dbus_error_name: D-Bus error name.
- * @dbus_error_message: D-Bus error message.
- *
- * Creates a #GError based on the contents of @dbus_error_name and
- * @dbus_error_message.
- *
- * Errors registered with g_dbus_error_register_error() will be looked
- * up using @dbus_error_name and if a match is found, the error domain
- * and code is used. Applications can use g_dbus_error_get_remote_error()
- * to recover @dbus_error_name.
- *
- * If a match against a registered error is not found and the D-Bus
- * error name is in a form as returned by g_dbus_error_encode_gerror()
- * the error domain and code encoded in the name is used to
- * create the #GError. Also, @dbus_error_name is added to the error message
- * such that it can be recovered with g_dbus_error_get_remote_error().
- *
- * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
- * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
- * added to the error message such that it can be recovered with
- * g_dbus_error_get_remote_error().
- *
- * In all three cases, @dbus_error_name can always be recovered from the
- * returned #GError using the g_dbus_error_get_remote_error() function
- * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
+ * g_dbus_proxy_call_with_unix_fd_list_finish:
+ * @proxy: A #GDBusProxy.
+ * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
+ * @error: Return location for error or %NULL.
*
- * This function is typically only used in object mappings to prepare
- * #GError instances for applications. Regular applications should not use
- * it.
+ * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
*
- * Returns: An allocated #GError. Free with g_error_free().
- * Since: 2.26
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_error_register_error:
- * @error_domain: A #GQuark for a error domain.
- * @error_code: An error code.
- * @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.
+ * 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.
+ * @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.
+ * @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.
*
- * This is typically done in the routine that returns the #GQuark for
- * an error domain.
+ * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
*
- * exists.
+ * This method is only available on UNIX.
*
- * Returns: %TRUE if the association was created, %FALSE if it already
- * Since: 2.26
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * return values. Free with g_variant_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_error_register_error_domain:
- * @error_domain_quark_name: The error domain name.
- * @quark_volatile: A pointer where to store the #GQuark.
- * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
- * @num_entries: Number of items to register.
+ * g_dbus_proxy_get_cached_property:
+ * @proxy: A #GDBusProxy.
+ * @property_name: Property name.
*
- * Helper function for associating a #GError error domain with D-Bus error names.
+ * Looks up the value for a property from the cache. This call does no
+ * blocking IO.
+ *
+ * If @proxy has an expected interface (see
+ * #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().
* Since: 2.26
*/
/**
- * g_dbus_error_set_dbus_error:
- * @error: A pointer to a #GError or %NULL.
- * @dbus_error_name: D-Bus error name.
- * @dbus_error_message: D-Bus error message.
- * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
- * @...: Arguments for @format.
+ * g_dbus_proxy_get_cached_property_names:
+ * @proxy: A #GDBusProxy.
*
- * Does nothing if @error is %NULL. Otherwise sets *@error to
- * a new #GError created with g_dbus_error_new_for_dbus_error()
- * with @dbus_error_message prepend with @format (unless %NULL).
+ * 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().
* Since: 2.26
*/
/**
- * g_dbus_error_set_dbus_error_valist:
- * @error: A pointer to a #GError or %NULL.
- * @dbus_error_name: D-Bus error name.
- * @dbus_error_message: D-Bus error message.
- * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
- * @var_args: Arguments for @format.
+ * g_dbus_proxy_get_connection:
+ * @proxy: A #GDBusProxy.
*
- * Like g_dbus_error_set_dbus_error() but intended for language bindings.
+ * Gets the connection @proxy is for.
*
+ * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
* Since: 2.26
*/
/**
- * g_dbus_error_strip_remote_error:
- * @error: A #GError.
+ * g_dbus_proxy_get_default_timeout:
+ * @proxy: A #GDBusProxy.
*
- * Looks for extra information in the error message used to recover
- * the D-Bus error name and strips it if found. If stripped, the
- * message field in @error will correspond exactly to what was
- * received on the wire.
+ * Gets the timeout to use if -1 (specifying default timeout) is
+ * passed as @timeout_msec in the g_dbus_proxy_call() and
+ * g_dbus_proxy_call_sync() functions.
*
- * This is typically used when presenting errors to the end user.
+ * See the #GDBusProxy:g-default-timeout property for more details.
*
- * Returns: %TRUE if information was stripped, %FALSE otherwise.
+ * Returns: Timeout to use for @proxy.
* Since: 2.26
*/
/**
- * g_dbus_error_unregister_error:
- * @error_domain: A #GQuark for a error domain.
- * @error_code: An error code.
- * @dbus_error_name: A D-Bus error name.
+ * g_dbus_proxy_get_flags:
+ * @proxy: A #GDBusProxy.
*
- * Destroys an association previously set up with g_dbus_error_register_error().
+ * Gets the flags that @proxy was constructed with.
*
- * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
+ * Returns: Flags from the #GDBusProxyFlags enumeration.
* Since: 2.26
*/
/**
- * g_dbus_generate_guid:
- *
- * Generate a D-Bus GUID that can be used with
- * e.g. g_dbus_connection_new().
+ * g_dbus_proxy_get_interface_info:
+ * @proxy: A #GDBusProxy
*
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * Returns the #GDBusInterfaceInfo, if any, specifying the interface
+ * that @proxy conforms to. See the #GDBusProxy:g-interface-info
+ * property for more details.
*
- * Returns: A valid D-Bus GUID. Free with g_free().
+ * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
+ * object, it is owned by @proxy.
* Since: 2.26
*/
/**
- * g_dbus_gvalue_to_gvariant:
- * @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.
- *
- * 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>
- * 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.
- *
- * 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).
- *
- * See the g_dbus_gvariant_to_gvalue() function for how to convert a
- * #GVariant to a #GValue.
+ * g_dbus_proxy_get_interface_name:
+ * @proxy: A #GDBusProxy.
*
- * @type holding the data from @gvalue or %NULL in case of
- * failure. Free with g_variant_unref().
+ * Gets the D-Bus interface name @proxy is for.
*
- * Returns: A #GVariant (never floating) of #GVariantType
- * Since: 2.30
+ * Returns: A string owned by @proxy. Do not free.
+ * Since: 2.26
*/
/**
- * g_dbus_gvariant_to_gvalue:
- * @value: A #GVariant.
- * @out_gvalue: Return location pointing to a zero-filled (uninitialized) #GValue.
- *
- * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
- *
- * The rules specified in the g_dbus_gvalue_to_gvariant() function are
- * used - this function is essentially its reverse form.
+ * g_dbus_proxy_get_name:
+ * @proxy: A #GDBusProxy.
*
- * The conversion never fails - a valid #GValue is always returned in
- * @out_gvalue.
+ * Gets the name that @proxy was constructed for.
*
- * Since: 2.30
+ * Returns: A string owned by @proxy. Do not free.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_get_info:
- * @interface_: An exported D-Bus interface.
+ * g_dbus_proxy_get_name_owner:
+ * @proxy: A #GDBusProxy.
*
- * Gets D-Bus introspection information for the D-Bus interface
- * implemented by @interface_.
+ * The unique name that owns the name that @proxy is for or %NULL if
+ * no-one currently owns that name. You may connect to the
+ * #GObject::notify signal to track changes to the
+ * #GDBusProxy:g-name-owner property.
*
- * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
- * Since: 2.30
+ * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
+ * Since: 2.26
*/
/**
- * g_dbus_interface_get_object:
- * @interface_: An exported D-Bus interface.
- *
- * Gets the #GDBusObject that @interface_ belongs to, if any.
+ * g_dbus_proxy_get_object_path:
+ * @proxy: A #GDBusProxy.
*
- * reference belongs to @interface_ and should not be freed.
+ * Gets the object path @proxy is for.
*
- * Returns: (transfer none): A #GDBusObject or %NULL. The returned
- * Since: 2.30
+ * Returns: A string owned by @proxy. Do not free.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_info_cache_build:
- * @info: A #GDBusInterfaceInfo.
+ * g_dbus_proxy_new:
+ * @connection: A #GDBusConnection.
+ * @flags: Flags used when constructing the proxy.
+ * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
+ * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+ * @object_path: An object path.
+ * @interface_name: A D-Bus interface name.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: Callback function to invoke when the proxy is ready.
+ * @user_data: User data to pass to @callback.
*
- * Builds a lookup-cache to speed up
- * g_dbus_interface_info_lookup_method(),
- * g_dbus_interface_info_lookup_signal() and
- * g_dbus_interface_info_lookup_property().
+ * Creates a proxy for accessing @interface_name on the remote object
+ * at @object_path owned by @name at @connection and asynchronously
+ * loads D-Bus properties unless the
+ * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
+ * the #GDBusProxy::g-properties-changed signal to get notified about
+ * property changes.
*
- * If this has already been called with @info, the existing cache is
- * used and its use count is increased.
+ * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
+ * match rules for signals. Connect to the #GDBusProxy::g-signal signal
+ * to handle signals from the remote object.
*
- * Note that @info cannot be modified until
- * g_dbus_interface_info_cache_release() is called.
+ * If @name is a well-known name and the
+ * %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.
*
- * Since: 2.30
- */
-
-
-/**
- * g_dbus_interface_info_cache_release:
- * @info: A GDBusInterfaceInfo
+ * This is a failable asynchronous constructor - when the proxy is
+ * ready, @callback will be invoked and you can use
+ * g_dbus_proxy_new_finish() to get the result.
+ *
+ * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
*
- * Decrements the usage count for the cache for @info built by
- * g_dbus_interface_info_cache_build() (if any) and frees the
- * resources used by the cache if the usage count drops to zero.
+ * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
*
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_interface_info_generate_xml:
- * @info: A #GDBusNodeInfo
- * @indent: Indentation level.
- * @string_builder: (out): A #GString to to append XML data to.
- *
- * Appends an XML representation of @info (and its children) to @string_builder.
+ * g_dbus_proxy_new_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
+ * @error: Return location for error or %NULL.
*
- * This function is typically used for generating introspection XML
- * documents at run-time for handling the
- * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
- * method.
+ * Finishes creating a #GDBusProxy.
*
+ * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_interface_info_lookup_method:
- * @info: A #GDBusInterfaceInfo.
- * @name: A D-Bus method name (typically in CamelCase)
+ * g_dbus_proxy_new_for_bus:
+ * @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.
+ * @name: A bus name (well-known or unique).
+ * @object_path: An object path.
+ * @interface_name: A D-Bus interface name.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @callback: Callback function to invoke when the proxy is ready.
+ * @user_data: User data to pass to @callback.
*
- * Looks up information about a method.
+ * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
*
- * This cost of this function is O(n) in number of methods unless
- * g_dbus_interface_info_cache_build() has been used on @info.
+ * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
*
- * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
/**
- * g_dbus_interface_info_lookup_property:
- * @info: A #GDBusInterfaceInfo.
- * @name: A D-Bus property name (typically in CamelCase).
- *
- * Looks up information about a property.
+ * g_dbus_proxy_new_for_bus_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
+ * @error: Return location for error or %NULL.
*
- * This cost of this function is O(n) in number of properties unless
- * g_dbus_interface_info_cache_build() has been used on @info.
+ * Finishes creating a #GDBusProxy.
*
- * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_interface_info_lookup_signal:
- * @info: A #GDBusInterfaceInfo.
- * @name: A D-Bus signal name (typically in CamelCase)
+ * 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.
+ * @name: A bus name (well-known or unique).
+ * @object_path: An object path.
+ * @interface_name: A D-Bus interface name.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Looks up information about a signal.
+ * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
*
- * This cost of this function is O(n) in number of signals unless
- * g_dbus_interface_info_cache_build() has been used on @info.
+ * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
*
- * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_interface_info_ref:
- * @info: A #GDBusInterfaceInfo
+ * g_dbus_proxy_new_sync:
+ * @connection: A #GDBusConnection.
+ * @flags: Flags used when constructing the proxy.
+ * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
+ * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+ * @object_path: An object path.
+ * @interface_name: A D-Bus interface name.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: (allow-none): Return location for error or %NULL.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Creates a proxy for accessing @interface_name on the remote object
+ * at @object_path owned by @name at @connection and synchronously
+ * loads D-Bus properties unless the
+ * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
*
- * Returns: The same @info.
- * Since: 2.26
- */
-
-
-/**
- * g_dbus_interface_info_unref:
- * @info: A #GDBusInterfaceInfo.
+ * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
+ * match rules for signals. Connect to the #GDBusProxy::g-signal signal
+ * to handle signals from the remote object.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * If @name is a well-known name and the
+ * %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.
*
+ * #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
*/
/**
- * g_dbus_interface_set_object:
- * @interface_: An exported D-Bus interface.
- * @object: A #GDBusObject or %NULL.
+ * g_dbus_proxy_set_cached_property:
+ * @proxy: A #GDBusProxy
+ * @property_name: Property name.
+ * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
*
- * Sets the #GDBusObject for @interface_ to @object.
+ * If @value is not %NULL, sets the cached value for the property with
+ * name @property_name to the value in @value.
*
- * Note that @interface_ will hold a weak reference to @object.
+ * If @value is %NULL, then the cached value is removed from the
+ * property cache.
*
- * Since: 2.30
+ * If @proxy has an expected interface (see
+ * #GDBusProxy:g-interface-info) and @property_name is referenced by
+ * it, then @value is checked against the type of the property.
+ *
+ * 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)",
+ * "A String",
+ * 42));
+ * ]|
+ *
+ * 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
+ * `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
*/
/**
- * g_dbus_interface_skeleton_export:
- * @interface_: The D-Bus interface to export.
- * @connection: A #GDBusConnection to export @interface_ on.
- * @object_path: The path to export the interface at.
- * @error: Return location for error or %NULL.
- *
- * Exports @interface_ at @object_path on @connection.
- *
- * This can be called multiple times to export the same @interface_
- * onto multiple connections however the @object_path provided must be
- * the same for all connections.
+ * g_dbus_proxy_set_default_timeout:
+ * @proxy: A #GDBusProxy.
+ * @timeout_msec: Timeout in milliseconds.
*
- * Use g_dbus_interface_skeleton_unexport() to unexport the object.
+ * Sets the timeout to use if -1 (specifying default timeout) is
+ * passed as @timeout_msec in the g_dbus_proxy_call() and
+ * g_dbus_proxy_call_sync() functions.
*
- * @error set.
+ * See the #GDBusProxy:g-default-timeout property for more details.
*
- * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_flush:
- * @interface_: A #GDBusInterfaceSkeleton.
- *
- * If @interface_ has outstanding changes, request for these changes to be
- * emitted immediately.
+ * g_dbus_proxy_set_interface_info:
+ * @proxy: A #GDBusProxy
+ * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
*
- * For example, an exported D-Bus interface may queue up property
- * changes and emit the
- * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
- * signal later (e.g. in an idle handler). This technique is useful
- * for collapsing multiple property changes into one.
+ * Ensure that interactions with @proxy conform to the given
+ * interface. See the #GDBusProxy:g-interface-info property for more
+ * details.
*
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_connection:
- * @interface_: A #GDBusInterfaceSkeleton.
- *
- * Gets the first connection that @interface_ is exported on, if any.
+ * g_dbus_server_get_client_address:
+ * @server: A #GDBusServer.
*
- * not exported anywhere. Do not free, the object belongs to @interface_.
+ * Gets a D-Bus address string that can be used by clients to connect
+ * to @server.
*
- * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
- * Since: 2.30
+ * Returns: A D-Bus address string. Do not free, the string is owned
+ * by @server.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_connections:
- * @interface_: A #GDBusInterfaceSkeleton.
- *
- * Gets a list of the connections that @interface_ is exported on.
+ * g_dbus_server_get_flags:
+ * @server: A #GDBusServer.
*
- * 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().
+ * Gets the flags for @server.
*
- * Returns: (element-type GDBusConnection) (transfer full): A list of
- * Since: 2.32
+ * Returns: A set of flags from the #GDBusServerFlags enumeration.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_flags:
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_dbus_server_get_guid:
+ * @server: A #GDBusServer.
*
- * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
- * of @interface_
+ * Gets the GUID for @server.
*
- * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
- * Since: 2.30
+ * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_info:
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_dbus_server_is_active:
+ * @server: A #GDBusServer.
*
- * Gets D-Bus introspection information for the D-Bus interface
- * implemented by @interface_.
+ * Gets whether @server is active.
*
- * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
- * Since: 2.30
+ * Returns: %TRUE if server is active, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_object_path:
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_dbus_server_new_sync:
+ * @address: A D-Bus address.
+ * @flags: Flags from the #GDBusServerFlags enumeration.
+ * @guid: A D-Bus GUID.
+ * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
+ * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @error: Return location for server or %NULL.
*
- * Gets the object path that @interface_ is exported on, if any.
+ * Creates a new D-Bus server that listens on the first address in
+ * @address that works.
*
- * anywhere. Do not free, the string belongs to @interface_.
+ * Once constructed, you can use g_dbus_server_get_client_address() to
+ * get a D-Bus address string that clients can use to connect.
*
- * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
- * Since: 2.30
+ * Connect to the #GDBusServer::new-connection signal to handle
+ * incoming connections.
+ *
+ * The returned #GDBusServer isn't active - you have to start it with
+ * g_dbus_server_start().
+ *
+ * #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().
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_properties:
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_dbus_server_start:
+ * @server: A #GDBusServer.
*
- * Gets all D-Bus properties for @interface_.
+ * Starts @server.
*
- * Returns: (transfer full): A #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref().
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_get_vtable: (skip)
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_dbus_server_stop:
+ * @server: A #GDBusServer.
*
- * Gets the interface vtable for the D-Bus interface implemented by
- * @interface_. The returned function pointers should expect @interface_
- * itself to be passed as @user_data.
+ * Stops @server.
*
- * Returns: A #GDBusInterfaceVTable (never %NULL).
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_has_connection:
- * @interface_: A #GDBusInterfaceSkeleton.
- * @connection: A #GDBusConnection.
+ * g_dbus_signal_info_ref:
+ * @info: A #GDBusSignalInfo
*
- * Checks if @interface_ is export on @connection.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
- * Since: 2.32
+ * Returns: The same @info.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_set_flags:
- * @interface_: A #GDBusInterfaceSkeleton.
- * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
+ * g_dbus_signal_info_unref:
+ * @info: A #GDBusSignalInfo.
*
- * Sets flags describing what the behavior of @skeleton should be.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Since: 2.30
+ * Since: 2.26
*/
/**
- * g_dbus_interface_skeleton_unexport:
- * @interface_: A #GDBusInterfaceSkeleton.
+ * 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()
*
- * Stops exporting @interface_ on all connections it is exported on.
+ * Gets the user-visible display name of the "additional application
+ * action" specified by @action_name.
*
- * To unexport @interface_ from only a single connection, use
- * g_dbus_interface_skeleton_export_from_connection()
+ * This corresponds to the "Name" key within the keyfile group for the
+ * action.
*
- * Since: 2.30
+ * Returns: (transfer full): the locale-specific action name
+ * Since: 2.38
*/
/**
- * g_dbus_interface_skeleton_unexport_from_connection:
- * @interface_: A #GDBusInterfaceSkeleton.
- * @connection: A #GDBusConnection.
+ * g_desktop_app_info_get_boolean:
+ * @info: a #GDesktopAppInfo
+ * @key: the key to look up
*
- * Stops exporting @interface_ on @connection.
+ * Looks up a boolean value in the keyfile backing @info.
*
- * To stop exporting on all connections the interface is exported on,
- * use g_dbus_interface_skeleton_unexport().
+ * The @key is looked up in the "Desktop Entry" group.
*
- * Since: 2.32
+ * Returns: the boolean value, or %FALSE if the key
+ * is not found
+ * Since: 2.36
*/
/**
- * g_dbus_is_address:
- * @string: A string.
- *
- * Checks if @string is a D-Bus address.
+ * g_desktop_app_info_get_categories:
+ * @info: a #GDesktopAppInfo
*
- * This doesn't check if @string is actually supported by #GDBusServer
- * or #GDBusConnection - use g_dbus_is_supported_address() to do more
- * checks.
+ * Gets the categories from the desktop file.
*
- * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
- * Since: 2.26
+ * Returns: The unparsed Categories key from the desktop file;
+ * i.e. no attempt is made to split it by ';' or validate it.
*/
/**
- * g_dbus_is_guid:
- * @string: The string to check.
- *
- * Checks if @string is a D-Bus GUID.
+ * g_desktop_app_info_get_filename:
+ * @info: a #GDesktopAppInfo
*
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * When @info was created from a known filename, return it. In some
+ * situations such as the #GDesktopAppInfo returned from
+ * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
*
- * Returns: %TRUE if @string is a guid, %FALSE otherwise.
- * Since: 2.26
+ * Returns: The full path to the file for @info, or %NULL if not known.
+ * Since: 2.24
*/
/**
- * g_dbus_is_interface_name:
- * @string: The string to check.
+ * g_desktop_app_info_get_generic_name:
+ * @info: a #GDesktopAppInfo
*
- * Checks if @string is a valid D-Bus interface name.
+ * Gets the generic name from the destkop file.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
- * Since: 2.26
+ * Returns: The value of the GenericName key
*/
/**
- * g_dbus_is_member_name:
- * @string: The string to check.
+ * g_desktop_app_info_get_implementations:
+ * @interface: the name of the interface
*
- * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
+ * Gets all applications that implement @interface.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
- * Since: 2.26
+ * 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_dbus_is_name:
- * @string: The string to check.
+ * g_desktop_app_info_get_is_hidden:
+ * @info: a #GDesktopAppInfo.
*
- * Checks if @string is a valid D-Bus bus name (either unique or well-known).
+ * A desktop file is hidden if the Hidden key in it is
+ * set to True.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
- * Since: 2.26
+ * Returns: %TRUE if hidden, %FALSE otherwise.
*/
/**
- * g_dbus_is_supported_address:
- * @string: A string.
- * @error: Return location for error or %NULL.
- *
- * Like g_dbus_is_address() but also checks if the library suppors the
- * transports in @string and that key/value pairs for each transport
- * are valid.
+ * g_desktop_app_info_get_keywords:
+ * @info: a #GDesktopAppInfo
*
- * supported by this library, %FALSE if @error is set.
+ * Gets the keywords from the desktop file.
*
- * Returns: %TRUE if @string is a valid D-Bus address that is
- * Since: 2.26
+ * Returns: (transfer none): The value of the Keywords key
+ * Since: 2.32
*/
/**
- * g_dbus_is_unique_name:
- * @string: The string to check.
+ * g_desktop_app_info_get_nodisplay:
+ * @info: a #GDesktopAppInfo
*
- * Checks if @string is a valid D-Bus unique bus name.
+ * Gets the value of the NoDisplay key, which helps determine if the
+ * application info should be shown in menus. See
+ * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
*
- * Returns: %TRUE if valid, %FALSE otherwise.
- * Since: 2.26
+ * Returns: The value of the NoDisplay key
+ * Since: 2.30
*/
/**
- * g_dbus_menu_model_get:
- * @connection: a #GDBusConnection
- * @bus_name: the bus name which exports the menu model
- * @object_path: the object path at which the menu model is exported
+ * g_desktop_app_info_get_show_in:
+ * @info: a #GDesktopAppInfo
+ * @desktop_env: (nullable): a string specifying a desktop name
*
- * Obtains a #GDBusMenuModel for the menu model which is exported
- * at the given @bus_name and @object_path.
+ * Checks if the application info should be shown in menus that list available
+ * applications for a specific name of the desktop, based on the
+ * `OnlyShowIn` and `NotShowIn` keys.
*
- * The thread default main context is taken at the time of this call.
- * All signals on the menu model (and any linked models) are reported
- * with respect to this context. All calls on the returned menu model
- * (and linked models) must also originate from this same context, with
- * the thread default main context unchanged.
+ * @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.
*
- * g_object_unref().
+ * Note that g_app_info_should_show() for @info will include this check (with
+ * %NULL for @desktop_env) as well as additional checks.
*
- * Returns: (transfer full): a #GDBusMenuModel object. Free with
- * Since: 2.32
+ * Returns: %TRUE if the @info should be shown in @desktop_env according to the
+ * `OnlyShowIn` and `NotShowIn` keys, %FALSE
+ * otherwise.
+ * Since: 2.30
*/
/**
- * g_dbus_message_bytes_needed:
- * @blob: A blob represent a binary D-Bus message.
- * @blob_len: The length of @blob (must be at least 16).
- * @error: Return location for error or %NULL.
- *
- * Utility function to calculate how many bytes are needed to
- * completely deserialize the D-Bus message stored at @blob.
+ * g_desktop_app_info_get_startup_wm_class:
+ * @info: a #GDesktopAppInfo that supports startup notify
*
- * @blob contains invalid data or not enough data is available to
- * determine the size).
+ * Retrieves the StartupWMClass field from @info. This represents the
+ * WM_CLASS property of the main window of the application, if launched
+ * through @info.
*
- * Returns: Number of bytes needed or -1 if @error is set (e.g. if
- * Since: 2.26
+ * Returns: (transfer none): the startup WM class, or %NULL if none is set
+ * in the desktop file.
+ * Since: 2.34
*/
/**
- * g_dbus_message_copy:
- * @message: A #GDBusMessage.
- * @error: Return location for error or %NULL.
- *
- * Copies @message. The copy is a deep copy and the returned
- * #GDBusMessage is completely identical except that it is guaranteed
- * to not be locked.
+ * g_desktop_app_info_get_string:
+ * @info: a #GDesktopAppInfo
+ * @key: the key to look up
*
- * This operation can fail if e.g. @message contains file descriptors
- * and the per-process or system-wide open files limit is reached.
+ * Looks up a string value in the keyfile backing @info.
*
- * Free with g_object_unref().
+ * The @key is looked up in the "Desktop Entry" group.
*
- * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
- * Since: 2.26
+ * Returns: a newly allocated string, or %NULL if the key
+ * is not found
+ * Since: 2.36
*/
/**
- * g_dbus_message_get_arg0:
- * @message: A #GDBusMessage.
- *
- * Convenience to get the first item in the body of @message.
+ * g_desktop_app_info_has_key:
+ * @info: a #GDesktopAppInfo
+ * @key: the key to look up
*
- * @message is not a string.
+ * Returns whether @key exists in the "Desktop Entry" group
+ * of the keyfile backing @info.
*
- * Returns: The string item or %NULL if the first item in the body of
- * Since: 2.26
+ * Returns: %TRUE if the @key exists
+ * Since: 2.36
*/
/**
- * g_dbus_message_get_body:
- * @message: A #GDBusMessage.
+ * 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
*
- * Gets the body of a message.
+ * Activates the named application action.
*
- * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
- * Since: 2.26
+ * 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_dbus_message_get_byte_order:
- * @message: A #GDBusMessage.
+ * g_desktop_app_info_launch_uris_as_manager:
+ * @appinfo: a #GDesktopAppInfo
+ * @uris: (element-type utf8): List of URIs
+ * @launch_context: (allow-none): a #GAppLaunchContext
+ * @spawn_flags: #GSpawnFlags, used for each process
+ * @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
*
- * Gets the byte order of @message.
+ * This function performs the equivalent of g_app_info_launch_uris(),
+ * but is intended primarily for operating system components that
+ * launch applications. Ordinary applications should use
+ * g_app_info_launch_uris().
*
- * Returns: The byte order.
+ * 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.
+ *
+ * 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_dbus_message_get_destination:
- * @message: A #GDBusMessage.
+ * g_desktop_app_info_list_actions:
+ * @info: a #GDesktopAppInfo
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+ * Returns the list of "additional application actions" supported on the
+ * desktop file, as per the desktop file specification.
*
- * Returns: The value.
- * Since: 2.26
+ * 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_dbus_message_get_error_name:
- * @message: A #GDBusMessage.
+ * g_desktop_app_info_lookup_get_default_for_uri_scheme:
+ * @lookup: a #GDesktopAppInfoLookup
+ * @uri_scheme: a string containing a URI scheme.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+ * Gets the default application for launching applications
+ * using this URI scheme for a particular GDesktopAppInfoLookup
+ * implementation.
*
- * Returns: The value.
- * Since: 2.26
+ * The GDesktopAppInfoLookup interface and this function is used
+ * to implement g_app_info_get_default_for_uri_scheme() backends
+ * in a GIO module. There is no reason for applications to use it
+ * directly. Applications should use g_app_info_get_default_for_uri_scheme().
+ *
+ * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
+ * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
*/
/**
- * g_dbus_message_get_flags:
- * @message: A #GDBusMessage.
+ * g_desktop_app_info_new:
+ * @desktop_id: the desktop file id
*
- * Gets the flags for @message.
+ * Creates a new #GDesktopAppInfo based on a desktop file id.
*
- * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
- * Since: 2.26
+ * 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 `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
+ * `/usr/share/applications/kde/foo.desktop`).
+ *
+ * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
*/
/**
- * g_dbus_message_get_header:
- * @message: A #GDBusMessage.
- * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
- *
- * Gets a header field on @message.
+ * g_desktop_app_info_new_from_filename:
+ * @filename: the path of a desktop file, in the GLib filename encoding
*
- * otherwise. Do not free, it is owned by @message.
+ * Creates a new #GDesktopAppInfo.
*
- * Returns: A #GVariant with the value if the header was found, %NULL
- * Since: 2.26
+ * Returns: a new #GDesktopAppInfo or %NULL on error.
*/
/**
- * g_dbus_message_get_header_fields:
- * @message: A #GDBusMessage.
- *
- * Gets an array of all header fields on @message that are set.
+ * g_desktop_app_info_new_from_keyfile:
+ * @key_file: an opened #GKeyFile
*
- * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a
- * #guchar. Free with g_free().
+ * Creates a new #GDesktopAppInfo.
*
- * Returns: An array of header fields terminated by
- * Since: 2.26
+ * Returns: a new #GDesktopAppInfo or %NULL on error.
+ * Since: 2.18
*/
/**
- * g_dbus_message_get_interface:
- * @message: A #GDBusMessage.
+ * g_desktop_app_info_search:
+ * @search_string: the search string to use
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ * Searches desktop files for ones that match @search_string.
*
- * Returns: The value.
- * Since: 2.26
+ * 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_dbus_message_get_locked:
- * @message: A #GDBusMessage.
+ * g_desktop_app_info_set_desktop_env:
+ * @desktop_env: a string specifying what desktop this is
*
- * Checks whether @message is locked. To monitor changes to this
- * value, conncet to the #GObject::notify signal to listen for changes
- * on the #GDBusMessage:locked property.
+ * 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
+ * `OnlyShowIn` and `NotShowIn`
+ * desktop entry fields.
*
- * Returns: %TRUE if @message is locked, %FALSE otherwise.
- * Since: 2.26
+ * 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.
*/
/**
- * g_dbus_message_get_member:
- * @message: A #GDBusMessage.
+ * g_drive_can_eject:
+ * @drive: a #GDrive.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+ * Checks if a drive can be ejected.
*
- * Returns: The value.
- * Since: 2.26
+ * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
*/
/**
- * g_dbus_message_get_message_type:
- * @message: A #GDBusMessage.
+ * g_drive_can_poll_for_media:
+ * @drive: a #GDrive.
*
- * Gets the type of @message.
+ * Checks if a drive can be polled for media changes.
*
- * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
- * Since: 2.26
+ * Returns: %TRUE if the @drive can be polled for media changes,
+ * %FALSE otherwise.
*/
/**
- * g_dbus_message_get_num_unix_fds:
- * @message: A #GDBusMessage.
+ * g_drive_can_start:
+ * @drive: a #GDrive.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+ * Checks if a drive can be started.
*
- * Returns: The value.
- * Since: 2.26
+ * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_message_get_path:
- * @message: A #GDBusMessage.
+ * g_drive_can_start_degraded:
+ * @drive: a #GDrive.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+ * Checks if a drive can be started degraded.
*
- * Returns: The value.
- * Since: 2.26
+ * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_message_get_reply_serial:
- * @message: A #GDBusMessage.
+ * g_drive_can_stop:
+ * @drive: a #GDrive.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+ * Checks if a drive can be stopped.
*
- * Returns: The value.
- * Since: 2.26
+ * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_message_get_sender:
- * @message: A #GDBusMessage.
+ * g_drive_eject:
+ * @drive: a #GDrive.
+ * @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.
+ * @user_data: user data to pass to @callback
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+ * Asynchronously ejects a drive.
*
- * Returns: The value.
- * Since: 2.26
+ * When the operation is finished, @callback will be called.
+ * You can then call g_drive_eject_finish() to obtain the
+ * result of the operation.
+ *
+ * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
*/
/**
- * g_dbus_message_get_serial:
- * @message: A #GDBusMessage.
+ * g_drive_eject_finish:
+ * @drive: a #GDrive.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL
*
- * Gets the serial for @message.
+ * Finishes ejecting a drive.
*
- * Returns: A #guint32.
- * Since: 2.26
+ * Returns: %TRUE if the drive has been ejected successfully,
+ * %FALSE otherwise.
+ * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
*/
/**
- * g_dbus_message_get_signature:
- * @message: A #GDBusMessage.
+ * 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.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @user_data: user data passed to @callback.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+ * Ejects a drive. This is an asynchronous operation, and is
+ * finished by calling g_drive_eject_with_operation_finish() with the @drive
+ * and #GAsyncResult data returned in the @callback.
*
- * Returns: The value.
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * g_dbus_message_get_unix_fd_list:
- * @message: A #GDBusMessage.
- *
- * Gets the UNIX file descriptors associated with @message, if any.
- *
- * This method is only available on UNIX.
+ * 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.
*
- * associated. Do not free, this object is owned by @message.
+ * Finishes ejecting a drive. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
- * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
- * Since: 2.26
+ * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_message_lock:
- * @message: A #GDBusMessage.
+ * g_drive_enumerate_identifiers:
+ * @drive: a #GDrive
*
- * If @message is locked, does nothing. Otherwise locks the message.
+ * Gets the kinds of identifiers that @drive has.
+ * Use g_drive_get_identifier() to obtain the identifiers
+ * themselves.
*
- * Since: 2.26
+ * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
+ * array of strings containing kinds of identifiers. Use g_strfreev()
+ * to free.
*/
/**
- * g_dbus_message_new:
+ * g_drive_get_icon:
+ * @drive: a #GDrive.
*
- * Creates a new empty #GDBusMessage.
+ * Gets the icon for @drive.
*
- * Returns: A #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * Returns: (transfer full): #GIcon for the @drive.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_dbus_message_new_from_blob:
- * @blob: A blob represent a binary D-Bus message.
- * @blob_len: The length of @blob.
- * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
- * @error: Return location for error or %NULL.
- *
- * Creates a new #GDBusMessage from the data stored at @blob. The byte
- * order that the message was in can be retrieved using
- * g_dbus_message_get_byte_order().
+ * g_drive_get_identifier:
+ * @drive: a #GDrive
+ * @kind: the kind of identifier to return
*
- * g_object_unref().
+ * Gets the identifier of the given kind for @drive.
*
- * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
- * Since: 2.26
+ * Returns: a newly allocated string containing the
+ * requested identfier, or %NULL if the #GDrive
+ * doesn't have this kind of identifier.
*/
/**
- * g_dbus_message_new_method_call:
- * @name: A valid D-Bus name or %NULL.
- * @path: A valid object path.
- * @interface_: A valid D-Bus interface name or %NULL.
- * @method: A valid method name.
+ * g_drive_get_name:
+ * @drive: a #GDrive.
*
- * Creates a new #GDBusMessage for a method call.
+ * Gets the name of @drive.
*
- * Returns: A #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * Returns: a string containing @drive's name. The returned
+ * string should be freed when no longer needed.
*/
/**
- * 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.
- * @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_drive_get_sort_key:
+ * @drive: A #GDrive.
*
- * Creates a new #GDBusMessage that is an error reply to @method_call_message.
+ * Gets the sort key for @drive, if any.
*
- * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * Returns: Sorting key for @drive or %NULL if no such key is available.
+ * Since: 2.32
*/
/**
- * 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.
- * @error_name: A valid D-Bus error name.
- * @error_message: The D-Bus error message.
+ * g_drive_get_start_stop_type:
+ * @drive: a #GDrive.
*
- * Creates a new #GDBusMessage that is an error reply to @method_call_message.
+ * Gets a hint about how a drive can be started/stopped.
*
- * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * Returns: A value from the #GDriveStartStopType enumeration.
+ * Since: 2.22
*/
/**
- * 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.
- * @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_drive_get_symbolic_icon:
+ * @drive: a #GDrive.
*
- * Like g_dbus_message_new_method_error() but intended for language bindings.
+ * Gets the icon for @drive.
*
- * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * Returns: (transfer full): symbolic #GIcon for the @drive.
+ * Free the returned object with g_object_unref().
+ * Since: 2.34
*/
/**
- * 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.
+ * g_drive_get_volumes:
+ * @drive: a #GDrive.
*
- * Creates a new #GDBusMessage that is a reply to @method_call_message.
+ * Get a list of mountable volumes for @drive.
*
- * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * The returned list should be freed with g_list_free(), after
+ * its elements have been unreffed with g_object_unref().
+ *
+ * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
*/
/**
- * g_dbus_message_new_signal:
- * @path: A valid object path.
- * @interface_: A valid D-Bus interface name.
- * @signal: A valid signal name.
+ * g_drive_has_media:
+ * @drive: a #GDrive.
*
- * Creates a new #GDBusMessage for a signal emission.
+ * Checks if the @drive has media. Note that the OS may not be polling
+ * the drive for media changes; see g_drive_is_media_check_automatic()
+ * for more details.
*
- * Returns: A #GDBusMessage. Free with g_object_unref().
- * Since: 2.26
+ * Returns: %TRUE if @drive has media, %FALSE otherwise.
*/
/**
- * g_dbus_message_print:
- * @message: A #GDBusMessage.
- * @indent: Indentation level.
- *
- * Produces a human-readable multi-line description of @message.
+ * g_drive_has_volumes:
+ * @drive: a #GDrive.
*
- * 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>
- * Flags: none
- * Version: 0
- * Serial: 4
- * Headers:
- * path -> objectpath '/org/gtk/GDBus/TestObject'
- * interface -> 'org.gtk.GDBus.TestInterface'
- * member -> 'GimmeStdout'
- * destination -> ':1.146'
- * Body: ()
- * UNIX File Descriptors:
- * (none)
- * </programlisting>
- * or
- * <programlisting>
- * 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:
- * 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>
+ * Check if @drive has any mountable volumes.
*
- * Type: method-return
- * Returns: A string that should be freed with g_free().
- * Since: 2.26
+ * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
*/
/**
- * g_dbus_message_set_body:
- * @message: A #GDBusMessage.
- * @body: Either %NULL or a #GVariant that is a tuple.
- *
- * Sets the body @message. As a side-effect the
- * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
- * type string of @body (or cleared if @body is %NULL).
+ * g_drive_is_media_check_automatic:
+ * @drive: a #GDrive.
*
- * If @body is floating, @message assumes ownership of @body.
+ * Checks if @drive is capabable of automatically detecting media changes.
*
- * Since: 2.26
+ * Returns: %TRUE if the @drive is capabable of automatically detecting
+ * media changes, %FALSE otherwise.
*/
/**
- * g_dbus_message_set_byte_order:
- * @message: A #GDBusMessage.
- * @byte_order: The byte order.
+ * g_drive_is_media_removable:
+ * @drive: a #GDrive.
*
- * Sets the byte order of @message.
+ * Checks if the @drive supports removable media.
+ *
+ * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
*/
/**
- * g_dbus_message_set_destination:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_drive_poll_for_media:
+ * @drive: a #GDrive.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @user_data: user data to pass to @callback
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+ * Asynchronously polls @drive to see if media has been inserted or removed.
*
- * Since: 2.26
+ * When the operation is finished, @callback will be called.
+ * You can then call g_drive_poll_for_media_finish() to obtain the
+ * result of the operation.
*/
/**
- * g_dbus_message_set_error_name:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_drive_poll_for_media_finish:
+ * @drive: a #GDrive.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+ * Finishes an operation started with g_drive_poll_for_media() on a drive.
*
- * Since: 2.26
+ * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
+ * %FALSE otherwise.
*/
/**
- * g_dbus_message_set_flags:
- * @message: A #GDBusMessage.
- * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
+ * g_drive_start:
+ * @drive: a #GDrive.
+ * @flags: flags affecting the start 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.
+ * @user_data: user data to pass to @callback
*
- * Sets the flags to set on @message.
+ * Asynchronously starts a drive.
*
- * Since: 2.26
+ * When the operation is finished, @callback will be called.
+ * You can then call g_drive_start_finish() to obtain the
+ * result of the operation.
+ *
+ * Since: 2.22
*/
/**
- * g_dbus_message_set_header:
- * @message: A #GDBusMessage.
- * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
- * @value: A #GVariant to set the header field or %NULL to clear the header field.
- *
- * Sets a header field on @message.
+ * g_drive_start_finish:
+ * @drive: a #GDrive.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL
*
- * If @value is floating, @message assumes ownership of @value.
+ * Finishes starting a drive.
*
- * Since: 2.26
+ * Returns: %TRUE if the drive has been started successfully,
+ * %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_message_set_interface:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * 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.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @user_data: user data to pass to @callback
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ * Asynchronously stops a drive.
*
- * Since: 2.26
+ * When the operation is finished, @callback will be called.
+ * You can then call g_drive_stop_finish() to obtain the
+ * result of the operation.
+ *
+ * Since: 2.22
*/
/**
- * g_dbus_message_set_member:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_drive_stop_finish:
+ * @drive: a #GDrive.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+ * Finishes stopping a drive.
*
- * Since: 2.26
+ * Returns: %TRUE if the drive has been stopped successfully,
+ * %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_message_set_message_type:
- * @message: A #GDBusMessage.
- * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
+ * g_emblem_get_icon:
+ * @emblem: a #GEmblem from which the icon should be extracted.
*
- * Sets @message to be of @type.
+ * Gives back the icon from @emblem.
*
- * Since: 2.26
+ * Returns: (transfer none): a #GIcon. The returned object belongs to
+ * the emblem and should not be modified or freed.
+ * Since: 2.18
*/
/**
- * g_dbus_message_set_num_unix_fds:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_emblem_get_origin:
+ * @emblem: a #GEmblem
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+ * Gets the origin of the emblem.
*
- * Since: 2.26
+ * Returns: (transfer none): the origin of the emblem
+ * Since: 2.18
*/
/**
- * g_dbus_message_set_path:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_emblem_new:
+ * @icon: a GIcon containing the icon.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+ * Creates a new emblem for @icon.
*
- * Since: 2.26
+ * Returns: a new #GEmblem.
+ * Since: 2.18
*/
/**
- * g_dbus_message_set_reply_serial:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_emblem_new_with_origin:
+ * @icon: a GIcon containing the icon.
+ * @origin: a GEmblemOrigin enum defining the emblem's origin
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+ * Creates a new emblem for @icon.
*
- * Since: 2.26
+ * Returns: a new #GEmblem.
+ * Since: 2.18
*/
/**
- * g_dbus_message_set_sender:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_emblemed_icon_add_emblem:
+ * @emblemed: a #GEmblemedIcon
+ * @emblem: a #GEmblem
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+ * Adds @emblem to the #GList of #GEmblems.
*
- * Since: 2.26
+ * Since: 2.18
*/
/**
- * g_dbus_message_set_serial:
- * @message: A #GDBusMessage.
- * @serial: A #guint32.
+ * g_emblemed_icon_clear_emblems:
+ * @emblemed: a #GEmblemedIcon
*
- * Sets the serial for @message.
+ * Removes all the emblems from @icon.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * g_dbus_message_set_signature:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_emblemed_icon_get_emblems:
+ * @emblemed: a #GEmblemedIcon
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+ * Gets the list of emblems for the @icon.
*
- * Since: 2.26
+ * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
+ * #GEmblems that is owned by @emblemed
+ * Since: 2.18
*/
/**
- * g_dbus_message_set_unix_fd_list:
- * @message: A #GDBusMessage.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
- *
- * Sets the UNIX file descriptors associated with @message. As a
- * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
- * field is set to the number of fds in @fd_list (or cleared if
- * @fd_list is %NULL).
+ * g_emblemed_icon_get_icon:
+ * @emblemed: a #GEmblemedIcon
*
- * This method is only available on UNIX.
+ * Gets the main icon for @emblemed.
*
- * Since: 2.26
+ * Returns: (transfer none): a #GIcon that is owned by @emblemed
+ * Since: 2.18
*/
/**
- * g_dbus_message_to_blob:
- * @message: A #GDBusMessage.
- * @out_size: Return location for size of generated blob.
- * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
- * @error: Return location for error.
- *
- * Serializes @message to a blob. The byte order returned by
- * g_dbus_message_get_byte_order() will be used.
+ * g_emblemed_icon_new:
+ * @icon: a #GIcon
+ * @emblem: (allow-none): a #GEmblem, or %NULL
*
- * generated by @message or %NULL if @error is set. Free with g_free().
+ * Creates a new emblemed icon for @icon with the emblem @emblem.
*
- * Returns: A pointer to a valid binary D-Bus message of @out_size bytes
- * Since: 2.26
+ * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
+ * Since: 2.18
*/
/**
- * g_dbus_message_to_gerror:
- * @message: A #GDBusMessage.
- * @error: The #GError to set.
+ * g_file_append_to:
+ * @file: input #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
- * nothing and returns %FALSE.
+ * Gets an output stream for appending data to the file.
+ * If the file doesn't already exist it is created.
*
- * Otherwise this method encodes the error in @message as a #GError
- * using g_dbus_error_set_dbus_error() using the information in the
- * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
- * well as the first string item in @message's body.
+ * 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.
*
- * Returns: %TRUE if @error was set, %FALSE otherwise.
- * Since: 2.26
+ * 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.
+ *
+ * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_dbus_method_info_ref:
- * @info: A #GDBusMethodInfo
+ * g_file_append_to_async:
+ * @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
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Asynchronously opens @file for appending.
*
- * Returns: The same @info.
- * Since: 2.26
+ * 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.
*/
/**
- * g_dbus_method_info_unref:
- * @info: A #GDBusMethodInfo.
- *
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * g_file_append_to_finish:
+ * @file: input #GFile
+ * @res: #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Since: 2.26
+ * 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().
*/
/**
- * g_dbus_method_invocation_get_connection:
- * @invocation: A #GDBusMethodInvocation.
- *
- * Gets the #GDBusConnection the method was invoked on.
+ * g_file_attribute_info_list_add:
+ * @list: a #GFileAttributeInfoList.
+ * @name: the name of the attribute to add.
+ * @type: the #GFileAttributeType for the attribute.
+ * @flags: #GFileAttributeInfoFlags for the attribute.
*
- * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Adds a new attribute with @name to the @list, setting
+ * its @type and @flags.
*/
/**
- * g_dbus_method_invocation_get_interface_name:
- * @invocation: A #GDBusMethodInvocation.
+ * g_file_attribute_info_list_dup:
+ * @list: a #GFileAttributeInfoList to duplicate.
*
- * Gets the name of the D-Bus interface the method was invoked on.
+ * Makes a duplicate of a file attribute info list.
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: a copy of the given @list.
*/
/**
- * g_dbus_method_invocation_get_message:
- * @invocation: A #GDBusMethodInvocation.
- *
- * Gets the #GDBusMessage for the method invocation. This is useful if
- * you need to use low-level protocol features, such as UNIX file
- * descriptor passing, that cannot be properly expressed in the
- * #GVariant API.
+ * g_file_attribute_info_list_lookup:
+ * @list: a #GFileAttributeInfoList.
+ * @name: the name of the attribute to lookup.
*
- * 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.
+ * Gets the file attribute with the name @name from @list.
*
- * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
+ * attribute isn't found.
*/
/**
- * g_dbus_method_invocation_get_method_info:
- * @invocation: A #GDBusMethodInvocation.
+ * g_file_attribute_info_list_new:
*
- * Gets information about the method call, if any.
+ * Creates a new file attribute info list.
*
- * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: a #GFileAttributeInfoList.
*/
/**
- * g_dbus_method_invocation_get_method_name:
- * @invocation: A #GDBusMethodInvocation.
+ * g_file_attribute_info_list_ref:
+ * @list: a #GFileAttributeInfoList to reference.
*
- * Gets the name of the method that was invoked.
+ * References a file attribute info list.
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: #GFileAttributeInfoList or %NULL on error.
*/
/**
- * g_dbus_method_invocation_get_object_path:
- * @invocation: A #GDBusMethodInvocation.
- *
- * Gets the object path the method was invoked on.
+ * g_file_attribute_info_list_unref:
+ * @list: The #GFileAttributeInfoList to unreference.
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Removes a reference from the given @list. If the reference count
+ * falls to zero, the @list is deleted.
*/
/**
- * g_dbus_method_invocation_get_parameters:
- * @invocation: A #GDBusMethodInvocation.
+ * g_file_attribute_matcher_enumerate_namespace:
+ * @matcher: a #GFileAttributeMatcher.
+ * @ns: a string containing a file attribute namespace.
*
- * Gets the parameters of the method invocation. If there are no input
- * parameters then this will return a GVariant with 0 children rather than NULL.
+ * Checks if the matcher will match all of the keys in a given namespace.
+ * This will always return %TRUE if a wildcard character is in use (e.g. if
+ * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
+ * using "*" and namespace is anything.)
*
- * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
- * Since: 2.26
+ * TODO: this is awkwardly worded.
+ *
+ * Returns: %TRUE if the matcher matches all of the entries
+ * in the given @ns, %FALSE otherwise.
*/
/**
- * g_dbus_method_invocation_get_sender:
- * @invocation: A #GDBusMethodInvocation.
+ * g_file_attribute_matcher_enumerate_next:
+ * @matcher: a #GFileAttributeMatcher.
*
- * Gets the bus name that invoked the method.
+ * Gets the next matched attribute from a #GFileAttributeMatcher.
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: a string containing the next attribute or %NULL if
+ * no more attribute exist.
*/
/**
- * g_dbus_method_invocation_get_user_data: (skip)
- * @invocation: A #GDBusMethodInvocation.
+ * g_file_attribute_matcher_matches:
+ * @matcher: a #GFileAttributeMatcher.
+ * @attribute: a file attribute key.
*
- * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
+ * Checks if an attribute will be matched by an attribute matcher. If
+ * the matcher was created with the "*" matching string, this function
+ * will always return %TRUE.
*
- * Returns: A #gpointer.
- * Since: 2.26
+ * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
*/
/**
- * g_dbus_method_invocation_return_dbus_error:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @error_name: A valid D-Bus error name.
- * @error_message: A valid D-Bus error message.
- *
- * Finishes handling a D-Bus method call by returning an error.
+ * g_file_attribute_matcher_matches_only:
+ * @matcher: a #GFileAttributeMatcher.
+ * @attribute: a file attribute key.
*
- * This method will free @invocation, you cannot use it afterwards.
+ * Checks if a attribute matcher only matches a given attribute. Always
+ * returns %FALSE if "*" was used when creating the matcher.
*
- * Since: 2.26
+ * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
*/
/**
- * g_dbus_method_invocation_return_error:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @domain: A #GQuark for the #GError error domain.
- * @code: The error code.
- * @format: printf()-style format.
- * @...: Parameters for @format.
+ * g_file_attribute_matcher_new:
+ * @attributes: an attribute string to match.
*
- * Finishes handling a D-Bus method call by returning an error.
+ * Creates a new file attribute matcher, which matches attributes
+ * 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.
*
- * See g_dbus_error_encode_gerror() for details about what error name
- * 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.
+ * The @attribute string should be formatted with specific keys separated
+ * from namespaces with a double colon. Several "namespace::key" strings may be
+ * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
+ * The wildcard "*" may be used to match all keys and namespaces, or
+ * "namespace::*" will match all keys in a given namespace.
*
- * If you are writing an application intended to be portable,
- * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
- * or use g_dbus_method_invocation_return_dbus_error().
+ * ## Examples of file attribute matcher strings and results
*
- * This method will free @invocation, you cannot use it afterwards.
+ * - `"*"`: 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.
*
- * Since: 2.26
+ * Returns: a #GFileAttributeMatcher
*/
/**
- * g_dbus_method_invocation_return_error_literal:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @domain: A #GQuark for the #GError error domain.
- * @code: The error code.
- * @message: The error message.
- *
- * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
+ * g_file_attribute_matcher_ref:
+ * @matcher: a #GFileAttributeMatcher.
*
- * This method will free @invocation, you cannot use it afterwards.
+ * References a file attribute matcher.
*
- * Since: 2.26
+ * Returns: a #GFileAttributeMatcher.
*/
/**
- * g_dbus_method_invocation_return_error_valist:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @domain: A #GQuark for the #GError error domain.
- * @code: The error code.
- * @format: printf()-style format.
- * @var_args: #va_list of parameters for @format.
+ * g_file_attribute_matcher_subtract:
+ * @matcher: Matcher to subtract from
+ * @subtract: The matcher to subtract
*
- * Like g_dbus_method_invocation_return_error() but intended for
- * language bindings.
+ * Subtracts all attributes of @subtract from @matcher and returns
+ * a matcher that supports those attributes.
*
- * This method will free @invocation, you cannot use it afterwards.
+ * Note that currently it is not possible to remove a single
+ * attribute when the @matcher matches the whole namespace - or remove
+ * a namespace or attribute when the matcher matches everything. This
+ * is a limitation of the current implementation, but may be fixed
+ * in the future.
*
- * Since: 2.26
+ * Returns: A file attribute matcher matching all attributes of
+ * @matcher that are not matched by @subtract
*/
/**
- * g_dbus_method_invocation_return_gerror:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @error: A #GError.
- *
- * Like g_dbus_method_invocation_return_error() but takes a #GError
- * instead of the error domain, error code and message.
+ * g_file_attribute_matcher_to_string:
+ * @matcher: (allow-none): a #GFileAttributeMatcher.
*
- * This method will free @invocation, you cannot use it afterwards.
+ * Prints what the matcher is matching against. The format will be
+ * equal to the format passed to g_file_attribute_matcher_new().
+ * The output however, might not be identical, as the matcher may
+ * decide to use a different order or omit needless parts.
*
- * Since: 2.26
+ * Returns: a string describing the attributes the matcher matches
+ * against or %NULL if @matcher was %NULL.
+ * Since: 2.32
*/
/**
- * g_dbus_method_invocation_return_value:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
- *
- * Finishes handling a D-Bus method call by returning @parameters.
- * If the @parameters GVariant is floating, it is consumed.
- *
- * It is an error if @parameters is not of the right format.
- *
- * This method will free @invocation, you cannot use it afterwards.
+ * g_file_attribute_matcher_unref:
+ * @matcher: a #GFileAttributeMatcher.
*
- * Since: 2.26
+ * Unreferences @matcher. If the reference count falls below 1,
+ * the @matcher is automatically freed.
*/
/**
- * g_dbus_method_invocation_return_value_with_unix_fd_list:
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
+ * g_file_attribute_value_dup:
+ * @other: a #GFileAttributeValue to duplicate.
*
- * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
- *
- * This method is only available on UNIX.
- *
- * This method will free @invocation, you cannot use it afterwards.
+ * Duplicates a file attribute.
*
- * Since: 2.30
+ * Returns: a duplicate of the @other.
*/
/**
- * g_dbus_method_invocation_take_error: (skip)
- * @invocation: (transfer full): A #GDBusMethodInvocation.
- * @error: (transfer full): A #GError.
- *
- * Like g_dbus_method_invocation_return_gerror() but takes ownership
- * of @error so the caller does not need to free it.
+ * g_file_attribute_value_set:
+ * @attr: a #GFileAttributeValue to set the value in.
+ * @new_value: a #GFileAttributeValue to get the value from.
*
- * This method will free @invocation, you cannot use it afterwards.
- *
- * Since: 2.30
+ * Sets an attribute's value from another attribute.
*/
/**
- * g_dbus_node_info_generate_xml:
- * @info: A #GDBusNodeInfo.
- * @indent: Indentation level.
- * @string_builder: (out): A #GString to to append XML data to.
+ * g_file_copy:
+ * @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
+ * @progress_callback_data: (closure): user data to pass to @progress_callback
+ * @error: #GError to set on error, or %NULL
+ *
+ * Copies the file @source to the location specified by @destination.
+ * Can not handle recursive copies of directories.
+ *
+ * If the flag #G_FILE_COPY_OVERWRITE is specified an already
+ * existing @destination file is overwritten.
+ *
+ * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
+ * will be copied as symlinks, otherwise the target of the
+ * @source symlink will be copied.
+ *
+ * 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 @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.
*
- * Appends an XML representation of @info (and its children) to @string_builder.
+ * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then
+ * the error %G_IO_ERROR_EXISTS is returned.
*
- * This function is typically used for generating introspection XML documents at run-time for
- * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
+ * 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.
*
- * Since: 2.26
+ * 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.
+ *
+ * If you are interested in copying the #GFile object itself (not the on-disk
+ * file), see g_file_dup().
+ *
+ * Returns: %TRUE on success, %FALSE otherwise.
*/
/**
- * g_dbus_node_info_lookup_interface:
- * @info: A #GDBusNodeInfo.
- * @name: A D-Bus interface name.
+ * g_file_copy_async: (skip)
+ * @source: input #GFile
+ * @destination: destination #GFile
+ * @flags: set of #GFileCopyFlags
+ * @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
*
- * Looks up information about an interface.
+ * Copies the file @source to the location specified by @destination
+ * asynchronously. For details of the behaviour, see g_file_copy().
*
- * This cost of this function is O(n) in number of interfaces.
+ * If @progress_callback is not %NULL, then that function that will be called
+ * 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.
*
- * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
- * Since: 2.26
+ * 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_dbus_node_info_new_for_xml:
- * @xml_data: Valid D-Bus introspection XML.
- * @error: Return location for error.
- *
- * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
+ * 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
*
- * Note that this routine is using a
- * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
- * parser that only accepts a subset of valid XML documents.
+ * Copies the file attributes from @source to @destination.
*
- * with g_dbus_node_info_unref().
+ * Normally only a subset of the file attributes are copied,
+ * those that are copies in a normal file copy operation
+ * (which for instance does not include e.g. owner). However
+ * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
+ * all the metadata that is possible to copy is copied. This
+ * is useful when implementing move by copy + delete source.
*
- * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
- * Since: 2.26
+ * Returns: %TRUE if the attributes were copied successfully,
+ * %FALSE otherwise.
*/
/**
- * g_dbus_node_info_ref:
- * @info: A #GDBusNodeInfo
+ * g_file_copy_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Finishes copying the file started with g_file_copy_async().
*
- * Returns: The same @info.
- * Since: 2.26
+ * Returns: a %TRUE on success, %FALSE on error.
*/
/**
- * g_dbus_node_info_unref:
- * @info: A #GDBusNodeInfo.
+ * g_file_create:
+ * @file: input #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Creates a new file and returns an output stream for writing to it.
+ * The file must not already exist.
*
- * Since: 2.26
- */
-
-
-/**
- * g_dbus_object_get_interface:
- * @object: A #GDBusObject.
- * @interface_name: A D-Bus interface name.
+ * 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.
*
- * Gets the D-Bus interface with name @interface_name associated with
- * @object, if any.
+ * 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.
*
- * #GDBusInterface that must be freed with g_object_unref().
+ * 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): %NULL if not found, otherwise a
- * Since: 2.30
+ * Returns: (transfer full): a #GFileOutputStream for the newly created
+ * file, or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_dbus_object_get_interfaces:
- * @object: A #GDBusObject.
+ * g_file_create_async:
+ * @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
*
- * Gets the D-Bus interfaces associated with @object.
+ * Asynchronously creates a new file and returns an output stream
+ * for writing to it. The file must not already exist.
*
- * The returned list must be freed by g_list_free() after each element has been freed
- * with g_object_unref().
+ * For more details, see g_file_create() which is
+ * the synchronous version of this call.
*
- * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
- * Since: 2.30
+ * 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_dbus_object_get_object_path:
- * @object: A #GDBusObject.
+ * g_file_create_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Gets the object path for @object.
+ * Finishes an asynchronous file create operation started with
+ * g_file_create_async().
*
- * Returns: A string owned by @object. Do not free.
- * Since: 2.30
+ * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_dbus_object_manager_client_get_connection:
- * @manager: A #GDBusObjectManagerClient
+ * g_file_create_readwrite:
+ * @file: a #GFile
+ * @flags: a set of #GFileCreateFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: return location for a #GError, or %NULL
*
- * Gets the #GDBusConnection used by @manager.
+ * Creates a new file and returns a stream for reading and
+ * writing to it. The file must not already exist.
*
- * the object belongs to @manager.
+ * 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.
*
- * Returns: (transfer none): A #GDBusConnection object. Do not free,
- * Since: 2.30
+ * 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.
+ *
+ * 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().
+ * Since: 2.22
*/
/**
- * g_dbus_object_manager_client_get_flags:
- * @manager: A #GDBusObjectManagerClient
+ * g_file_create_readwrite_async:
+ * @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
*
- * Gets the flags that @manager was constructed with.
+ * Asynchronously creates a new file and returns a stream
+ * for reading and writing to it. The file must not already exist.
*
- * enumeration.
+ * For more details, see g_file_create_readwrite() which is
+ * the synchronous version of this call.
*
- * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
- * Since: 2.30
+ * 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
*/
/**
- * g_dbus_object_manager_client_get_name:
- * @manager: A #GDBusObjectManagerClient
- *
- * Gets the name that @manager is for.
+ * g_file_create_readwrite_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * belongs to @manager.
+ * Finishes an asynchronous file create operation started with
+ * g_file_create_readwrite_async().
*
- * Returns: A unique or well-known name. Do not free, the string
- * Since: 2.30
+ * Returns: (transfer full): a #GFileIOStream or %NULL on error.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
*/
/**
- * g_dbus_object_manager_client_get_name_owner:
- * @manager: A #GDBusObjectManagerClient.
+ * g_file_delete: (virtual delete_file)
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * The unique name that owns the name that @manager is for or %NULL if
- * no-one currently owns that name. You can connect to the
- * #GObject::notify signal to track changes to the
- * #GDBusObjectManagerClient:name-owner property.
+ * 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().
*
- * g_free().
+ * 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: The name owner or %NULL if no name owner exists. Free with
- * Since: 2.30
+ * Returns: %TRUE if the file was deleted. %FALSE otherwise.
*/
/**
- * g_dbus_object_manager_client_new:
- * @connection: A #GDBusConnection.
- * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
- * @name: The owner of the control object (unique or well-known name).
- * @object_path: The object path of the control object.
- * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
- * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
- * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
- * @cancellable: A #GCancellable or %NULL
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
- *
- * Asynchronously creates a new #GDBusObjectManagerClient object.
+ * 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
*
- * 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>
- * 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.
+ * 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.30
+ * Since: 2.34
*/
/**
- * g_dbus_object_manager_client_new_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
- * @error: Return location for error or %NULL.
- *
- * Finishes an operation started with g_dbus_object_manager_client_new().
+ * g_file_delete_finish: (virtual delete_file_finish)
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
+ * Finishes deleting a file started with g_file_delete_async().
*
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
- * Since: 2.30
+ * Returns: %TRUE if the file was deleted. %FALSE otherwise.
+ * Since: 2.34
*/
/**
- * g_dbus_object_manager_client_new_for_bus:
- * @bus_type: A #GBusType.
- * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
- * @name: The owner of the control object (unique or well-known name).
- * @object_path: The object path of the control object.
- * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
- * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
- * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
- * @cancellable: A #GCancellable or %NULL
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
- *
- * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
- * #GDBusConnection.
+ * g_file_descriptor_based_get_fd:
+ * @fd_based: a #GFileDescriptorBased.
*
- * 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>
- * 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.
+ * Gets the underlying file descriptor.
*
- * Since: 2.30
+ * Returns: The file descriptor
+ * Since: 2.24
*/
/**
- * g_dbus_object_manager_client_new_for_bus_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
- * @error: Return location for error or %NULL.
+ * g_file_dup:
+ * @file: input #GFile
*
- * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
+ * 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.
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
+ * This call does no blocking I/O.
*
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
- * Since: 2.30
+ * Returns: (transfer full): a new #GFile that is a duplicate
+ * of the given #GFile.
*/
/**
- * g_dbus_object_manager_client_new_for_bus_sync:
- * @bus_type: A #GBusType.
- * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
- * @name: The owner of the control object (unique or well-known name).
- * @object_path: The object path of the control object.
- * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
- * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
- * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
- * @cancellable: A #GCancellable or %NULL
- * @error: Return location for error or %NULL.
- *
- * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
- * of a #GDBusConnection.
+ * g_file_eject_mountable:
+ * @file: input #GFile
+ * @flags: flags affecting the operation
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: (closure): the data to pass to callback function
*
- * This is a synchronous failable constructor - the calling thread is
- * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
- * for the asynchronous version.
+ * Starts an asynchronous eject on a mountable.
+ * When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with
+ * g_file_eject_mountable_finish().
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
+ * 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) (type GDBusObjectManagerClient): A
- * Since: 2.30
+ * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
*/
/**
- * 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).
- * @object_path: The object path of the control object.
- * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
- * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
- * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
- * @cancellable: A #GCancellable or %NULL
- * @error: Return location for error or %NULL.
- *
- * Creates a new #GDBusObjectManagerClient object.
- *
- * This is a synchronous failable constructor - the calling thread is
- * blocked until a reply is received. See g_dbus_object_manager_client_new()
- * for the asynchronous version.
+ * g_file_eject_mountable_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
+ * Finishes an asynchronous eject operation started by
+ * g_file_eject_mountable().
*
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
- * Since: 2.30
+ * Returns: %TRUE if the @file was ejected successfully.
+ * %FALSE otherwise.
+ * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish()
+ * instead.
*/
/**
- * g_dbus_object_manager_get_interface:
- * @manager: A #GDBusObjectManager.
- * @object_path: Object path to lookup.
- * @interface_name: D-Bus interface name to lookup.
+ * g_file_eject_mountable_with_operation:
+ * @file: input #GFile
+ * @flags: flags affecting the operation
+ * @mount_operation: (allow-none): a #GMountOperation,
+ * or %NULL to avoid user interaction
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: (closure): the data to pass to callback function
*
- * Gets the interface proxy for @interface_name at @object_path, if
- * any.
+ * Starts an asynchronous eject on a mountable.
+ * When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with
+ * g_file_eject_mountable_with_operation_finish().
*
- * with g_object_unref().
+ * 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 #GDBusInterface instance or %NULL. Free
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * g_dbus_object_manager_get_object:
- * @manager: A #GDBusObjectManager.
- * @object_path: Object path to lookup.
- *
- * Gets the #GDBusObjectProxy at @object_path, if any.
+ * g_file_eject_mountable_with_operation_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * g_object_unref().
+ * Finishes an asynchronous eject operation started by
+ * g_file_eject_mountable_with_operation().
*
- * Returns: (transfer full): A #GDBusObject or %NULL. Free with
- * Since: 2.30
+ * Returns: %TRUE if the @file was ejected successfully.
+ * %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_dbus_object_manager_get_object_path:
- * @manager: A #GDBusObjectManager.
+ * 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 object path that @manager is for.
+ * 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.
*
- * Returns: A string owned by @manager. Do not free.
- * Since: 2.30
+ * 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().
*/
/**
- * g_dbus_object_manager_get_objects:
- * @manager: A #GDBusObjectManager.
+ * g_file_enumerate_children_async:
+ * @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
*
- * Gets all #GDBusObject objects known to @manager.
+ * 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.
*
- * #GDBusObject objects. The returned list should be freed with
- * g_list_free() after each element has been freed with
- * g_object_unref().
+ * For more details, see g_file_enumerate_children() which is
+ * the synchronous version of this call.
*
- * Returns: (transfer full) (element-type GDBusObject): A list of
- * Since: 2.30
+ * 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_dbus_object_manager_server_export:
- * @manager: A #GDBusObjectManagerServer.
- * @object: A #GDBusObjectSkeleton.
+ * g_file_enumerate_children_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
- * Exports @object on @manager.
+ * Finishes an async enumerate children operation.
+ * See g_file_enumerate_children_async().
*
- * If there is already a #GDBusObject exported at the object path,
- * then the old object is removed.
+ * Returns: (transfer full): a #GFileEnumerator or %NULL
+ * if an error occurred.
+ * Free the returned object with g_object_unref().
+ */
+
+
+/**
+ * g_file_enumerator_close:
+ * @enumerator: a #GFileEnumerator.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * The object path for @object must be in the hierarchy rooted by the
- * object path for @manager.
+ * Releases all resources used by this enumerator, making the
+ * enumerator return %G_IO_ERROR_CLOSED on all calls.
*
- * Note that @manager will take a reference on @object for as long as
- * it is exported.
+ * This will be automatically called when the last reference
+ * is dropped, but you might want to call this function to make
+ * sure resources are released as early as possible.
*
- * Since: 2.30
+ * Returns: #TRUE on success or #FALSE on error.
*/
/**
- * g_dbus_object_manager_server_export_uniquely:
- * @manager: A #GDBusObjectManagerServer.
- * @object: An object.
+ * g_file_enumerator_close_async:
+ * @enumerator: a #GFileEnumerator.
+ * @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
*
- * 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.
+ * Asynchronously closes the file enumerator.
*
- * Since: 2.30
+ * 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 in
+ * g_file_enumerator_close_finish().
*/
/**
- * g_dbus_object_manager_server_get_connection:
- * @manager: A #GDBusObjectManagerServer
+ * g_file_enumerator_close_finish:
+ * @enumerator: a #GFileEnumerator.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Gets the #GDBusConnection used by @manager.
+ * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
*
- * @manager isn't exported on a connection. The returned object should
- * be freed with g_object_unref().
+ * If the file enumerator was already closed when g_file_enumerator_close_async()
+ * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
+ * return %FALSE. If the file enumerator had pending operation when the close
+ * operation was started, then this function will report %G_IO_ERROR_PENDING, and
+ * return %FALSE. If @cancellable was not %NULL, then the operation may have been
+ * cancelled by triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
+ * returned.
*
- * Returns: (transfer full): A #GDBusConnection object or %NULL if
- * Since: 2.30
+ * Returns: %TRUE if the close operation has finished successfully.
*/
/**
- * g_dbus_object_manager_server_new:
- * @object_path: The object path to export the manager object at.
+ * 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);
+ * ]|
*
- * Creates a new #GDBusObjectManagerServer object.
+ * Returns: (transfer full): a #GFile for the #GFileInfo passed it.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_file_enumerator_get_container:
+ * @enumerator: a #GFileEnumerator
*
- * The returned server isn't yet exported on any connection. To do so,
- * use g_dbus_object_manager_server_set_connection(). Normally you
- * want to export all of your objects before doing so to avoid <ulink
- * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
- * signals being emitted.
+ * Get the #GFile container which is being enumerated.
*
- * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
- * Since: 2.30
+ * Returns: (transfer none): the #GFile which is being enumerated.
+ * Since: 2.18
*/
/**
- * g_dbus_object_manager_server_set_connection:
- * @manager: A #GDBusObjectManagerServer.
- * @connection: (allow-none): A #GDBusConnection or %NULL.
+ * g_file_enumerator_has_pending:
+ * @enumerator: a #GFileEnumerator.
*
- * Exports all objects managed by @manager on @connection. If
- * @connection is %NULL, stops exporting objects.
+ * Checks if the file enumerator has pending operations.
+ *
+ * Returns: %TRUE if the @enumerator has pending operations.
*/
/**
- * g_dbus_object_manager_server_unexport:
- * @manager: A #GDBusObjectManagerServer.
- * @object_path: An object path.
- *
- * If @manager has an object at @path, removes the object. Otherwise
- * does nothing.
+ * g_file_enumerator_is_closed:
+ * @enumerator: a #GFileEnumerator.
*
- * Note that @object_path must be in the hierarchy rooted by the
- * object path for @manager.
+ * Checks if the file enumerator has been closed.
*
- * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
- * Since: 2.30
+ * Returns: %TRUE if the @enumerator is closed.
*/
/**
- * g_dbus_object_proxy_get_connection:
- * @proxy: a #GDBusObjectProxy
+ * 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
*
- * Gets the connection that @proxy is for.
+ * 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.
*
- * object is owned by @proxy.
+ * 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.
*
- * Returns: (transfer none): A #GDBusConnection. Do not free, the
- * Since: 2.30
+ * 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_dbus_object_proxy_new:
- * @connection: a #GDBusConnection
- * @object_path: the object path
+ * g_file_enumerator_next_file:
+ * @enumerator: a #GFileEnumerator.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Creates a new #GDBusObjectProxy for the given connection and
- * object path.
+ * Returns information for the next file in the enumerated object.
+ * Will block until the information is available. The #GFileInfo
+ * returned from this function will contain attributes that match the
+ * attribute string that was passed when the #GFileEnumerator was created.
*
- * Returns: a new #GDBusObjectProxy
- * Since: 2.30
+ * 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: (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_dbus_object_skeleton_add_interface:
- * @object: A #GDBusObjectSkeleton.
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_file_enumerator_next_files_async:
+ * @enumerator: a #GFileEnumerator.
+ * @num_files: the number of file info objects to 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
*
- * Adds @interface_ to @object.
+ * Request information for a number of files from the enumerator asynchronously.
+ * When all i/o for the operation is finished the @callback will be called with
+ * the requested information.
*
- * If @object already contains a #GDBusInterfaceSkeleton with the same
- * interface name, it is removed before @interface_ is added.
+ * See the documentation of #GFileEnumerator for information about the
+ * order of returned files.
*
- * Note that @object takes its own reference on @interface_ and holds
- * it until removed.
+ * 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
+ * error will be reported. If a request is cancelled the callback will be called
+ * with %G_IO_ERROR_CANCELLED.
*
- * Since: 2.30
+ * During an async request no other sync and async calls are allowed, and will
+ * result in %G_IO_ERROR_PENDING errors.
+ *
+ * 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.
*/
/**
- * g_dbus_object_skeleton_flush:
- * @object: A #GDBusObjectSkeleton.
+ * 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.
*
- * This method simply calls g_dbus_interface_skeleton_flush() on all
- * interfaces belonging to @object. See that method for when flushing
- * is useful.
+ * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
*
- * Since: 2.30
+ * 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_dbus_object_skeleton_new:
- * @object_path: An object path.
- *
- * Creates a new #GDBusObjectSkeleton.
+ * g_file_enumerator_set_pending:
+ * @enumerator: a #GFileEnumerator.
+ * @pending: a boolean value.
*
- * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
- * Since: 2.30
+ * Sets the file enumerator as having pending operations.
*/
/**
- * g_dbus_object_skeleton_remove_interface:
- * @object: A #GDBusObjectSkeleton.
- * @interface_: A #GDBusInterfaceSkeleton.
+ * g_file_equal:
+ * @file1: the first #GFile
+ * @file2: the second #GFile
*
- * Removes @interface_ from @object.
+ * Checks if the two given #GFiles refer to the same file.
*
- * Since: 2.30
+ * 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.
+ *
+ * Returns: %TRUE if @file1 and @file2 are equal.
*/
/**
- * g_dbus_object_skeleton_remove_interface_by_name:
- * @object: A #GDBusObjectSkeleton.
- * @interface_name: A D-Bus interface name.
+ * g_file_find_enclosing_mount:
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError
*
- * Removes the #GDBusInterface with @interface_name from @object.
+ * Gets a #GMount for the #GFile.
*
- * If no D-Bus interface of the given interface exists, this function
- * does nothing.
+ * 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.
*
- * Since: 2.30
+ * 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().
*/
/**
- * g_dbus_object_skeleton_set_object_path:
- * @object: A #GDBusObjectSkeleton.
- * @object_path: A valid D-Bus object path.
+ * g_file_find_enclosing_mount_async:
+ * @file: a #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
*
- * Sets the object path for @object.
+ * Asynchronously gets the mount for the file.
*
- * Since: 2.30
+ * 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.
*/
/**
- * g_dbus_property_info_ref:
- * @info: A #GDBusPropertyInfo
+ * g_file_find_enclosing_mount_finish:
+ * @file: a #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Finishes an asynchronous find mount request.
+ * See g_file_find_enclosing_mount_async().
*
- * Returns: The same @info.
- * Since: 2.26
+ * Returns: (transfer full): #GMount for given @file or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_dbus_property_info_unref:
- * @info: A #GDBusPropertyInfo.
+ * g_file_get_basename:
+ * @file: input #GFile
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Gets the base name (the last component of the path) for a given #GFile.
*
- * Since: 2.26
+ * If called for the top level of a system (such as the filesystem root
+ * 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
+ * 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.
+ *
+ * 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_dbus_proxy_call:
- * @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.
- * @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.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: 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.
+ * g_file_get_child:
+ * @file: input #GFile
+ * @name: string containing the child's basename
*
- * Asynchronously invokes the @method_name method on @proxy.
+ * Gets a child of @file with basename equal to @name.
*
- * If @method_name contains any dots, then @name is split into interface and
- * method name parts. This allows using @proxy for invoking methods on
- * other interfaces.
+ * Note that the file with that specific name might not exist, but
+ * you can still have a #GFile that points to it. You can use this
+ * for instance to create that file.
*
- * If the #GDBusConnection associated with @proxy is closed then
- * the operation will fail with %G_IO_ERROR_CLOSED. If
- * @cancellable is canceled, the operation will fail with
- * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
- * compatible with the D-Bus protocol, the operation fails with
- * %G_IO_ERROR_INVALID_ARGUMENT.
+ * This call does no blocking I/O.
*
- * If the @parameters #GVariant is floating, it is consumed. This allows
- * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
- * g_dbus_proxy_call (proxy,
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * (GAsyncReadyCallback) two_strings_done,
- * &data);
- * ]|
+ * 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: return location for an error
*
- * If @proxy has an expected interface (see
- * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
- * then the return value is checked against the return type.
+ * 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 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 then call g_dbus_proxy_call_finish() to get the result of
- * the operation. See g_dbus_proxy_call_sync() for the synchronous
- * version of this method.
+ * This call does no blocking I/O.
*
- * Since: 2.26
+ * 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_dbus_proxy_call_finish:
- * @proxy: A #GDBusProxy.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
- * @error: Return location for error or %NULL.
+ * g_file_get_parent:
+ * @file: input #GFile
*
- * Finishes an operation started with g_dbus_proxy_call().
+ * Gets the parent directory for the @file.
+ * If the @file represents the root directory of the
+ * file system, then %NULL will be returned.
*
- * return values. Free with g_variant_unref().
+ * This call does no blocking I/O.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * Since: 2.26
+ * 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_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.
- * @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.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_file_get_parse_name:
+ * @file: input #GFile
*
- * Synchronously invokes the @method_name method on @proxy.
+ * Gets the parse name of the @file.
+ * A parse name is a UTF-8 string that describes the
+ * file such that one can get the #GFile back using
+ * g_file_parse_name().
*
- * If @method_name contains any dots, then @name is split into interface and
- * method name parts. This allows using @proxy for invoking methods on
- * other interfaces.
+ * This is generally used to show the #GFile as a nice
+ * full-pathname kind of string in a user interface,
+ * like in a location entry.
*
- * If the #GDBusConnection associated with @proxy is disconnected then
- * the operation will fail with %G_IO_ERROR_CLOSED. If
- * @cancellable is canceled, the operation will fail with
- * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
- * compatible with the D-Bus protocol, the operation fails with
- * %G_IO_ERROR_INVALID_ARGUMENT.
+ * For local files with names that can safely be converted
+ * to UTF-8 the pathname is used, otherwise the IRI is used
+ * (a form of URI that allows UTF-8 characters unescaped).
*
- * If the @parameters #GVariant is floating, it is consumed. This allows
- * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
- * g_dbus_proxy_call_sync (proxy,
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * &error);
- * ]|
+ * This call does no blocking I/O.
*
- * The calling thread is blocked until a reply is received. See
- * g_dbus_proxy_call() for the asynchronous version of this
- * method.
+ * 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
*
- * If @proxy has an expected interface (see
- * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
- * then the return value is checked against the return type.
+ * Gets the local pathname for #GFile, if one exists.
*
- * return values. Free with g_variant_unref().
+ * This call does no blocking I/O.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * Since: 2.26
+ * 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_dbus_proxy_call_with_unix_fd_list:
- * @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.
- * @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.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: 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.
+ * g_file_get_relative_path:
+ * @parent: input #GFile
+ * @descendant: input #GFile
*
- * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
+ * Gets the path for @descendant relative to @parent.
*
- * This method is only available on UNIX.
+ * This call does no blocking I/O.
*
- * Since: 2.30
+ * 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_dbus_proxy_call_with_unix_fd_list_finish:
- * @proxy: A #GDBusProxy.
- * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
- * @error: Return location for error or %NULL.
+ * g_file_get_uri:
+ * @file: input #GFile
*
- * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
+ * Gets the URI for the @file.
*
- * return values. Free with g_variant_unref().
+ * This call does no blocking I/O.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * Since: 2.30
+ * Returns: a string containing the #GFile's URI.
+ * The returned string should be freed with g_free()
+ * when no longer needed.
*/
/**
- * 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.
- * @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.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
- * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
- *
- * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
+ * g_file_get_uri_scheme:
+ * @file: input #GFile
*
- * This method is only available on UNIX.
+ * Gets the URI scheme for a #GFile.
+ * RFC 3986 decodes the scheme as:
+ * |[
+ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+ * ]|
+ * Common schemes include "file", "http", "ftp", etc.
*
- * return values. Free with g_variant_unref().
+ * This call does no blocking I/O.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * Since: 2.30
+ * Returns: a string containing the URI scheme for the given
+ * #GFile. The returned string should be freed with g_free()
+ * when no longer needed.
*/
/**
- * g_dbus_proxy_get_cached_property:
- * @proxy: A #GDBusProxy.
- * @property_name: Property name.
- *
- * Looks up the value for a property from the cache. This call does no
- * blocking IO.
+ * g_file_has_parent:
+ * @file: input #GFile
+ * @parent: (allow-none): the parent to check for, or %NULL
*
- * If @proxy has an expected interface (see
- * #GDBusProxy:g-interface-info) and @property_name is referenced by
- * it, then @value is checked against the type of the property.
+ * Checks if @file has a parent, and optionally, if it is @parent.
*
- * for @property_name or %NULL if the value is not in the cache. The
- * returned reference must be freed with g_variant_unref().
+ * If @parent is %NULL then this function returns %TRUE if @file has any
+ * parent at all. If @parent is non-%NULL then %TRUE is only returned
+ * if @file is a child of @parent.
*
- * Returns: A reference to the #GVariant instance that holds the value
- * Since: 2.26
+ * Returns: %TRUE if @file is a child of @parent (or any parent in the
+ * case that @parent is %NULL).
+ * Since: 2.24
*/
/**
- * g_dbus_proxy_get_cached_property_names:
- * @proxy: A #GDBusProxy.
+ * g_file_has_prefix: (virtual prefix_matches)
+ * @file: input #GFile
+ * @prefix: input #GFile
*
- * Gets the names of all cached properties on @proxy.
+ * Checks whether @file has the prefix specified by @prefix.
*
- * @proxy has no cached properties. Free the returned array with
- * g_strfreev().
+ * 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.
*
- * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
- * Since: 2.26
+ * 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.
+ *
+ * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix,
+ * %FALSE otherwise.
*/
/**
- * g_dbus_proxy_get_connection:
- * @proxy: A #GDBusProxy.
+ * g_file_has_uri_scheme:
+ * @file: input #GFile
+ * @uri_scheme: a string containing a URI scheme
*
- * Gets the connection @proxy is for.
+ * Checks to see if a #GFile has a given URI scheme.
*
- * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
- * Since: 2.26
+ * 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.
*/
/**
- * g_dbus_proxy_get_default_timeout:
- * @proxy: A #GDBusProxy.
+ * g_file_hash: (virtual hash)
+ * @file: (type GFile): #gconstpointer to a #GFile
*
- * Gets the timeout to use if -1 (specifying default timeout) is
- * passed as @timeout_msec in the g_dbus_proxy_call() and
- * g_dbus_proxy_call_sync() functions.
+ * Creates a hash value for a #GFile.
*
- * See the #GDBusProxy:g-default-timeout property for more details.
+ * This call does no blocking I/O.
*
- * Returns: Timeout to use for @proxy.
- * Since: 2.26
+ * 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.
*/
/**
- * g_dbus_proxy_get_flags:
- * @proxy: A #GDBusProxy.
+ * g_file_icon_get_file:
+ * @icon: a #GIcon.
*
- * Gets the flags that @proxy was constructed with.
+ * Gets the #GFile associated with the given @icon.
*
- * Returns: Flags from the #GDBusProxyFlags enumeration.
- * Since: 2.26
+ * Returns: (transfer none): a #GFile, or %NULL.
*/
/**
- * g_dbus_proxy_get_interface_info:
- * @proxy: A #GDBusProxy
- *
- * Returns the #GDBusInterfaceInfo, if any, specifying the interface
- * that @proxy conforms to. See the #GDBusProxy:g-interface-info
- * property for more details.
+ * g_file_icon_new:
+ * @file: a #GFile.
*
- * object, it is owned by @proxy.
+ * Creates a new icon for a file.
*
- * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
- * Since: 2.26
+ * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
+ * @file, or %NULL on error.
*/
/**
- * g_dbus_proxy_get_interface_name:
- * @proxy: A #GDBusProxy.
- *
- * Gets the D-Bus interface name @proxy is for.
+ * g_file_info_clear_status:
+ * @info: a #GFileInfo.
*
- * Returns: A string owned by @proxy. Do not free.
- * Since: 2.26
+ * Clears the status information from @info.
*/
/**
- * g_dbus_proxy_get_name:
- * @proxy: A #GDBusProxy.
- *
- * Gets the name that @proxy was constructed for.
+ * g_file_info_copy_into:
+ * @src_info: source to copy attributes from.
+ * @dest_info: destination to copy attributes to.
*
- * Returns: A string owned by @proxy. Do not free.
- * Since: 2.26
+ * Copies all of the [GFileAttribute][gio-GFileAttribute]
+ * from @src_info to @dest_info.
*/
/**
- * g_dbus_proxy_get_name_owner:
- * @proxy: A #GDBusProxy.
+ * g_file_info_dup:
+ * @other: a #GFileInfo.
*
- * The unique name that owns the name that @proxy is for or %NULL if
- * no-one currently owns that name. You may connect to the
- * #GObject::notify signal to track changes to the
- * #GDBusProxy:g-name-owner property.
+ * Duplicates a file info structure.
*
- * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
- * Since: 2.26
+ * Returns: (transfer full): a duplicate #GFileInfo of @other.
*/
/**
- * g_dbus_proxy_get_object_path:
- * @proxy: A #GDBusProxy.
+ * g_file_info_get_attribute_as_string:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Gets the object path @proxy is for.
+ * Gets the value of a attribute, formated as a string.
+ * This escapes things as needed to make the string valid
+ * utf8.
*
- * Returns: A string owned by @proxy. Do not free.
- * Since: 2.26
+ * Returns: a UTF-8 string associated with the given @attribute.
+ * When you're done with the string it must be freed with g_free().
*/
/**
- * g_dbus_proxy_new:
- * @connection: A #GDBusConnection.
- * @flags: Flags used when constructing the proxy.
- * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
- * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
- * @object_path: An object path.
- * @interface_name: A D-Bus interface name.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: Callback function to invoke when the proxy is ready.
- * @user_data: User data to pass to @callback.
- *
- * Creates a proxy for accessing @interface_name on the remote object
- * at @object_path owned by @name at @connection and asynchronously
- * loads D-Bus properties unless the
- * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
- * the #GDBusProxy::g-properties-changed signal to get notified about
- * property changes.
- *
- * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
- * match rules for signals. Connect to the #GDBusProxy::g-signal signal
- * 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.
- *
- * This is a failable asynchronous constructor - when the proxy is
- * ready, @callback will be invoked and you can use
- * g_dbus_proxy_new_finish() to get the result.
- *
- * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
+ * g_file_info_get_attribute_boolean:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+ * Gets the value of a boolean attribute. If the attribute does not
+ * contain a boolean value, %FALSE will be returned.
*
- * Since: 2.26
+ * Returns: the boolean value contained within the attribute.
*/
/**
- * g_dbus_proxy_new_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
- * @error: Return location for error or %NULL.
+ * g_file_info_get_attribute_byte_string:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Finishes creating a #GDBusProxy.
+ * Gets the value of a byte string attribute. If the attribute does
+ * not contain a byte string, %NULL will be returned.
*
- * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: the contents of the @attribute value as a byte string, or
+ * %NULL otherwise.
*/
/**
- * g_dbus_proxy_new_for_bus:
- * @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.
- * @name: A bus name (well-known or unique).
- * @object_path: An object path.
- * @interface_name: A D-Bus interface name.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: Callback function to invoke when the proxy is ready.
- * @user_data: User data to pass to @callback.
- *
- * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
+ * g_file_info_get_attribute_data:
+ * @info: a #GFileInfo
+ * @attribute: a file attribute key
+ * @type: (out) (allow-none): return location for the attribute type, or %NULL
+ * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
+ * @status: (out) (allow-none): return location for the attribute status, or %NULL
*
- * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+ * Gets the attribute type, value and status for an attribute key.
*
- * Since: 2.26
+ * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
+ * %FALSE otherwise.
*/
/**
- * g_dbus_proxy_new_for_bus_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
- * @error: Return location for error or %NULL.
+ * g_file_info_get_attribute_int32:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Finishes creating a #GDBusProxy.
+ * Gets a signed 32-bit integer contained within the attribute. If the
+ * attribute does not contain a signed 32-bit integer, or is invalid,
+ * 0 will be returned.
*
- * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: a signed 32-bit integer from the attribute.
*/
/**
- * 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.
- * @name: A bus name (well-known or unique).
- * @object_path: An object path.
- * @interface_name: A D-Bus interface name.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
- *
- * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
+ * g_file_info_get_attribute_int64:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+ * Gets a signed 64-bit integer contained within the attribute. If the
+ * attribute does not contain an signed 64-bit integer, or is invalid,
+ * 0 will be returned.
*
- * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: a signed 64-bit integer from the attribute.
*/
/**
- * g_dbus_proxy_new_sync:
- * @connection: A #GDBusConnection.
- * @flags: Flags used when constructing the proxy.
- * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
- * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
- * @object_path: An object path.
- * @interface_name: A D-Bus interface name.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: (allow-none): Return location for error or %NULL.
- *
- * Creates a proxy for accessing @interface_name on the remote object
- * at @object_path owned by @name at @connection and synchronously
- * loads D-Bus properties unless the
- * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
- *
- * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
- * match rules for signals. Connect to the #GDBusProxy::g-signal signal
- * 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.
- *
- * This is a synchronous failable constructor. See g_dbus_proxy_new()
- * and g_dbus_proxy_new_finish() for the asynchronous version.
+ * g_file_info_get_attribute_object:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+ * Gets the value of a #GObject attribute. If the attribute does
+ * not contain a #GObject, %NULL will be returned.
*
- * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: (transfer none): a #GObject associated with the given @attribute, or
+ * %NULL otherwise.
*/
/**
- * g_dbus_proxy_set_cached_property:
- * @proxy: A #GDBusProxy
- * @property_name: Property name.
- * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
- *
- * If @value is not %NULL, sets the cached value for the property with
- * name @property_name to the value in @value.
- *
- * If @value is %NULL, then the cached value is removed from the
- * property cache.
- *
- * If @proxy has an expected interface (see
- * #GDBusProxy:g-interface-info) and @property_name is referenced by
- * it, then @value is checked against the type of the property.
- *
- * If the @value #GVariant is floating, it is consumed. This allows
- * convenient 'inline' use of g_variant_new(), e.g.
- * |[
- * g_dbus_proxy_set_cached_property (proxy,
- * "SomeProperty",
- * g_variant_new ("(si)",
- * "A String",
- * 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.
+ * g_file_info_get_attribute_status:
+ * @info: a #GFileInfo
+ * @attribute: a file attribute key
*
- * 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>.
+ * Gets the attribute status for an attribute key.
*
- * Since: 2.26
+ * Returns: a #GFileAttributeStatus for the given @attribute, or
+ * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
*/
/**
- * g_dbus_proxy_set_default_timeout:
- * @proxy: A #GDBusProxy.
- * @timeout_msec: Timeout in milliseconds.
- *
- * Sets the timeout to use if -1 (specifying default timeout) is
- * passed as @timeout_msec in the g_dbus_proxy_call() and
- * g_dbus_proxy_call_sync() functions.
+ * g_file_info_get_attribute_string:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * See the #GDBusProxy:g-default-timeout property for more details.
+ * Gets the value of a string attribute. If the attribute does
+ * not contain a string, %NULL will be returned.
*
- * Since: 2.26
+ * Returns: the contents of the @attribute value as a UTF-8 string, or
+ * %NULL otherwise.
*/
/**
- * g_dbus_proxy_set_interface_info:
- * @proxy: A #GDBusProxy
- * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
+ * g_file_info_get_attribute_stringv:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Ensure that interactions with @proxy conform to the given
- * interface. See the #GDBusProxy:g-interface-info property for more
- * details.
+ * Gets the value of a stringv attribute. If the attribute does
+ * not contain a stringv, %NULL will be returned.
*
- * Since: 2.26
+ * 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
*/
/**
- * g_dbus_server_get_client_address:
- * @server: A #GDBusServer.
- *
- * Gets a D-Bus address string that can be used by clients to connect
- * to @server.
+ * g_file_info_get_attribute_type:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * by @server.
+ * Gets the attribute type for an attribute key.
*
- * Returns: A D-Bus address string. Do not free, the string is owned
- * Since: 2.26
+ * Returns: a #GFileAttributeType for the given @attribute, or
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
*/
/**
- * g_dbus_server_get_flags:
- * @server: A #GDBusServer.
+ * g_file_info_get_attribute_uint32:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Gets the flags for @server.
+ * Gets an unsigned 32-bit integer contained within the attribute. If the
+ * attribute does not contain an unsigned 32-bit integer, or is invalid,
+ * 0 will be returned.
*
- * Returns: A set of flags from the #GDBusServerFlags enumeration.
- * Since: 2.26
+ * Returns: an unsigned 32-bit integer from the attribute.
*/
/**
- * g_dbus_server_get_guid:
- * @server: A #GDBusServer.
+ * g_file_info_get_attribute_uint64:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Gets the GUID for @server.
+ * Gets a unsigned 64-bit integer contained within the attribute. If the
+ * attribute does not contain an unsigned 64-bit integer, or is invalid,
+ * 0 will be returned.
*
- * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
- * Since: 2.26
+ * Returns: a unsigned 64-bit integer from the attribute.
*/
/**
- * g_dbus_server_is_active:
- * @server: A #GDBusServer.
+ * g_file_info_get_content_type:
+ * @info: a #GFileInfo.
*
- * Gets whether @server is active.
+ * Gets the file's content type.
*
- * Returns: %TRUE if server is active, %FALSE otherwise.
- * Since: 2.26
+ * Returns: a string containing the file's content type.
*/
/**
- * g_dbus_server_new_sync:
- * @address: A D-Bus address.
- * @flags: Flags from the #GDBusServerFlags enumeration.
- * @guid: A D-Bus GUID.
- * @observer: A #GDBusAuthObserver or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for server or %NULL.
+ * g_file_info_get_deletion_date:
+ * @info: a #GFileInfo.
*
- * Creates a new D-Bus server that listens on the first address in
- * @address that works.
+ * 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.
*
- * Once constructed, you can use g_dbus_server_get_client_address() to
- * get a D-Bus address string that clients can use to connect.
+ * Returns: a #GDateTime, or %NULL.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_file_info_get_display_name:
+ * @info: a #GFileInfo.
*
- * Connect to the #GDBusServer::new-connection signal to handle
- * incoming connections.
+ * Gets a display name for a file.
*
- * The returned #GDBusServer isn't active - you have to start it with
- * g_dbus_server_start().
+ * Returns: a string containing the display name.
+ */
+
+
+/**
+ * g_file_info_get_edit_name:
+ * @info: a #GFileInfo.
*
- * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
- * be used.
+ * Gets the edit name for a file.
*
- * This is a synchronous failable constructor. See
- * g_dbus_server_new() for the asynchronous version.
+ * Returns: a string containing the edit name.
+ */
+
+
+/**
+ * g_file_info_get_etag:
+ * @info: a #GFileInfo.
*
- * g_object_unref().
+ * Gets the [entity tag][gfile-etag] for a given
+ * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
*
- * Returns: A #GDBusServer or %NULL if @error is set. Free with
- * Since: 2.26
+ * Returns: a string containing the value of the "etag:value" attribute.
*/
/**
- * g_dbus_server_start:
- * @server: A #GDBusServer.
+ * g_file_info_get_file_type:
+ * @info: a #GFileInfo.
*
- * Starts @server.
+ * Gets a file's type (whether it is a regular file, symlink, etc).
+ * This is different from the file's content type, see g_file_info_get_content_type().
*
- * Since: 2.26
+ * Returns: a #GFileType for the given file.
*/
/**
- * g_dbus_server_stop:
- * @server: A #GDBusServer.
+ * g_file_info_get_icon:
+ * @info: a #GFileInfo.
*
- * Stops @server.
+ * Gets the icon for a file.
*
- * Since: 2.26
+ * Returns: (transfer none): #GIcon for the given @info.
*/
/**
- * g_dbus_signal_info_ref:
- * @info: A #GDBusSignalInfo
+ * g_file_info_get_is_backup:
+ * @info: a #GFileInfo.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Checks if a file is a backup file.
*
- * Returns: The same @info.
- * Since: 2.26
+ * Returns: %TRUE if file is a backup file, %FALSE otherwise.
*/
/**
- * g_dbus_signal_info_unref:
- * @info: A #GDBusSignalInfo.
+ * g_file_info_get_is_hidden:
+ * @info: a #GFileInfo.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Checks if a file is hidden.
*
- * Since: 2.26
+ * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
*/
/**
- * g_desktop_app_info_get_categories:
- * @info: a #GDesktopAppInfo
+ * g_file_info_get_is_symlink:
+ * @info: a #GFileInfo.
*
- * Gets the categories from the desktop file.
+ * Checks if a file is a symlink.
*
- * i.e. no attempt is made to split it by ';' or validate it.
+ * Returns: %TRUE if the given @info is a symlink.
+ */
+
+
+/**
+ * g_file_info_get_modification_time:
+ * @info: a #GFileInfo.
+ * @result: (out caller-allocates): a #GTimeVal.
*
- * Returns: The unparsed Categories key from the desktop file;
+ * Gets the modification time of the current @info and sets it
+ * in @result.
*/
/**
- * g_desktop_app_info_get_filename:
- * @info: a #GDesktopAppInfo
+ * g_file_info_get_name:
+ * @info: a #GFileInfo.
*
- * When @info was created from a known filename, return it. In some
- * situations such as the #GDesktopAppInfo returned from
- * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
+ * Gets the name for a file.
*
- * Returns: The full path to the file for @info, or %NULL if not known.
- * Since: 2.24
+ * Returns: a string containing the file name.
*/
/**
- * g_desktop_app_info_get_generic_name:
- * @info: a #GDesktopAppInfo
+ * g_file_info_get_size:
+ * @info: a #GFileInfo.
*
- * Gets the generic name from the destkop file.
+ * Gets the file's size.
*
- * Returns: The value of the GenericName key
+ * Returns: a #goffset containing the file's size.
*/
/**
- * g_desktop_app_info_get_is_hidden:
- * @info: a #GDesktopAppInfo.
+ * g_file_info_get_sort_order:
+ * @info: a #GFileInfo.
*
- * A desktop file is hidden if the Hidden key in it is
- * set to True.
+ * Gets the value of the sort_order attribute from the #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
*
- * Returns: %TRUE if hidden, %FALSE otherwise.
+ * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
*/
/**
- * g_desktop_app_info_get_keywords:
- * @info: a #GDesktopAppInfo
+ * g_file_info_get_symbolic_icon:
+ * @info: a #GFileInfo.
*
- * Gets the keywords from the desktop file.
+ * Gets the symbolic icon for a file.
*
- * Returns: (transfer none): The value of the X-GNOME-Keywords key
- * Since: 2.32
+ * Returns: (transfer none): #GIcon for the given @info.
+ * Since: 2.34
*/
/**
- * g_desktop_app_info_get_nodisplay:
- * @info: a #GDesktopAppInfo
+ * g_file_info_get_symlink_target:
+ * @info: a #GFileInfo.
*
- * Gets the value of the NoDisplay key, which helps determine if the
- * application info should be shown in menus. See
- * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
+ * Gets the symlink target for a given #GFileInfo.
*
- * Returns: The value of the NoDisplay key
- * Since: 2.30
+ * Returns: a string containing the symlink target.
*/
/**
- * g_desktop_app_info_get_show_in:
- * @info: a #GDesktopAppInfo
- * @desktop_env: a string specifying a desktop name
+ * g_file_info_has_attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * 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.
+ * Checks if a file info structure has an attribute named @attribute.
+ *
+ * Returns: %TRUE if @Ginfo has an attribute named @attribute,
+ * %FALSE otherwise.
+ */
+
+
+/**
+ * g_file_info_has_namespace:
+ * @info: a #GFileInfo.
+ * @name_space: a file attribute namespace.
*
- * If @desktop_env is %NULL, then the name of the desktop set with
- * g_desktop_app_info_set_desktop_env() is used.
+ * Checks if a file info structure has an attribute in the
+ * specified @name_space.
*
- * 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 @Ginfo has an attribute in @name_space,
+ * %FALSE otherwise.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_file_info_list_attributes:
+ * @info: a #GFileInfo.
+ * @name_space: a file attribute key's namespace.
*
- * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
- * otherwise.
+ * Lists the file info structure's attributes.
*
- * Returns: %TRUE if the @info should be shown in @desktop_env according to the
- * Since: 2.30
+ * 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_desktop_app_info_launch_uris_as_manager:
- * @appinfo: a #GDesktopAppInfo
- * @uris: (element-type utf8): List of URIs
- * @launch_context: 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
- * @error: return location for a #GError, or %NULL
- *
- * This function performs the equivalent of g_app_info_launch_uris(),
- * but is intended primarily for operating system components that
- * 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.
+ * g_file_info_new:
*
- * 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.
+ * Creates a new file info structure.
*
- * Returns: %TRUE on successful launch, %FALSE otherwise.
+ * Returns: a #GFileInfo.
*/
/**
- * g_desktop_app_info_lookup_get_default_for_uri_scheme:
- * @lookup: a #GDesktopAppInfoLookup
- * @uri_scheme: a string containing a URI scheme.
- *
- * Gets the default application for launching applications
- * using this URI scheme for a particular GDesktopAppInfoLookup
- * implementation.
- *
- * The GDesktopAppInfoLookup interface and this function is used
- * to implement g_app_info_get_default_for_uri_scheme() backends
- * in a GIO module. There is no reason for applications to use it
- * directly. Applications should use g_app_info_get_default_for_uri_scheme().
+ * g_file_info_remove_attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
*
- * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
- * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
+ * Removes all cases of @attribute from @info if it exists.
*/
/**
- * g_desktop_app_info_new:
- * @desktop_id: the desktop file id
- *
- * Creates a new #GDesktopAppInfo based on a desktop file id.
- *
- * 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>
- * (i.e. a desktop id of kde-foo.desktop will match
- * <filename>/usr/share/applications/kde/foo.desktop</filename>).
+ * g_file_info_set_attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @type: a #GFileAttributeType
+ * @value_p: pointer to the value
*
- * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
+ * Sets the @attribute to contain the given value, if possible. To unset the
+ * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
*/
/**
- * g_desktop_app_info_new_from_filename:
- * @filename: the path of a desktop file, in the GLib filename encoding
- *
- * Creates a new #GDesktopAppInfo.
+ * g_file_info_set_attribute_boolean:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a boolean value.
*
- * Returns: a new #GDesktopAppInfo or %NULL on error.
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * g_desktop_app_info_new_from_keyfile:
- * @key_file: an opened #GKeyFile
- *
- * Creates a new #GDesktopAppInfo.
+ * g_file_info_set_attribute_byte_string:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a byte string.
*
- * Returns: a new #GDesktopAppInfo or %NULL on error.
- * Since: 2.18
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * 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>
- * 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>
+ * g_file_info_set_attribute_int32:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a signed 32-bit integer
*
- * Should be called only once; subsequent calls are ignored.
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * g_drive_can_eject:
- * @drive: a #GDrive.
- *
- * Checks if a drive can be ejected.
+ * g_file_info_set_attribute_int64:
+ * @info: a #GFileInfo.
+ * @attribute: attribute name to set.
+ * @attr_value: int64 value to set attribute to.
*
- * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * g_drive_can_poll_for_media:
- * @drive: a #GDrive.
- *
- * Checks if a drive can be polled for media changes.
- *
- * %FALSE otherwise.
+ * g_file_info_set_attribute_mask:
+ * @info: a #GFileInfo.
+ * @mask: a #GFileAttributeMatcher.
*
- * Returns: %TRUE if the @drive can be polled for media changes,
+ * Sets @mask on @info to match specific attribute types.
*/
/**
- * g_drive_can_start:
- * @drive: a #GDrive.
- *
- * Checks if a drive can be started.
+ * g_file_info_set_attribute_object:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a #GObject.
*
- * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
- * Since: 2.22
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * g_drive_can_start_degraded:
- * @drive: a #GDrive.
+ * g_file_info_set_attribute_status:
+ * @info: a #GFileInfo
+ * @attribute: a file attribute key
+ * @status: a #GFileAttributeStatus
*
- * Checks if a drive can be started degraded.
+ * Sets the attribute status for an attribute key. This is only
+ * needed by external code that implement g_file_set_attributes_from_info()
+ * or similar functions.
*
- * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
+ * The attribute must exist in @info for this to work. Otherwise %FALSE
+ * is returned and @info is unchanged.
+ *
+ * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
* Since: 2.22
*/
/**
- * g_drive_can_stop:
- * @drive: a #GDrive.
- *
- * Checks if a drive can be stopped.
+ * g_file_info_set_attribute_string:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a UTF-8 string.
*
- * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
- * Since: 2.22
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * g_drive_eject:
- * @drive: a #GDrive.
- * @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.
- * @user_data: user data to pass to @callback
- *
- * Asynchronously ejects a drive.
+ * g_file_info_set_attribute_stringv:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key
+ * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
*
- * When the operation is finished, @callback will be called.
- * You can then call g_drive_eject_finish() to obtain the
- * result of the operation.
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*
- * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
+ * Sinze: 2.22
*/
/**
- * g_drive_eject_finish:
- * @drive: a #GDrive.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes ejecting a drive.
- *
- * %FALSE otherwise.
+ * g_file_info_set_attribute_uint32:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: an unsigned 32-bit integer.
*
- * Returns: %TRUE if the drive has been ejected successfully,
- * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * 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.
- * @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 drive. This is an asynchronous operation, and is
- * finished by calling g_drive_eject_with_operation_finish() with the @drive
- * and #GAsyncResult data returned in the @callback.
+ * g_file_info_set_attribute_uint64:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: an unsigned 64-bit integer.
*
- * Since: 2.22
+ * Sets the @attribute to contain the given @attr_value,
+ * if possible.
*/
/**
- * 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.
- *
- * Finishes ejecting a drive. If any errors occurred during the operation,
- * @error will be set to contain the errors and %FALSE will be returned.
+ * g_file_info_set_content_type:
+ * @info: a #GFileInfo.
+ * @content_type: a content type. See [GContentType][gio-GContentType]
*
- * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
- * Since: 2.22
+ * Sets the content type attribute for a given #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
*/
/**
- * g_drive_enumerate_identifiers:
- * @drive: a #GDrive
- *
- * Gets the kinds of identifiers that @drive has.
- * Use g_drive_get_identifer() to obtain the identifiers
- * themselves.
+ * g_file_info_set_display_name:
+ * @info: a #GFileInfo.
+ * @display_name: a string containing a display name.
*
- * array of strings containing kinds of identifiers. Use g_strfreev()
- * to free.
+ * Sets the display name for the current #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
+ */
+
+
+/**
+ * g_file_info_set_edit_name:
+ * @info: a #GFileInfo.
+ * @edit_name: a string containing an edit name.
*
- * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
+ * Sets the edit name for the current file.
+ * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
*/
/**
- * g_drive_get_icon:
- * @drive: a #GDrive.
+ * g_file_info_set_file_type:
+ * @info: a #GFileInfo.
+ * @type: a #GFileType.
*
- * Gets the icon for @drive.
+ * Sets the file type in a #GFileInfo to @type.
+ * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
+ */
+
+
+/**
+ * g_file_info_set_icon:
+ * @info: a #GFileInfo.
+ * @icon: a #GIcon.
*
- * Free the returned object with g_object_unref().
+ * Sets the icon for a given #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
+ */
+
+
+/**
+ * g_file_info_set_is_hidden:
+ * @info: a #GFileInfo.
+ * @is_hidden: a #gboolean.
*
- * Returns: (transfer full): #GIcon for the @drive.
+ * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
+ * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
*/
/**
- * g_drive_get_identifier:
- * @drive: a #GDrive
- * @kind: the kind of identifier to return
- *
- * Gets the identifier of the given kind for @drive.
- *
- * requested identfier, or %NULL if the #GDrive
- * doesn't have this kind of identifier.
+ * g_file_info_set_is_symlink:
+ * @info: a #GFileInfo.
+ * @is_symlink: a #gboolean.
*
- * Returns: a newly allocated string containing the
+ * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
+ * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
*/
/**
- * g_drive_get_name:
- * @drive: a #GDrive.
- *
- * Gets the name of @drive.
- *
- * string should be freed when no longer needed.
+ * g_file_info_set_modification_time:
+ * @info: a #GFileInfo.
+ * @mtime: a #GTimeVal.
*
- * Returns: a string containing @drive's name. The returned
+ * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
+ * info to the given time value.
*/
/**
- * g_drive_get_sort_key:
- * @drive: A #GDrive.
- *
- * Gets the sort key for @drive, if any.
+ * g_file_info_set_name:
+ * @info: a #GFileInfo.
+ * @name: a string containing a name.
*
- * Returns: Sorting key for @drive or %NULL if no such key is available.
- * Since: 2.32
+ * Sets the name attribute for the current #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
*/
/**
- * g_drive_get_start_stop_type:
- * @drive: a #GDrive.
- *
- * Gets a hint about how a drive can be started/stopped.
+ * g_file_info_set_size:
+ * @info: a #GFileInfo.
+ * @size: a #goffset containing the file's size.
*
- * Returns: A value from the #GDriveStartStopType enumeration.
- * Since: 2.22
+ * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
+ * to the given size.
*/
/**
- * g_drive_get_volumes:
- * @drive: a #GDrive.
- *
- * Get a list of mountable volumes for @drive.
- *
- * The returned list should be freed with g_list_free(), after
- * its elements have been unreffed with g_object_unref().
+ * g_file_info_set_sort_order:
+ * @info: a #GFileInfo.
+ * @sort_order: a sort order integer.
*
- * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
+ * Sets the sort order attribute in the file info structure. See
+ * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
*/
/**
- * g_drive_has_media:
- * @drive: a #GDrive.
+ * g_file_info_set_symbolic_icon:
+ * @info: a #GFileInfo.
+ * @icon: a #GIcon.
*
- * Checks if the @drive has media. Note that the OS may not be polling
- * the drive for media changes; see g_drive_is_media_check_automatic()
- * for more details.
+ * Sets the symbolic icon for a given #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
*
- * Returns: %TRUE if @drive has media, %FALSE otherwise.
+ * Since: 2.34
*/
/**
- * g_drive_has_volumes:
- * @drive: a #GDrive.
- *
- * Check if @drive has any mountable volumes.
+ * g_file_info_set_symlink_target:
+ * @info: a #GFileInfo.
+ * @symlink_target: a static string containing a path to a symlink target.
*
- * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
+ * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
+ * to the given symlink target.
*/
/**
- * g_drive_is_media_check_automatic:
- * @drive: a #GDrive.
- *
- * Checks if @drive is capabable of automatically detecting media changes.
- *
- * media changes, %FALSE otherwise.
+ * g_file_info_unset_attribute_mask:
+ * @info: #GFileInfo.
*
- * Returns: %TRUE if the @drive is capabable of automatically detecting
+ * Unsets a mask set by g_file_info_set_attribute_mask(), if one
+ * is set.
*/
/**
- * g_drive_is_media_removable:
- * @drive: a #GDrive.
+ * g_file_input_stream_query_info:
+ * @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.
*
- * Checks if the @drive supports removable media.
+ * Queries a file input stream the given @attributes. This function blocks
+ * while querying the stream. For the asynchronous (non-blocking) version
+ * of this function, see g_file_input_stream_query_info_async(). While the
+ * stream is blocked, the stream will set the pending flag internally, and
+ * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
*
- * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
+ * Returns: (transfer full): a #GFileInfo, or %NULL on error.
*/
/**
- * g_drive_poll_for_media:
- * @drive: a #GDrive.
+ * g_file_input_stream_query_info_async:
+ * @stream: a #GFileInputStream.
+ * @attributes: a file attribute query string.
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
- * @user_data: user data to pass to @callback
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * Asynchronously polls @drive to see if media has been inserted or removed.
+ * Queries the stream information asynchronously.
+ * When the operation is finished @callback will be called.
+ * You can then call g_file_input_stream_query_info_finish()
+ * to get the result of the operation.
*
- * When the operation is finished, @callback will be called.
- * You can then call g_drive_poll_for_media_finish() to obtain the
- * result of the operation.
+ * For the synchronous version of this function,
+ * see g_file_input_stream_query_info().
+ *
+ * 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 set
*/
/**
- * g_drive_poll_for_media_finish:
- * @drive: a #GDrive.
+ * g_file_input_stream_query_info_finish:
+ * @stream: a #GFileInputStream.
* @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes an operation started with g_drive_poll_for_media() on a drive.
+ * @error: a #GError location to store the error occurring,
+ * or %NULL to ignore.
*
- * %FALSE otherwise.
+ * Finishes an asynchronous info query operation.
*
- * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
+ * Returns: (transfer full): #GFileInfo.
*/
/**
- * g_drive_start:
- * @drive: a #GDrive.
- * @flags: flags affecting the start 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.
- * @user_data: user data to pass to @callback
- *
- * Asynchronously starts a drive.
+ * g_file_io_stream_get_etag:
+ * @stream: a #GFileIOStream.
*
- * When the operation is finished, @callback will be called.
- * You can then call g_drive_start_finish() to obtain the
- * result of the operation.
+ * Gets the entity tag for the file when it has been written.
+ * This must be called after the stream has been written
+ * and closed, as the etag can change while writing.
*
+ * Returns: the entity tag for the stream.
* Since: 2.22
*/
/**
- * g_drive_start_finish:
- * @drive: a #GDrive.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * g_file_io_stream_query_info:
+ * @stream: a #GFileIOStream.
+ * @attributes: a file attribute query string.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Finishes starting a drive.
+ * Queries a file io stream for the given @attributes.
+ * This function blocks while querying the stream. For the asynchronous
+ * version of this function, see g_file_io_stream_query_info_async().
+ * While the stream is blocked, the stream will set the pending flag
+ * internally, and any other operations on the stream will fail with
+ * %G_IO_ERROR_PENDING.
*
- * %FALSE otherwise.
+ * Can fail if the stream was already closed (with @error being set to
+ * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+ * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
+ * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
+ * all cases of failure, %NULL will be returned.
*
- * Returns: %TRUE if the drive has been started successfully,
+ * 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 set, and %NULL will
+ * be returned.
+ *
+ * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
* 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.
+ * g_file_io_stream_query_info_async:
+ * @stream: a #GFileIOStream.
+ * @attributes: a file attribute query string.
+ * @io_priority: the [I/O priority][gio-GIOScheduler] of the request
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
- * @user_data: user data to pass to @callback
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * Asynchronously stops a drive.
+ * Asynchronously queries the @stream for a #GFileInfo. When completed,
+ * @callback will be called with a #GAsyncResult which can be used to
+ * finish the operation with g_file_io_stream_query_info_finish().
*
- * When the operation is finished, @callback will be called.
- * You can then call g_drive_stop_finish() to obtain the
- * result of the operation.
+ * For the synchronous version of this function, see
+ * g_file_io_stream_query_info().
*
* Since: 2.22
*/
/**
- * g_drive_stop_finish:
- * @drive: a #GDrive.
+ * g_file_io_stream_query_info_finish:
+ * @stream: a #GFileIOStream.
* @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes stopping a drive.
+ * @error: a #GError, %NULL to ignore.
*
- * %FALSE otherwise.
+ * Finalizes the asynchronous query started
+ * by g_file_io_stream_query_info_async().
*
- * Returns: %TRUE if the drive has been stopped successfully,
+ * Returns: (transfer full): A #GFileInfo for the finished query.
* Since: 2.22
*/
/**
- * g_emblem_get_icon:
- * @emblem: a #GEmblem from which the icon should be extracted.
+ * g_file_is_native:
+ * @file: input #GFile
*
- * Gives back the icon from @emblem.
+ * Checks to see if a file is native to the platform.
+ *
+ * A native file s one expressed in the platform-native filename format,
+ * 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.
*
- * the emblem and should not be modified or freed.
+ * 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.
*
- * Returns: (transfer none): a #GIcon. The returned object belongs to
- * Since: 2.18
+ * This call does no blocking I/O.
+ *
+ * Returns: %TRUE if @file is native
*/
/**
- * g_emblem_get_origin:
- * @emblem: a #GEmblem
+ * 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
+ * @error: a #GError, or %NULL
*
- * Gets the origin of the emblem.
+ * Loads the content of the file into memory. The data is always
+ * zero-terminated, but this is not included in the resultant @length.
+ * The returned @content should be freed with g_free() when no longer
+ * needed.
*
- * Returns: (transfer none): the origin of the emblem
- * Since: 2.18
+ * 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 the @file's contents were successfully loaded.
+ * %FALSE if there were errors.
*/
/**
- * g_emblem_new:
- * @icon: a GIcon containing the icon.
+ * g_file_load_contents_async:
+ * @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
+ *
+ * Starts an asynchronous load of the @file's contents.
+ *
+ * For more details, see g_file_load_contents() which is
+ * the synchronous version of this call.
*
- * Creates a new emblem for @icon.
+ * When the load operation has completed, @callback will be called
+ * with @user data. To finish the operation, call
+ * g_file_load_contents_finish() with the #GAsyncResult returned by
+ * the @callback.
*
- * Returns: a new #GEmblem.
- * Since: 2.18
+ * 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_emblem_new_with_origin:
- * @icon: a GIcon containing the icon.
- * @origin: a GEmblemOrigin enum defining the emblem's origin
+ * 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
+ * @error: a #GError, or %NULL
*
- * Creates a new emblem for @icon.
+ * Finishes an asynchronous load of the @file's contents.
+ * The contents are placed in @contents, and @length is set to the
+ * size of the @contents string. The @content should be freed with
+ * g_free() when no longer needed. If @etag_out is present, it will be
+ * set to the new entity tag for the @file.
*
- * Returns: a new #GEmblem.
- * Since: 2.18
+ * Returns: %TRUE if the load was successful. If %FALSE and @error is
+ * present, it will be set appropriately.
*/
/**
- * g_emblemed_icon_add_emblem:
- * @emblemed: a #GEmblemedIcon
- * @emblem: a #GEmblem
+ * 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
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to the callback functions
*
- * Adds @emblem to the #GList of #GEmblem <!-- -->s.
+ * 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().
*
- * Since: 2.18
+ * Users of this function should be aware that @user_data is passed to
+ * both the @read_more_callback and the @callback.
+ *
+ * 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_emblemed_icon_clear_emblems:
- * @emblemed: a #GEmblemedIcon
+ * 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
+ * @error: a #GError, or %NULL
*
- * Removes all the emblems from @icon.
+ * Finishes an asynchronous partial load operation that was started
+ * with g_file_load_partial_contents_async(). The data is always
+ * zero-terminated, but this is not included in the resultant @length.
+ * The returned @content should be freed with g_free() when no longer
+ * needed.
*
- * Since: 2.28
+ * Returns: %TRUE if the load was successful. If %FALSE and @error is
+ * present, it will be set appropriately.
*/
/**
- * g_emblemed_icon_get_emblems:
- * @emblemed: a #GEmblemedIcon
+ * g_file_make_directory:
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * Gets the list of emblems for the @icon.
+ * 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
+ * %G_IO_ERROR_NOT_SUPPORTED.
*
- * #GEmblem <!-- -->s that is owned by @emblemed
+ * For a local #GFile the newly created directory will have the default
+ * (current) ownership and permissions of the current process.
*
- * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
- * Since: 2.18
+ * 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 on successful creation, %FALSE otherwise.
*/
/**
- * g_emblemed_icon_get_icon:
- * @emblemed: a #GEmblemedIcon
+ * 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
*
- * Gets the main icon for @emblemed.
+ * Asynchronously creates a directory.
*
- * Returns: (transfer none): a #GIcon that is owned by @emblemed
- * Since: 2.18
+ * Since: 2.38
*/
/**
- * g_emblemed_icon_new:
- * @icon: a #GIcon
- * @emblem: (allow-none): a #GEmblem, or %NULL
+ * g_file_make_directory_finish: (virtual make_directory_finish)
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Creates a new emblemed icon for @icon with the emblem @emblem.
+ * Finishes an asynchronous directory creation, started with
+ * g_file_make_directory_async().
*
- * Returns: (transfer full): a new #GIcon
- * Since: 2.18
+ * Returns: %TRUE on successful directory creation, %FALSE otherwise.
+ * Since: 2.38
*/
/**
- * g_file_append_to:
- * @file: input #GFile.
- * @flags: a set of #GFileCreateFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * g_file_make_directory_with_parents:
+ * @file: input #GFile
+ * @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.
+ * 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().
*
- * 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.
+ * For a local #GFile the newly created directories will have the default
+ * (current) ownership and permissions of the current process.
*
* 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.
- *
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
+ * Returns: %TRUE if all directories have been successfully created, %FALSE
+ * otherwise.
+ * Since: 2.18
*/
/**
- * 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
- * @user_data: (closure): the data to pass to callback function
+ * 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
*
- * Asynchronously opens @file for appending.
+ * Creates a symbolic link named @file which contains the string
+ * @symlink_value.
*
- * For more details, see g_file_append_to() which is
- * the synchronous version of this call.
+ * 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_append_to_finish() to get the result of the operation.
+ * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
*/
/**
- * g_file_append_to_finish:
- * @file: input #GFile.
- * @res: #GAsyncResult
- * @error: a #GError, or %NULL
+ * 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
*
- * Finishes an asynchronous file append operation started with
- * g_file_append_to_async().
+ * Recursively measures the disk usage of @file.
*
- * Free the returned object with g_object_unref().
+ * 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).
*
- * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error.
- */
-
-
-/**
- * g_file_attribute_info_list_add:
- * @list: a #GFileAttributeInfoList.
- * @name: the name of the attribute to add.
- * @type: the #GFileAttributeType for the attribute.
- * @flags: #GFileAttributeInfoFlags for the attribute.
+ * 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.
*
- * Adds a new attribute with @name to the @list, setting
- * its @type and @flags.
- */
-
-
-/**
- * g_file_attribute_info_list_dup:
- * @list: a #GFileAttributeInfoList to duplicate.
+ * 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.
*
- * Makes a duplicate of a file attribute info list.
+ * @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: a copy of the given @list.
+ * Returns: %TRUE if successful, with the out parameters set.
+ * %FALSE otherwise, with @error set.
+ * Since: 2.38
*/
/**
- * g_file_attribute_info_list_lookup:
- * @list: a #GFileAttributeInfoList.
- * @name: the name of the attribute to lookup.
+ * 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
*
- * Gets the file attribute with the name @name from @list.
+ * Recursively measures the disk usage of @file.
*
- * attribute isn't found.
+ * This is the asynchronous version of g_file_measure_disk_usage(). See
+ * there for more information.
*
- * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
+ * Since: 2.38
*/
/**
- * g_file_attribute_info_list_new:
+ * 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
*
- * Creates a new file attribute info list.
+ * Collects the results from an earlier call to
+ * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for
+ * more information.
*
- * Returns: a #GFileAttributeInfoList.
+ * Returns: %TRUE if successful, with the out parameters set.
+ * %FALSE otherwise, with @error set.
+ * Since: 2.38
*/
/**
- * g_file_attribute_info_list_ref:
- * @list: a #GFileAttributeInfoList to reference.
+ * g_file_monitor:
+ * @file: input #GFile
+ * @flags: a set of #GFileMonitorFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * References a file attribute info list.
+ * Obtains a file or directory monitor for the given file,
+ * depending on the type of the file.
*
- * Returns: #GFileAttributeInfoList or %NULL on 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.
+ *
+ * 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_attribute_info_list_unref:
- * @list: The #GFileAttributeInfoList to unreference.
+ * g_file_monitor_cancel:
+ * @monitor: a #GFileMonitor.
*
- * Removes a reference from the given @list. If the reference count
- * falls to zero, the @list is deleted.
+ * Cancels a file monitor.
+ *
+ * Returns: %TRUE if monitor was cancelled.
*/
/**
- * g_file_attribute_matcher_enumerate_namespace:
- * @matcher: a #GFileAttributeMatcher.
- * @ns: a string containing a file attribute namespace.
+ * 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
*
- * Checks if the matcher will match all of the keys in a given namespace.
- * This will always return %TRUE if a wildcard character is in use (e.g. if
- * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
- * using "*" and namespace is anything.)
+ * Obtains a directory monitor for the given file.
+ * This may fail if directory monitoring is not supported.
*
- * TODO: this is awkwardly worded.
+ * 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.
*
- * in the given @ns, %FALSE otherwise.
+ * 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: %TRUE if the matcher matches all of the entries
+ * Returns: (transfer full): a #GFileMonitor for the given @file,
+ * or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_attribute_matcher_enumerate_next:
- * @matcher: a #GFileAttributeMatcher.
- *
- * Gets the next matched attribute from a #GFileAttributeMatcher.
+ * g_file_monitor_emit_event:
+ * @monitor: a #GFileMonitor.
+ * @child: a #GFile.
+ * @other_file: a #GFile.
+ * @event_type: a set of #GFileMonitorEvent flags.
*
- * no more attribute exist.
+ * Emits the #GFileMonitor::changed signal if a change
+ * has taken place. Should be called from file monitor
+ * implementations only.
*
- * Returns: a string containing the next attribute or %NULL if
+ * The signal will be emitted from an idle handler (in the
+ * [thread-default main context][g-main-context-push-thread-default]).
*/
/**
- * g_file_attribute_matcher_matches:
- * @matcher: a #GFileAttributeMatcher.
- * @attribute: a file attribute key.
+ * 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
*
- * Checks if an attribute will be matched by an attribute matcher. If
- * the matcher was created with the "*" matching string, this function
- * will always return %TRUE.
+ * Obtains a file monitor for the given file. If no file notification
+ * mechanism exists, then regular polling of the file is used.
*
- * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
- */
-
-
-/**
- * g_file_attribute_matcher_matches_only:
- * @matcher: a #GFileAttributeMatcher.
- * @attribute: a file attribute key.
+ * 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.
*
- * Checks if a attribute matcher only matches a given attribute. Always
- * returns %FALSE if "*" was used when creating the matcher.
+ * 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: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
+ * Returns: (transfer full): a #GFileMonitor for the given @file,
+ * or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_attribute_matcher_new:
- * @attributes: an attribute string to match.
- *
- * Creates a new file attribute matcher, which matches attributes
- * against a given string. #GFileAttributeMatcher<!-- -->s 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 @attribute string should be formatted with specific keys separated
- * from namespaces with a double colon. Several "namespace::key" strings may be
- * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
- * The wildcard "*" may be used to match all keys and namespaces, or
- * "namespace::*" will match all keys in a given namespace.
+ * g_file_monitor_is_cancelled:
+ * @monitor: a #GFileMonitor
*
- * 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>
+ * Returns whether the monitor is canceled.
*
- * Returns: a #GFileAttributeMatcher.
+ * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
*/
/**
- * g_file_attribute_matcher_ref:
- * @matcher: a #GFileAttributeMatcher.
- *
- * References a file attribute matcher.
+ * g_file_monitor_set_rate_limit:
+ * @monitor: a #GFileMonitor.
+ * @limit_msecs: a non-negative integer with the limit in milliseconds
+ * to poll for changes
*
- * Returns: a #GFileAttributeMatcher.
+ * Sets the rate limit to which the @monitor will report
+ * consecutive change events to the same file.
*/
/**
- * g_file_attribute_matcher_subtract:
- * @matcher: Matcher to subtract from
- * @subtract: The matcher to subtract
+ * g_file_mount_enclosing_volume:
+ * @location: input #GFile
+ * @flags: flags affecting the operation
+ * @mount_operation: (allow-none): a #GMountOperation
+ * or %NULL to avoid user interaction
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: the data to pass to callback function
*
- * Subtracts all attributes of @subtract from @matcher and returns
- * a matcher that supports those attributes.
+ * Starts a @mount_operation, mounting the volume that contains
+ * the file @location.
*
- * Note that currently it is not possible to remove a single
- * attribute when the @matcher matches the whole namespace - or remove
- * a namespace or attribute when the matcher matches everything. This
- * is a limitation of the current implementation, but may be fixed
- * in the future.
+ * 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().
+ *
+ * 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_mount_enclosing_volume_finish:
+ * @location: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * @matcher that are not matched by @subtract
+ * Finishes a mount operation started by g_file_mount_enclosing_volume().
*
- * Returns: A file attribute matcher matching all attributes of
+ * Returns: %TRUE if successful. If an error has occurred,
+ * this function will return %FALSE and set @error
+ * appropriately if present.
*/
/**
- * g_file_attribute_matcher_to_string:
- * @matcher: (allow-none): a #GFileAttributeMatcher.
+ * g_file_mount_mountable:
+ * @file: input #GFile
+ * @flags: flags affecting the operation
+ * @mount_operation: (allow-none): a #GMountOperation,
+ * or %NULL to avoid user interaction
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: (closure): the data to pass to callback function
*
- * Prints what the matcher is matching against. The format will be
- * equal to the format passed to g_file_attribute_matcher_new().
- * The output however, might not be identical, as the matcher may
- * decide to use a different order or omit needless parts.
+ * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
+ * Using @mount_operation, you can request callbacks when, for instance,
+ * passwords are needed during authentication.
*
- * against or %NULL if @matcher was %NULL.
+ * 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 string describing the attributes the matcher matches
- * Since: 2.32
+ * 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_attribute_matcher_unref:
- * @matcher: a #GFileAttributeMatcher.
+ * g_file_mount_mountable_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Unreferences @matcher. If the reference count falls below 1,
- * the @matcher is automatically freed.
+ * 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().
*/
/**
- * g_file_copy:
- * @source: input #GFile.
- * @destination: destination #GFile
+ * 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): 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
+ * @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
*
- * Copies the file @source to the location specified by @destination.
- * Can not handle recursive copies of directories.
+ * 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 is returned.
+ * #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 you are interested in copying the #GFile object itself (not the on-disk
- * file), see g_file_dup().
+ * Returns: %TRUE on successful move, %FALSE otherwise.
+ */
+
+
+/**
+ * g_file_new_for_commandline_arg:
+ * @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: %TRUE on success, %FALSE otherwise.
+ * Returns: (transfer full): a new #GFile.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_copy_async: (skip)
- * @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
- * @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
+ * g_file_new_for_commandline_arg_and_cwd:
+ * @arg: a command line string
+ * @cwd: the current working directory of the commandline
*
- * Copies the file @source to the location specified by @destination
- * asynchronously. For details of the behaviour, see g_file_copy().
+ * Creates a #GFile with the given argument from the command line.
*
- * 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.
+ * 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.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_copy_finish() to get the result of the operation.
+ * 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_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.
- *
- * Copies the file attributes from @source to @destination.
+ * g_file_new_for_path:
+ * @path: a string containing a relative or absolute path.
+ * The string must be encoded in the glib filename encoding.
*
- * Normally only a subset of the file attributes are copied,
- * those that are copies in a normal file copy operation
- * (which for instance does not include e.g. owner). However
- * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
- * all the metadata that is possible to copy is copied. This
- * is useful when implementing move by copy + delete source.
+ * 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: %TRUE if the attributes were copied successfully, %FALSE otherwise.
+ * Returns: (transfer full): a new #GFile for the given @path.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_copy_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * g_file_new_for_uri:
+ * @uri: a UTF-8 string containing a URI
*
- * Finishes copying the file started with
- * g_file_copy_async().
+ * 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: a %TRUE on success, %FALSE on error.
+ * Returns: (transfer full): a new #GFile for the given @uri.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_create:
- * @file: input #GFile.
- * @flags: a set of #GFileCreateFlags.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * 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
* @error: a #GError, or %NULL
*
- * Creates a new file and returns an output stream for writing to it.
- * The file must not already exist.
+ * Opens a file in the preferred directory for temporary files (as
+ * returned by g_get_tmp_dir()) and returns a #GFile and
+ * #GFileIOStream pointing 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.
+ * @tmpl should be a string in the GLib file name encoding
+ * containing a sequence of six 'X' characters, and containing no
+ * directory components. If it is %NULL, a default template is used.
*
- * 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.
+ * Unlike the other #GFile constructors, this will return %NULL if
+ * a temporary file could not be created.
*
- * 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 new #GFile.
+ * Free the returned object with g_object_unref().
+ * Since: 2.32
+ */
+
+
+/**
+ * g_file_open_readwrite:
+ * @file: #GFile to open
+ * @cancellable: (allow-none): a #GCancellable
+ * @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.
+ *
+ * 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.
*
- * %NULL on error.
- * Free the returned object with g_object_unref().
+ * 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): a #GFileOutputStream for the newly created file, or
+ * Returns: (transfer full): #GFileIOStream or %NULL on error.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
*/
/**
- * 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
+ * g_file_open_readwrite_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: (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 opens @file for reading and writing.
*
- * For more details, see g_file_create() which is
+ * 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_create_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_create_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
+ * g_file_open_readwrite_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
* @error: a #GError, or %NULL
*
- * Finishes an asynchronous file create operation started with
- * g_file_create_async().
+ * Finishes an asynchronous file read operation started with
+ * g_file_open_readwrite_async().
*
- * 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_get_etag:
+ * @stream: a #GFileOutputStream.
*
- * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
+ * Gets the entity tag for the file when it has been written.
+ * This must be called after the stream has been written
+ * and closed, as the etag can change while writing.
+ *
+ * Returns: the entity tag for the stream.
*/
/**
- * g_file_create_readwrite:
- * @file: a #GFile
- * @flags: a set of #GFileCreateFlags
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: return location for a #GError, or %NULL
+ * g_file_output_stream_query_info:
+ * @stream: a #GFileOutputStream.
+ * @attributes: a file attribute query string.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Creates a new file and returns a stream for reading and writing to it.
- * The file must not already exist.
+ * Queries a file output stream for the given @attributes.
+ * This function blocks while querying the stream. For the asynchronous
+ * version of this function, see g_file_output_stream_query_info_async().
+ * While the stream is blocked, the stream will set the pending flag
+ * internally, and any other operations on the stream will fail with
+ * %G_IO_ERROR_PENDING.
*
- * 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.
+ * Can fail if the stream was already closed (with @error being set to
+ * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+ * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
+ * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
+ * all cases of failure, %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.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
+ * be returned.
+ *
+ * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
+ */
+
+
+/**
+ * g_file_output_stream_query_info_async:
+ * @stream: a #GFileOutputStream.
+ * @attributes: a file attribute query string.
+ * @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
+ *
+ * Asynchronously queries the @stream for a #GFileInfo. When completed,
+ * @callback will be called with a #GAsyncResult which can be used to
+ * finish the operation with g_file_output_stream_query_info_finish().
+ *
+ * For the synchronous version of this function, see
+ * g_file_output_stream_query_info().
+ */
+
+
+/**
+ * g_file_output_stream_query_info_finish:
+ * @stream: a #GFileOutputStream.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, %NULL to ignore.
*
- * 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.
+ * Finalizes the asynchronous query started
+ * by g_file_output_stream_query_info_async().
*
- * 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 #GFileInfo for the finished query.
+ */
+
+
+/**
+ * g_file_parse_name:
+ * @parse_name: a file name or path to be parsed
*
- * Free the returned object with g_object_unref().
+ * 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 #GFileIOStream for the newly created file, or %NULL on error.
- * Since: 2.22
+ * Returns: (transfer full): a new #GFile.
*/
/**
- * g_file_create_readwrite_async:
+ * g_file_poll_mountable:
* @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
- * @user_data: (closure): the data to pass to callback function
+ * @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
*
- * Asynchronously creates a new file and returns a stream for reading and
- * writing to it. The file must not already exist.
+ * Polls a file of type #G_FILE_TYPE_MOUNTABLE.
*
- * For more details, see g_file_create_readwrite() which is
- * the synchronous version of this call.
+ * 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_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_mount_mountable_finish() to get
+ * the result of the operation.
*
* Since: 2.22
*/
/**
- * g_file_create_readwrite_finish:
+ * g_file_poll_mountable_finish:
* @file: input #GFile
- * @res: a #GAsyncResult
+ * @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
- * Finishes an asynchronous file create operation started with
- * g_file_create_readwrite_async().
+ * Finishes a poll operation. See g_file_poll_mountable() for details.
*
- * Free the returned object with g_object_unref().
+ * Finish an asynchronous poll operation that was polled
+ * with g_file_poll_mountable().
*
- * Returns: (transfer full): a #GFileIOStream or %NULL on error.
+ * Returns: %TRUE if the operation finished successfully. %FALSE
+ * otherwise.
* Since: 2.22
*/
/**
- * g_file_delete:
- * @file: input #GFile.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * g_file_query_default_handler:
+ * @file: a #GFile to open
+ * @cancellable: 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.
+ * Returns the #GAppInfo that is registered as the default
+ * application to handle the file specified by @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.
*
- * Virtual: delete_file
- * Returns: %TRUE if the file was deleted. %FALSE otherwise.
+ * 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_descriptor_based_get_fd:
- * @fd_based: a #GFileDescriptorBased.
+ * g_file_query_exists:
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
*
- * Gets the underlying file descriptor.
+ * Utility function to check if a particular file exists. This is
+ * implemented using g_file_query_info() and as such does blocking I/O.
*
- * Returns: The file descriptor
- * Since: 2.24
- */
-
-
-/**
- * g_file_dup:
- * @file: input #GFile.
+ * Note that in many cases it is racy to first check for file existence
+ * and then execute something based on the outcome of that, because the
+ * file might have been created or removed in between the operations. The
+ * general approach to handling that is to not check, but just do the
+ * operation and handle the errors as they come.
*
- * 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.
+ * 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.
*
- * This call does no blocking i/o.
+ * 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: (transfer full): a new #GFile that is a duplicate of the given #GFile.
+ * Returns: %TRUE if the file exists (and can be detected without error),
+ * %FALSE otherwise (or if cancelled).
*/
/**
- * g_file_eject_mountable:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: (closure): the data to pass to callback function
+ * 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
*
- * Starts an asynchronous eject on a mountable.
- * When this operation has completed, @callback will be called with
- * @user_user data, and the operation can be finalized with
- * g_file_eject_mountable_finish().
+ * Utility function to inspect the #GFileType of a file. This is
+ * implemented using g_file_query_info() and as such does blocking I/O.
*
- * 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 primary use case of this method is to check if a file is
+ * a regular file, directory, or symlink.
*
- * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
+ * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN
+ * if the file does not exist
+ * Since: 2.18
*/
/**
- * g_file_eject_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * 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
*
- * Finishes an asynchronous eject operation started by
- * g_file_eject_mountable().
+ * 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.
*
- * otherwise.
+ * 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.
*
- * Returns: %TRUE if the @file was ejected successfully. %FALSE
- * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead.
+ * 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().
*/
/**
- * g_file_eject_mountable_with_operation:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
+ * g_file_query_filesystem_info_async:
+ * @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
*
- * Starts an asynchronous eject on a mountable.
- * When this operation has completed, @callback will be called with
- * @user_user data, and the operation can be finalized with
- * g_file_eject_mountable_with_operation_finish().
+ * Asynchronously gets the requested information about the filesystem
+ * that the specified @file is on. The result is a #GFileInfo object
+ * that contains key-value attributes (such as type or size for 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.
+ * For more details, see g_file_query_filesystem_info() which is the
+ * synchronous version of this call.
*
- * Since: 2.22
+ * 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_eject_mountable_with_operation_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes an asynchronous eject operation started by
- * g_file_eject_mountable_with_operation().
+ * g_file_query_filesystem_info_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
- * otherwise.
+ * Finishes an asynchronous filesystem info query.
+ * See g_file_query_filesystem_info_async().
*
- * Returns: %TRUE if the @file was ejected successfully. %FALSE
- * Since: 2.22
+ * Returns: (transfer full): #GFileInfo for given @file
+ * or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * 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.
+ * 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
*
- * 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.
*
- * 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.
+ * 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.
*
- * Free the returned object with g_object_unref().
+ * 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 #GFileEnumerator if successful, %NULL on error.
+ * Returns: (transfer full): a #GFileInfo for the given @file, or %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
+ * g_file_query_info_async:
+ * @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 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_enumerate_children() 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_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_query_info_finish() to get the result of the operation.
*/
/**
- * g_file_enumerate_children_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError.
+ * g_file_query_info_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
*
- * Finishes an async enumerate children operation.
- * See g_file_enumerate_children_async().
+ * 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().
+ */
+
+
+/**
+ * g_file_query_settable_attributes:
+ * @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.
*
- * Free the returned object with g_object_unref().
+ * 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 #GFileEnumerator or %NULL if an error occurred.
+ * Returns: a #GFileAttributeInfoList describing the settable attributes.
+ * When you are done with it, release it with
+ * g_file_attribute_info_list_unref()
*/
/**
- * g_file_enumerator_close:
- * @enumerator: a #GFileEnumerator.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: location to store the error occurring, or %NULL to ignore
+ * g_file_query_writable_namespaces:
+ * @file: input #GFile
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * Releases all resources used by this enumerator, making the
- * enumerator return %G_IO_ERROR_CLOSED on all calls.
+ * Obtain the list of attribute namespaces where new attributes
+ * can be created by a user. An example of this is extended
+ * attributes (in the "xattr" namespace).
*
- * This will be automatically called when the last reference
- * is dropped, but you might want to call this function to make
- * sure resources are released as early as possible.
+ * 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 on success or #FALSE on error.
+ * Returns: a #GFileAttributeInfoList describing the writable namespaces.
+ * When you are done with it, release it with
+ * g_file_attribute_info_list_unref()
*/
/**
- * g_file_enumerator_close_async:
- * @enumerator: a #GFileEnumerator.
- * @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
- * @user_data: (closure): the data to pass to callback function
+ * g_file_read: (virtual read_fn)
+ * @file: #GFile to read
+ * @cancellable: (allow-none): a #GCancellable
+ * @error: a #GError, or %NULL
*
- * Asynchronously closes the file enumerator.
+ * Opens a file for reading. The result is a #GFileInputStream that
+ * can be used to read 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 in
- * g_file_enumerator_close_finish().
+ * 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.
+ *
+ * Returns: (transfer full): #GFileInputStream or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_enumerator_close_finish:
- * @enumerator: a #GFileEnumerator.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_file_read_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: (scope async): a #GAsyncReadyCallback to call
+ * when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
+ * Asynchronously opens @file for reading.
*
- * If the file enumerator was already closed when g_file_enumerator_close_async()
- * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
- * return %FALSE. If the file enumerator had pending operation when the close
- * operation was started, then this function will report %G_IO_ERROR_PENDING, and
- * return %FALSE. If @cancellable was not %NULL, then the operation may have been
- * cancelled by triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
- * returned.
+ * For more details, see g_file_read() which is
+ * the synchronous version of this call.
*
- * Returns: %TRUE if the close operation has finished successfully.
+ * 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_enumerator_get_container:
- * @enumerator: a #GFileEnumerator
+ * g_file_read_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Get the #GFile container which is being enumerated.
+ * Finishes an asynchronous file read operation started with
+ * g_file_read_async().
*
- * Returns: (transfer none): the #GFile which is being enumerated.
- * Since: 2.18
+ * Returns: (transfer full): a #GFileInputStream or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_enumerator_has_pending:
- * @enumerator: a #GFileEnumerator.
+ * g_file_replace:
+ * @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
*
- * Checks if the file enumerator has pending operations.
+ * Returns an output stream for overwriting the file, possibly
+ * creating a backup copy of the file first. If the file doesn't exist,
+ * it will be created.
*
- * Returns: %TRUE if the @enumerator has pending operations.
+ * This will try to replace the file in the safest way possible so
+ * that any errors during the writing will not affect an already
+ * existing copy of the file. For instance, for local files it
+ * may write to a temporary file and then atomically rename over
+ * the destination when the stream is closed.
+ *
+ * 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 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.
+ *
+ * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_enumerator_is_closed:
- * @enumerator: a #GFileEnumerator.
+ * g_file_replace_async:
+ * @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
*
- * Checks if the file enumerator has been closed.
+ * Asynchronously overwrites the file, replacing the contents,
+ * possibly creating a backup copy of the file first.
*
- * Returns: %TRUE if the @enumerator is closed.
+ * 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.
*/
/**
- * g_file_enumerator_next_file:
- * @enumerator: a #GFileEnumerator.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: location to store the error occurring, or %NULL to ignore
+ * 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 [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
*
- * Returns information for the next file in the enumerated object.
- * Will block until the information is available. The #GFileInfo
- * returned from this function will contain attributes that match the
- * attribute string that was passed when the #GFileEnumerator was created.
+ * Replaces the contents of @file with @contents of @length bytes.
*
- * 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.
+ * 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 @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.
*
- * Free the returned object with g_object_unref() when no longer needed.
+ * The returned @new_etag can be used to verify that the file hasn't
+ * changed the next time it is saved over.
*
- * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
+ * Returns: %TRUE if successful. If an error has occurred, this function
+ * will return %FALSE and set @error appropriately if present.
*/
/**
- * 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.
- * @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_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 [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
*
- * Request information for a number of files from the enumerator asynchronously.
- * When all i/o for the operation is finished the @callback will be called with
- * the requested information.
+ * Starts an asynchronous replacement of @file with the given
+ * @contents of @length bytes. @etag will replace the document's
+ * current entity tag.
*
- * 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
- * error will be reported. If a request is cancelled the callback will be called
- * with %G_IO_ERROR_CANCELLED.
+ * 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().
*
- * During an async request no other sync and async calls are allowed, and will
- * result in %G_IO_ERROR_PENDING 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.
*
- * 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.
+ * 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_enumerator_next_files_finish:
- * @enumerator: a #GFileEnumerator.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * 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 the asynchronous operation started with g_file_enumerator_next_files_async().
+ * 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.
*
- * g_list_free() and unref the infos with g_object_unref() when you're
- * done with them.
+ * 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().
*
- * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
+ * Since: 2.40
*/
/**
- * g_file_enumerator_set_pending:
- * @enumerator: a #GFileEnumerator.
- * @pending: a boolean value.
+ * 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
*
- * Sets the file enumerator as having pending operations.
+ * 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_equal:
- * @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
- * file on the filesystem due to various forms of filename
- * aliasing.
- *
- * This call does no blocking i/o.
+ * g_file_replace_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * %FALSE if either is not a #GFile.
+ * Finishes an asynchronous file replace operation started with
+ * g_file_replace_async().
*
- * Returns: %TRUE if @file1 and @file2 are equal.
+ * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_find_enclosing_mount:
- * @file: input #GFile.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
- *
- * Gets a #GMount for the #GFile.
+ * g_file_replace_readwrite:
+ * @file: a #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: return location for a #GError, or %NULL
*
- * 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.
+ * 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.
*
- * 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 details about the behaviour, see g_file_replace() which does the
+ * same thing but returns an output stream only.
*
- * Free the returned object with g_object_unref().
+ * 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 #GMount where the @file is located or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream or %NULL on error.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
*/
/**
- * 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
+ * g_file_replace_readwrite_async:
+ * @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 gets the mount for the file.
+ * 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_find_enclosing_mount() which is
+ * 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_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_replace_readwrite_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.22
*/
/**
- * g_file_find_enclosing_mount_finish:
- * @file: a #GFile
+ * g_file_replace_readwrite_finish:
+ * @file: input #GFile
* @res: a #GAsyncResult
- * @error: a #GError
- *
- * Finishes an asynchronous find mount request.
- * See g_file_find_enclosing_mount_async().
+ * @error: a #GError, or %NULL
*
- * Free the returned object with g_object_unref().
+ * Finishes an asynchronous file replace operation started with
+ * g_file_replace_readwrite_async().
*
- * Returns: (transfer full): #GMount for given @file or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
*/
/**
- * g_file_get_basename:
- * @file: input #GFile.
+ * g_file_resolve_relative_path:
+ * @file: input #GFile
+ * @relative_path: a given relative path string
*
- * Gets the base name (the last component of the path) for a given #GFile.
+ * Resolves a relative path for @file to an absolute path.
*
- * If called for the top level of a system (such as the filesystem root
- * or a uri like sftp://host/) it will return a single directory separator
- * (and on Windows, possibly a drive letter).
+ * This call does no blocking I/O.
*
- * 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().
+ * 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
+ * @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
+ * @error: a #GError, or %NULL
+ *
+ * Sets an attribute in the file with attribute name @attribute to @value.
*
- * This call does no blocking i/o.
+ * Some attributes can be unset by setting @attribute to
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
*
- * if given #GFile is invalid. The returned string should be
- * freed with g_free() when no longer needed.
+ * 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: string containing the #GFile's base name, or %NULL
+ * Returns: %TRUE if the attribute was set, %FALSE otherwise.
*/
/**
- * g_file_get_child:
- * @file: input #GFile.
- * @name: string containing the child's basename.
+ * 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
+ * @error: a #GError, or %NULL
*
- * Gets a child of @file with basename equal to @name.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
+ * If @attribute is of a different type, this operation will fail,
+ * returning %FALSE.
*
- * Note that the file with that specific name might not exist, but
- * you can still have a #GFile that points to it. You can use this
- * for instance to create that 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.
*
- * This call does no blocking i/o.
+ * 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
+ * @error: a #GError, or %NULL
*
- * Free the returned object with g_object_unref().
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
+ * If @attribute is of a different type, this operation will fail.
*
- * Returns: (transfer full): a #GFile to a child specified by @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.
+ *
+ * Returns: %TRUE if the @attribute was successfully set to @value
+ * in the @file, %FALSE otherwise.
*/
/**
- * g_file_get_child_for_display_name:
- * @file: input #GFile.
- * @display_name: string to a possible child.
- * @error: #GError.
- *
- * 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.
+ * 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
+ * @error: a #GError, or %NULL
*
- * This call does no blocking i/o.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
+ * If @attribute is of a different type, this operation will fail.
*
- * %NULL if the display name couldn't be converted.
- * Free the returned object with g_object_unref().
+ * 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 #GFile to the specified child, or
+ * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
*/
/**
- * g_file_get_parent:
- * @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.
+ * 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
+ * @error: a #GError, or %NULL
*
- * This call does no blocking i/o.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
+ * If @attribute is of a different type, this operation will fail.
*
- * #GFile or %NULL if there is no parent.
- * Free the returned object with g_object_unref().
+ * 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 #GFile structure to the parent of the given
+ * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
*/
/**
- * g_file_get_parse_name:
- * @file: input #GFile.
- *
- * Gets the parse name of the @file.
- * A parse name is a UTF-8 string that describes the
- * file such that one can get the #GFile back using
- * g_file_parse_name().
- *
- * This is generally used to show the #GFile as a nice
- * full-pathname kind of string in a user interface,
- * 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).
+ * 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
+ * @error: a #GError, or %NULL
*
- * This call does no blocking i/o.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
+ * If @attribute is of a different type, this operation will fail.
*
- * string should be freed with g_free() when no longer needed.
+ * 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 string containing the #GFile's parse name. The returned
+ * Returns: %TRUE if the @attribute was successfully set to @value
+ * in the @file, %FALSE otherwise.
*/
/**
- * g_file_get_path:
- * @file: input #GFile.
- *
- * Gets the local pathname for #GFile, if one exists.
+ * 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
+ * @error: a #GError, or %NULL
*
- * This call does no blocking i/o.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
+ * If @attribute is of a different type, this operation will fail.
*
- * no such path exists. The returned string should be
- * freed with g_free() when no longer needed.
+ * 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: string containing the #GFile's path, or %NULL if
+ * Returns: %TRUE if the @attribute was successfully set to @value
+ * in the @file, %FALSE otherwise.
*/
/**
- * g_file_get_relative_path:
- * @parent: input #GFile.
- * @descendant: input #GFile.
- *
- * Gets the path for @descendant relative to @parent.
+ * g_file_set_attributes_async:
+ * @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
*
- * This call does no blocking i/o.
+ * Asynchronously sets the attributes of @file with @info.
*
- * 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.
+ * For more details, see g_file_set_attributes_from_info(),
+ * which is the synchronous version of this call.
*
- * Returns: string with the relative path from @descendant
+ * 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_get_uri:
- * @file: input #GFile.
- *
- * Gets the URI for the @file.
- *
- * This call does no blocking i/o.
+ * g_file_set_attributes_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @info: (out) (transfer full): a #GFileInfo
+ * @error: a #GError, or %NULL
*
- * The returned string should be freed with g_free() when no longer needed.
+ * Finishes setting an attribute started in g_file_set_attributes_async().
*
- * Returns: a string containing the #GFile's URI.
+ * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
*/
/**
- * g_file_get_uri_scheme:
- * @file: input #GFile.
+ * g_file_set_attributes_from_info:
+ * @file: input #GFile
+ * @info: a #GFileInfo
+ * @flags: #GFileQueryInfoFlags
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * 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.
+ * Tries to set all attributes in the #GFileInfo on the target
+ * values, not stopping on the first error.
*
- * This call does no blocking i/o.
+ * 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.
*
- * #GFile. The returned string should be freed with g_free()
- * when no longer needed.
+ * 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 string containing the URI scheme for the given
+ * Returns: %FALSE if there was any error, %TRUE otherwise.
*/
/**
- * g_file_has_parent:
+ * g_file_set_display_name:
* @file: input #GFile
- * @parent: the parent to check for, or %NULL
+ * @display_name: a string
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @error: a #GError, or %NULL
*
- * Checks if @file has a parent, and optionally, if it is @parent.
+ * Renames @file to the specified display name.
*
- * If @parent is %NULL then this function returns %TRUE if @file has any
- * parent at all. If @parent is non-%NULL then %TRUE is only returned
- * if @file is a child of @parent.
+ * 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.
*
- * case that @parent is %NULL).
+ * 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().
*
- * Returns: %TRUE if @file is a child of @parent (or any parent in the
- * Since: 2.24
+ * On success the resulting converted filename is 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 #GFile specifying what @file was renamed to,
+ * or %NULL if there was an error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_has_prefix:
- * @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.
+ * g_file_set_display_name_async:
+ * @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
*
- * 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.
+ * Asynchronously sets the display name for a given #GFile.
*
- * %FALSE otherwise.
+ * For more details, see g_file_set_display_name() which is
+ * the synchronous version of this call.
*
- * Virtual: prefix_matches
- * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix.
+ * 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_has_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.
+ * g_file_set_display_name_finish:
+ * @file: input #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * given URI scheme, %FALSE if URI scheme is %NULL,
- * not supported, or #GFile is invalid.
+ * Finishes setting a display name started with
+ * g_file_set_display_name_async().
*
- * Returns: %TRUE if #GFile's backend supports the
+ * Returns: (transfer full): a #GFile or %NULL on error.
+ * Free the returned object with g_object_unref().
*/
/**
- * g_file_hash:
- * @file: (type GFile): #gconstpointer to a #GFile.
+ * g_file_start_mountable:
+ * @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
+ * @user_data: the data to pass to callback function
*
- * Creates a hash value for a #GFile.
+ * Starts a file of type #G_FILE_TYPE_MOUNTABLE.
+ * Using @start_operation, you can request callbacks when, for instance,
+ * passwords are needed during authentication.
*
- * This call does no blocking i/o.
+ * 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.
*
- * 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.
+ * 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.
*
- * Virtual: hash
- * Returns: 0 if @file is not a valid #GFile, otherwise an
+ * Since: 2.22
*/
/**
- * g_file_icon_get_file:
- * @icon: a #GIcon.
+ * g_file_start_mountable_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Gets the #GFile associated with the given @icon.
+ * Finishes a start operation. See g_file_start_mountable() for details.
*
- * Returns: (transfer none): a #GFile, or %NULL.
+ * Finish an asynchronous start operation that was started
+ * with g_file_start_mountable().
+ *
+ * Returns: %TRUE if the operation finished successfully. %FALSE
+ * otherwise.
+ * Since: 2.22
*/
/**
- * g_file_icon_new:
- * @file: a #GFile.
+ * g_file_stop_mountable:
+ * @file: input #GFile
+ * @flags: flags affecting the operation
+ * @mount_operation: (allow-none): a #GMountOperation,
+ * or %NULL to avoid user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: the data to pass to callback function
*
- * Creates a new icon for a file.
+ * Stops a file of type #G_FILE_TYPE_MOUNTABLE.
*
- * Returns: (transfer full): a #GIcon for the given @file, or %NULL on error.
- */
-
-
-/**
- * g_file_info_clear_status:
- * @info: a #GFileInfo.
+ * 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.
*
- * Clears the status information from @info.
- */
-
-
-/**
- * g_file_info_copy_into:
- * @src_info: source to copy attributes from.
- * @dest_info: destination to copy attributes to.
+ * 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.
*
- * Copies all of the #GFileAttribute<!-- -->s from @src_info to @dest_info.
+ * Since: 2.22
*/
/**
- * g_file_info_dup:
- * @other: a #GFileInfo.
+ * g_file_stop_mountable_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Duplicates a file info structure.
+ * Finishes an stop operation, see g_file_stop_mountable() for details.
*
- * Returns: (transfer full): a duplicate #GFileInfo of @other.
+ * Finish an asynchronous stop operation that was started
+ * with g_file_stop_mountable().
+ *
+ * Returns: %TRUE if the operation finished successfully.
+ * %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_file_info_get_attribute_as_string:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- *
- * Gets the value of a attribute, formated as a string.
- * This escapes things as needed to make the string valid
- * utf8.
+ * g_file_supports_thread_contexts:
+ * @file: a #GFile
*
- * When you're done with the string it must be freed with g_free().
+ * 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: a UTF-8 string associated with the given @attribute.
+ * Returns: Whether or not @file supports thread-default contexts.
+ * Since: 2.22
*/
/**
- * g_file_info_get_attribute_boolean:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * 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
*
- * Gets the value of a boolean attribute. If the attribute does not
- * contain a boolean value, %FALSE will be returned.
+ * Sends @file to the "Trashcan", if possible. This is similar to
+ * deleting it, but the user can recover it before emptying the trashcan.
+ * Not all file systems support trashing, so this call can return the
+ * %G_IO_ERROR_NOT_SUPPORTED error.
*
- * Returns: the boolean value contained within the 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: %TRUE on successful trash, %FALSE otherwise.
*/
/**
- * g_file_info_get_attribute_byte_string:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- *
- * Gets the value of a byte string attribute. If the attribute does
- * not contain a byte string, %NULL 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
*
- * %NULL otherwise.
+ * Asynchronously sends @file to the Trash location, if possible.
*
- * Returns: the contents of the @attribute value as a byte string, or
+ * Since: 2.38
*/
/**
- * g_file_info_get_attribute_data:
- * @info: a #GFileInfo
- * @attribute: a file attribute key
- * @type: (out) (allow-none): return location for the attribute type, or %NULL
- * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
- * @status: (out) (allow-none): return location for the attribute status, or %NULL
- *
- * Gets the attribute type, value and status for an attribute key.
+ * g_file_trash_finish: (virtual trash_finish)
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * %FALSE otherwise.
+ * Finishes an asynchronous file trashing operation, started with
+ * g_file_trash_async().
*
- * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
+ * Returns: %TRUE on successful trash, %FALSE otherwise.
+ * Since: 2.38
*/
/**
- * g_file_info_get_attribute_int32:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_file_unmount_mountable:
+ * @file: input #GFile
+ * @flags: flags affecting the operation
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: (closure): the data to pass to callback function
*
- * Gets a signed 32-bit integer contained within the attribute. If the
- * attribute does not contain a signed 32-bit integer, or is invalid,
- * 0 will be returned.
+ * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
*
- * Returns: a signed 32-bit integer from the 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.
+ *
+ * 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_info_get_attribute_int64:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_file_unmount_mountable_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Gets a signed 64-bit integer contained within the attribute. If the
- * attribute does not contain an signed 64-bit integer, or is invalid,
- * 0 will be returned.
+ * Finishes an unmount operation, see g_file_unmount_mountable() for details.
*
- * Returns: a signed 64-bit integer from the attribute.
+ * 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.
*/
/**
- * g_file_info_get_attribute_object:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_file_unmount_mountable_with_operation:
+ * @file: input #GFile
+ * @flags: flags affecting the operation
+ * @mount_operation: (allow-none): a #GMountOperation,
+ * or %NULL to avoid user interaction
+ * @cancellable: (allow-none): optional #GCancellable object,
+ * %NULL to ignore
+ * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call
+ * when the request is satisfied, or %NULL
+ * @user_data: (closure): the data to pass to callback function
*
- * Gets the value of a #GObject attribute. If the attribute does
- * not contain a #GObject, %NULL will be returned.
+ * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE.
*
- * %NULL otherwise.
+ * 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 none): a #GObject associated with the given @attribute, or
+ * 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_info_get_attribute_status:
- * @info: a #GFileInfo
- * @attribute: a file attribute key
+ * g_file_unmount_mountable_with_operation_finish:
+ * @file: input #GFile
+ * @result: a #GAsyncResult
+ * @error: a #GError, or %NULL
*
- * Gets the attribute status for an attribute key.
+ * Finishes an unmount operation,
+ * see g_file_unmount_mountable_with_operation() for details.
*
- * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
+ * Finish an asynchronous unmount operation that was started
+ * with g_file_unmount_mountable_with_operation().
*
- * Returns: a #GFileAttributeStatus for the given @attribute, or
+ * Returns: %TRUE if the operation finished successfully.
+ * %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_file_info_get_attribute_string:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- *
- * Gets the value of a string attribute. If the attribute does
- * not contain a string, %NULL will be returned.
+ * g_filename_completer_get_completion_suffix:
+ * @completer: the filename completer.
+ * @initial_text: text to be completed.
*
- * %NULL otherwise.
+ * Obtains a completion for @initial_text from @completer.
*
- * Returns: the contents of the @attribute value as a UTF-8 string, or
+ * 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.
*/
/**
- * g_file_info_get_attribute_stringv:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- *
- * Gets the value of a stringv attribute. If the attribute does
- * not contain a stringv, %NULL will be returned.
+ * g_filename_completer_get_completions:
+ * @completer: the filename completer.
+ * @initial_text: text to be completed.
*
- * %NULL otherwise. Do not free. These returned strings are UTF-8.
+ * Gets an array of completion strings for a given initial text.
*
- * Returns: (transfer none): the contents of the @attribute value as a stringv, or
- * Since: 2.22
+ * 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_file_info_get_attribute_type:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_filename_completer_new:
*
- * Gets the attribute type for an attribute key.
+ * Creates a new filename completer.
*
- * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
+ * Returns: a #GFilenameCompleter.
+ */
+
+
+/**
+ * g_filename_completer_set_dirs_only:
+ * @completer: the filename completer.
+ * @dirs_only: a #gboolean.
*
- * Returns: a #GFileAttributeType for the given @attribute, or
+ * If @dirs_only is %TRUE, @completer will only
+ * complete directory names, and not file names.
*/
/**
- * g_file_info_get_attribute_uint32:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_filter_input_stream_get_base_stream:
+ * @stream: a #GFilterInputStream.
*
- * Gets an unsigned 32-bit integer contained within the attribute. If the
- * attribute does not contain an unsigned 32-bit integer, or is invalid,
- * 0 will be returned.
+ * Gets the base stream for the filter stream.
*
- * Returns: an unsigned 32-bit integer from the attribute.
+ * Returns: (transfer none): a #GInputStream.
*/
/**
- * g_file_info_get_attribute_uint64:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_filter_input_stream_get_close_base_stream:
+ * @stream: a #GFilterInputStream.
*
- * Gets a unsigned 64-bit integer contained within the attribute. If the
- * attribute does not contain an unsigned 64-bit integer, or is invalid,
- * 0 will be returned.
+ * Returns whether the base stream will be closed when @stream is
+ * closed.
*
- * Returns: a unsigned 64-bit integer from the attribute.
+ * Returns: %TRUE if the base stream will be closed.
*/
/**
- * g_file_info_get_content_type:
- * @info: a #GFileInfo.
- *
- * Gets the file's content type.
+ * g_filter_input_stream_set_close_base_stream:
+ * @stream: a #GFilterInputStream.
+ * @close_base: %TRUE to close the base stream.
*
- * Returns: a string containing the file's content type.
+ * Sets whether the base stream will be closed when @stream is closed.
*/
/**
- * g_file_info_get_display_name:
- * @info: a #GFileInfo.
+ * g_filter_output_stream_get_base_stream:
+ * @stream: a #GFilterOutputStream.
*
- * Gets a display name for a file.
+ * Gets the base stream for the filter stream.
*
- * Returns: a string containing the display name.
+ * Returns: (transfer none): a #GOutputStream.
*/
/**
- * g_file_info_get_edit_name:
- * @info: a #GFileInfo.
+ * g_filter_output_stream_get_close_base_stream:
+ * @stream: a #GFilterOutputStream.
*
- * Gets the edit name for a file.
+ * Returns whether the base stream will be closed when @stream is
+ * closed.
*
- * Returns: a string containing the edit name.
+ * Returns: %TRUE if the base stream will be closed.
*/
/**
- * g_file_info_get_etag:
- * @info: a #GFileInfo.
- *
- * Gets the <link linkend="gfile-etag">entity tag</link> for a given
- * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
+ * g_filter_output_stream_set_close_base_stream:
+ * @stream: a #GFilterOutputStream.
+ * @close_base: %TRUE to close the base stream.
*
- * Returns: a string containing the value of the "etag:value" attribute.
+ * Sets whether the base stream will be closed when @stream is closed.
*/
/**
- * g_file_info_get_file_type:
- * @info: a #GFileInfo.
+ * g_icon_deserialize:
+ * @value: a #GVariant created with g_icon_serialize()
*
- * Gets a file's type (whether it is a regular file, symlink, etc).
- * This is different from the file's content type, see g_file_info_get_content_type().
+ * Deserializes a #GIcon previously serialized using g_icon_serialize().
*
- * Returns: a #GFileType for the given file.
+ * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails.
+ * Since: 2.38
*/
/**
- * g_file_info_get_icon:
- * @info: a #GFileInfo.
+ * g_icon_equal:
+ * @icon1: (allow-none): pointer to the first #GIcon.
+ * @icon2: (allow-none): pointer to the second #GIcon.
*
- * Gets the icon for a file.
+ * Checks if two icons are equal.
*
- * Returns: (transfer none): #GIcon for the given @info.
+ * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
*/
/**
- * g_file_info_get_is_backup:
- * @info: a #GFileInfo.
+ * g_icon_hash: (virtual hash)
+ * @icon: #gconstpointer to an icon object.
*
- * Checks if a file is a backup file.
+ * Gets a hash for an icon.
*
- * Returns: %TRUE if file is a backup file, %FALSE otherwise.
+ * Returns: a #guint containing a hash for the @icon, suitable for
+ * use in a #GHashTable or similar data structure.
*/
/**
- * g_file_info_get_is_hidden:
- * @info: a #GFileInfo.
+ * g_icon_new_for_string:
+ * @str: A string obtained via g_icon_to_string().
+ * @error: Return location for error.
*
- * Checks if a file is hidden.
+ * Generate a #GIcon instance from @str. This function can fail if
+ * @str is not valid - see g_icon_to_string() for discussion.
*
- * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
+ * 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().
+ *
+ * Returns: (transfer full): An object implementing the #GIcon
+ * interface or %NULL if @error is set.
+ * Since: 2.20
*/
/**
- * g_file_info_get_is_symlink:
- * @info: a #GFileInfo.
+ * g_icon_serialize:
+ * @icon: a #GIcon
*
- * Checks if a file is a symlink.
+ * 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: %TRUE if the given @info is a symlink.
+ * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
+ * Since: 2.38
*/
/**
- * g_file_info_get_modification_time:
- * @info: a #GFileInfo.
- * @result: (out caller-allocates): a #GTimeVal.
+ * g_icon_to_string: (virtual to_tokens)
+ * @icon: a #GIcon.
*
- * Gets the modification time of the current @info and sets it
- * in @result.
+ * Generates a textual representation of @icon that can be used for
+ * serialization such as when passing @icon to a different process or
+ * saving it to persistent storage. Use g_icon_new_for_string() to
+ * get @icon back from the returned string.
+ *
+ * The encoding of the returned string is proprietary to #GIcon except
+ * in the following two cases
+ *
+ * - 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
*/
/**
- * g_file_info_get_name:
- * @info: a #GFileInfo.
+ * g_inet_address_equal:
+ * @address: A #GInetAddress.
+ * @other_address: Another #GInetAddress.
*
- * Gets the name for a file.
+ * Checks if two #GInetAddress instances are equal, e.g. the same address.
*
- * Returns: a string containing the file name.
+ * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
+ * Since: 2.30
*/
/**
- * g_file_info_get_size:
- * @info: a #GFileInfo.
+ * g_inet_address_get_family:
+ * @address: a #GInetAddress
*
- * Gets the file's size.
+ * Gets @address's family
*
- * Returns: a #goffset containing the file's size.
+ * Returns: @address's family
+ * Since: 2.22
*/
/**
- * g_file_info_get_sort_order:
- * @info: a #GFileInfo.
+ * g_inet_address_get_is_any:
+ * @address: a #GInetAddress
*
- * Gets the value of the sort_order attribute from the #GFileInfo.
- * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+ * Tests whether @address is the "any" address for its family.
*
- * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
+ * Returns: %TRUE if @address is the "any" address for its family.
+ * Since: 2.22
*/
/**
- * g_file_info_get_symlink_target:
- * @info: a #GFileInfo.
+ * g_inet_address_get_is_link_local:
+ * @address: a #GInetAddress
*
- * Gets the symlink target for a given #GFileInfo.
+ * Tests whether @address is a link-local address (that is, if it
+ * identifies a host on a local network that is not connected to the
+ * Internet).
*
- * Returns: a string containing the symlink target.
+ * Returns: %TRUE if @address is a link-local address.
+ * Since: 2.22
*/
/**
- * g_file_info_has_attribute:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- *
- * Checks if a file info structure has an attribute named @attribute.
+ * g_inet_address_get_is_loopback:
+ * @address: a #GInetAddress
*
- * %FALSE otherwise.
+ * Tests whether @address is the loopback address for its family.
*
- * Returns: %TRUE if @Ginfo has an attribute named @attribute,
+ * Returns: %TRUE if @address is the loopback address for its family.
+ * Since: 2.22
*/
/**
- * g_file_info_has_namespace:
- * @info: a #GFileInfo.
- * @name_space: a file attribute namespace.
- *
- * Checks if a file info structure has an attribute in the
- * specified @name_space.
+ * g_inet_address_get_is_mc_global:
+ * @address: a #GInetAddress
*
- * %FALSE otherwise.
+ * Tests whether @address is a global multicast address.
*
- * Returns: %TRUE if @Ginfo has an attribute in @name_space,
+ * Returns: %TRUE if @address is a global multicast address.
* Since: 2.22
*/
/**
- * g_file_info_list_attributes:
- * @info: a #GFileInfo.
- * @name_space: a file attribute key's namespace.
- *
- * Lists the file info structure's attributes.
+ * g_inet_address_get_is_mc_link_local:
+ * @address: a #GInetAddress
*
- * possible attribute types for the given @name_space, or
- * %NULL on error.
+ * Tests whether @address is a link-local multicast address.
*
- * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
+ * Returns: %TRUE if @address is a link-local multicast address.
+ * Since: 2.22
*/
/**
- * g_file_info_new:
+ * g_inet_address_get_is_mc_node_local:
+ * @address: a #GInetAddress
*
- * Creates a new file info structure.
+ * Tests whether @address is a node-local multicast address.
*
- * Returns: a #GFileInfo.
+ * Returns: %TRUE if @address is a node-local multicast address.
+ * Since: 2.22
*/
/**
- * g_file_info_remove_attribute:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
+ * g_inet_address_get_is_mc_org_local:
+ * @address: a #GInetAddress
*
- * Removes all cases of @attribute from @info if it exists.
+ * Tests whether @address is an organization-local multicast address.
+ *
+ * Returns: %TRUE if @address is an organization-local multicast address.
+ * Since: 2.22
*/
/**
- * g_file_info_set_attribute:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @type: a #GFileAttributeType
- * @value_p: pointer to the value
+ * g_inet_address_get_is_mc_site_local:
+ * @address: a #GInetAddress
+ *
+ * Tests whether @address is a site-local multicast address.
*
- * Sets the @attribute to contain the given value, if possible.
+ * Returns: %TRUE if @address is a site-local multicast address.
+ * Since: 2.22
*/
/**
- * g_file_info_set_attribute_boolean:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: a boolean value.
+ * g_inet_address_get_is_multicast:
+ * @address: a #GInetAddress
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Tests whether @address is a multicast address.
+ *
+ * Returns: %TRUE if @address is a multicast address.
+ * Since: 2.22
*/
/**
- * g_file_info_set_attribute_byte_string:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: a byte string.
+ * g_inet_address_get_is_site_local:
+ * @address: a #GInetAddress
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Tests whether @address is a site-local address such as 10.0.0.1
+ * (that is, the address identifies a host on a local network that can
+ * not be reached directly from the Internet, but which may have
+ * outgoing Internet connectivity via a NAT or firewall).
+ *
+ * Returns: %TRUE if @address is a site-local address.
+ * Since: 2.22
*/
/**
- * g_file_info_set_attribute_int32:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: a signed 32-bit integer
+ * g_inet_address_get_native_size:
+ * @address: a #GInetAddress
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Gets the size of the native raw binary address for @address. This
+ * is the size of the data that you get from g_inet_address_to_bytes().
+ *
+ * Returns: the number of bytes used for the native version of @address.
+ * Since: 2.22
*/
/**
- * g_file_info_set_attribute_int64:
- * @info: a #GFileInfo.
- * @attribute: attribute name to set.
- * @attr_value: int64 value to set attribute to.
+ * g_inet_address_mask_equal:
+ * @mask: a #GInetAddressMask
+ * @mask2: another #GInetAddressMask
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Tests if @mask and @mask2 are the same mask.
+ *
+ * Returns: whether @mask and @mask2 are the same mask
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_mask:
- * @info: a #GFileInfo.
- * @mask: a #GFileAttributeMatcher.
+ * g_inet_address_mask_get_address:
+ * @mask: a #GInetAddressMask
*
- * Sets @mask on @info to match specific attribute types.
+ * Gets @mask's base address
+ *
+ * Returns: (transfer none): @mask's base address
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_object:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: a #GObject.
+ * g_inet_address_mask_get_family:
+ * @mask: a #GInetAddressMask
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Gets the #GSocketFamily of @mask's address
+ *
+ * Returns: the #GSocketFamily of @mask's address
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_status:
- * @info: a #GFileInfo
- * @attribute: a file attribute key
- * @status: a #GFileAttributeStatus
- *
- * Sets the attribute status for an attribute key. This is only
- * needed by external code that implement g_file_set_attributes_from_info()
- * or similar functions.
+ * g_inet_address_mask_get_length:
+ * @mask: a #GInetAddressMask
*
- * The attribute must exist in @info for this to work. Otherwise %FALSE
- * is returned and @info is unchanged.
+ * Gets @mask's length
*
- * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
- * Since: 2.22
+ * Returns: @mask's length
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_string:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: a UTF-8 string.
+ * g_inet_address_mask_matches:
+ * @mask: a #GInetAddressMask
+ * @address: a #GInetAddress
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Tests if @address falls within the range described by @mask.
+ *
+ * Returns: whether @address falls within the range described by
+ * @mask.
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_stringv:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key
- * @attr_value: a %NULL terminated array of UTF-8 strings.
+ * g_inet_address_mask_new:
+ * @addr: a #GInetAddress
+ * @length: number of bits of @addr to use
+ * @error: return location for #GError, or %NULL
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Creates a new #GInetAddressMask representing all addresses whose
+ * first @length bits match @addr.
*
- * Sinze: 2.22
+ * Returns: a new #GInetAddressMask, or %NULL on error
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_uint32:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: an unsigned 32-bit integer.
+ * g_inet_address_mask_new_from_string:
+ * @mask_string: an IP address or address/length string
+ * @error: return location for #GError, or %NULL
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Parses @mask_string as an IP address and (optional) length, and
+ * creates a new #GInetAddressMask. The length, if present, is
+ * 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.
+ * Since: 2.32
*/
/**
- * g_file_info_set_attribute_uint64:
- * @info: a #GFileInfo.
- * @attribute: a file attribute key.
- * @attr_value: an unsigned 64-bit integer.
+ * g_inet_address_mask_to_string:
+ * @mask: a #GInetAddressMask
*
- * Sets the @attribute to contain the given @attr_value,
- * if possible.
+ * Converts @mask back to its corresponding string form.
+ *
+ * Returns: a string corresponding to @mask.
+ * Since: 2.32
*/
/**
- * g_file_info_set_content_type:
- * @info: a #GFileInfo.
- * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>.
+ * g_inet_address_new_any:
+ * @family: the address family
*
- * Sets the content type attribute for a given #GFileInfo.
- * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
+ * Creates a #GInetAddress for the "any" address (unassigned/"don't
+ * care") for @family.
+ *
+ * Returns: a new #GInetAddress corresponding to the "any" address
+ * for @family.
+ * Since: 2.22
*/
/**
- * g_file_info_set_display_name:
- * @info: a #GFileInfo.
- * @display_name: a string containing a display name.
+ * g_inet_address_new_from_bytes:
+ * @bytes: (array) (element-type guint8): raw address data
+ * @family: the address family of @bytes
*
- * Sets the display name for the current #GFileInfo.
- * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
+ * Creates a new #GInetAddress from the given @family and @bytes.
+ * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
+ * %G_SOCKET_FAMILY_IPV6.
+ *
+ * Returns: a new #GInetAddress corresponding to @family and @bytes.
+ * Since: 2.22
*/
/**
- * g_file_info_set_edit_name:
- * @info: a #GFileInfo.
- * @edit_name: a string containing an edit name.
+ * g_inet_address_new_from_string:
+ * @string: a string representation of an IP address
+ *
+ * Parses @string as an IP address and creates a new #GInetAddress.
*
- * Sets the edit name for the current file.
- * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
+ * Returns: a new #GInetAddress corresponding to @string, or %NULL if
+ * @string could not be parsed.
+ * Since: 2.22
*/
/**
- * g_file_info_set_file_type:
- * @info: a #GFileInfo.
- * @type: a #GFileType.
+ * g_inet_address_new_loopback:
+ * @family: the address family
*
- * Sets the file type in a #GFileInfo to @type.
- * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
+ * Creates a #GInetAddress for the loopback address for @family.
+ *
+ * Returns: a new #GInetAddress corresponding to the loopback address
+ * for @family.
+ * Since: 2.22
*/
/**
- * g_file_info_set_icon:
- * @info: a #GFileInfo.
- * @icon: a #GIcon.
+ * g_inet_address_to_bytes: (skip)
+ * @address: a #GInetAddress
*
- * Sets the icon for a given #GFileInfo.
- * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
+ * 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().
+ * Since: 2.22
*/
/**
- * g_file_info_set_is_hidden:
- * @info: a #GFileInfo.
- * @is_hidden: a #gboolean.
+ * g_inet_address_to_string:
+ * @address: a #GInetAddress
*
- * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink.
- * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
+ * Converts @address to string form.
+ *
+ * Returns: a representation of @address as a string, which should be
+ * freed after use.
+ * Since: 2.22
*/
/**
- * g_file_info_set_is_symlink:
- * @info: a #GFileInfo.
- * @is_symlink: a #gboolean.
+ * g_inet_socket_address_get_address:
+ * @address: a #GInetSocketAddress
*
- * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
- * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
+ * Gets @address's #GInetAddress.
+ *
+ * Returns: (transfer none): the #GInetAddress for @address, which must be
+ * g_object_ref()'d if it will be stored
+ * Since: 2.22
*/
/**
- * g_file_info_set_modification_time:
- * @info: a #GFileInfo.
- * @mtime: a #GTimeVal.
+ * g_inet_socket_address_get_flowinfo:
+ * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
*
- * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
- * info to the given time value.
+ * Gets the `sin6_flowinfo` field from @address,
+ * which must be an IPv6 address.
+ *
+ * Returns: the flowinfo field
+ * Since: 2.32
*/
/**
- * g_file_info_set_name:
- * @info: a #GFileInfo.
- * @name: a string containing a name.
+ * g_inet_socket_address_get_port:
+ * @address: a #GInetSocketAddress
*
- * Sets the name attribute for the current #GFileInfo.
- * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
+ * Gets @address's port.
+ *
+ * Returns: the port for @address
+ * Since: 2.22
*/
/**
- * g_file_info_set_size:
- * @info: a #GFileInfo.
- * @size: a #goffset containing the file's size.
+ * g_inet_socket_address_get_scope_id:
+ * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
*
- * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
- * to the given size.
+ * Gets the `sin6_scope_id` field from @address,
+ * which must be an IPv6 address.
+ *
+ * Returns: the scope id field
+ * Since: 2.32
*/
/**
- * g_file_info_set_sort_order:
- * @info: a #GFileInfo.
- * @sort_order: a sort order integer.
+ * g_inet_socket_address_new:
+ * @address: a #GInetAddress
+ * @port: a port number
*
- * Sets the sort order attribute in the file info structure. See
- * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+ * Creates a new #GInetSocketAddress for @address and @port.
+ *
+ * Returns: a new #GInetSocketAddress
+ * Since: 2.22
*/
/**
- * g_file_info_set_symlink_target:
- * @info: a #GFileInfo.
- * @symlink_target: a static string containing a path to a symlink target.
+ * g_inet_socket_address_new_from_string:
+ * @address: the string form of an IP address
+ * @port: a port number
*
- * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
- * to the given symlink target.
+ * 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_file_info_unset_attribute_mask:
- * @info: #GFileInfo.
+ * 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.
*
- * Unsets a mask set by g_file_info_set_attribute_mask(), if one
- * is set.
+ * Initializes the object implementing the interface.
+ *
+ * The object must be initialized before any real use after initial
+ * construction, either with this function or g_async_initable_init_async().
+ *
+ * Implementations may also support cancellation. If @cancellable is not %NULL,
+ * then initialization 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 and
+ * the object doesn't support cancellable initialization the error
+ * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+ *
+ * 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 [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.
+ * Only the first call initializes the object, further calls return the result
+ * 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.
+ * Since: 2.22
*/
/**
- * g_file_input_stream_query_info:
- * @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.
- *
- * Queries a file input stream the given @attributes. This function blocks
- * while querying the stream. For the asynchronous (non-blocking) version
- * of this function, see g_file_input_stream_query_info_async(). While the
- * stream is blocked, the stream will set the pending flag internally, and
- * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
+ * 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.
+ *
+ * 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 #GFileInfo, or %NULL on error.
+ * Returns: (type GObject.Object) (transfer full): a newly allocated
+ * #GObject, or %NULL on error
+ * Since: 2.22
*/
/**
- * 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.
- * @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
- *
- * Queries the stream information asynchronously.
- * When the operation is finished @callback will be called.
- * You can then call g_file_input_stream_query_info_finish()
- * to get the result of the operation.
+ * 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.
+ * @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.
*
- * For the synchronous version of this function,
- * see g_file_input_stream_query_info().
+ * 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.
*
- * 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 set
+ * Returns: (type GObject.Object) (transfer full): a newly allocated
+ * #GObject, or %NULL on error
+ * Since: 2.22
*/
/**
- * 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.
+ * g_initable_newv:
+ * @object_type: a #GType supporting #GInitable.
+ * @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.
*
- * Finishes an asynchronous info query operation.
+ * 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): #GFileInfo.
+ * Returns: (type GObject.Object) (transfer full): a newly allocated
+ * #GObject, or %NULL on error
+ * Since: 2.22
*/
/**
- * g_file_io_stream_get_etag:
- * @stream: a #GFileIOStream.
- *
- * Gets the entity tag for the file when it has been written.
- * This must be called after the stream has been written
- * and closed, as the etag can change while writing.
+ * g_input_stream_clear_pending:
+ * @stream: input stream
*
- * Returns: the entity tag for the stream.
- * Since: 2.22
+ * Clears the pending flag on @stream.
*/
/**
- * g_file_io_stream_query_info:
- * @stream: a #GFileIOStream.
- * @attributes: a file attribute query string.
+ * g_input_stream_close:
+ * @stream: A #GInputStream.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Queries a file io stream for the given @attributes.
- * This function blocks while querying the stream. For the asynchronous
- * version of this function, see g_file_io_stream_query_info_async().
- * While the stream is blocked, the stream will set the pending flag
- * internally, and any other operations on the stream will fail with
- * %G_IO_ERROR_PENDING.
+ * Closes the stream, releasing resources related to it.
*
- * Can fail if the stream was already closed (with @error being set to
- * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
- * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
- * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
- * all cases of failure, %NULL will be returned.
+ * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
+ * Closing a stream multiple times will not return an error.
+ *
+ * Streams will be automatically closed when the last reference
+ * is dropped, but you might want to call this function to make sure
+ * resources are released as early as possible.
+ *
+ * Some streams might keep the backing store of the stream (e.g. a file descriptor)
+ * open after the stream is closed. See the documentation for the individual
+ * stream for details.
+ *
+ * On failure the first error that happened will be reported, but the close
+ * operation will finish as much as possible. A stream that failed to
+ * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
+ * is important to check and report the error to the user.
*
* 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 set, and %NULL will
- * be returned.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ * Cancelling a close will still leave the stream closed, but some streams
+ * can use a faster close that doesn't block to e.g. check errors.
*
- * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
- * Since: 2.22
+ * Returns: %TRUE on success, %FALSE on failure
*/
/**
- * 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.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * g_input_stream_close_async:
+ * @stream: A #GInputStream.
+ * @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
*
- * Asynchronously queries the @stream for a #GFileInfo. When completed,
- * @callback will be called with a #GAsyncResult which can be used to
- * finish the operation with g_file_io_stream_query_info_finish().
- *
- * For the synchronous version of this function, see
- * g_file_io_stream_query_info().
+ * Requests an asynchronous closes of the stream, releasing resources related to it.
+ * When the operation is finished @callback will be called.
+ * You can then call g_input_stream_close_finish() to get the result of the
+ * operation.
*
- * Since: 2.22
+ * For behaviour details see g_input_stream_close().
+ *
+ * The asyncronous methods have a default fallback that uses threads to implement
+ * asynchronicity, so they are optional for inheriting classes. However, if you
+ * override one you must override all.
*/
/**
- * g_file_io_stream_query_info_finish:
- * @stream: a #GFileIOStream.
+ * g_input_stream_close_finish:
+ * @stream: a #GInputStream.
* @result: a #GAsyncResult.
- * @error: a #GError, %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Finalizes the asynchronous query started
- * by g_file_io_stream_query_info_async().
+ * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
*
- * Returns: (transfer full): A #GFileInfo for the finished query.
- * Since: 2.22
+ * Returns: %TRUE if the stream was closed successfully.
*/
/**
- * g_file_is_native:
- * @file: input #GFile.
- *
- * Checks to see if a file is native to the platform.
- *
- * A native file s one expressed in the platform-native filename format,
- * 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.
+ * g_input_stream_has_pending:
+ * @stream: input stream.
*
- * This call does no blocking i/o.
+ * Checks if an input stream has pending actions.
*
- * Returns: %TRUE if file is native.
+ * Returns: %TRUE if @stream has pending actions.
*/
/**
- * 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
- * @error: a #GError, or %NULL
- *
- * Loads the content of the file into memory. The data is always
- * zero-terminated, but this is not included in the resultant @length.
- * The returned @content should be freed with g_free() when no longer
- * needed.
- *
- * 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_input_stream_is_closed:
+ * @stream: input stream.
*
- * %FALSE if there were errors.
+ * Checks if an input stream is closed.
*
- * Returns: %TRUE if the @file's contents were successfully loaded.
+ * Returns: %TRUE if the stream is closed.
*/
/**
- * g_file_load_contents_async:
- * @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_input_stream_read:
+ * @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
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Starts an asynchronous load of the @file's contents.
+ * Tries to read @count bytes from the stream into the buffer starting at
+ * @buffer. Will block during this read.
*
- * For more details, see g_file_load_contents() which is
- * the synchronous version of this call.
+ * If count is zero returns zero and does nothing. A value of @count
+ * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
*
- * When the load operation has completed, @callback will be called
- * with @user data. To finish the operation, call
- * g_file_load_contents_finish() with the #GAsyncResult returned by
- * the @callback.
+ * On success, the number of bytes read into the buffer is returned.
+ * It is not an error if this is not the same as the requested size, as it
+ * 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.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+ * operation was partially finished when the operation was cancelled the
+ * partial result will be returned, without an error.
+ *
+ * On error -1 is returned and @error is set accordingly.
+ *
+ * Returns: Number of bytes read, or -1 on error, or 0 on end of file.
*/
/**
- * 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
- * @error: a #GError, or %NULL
+ * g_input_stream_read_all:
+ * @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
+ * @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.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Finishes an asynchronous load of the @file's contents.
- * The contents are placed in @contents, and @length is set to the
- * size of the @contents string. The @content should be freed with
- * g_free() when no longer needed. If @etag_out is present, it will be
- * set to the new entity tag for the @file.
+ * Tries to read @count bytes from the stream into the buffer starting at
+ * @buffer. Will block during this read.
+ *
+ * This function is similar to g_input_stream_read(), except it tries to
+ * read as many bytes as requested, only stopping on an error or end of stream.
+ *
+ * On a successful read of @count bytes, or if we reached the end of the
+ * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
+ * read into @buffer.
+ *
+ * If there is an error during the operation %FALSE is returned and @error
+ * is set to indicate the error status.
*
- * present, it will be set appropriately.
+ * 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 if the load was successful. If %FALSE and @error is
+ * Returns: %TRUE on success, %FALSE if there was an error
*/
/**
- * 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.
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied
- * @user_data: the data to pass to the callback functions.
+ * 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
*
- * 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().
+ * Request an asynchronous read of @count bytes from the stream into the
+ * buffer starting at @buffer.
*
- * Users of this function should be aware that @user_data is passed to
- * both the @read_more_callback and the @callback.
+ * This is the asynchronous equivalent of g_input_stream_read_all().
*
- * 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.
+ * 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_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
- * @error: a #GError, or %NULL
+ * 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 partial load operation that was started
- * with g_file_load_partial_contents_async(). The data is always
- * zero-terminated, but this is not included in the resultant @length.
- * The returned @content should be freed with g_free() when no longer
- * needed.
+ * Finishes an asynchronous stream read operation started with
+ * g_input_stream_read_all_async().
*
- * present, it will be set appropriately.
+ * 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 if the load was successful. If %FALSE and @error is
+ * Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
*/
/**
- * g_file_make_directory:
- * @file: input #GFile.
+ * g_input_stream_read_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.
- * @error: a #GError, or %NULL
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * 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
- * %G_IO_ERROR_NOT_SUPPORTED.
+ * Request an asynchronous read of @count bytes from the stream into the buffer
+ * starting at @buffer. When the operation is finished @callback will be called.
+ * You can then call g_input_stream_read_finish() to get the result of the
+ * operation.
*
- * For a local #GFile the newly created directory will have the default
- * (current) ownership and permissions of the current process.
+ * During an async request no other sync and async calls are allowed on @stream, and will
+ * result in %G_IO_ERROR_PENDING 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.
+ * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
*
- * Returns: %TRUE on successful creation, %FALSE otherwise.
+ * On success, the number of bytes read into the buffer 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. near the end of a file, but generally we try to read
+ * as many bytes as requested. Zero is returned on end of file
+ * (or if @count is zero), but never otherwise.
+ *
+ * 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.
+ *
+ * The asyncronous methods have a default fallback that uses threads to implement
+ * asynchronicity, so they are optional for inheriting classes. However, if you
+ * override one you must override all.
*/
/**
- * g_file_make_directory_with_parents:
- * @file: input #GFile.
+ * 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.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * 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().
+ * Like g_input_stream_read(), this tries to read @count bytes from
+ * the stream in a blocking fashion. However, rather than reading into
+ * a user-supplied buffer, this will create a new #GBytes containing
+ * the data that was read. This may be easier to use from language
+ * bindings.
*
- * For a local #GFile the newly created directories will have the default
- * (current) ownership and permissions of the current process.
+ * If count is zero, returns a zero-length #GBytes and does nothing. A
+ * value of @count larger than %G_MAXSSIZE will cause a
+ * %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
+ * On success, a new #GBytes is returned. It is not an error if the
+ * size of this object is not the same as the requested size, as it
+ * can happen e.g. near the end of a file. A zero-length #GBytes is
+ * returned on end of file (or if @count is zero), but never
+ * otherwise.
*
* 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.
+ * 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.
*
- * otherwise.
+ * On error %NULL is returned and @error is set accordingly.
*
- * Returns: %TRUE if all directories have been successfully created, %FALSE
- * Since: 2.18
+ * Returns: a new #GBytes, or %NULL on error
+ * Since: 2.34
*/
/**
- * 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
+ * g_input_stream_read_bytes_async:
+ * @stream: A #GInputStream.
+ * @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.
- * @error: a #GError.
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * Creates a symbolic link named @file which contains the string
- * @symlink_value.
+ * Request an asynchronous read of @count bytes from the stream into a
+ * new #GBytes. When the operation is finished @callback will be
+ * called. You can then call g_input_stream_read_bytes_finish() to get the
+ * result of the operation.
*
- * 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.
+ * During an async request no other sync and async calls are allowed
+ * on @stream, and will result in %G_IO_ERROR_PENDING errors.
*
- * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
+ * A value of @count larger than %G_MAXSSIZE will cause a
+ * %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
+ * On success, the new #GBytes will be passed to the callback. It is
+ * not an error if this is smaller than the requested size, as it can
+ * happen e.g. near the end of a file, but generally we try to read as
+ * many bytes as requested. Zero is returned on end of file (or if
+ * @count is zero), but never otherwise.
+ *
+ * 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_file_monitor:
- * @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 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.
+ * 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.
*
- * Free the returned object with g_object_unref().
+ * Finishes an asynchronous stream read-into-#GBytes operation.
*
- * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
- * Since: 2.18
+ * Returns: the newly-allocated #GBytes, or %NULL on error
+ * Since: 2.34
*/
/**
- * g_file_monitor_cancel:
- * @monitor: a #GFileMonitor.
+ * g_input_stream_read_finish:
+ * @stream: a #GInputStream.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Cancels a file monitor.
+ * Finishes an asynchronous stream read operation.
*
- * Returns: %TRUE if monitor was cancelled.
+ * Returns: number of bytes read in, or -1 on error, or 0 on end of file.
*/
/**
- * 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.
- *
- * Obtains a directory monitor for the given file.
- * This may fail if directory monitoring is not supported.
- *
- * 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_input_stream_set_pending:
+ * @stream: input stream
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Free the returned object with g_object_unref().
+ * Sets @stream to have actions pending. If the pending flag is
+ * already set or @stream is closed, it will return %FALSE and set
+ * @error.
*
- * Virtual: monitor_dir
- * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
+ * Returns: %TRUE if pending was previously unset and is now set.
*/
/**
- * g_file_monitor_emit_event:
- * @monitor: a #GFileMonitor.
- * @child: a #GFile.
- * @other_file: a #GFile.
- * @event_type: a set of #GFileMonitorEvent flags.
+ * g_input_stream_skip:
+ * @stream: a #GInputStream.
+ * @count: the number of bytes that will be skipped from the stream
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
+ *
+ * Tries to skip @count bytes from the stream. Will block during the operation.
*
- * Emits the #GFileMonitor::changed signal if a change
- * has taken place. Should be called from file monitor
- * implementations only.
+ * This is identical to g_input_stream_read(), from a behaviour standpoint,
+ * but the bytes that are skipped are not returned to the user. Some
+ * streams have an implementation that is more efficient than reading the data.
+ *
+ * This function is optional for inherited classes, as the default implementation
+ * emulates it using read.
+ *
+ * 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.
*
- * The signal will be emitted from an idle handler (in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link>).
+ * Returns: Number of bytes skipped, or -1 on error
*/
/**
- * g_file_monitor_file:
- * @file: input #GFile.
- * @flags: a set of #GFileMonitorFlags.
+ * g_input_stream_skip_async:
+ * @stream: A #GInputStream.
+ * @count: the number of bytes that will be skipped from the stream
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL.
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * Obtains a file monitor for the given file. If no file notification
- * mechanism exists, then regular polling of the file is used.
+ * Request an asynchronous skip of @count bytes from the stream.
+ * When the operation is finished @callback will be called.
+ * You can then call g_input_stream_skip_finish() to get the result
+ * of the operation.
*
- * 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.
+ * During an async request no other sync and async calls are allowed,
+ * and will result in %G_IO_ERROR_PENDING errors.
+ *
+ * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
+ * On success, the number of bytes skipped 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. near the end of a file, but generally we try to skip
+ * as many bytes as requested. Zero is returned on end of file
+ * (or if @count is zero), but never otherwise.
*
- * Free the returned object with g_object_unref().
+ * 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.
*
- * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
+ * The asynchronous methods have a default fallback that uses threads to
+ * implement asynchronicity, so they are optional for inheriting classes.
+ * However, if you override one, you must override all.
*/
/**
- * g_file_monitor_is_cancelled:
- * @monitor: a #GFileMonitor
+ * g_input_stream_skip_finish:
+ * @stream: a #GInputStream.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Returns whether the monitor is canceled.
+ * Finishes a stream skip operation.
*
- * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
+ * Returns: the size of the bytes skipped, or %-1 on error.
*/
/**
- * g_file_monitor_set_rate_limit:
- * @monitor: a #GFileMonitor.
- * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes
+ * g_io_error_from_errno:
+ * @err_no: Error number as defined in errno.h.
*
- * Sets the rate limit to which the @monitor will report
- * consecutive change events to the same file.
+ * 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_file_mount_enclosing_volume:
- * @location: input #GFile.
- * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: the data to pass to callback function
+ * g_io_error_from_win32_error:
+ * @error_code: Windows error number.
*
- * Starts a @mount_operation, mounting the volume that contains the file @location.
+ * 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).
*
- * 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().
+ * 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.)
*
- * 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: #GIOErrorEnum value for the given error number.
+ * Since: 2.26
*/
/**
- * g_file_mount_enclosing_volume_finish:
- * @location: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes a mount operation started by g_file_mount_enclosing_volume().
+ * g_io_error_quark:
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
+ * Gets the GIO Error Quark.
*
- * Returns: %TRUE if successful. If an error
+ * Returns: a #GQuark.
*/
/**
- * g_file_mount_mountable:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: (closure): the data to pass to callback function
+ * g_io_extension_get_name:
+ * @extension: a #GIOExtension
*
- * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
- * Using @mount_operation, you can request callbacks when, for instance,
- * passwords are needed during authentication.
+ * Gets the name under which @extension was registered.
*
- * 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.
+ * Note that the same type may be registered as extension
+ * for multiple extension points, under different names.
*
- * 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.
+ * Returns: the name of @extension.
*/
/**
- * g_file_mount_mountable_finish:
- * @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().
+ * g_io_extension_get_priority:
+ * @extension: a #GIOExtension
*
- * Free the returned object with g_object_unref().
+ * Gets the priority with which @extension was registered.
*
- * Returns: (transfer full): a #GFile or %NULL on error.
+ * Returns: the priority of @extension
*/
/**
- * 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: (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.
- *
- * If the flag #G_FILE_COPY_OVERWRITE is specified an already
- * existing @destination file is overwritten.
- *
- * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
- * will be copied as symlinks, otherwise the target of the
- * @source symlink will be copied.
- *
- * 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 @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 #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
- * error is returned. If trying to overwrite a directory with a directory the
- * G_IO_ERROR_WOULD_MERGE error is returned.
+ * g_io_extension_get_type:
+ * @extension: a #GIOExtension
*
- * 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).
+ * Gets the type associated with @extension.
*
- * Returns: %TRUE on successful move, %FALSE otherwise.
+ * Returns: the type of @extension
*/
/**
- * g_file_new_for_commandline_arg:
- * @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.
+ * g_io_extension_point_get_extension_by_name:
+ * @extension_point: a #GIOExtensionPoint
+ * @name: the name of the extension to get
*
- * Free the returned object with g_object_unref().
+ * Finds a #GIOExtension for an extension point by name.
*
- * Returns: (transfer full): a new #GFile.
+ * Returns: (transfer none): the #GIOExtension for @extension_point that has the
+ * given name, or %NULL if there is no extension with that name
*/
/**
- * g_file_new_for_path:
- * @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.
+ * g_io_extension_point_get_extensions:
+ * @extension_point: a #GIOExtensionPoint
*
- * Free the returned object with g_object_unref().
+ * Gets a list of all extensions that implement this extension point.
+ * The list is sorted by priority, beginning with the highest priority.
*
- * Returns: (transfer full): a new #GFile for the given @path.
+ * Returns: (element-type GIOExtension) (transfer none): a #GList of
+ * #GIOExtensions. The list is owned by GIO and should not be
+ * modified.
*/
/**
- * g_file_new_for_uri:
- * @uri: a UTF8 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.
+ * g_io_extension_point_get_required_type:
+ * @extension_point: a #GIOExtensionPoint
*
- * Free the returned object with g_object_unref().
+ * Gets the required type for @extension_point.
*
- * Returns: (transfer full): a new #GFile for the given @uri.
+ * Returns: the #GType that all implementations must have,
+ * or #G_TYPE_INVALID if the extension point has no required type
*/
/**
- * 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.
- * @error: a #GError, or %NULL
- *
- * Opens a file in the preferred directory for temporary files (as
- * returned by g_get_tmp_dir()) and returns a #GFile and
- * #GFileIOStream pointing to it.
- *
- * @template should be a string in the GLib file name encoding
- * containing a sequence of six 'X' characters, and containing no
- * directory components. If it is %NULL, a default template is used.
+ * g_io_extension_point_implement:
+ * @extension_point_name: the name of the extension point
+ * @type: the #GType to register as extension
+ * @extension_name: the name for the extension
+ * @priority: the priority for the extension
*
- * Unlike the other #GFile constructors, this will return %NULL if
- * a temporary file could not be created.
+ * Registers @type as extension for the extension point with name
+ * @extension_point_name.
*
- * Free the returned object with g_object_unref().
+ * If @type has already been registered as an extension for this
+ * extension point, the existing #GIOExtension object is returned.
*
- * Returns: (transfer full): a new #GFile.
- * Since: 2.32
+ * Returns: (transfer none): a #GIOExtension object for #GType
*/
/**
- * g_file_open_readwrite:
- * @file: #GFile to open
- * @cancellable: (allow-none): a #GCancellable
- * @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.
- *
- * 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.
+ * g_io_extension_point_lookup:
+ * @name: the name of the extension point
*
- * Free the returned object with g_object_unref().
+ * Looks up an existing extension point.
*
- * Returns: (transfer full): #GFileIOStream or %NULL on error.
- * Since: 2.22
+ * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
+ * is no registered extension point with the given name.
*/
/**
- * 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
- * @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.
+ * g_io_extension_point_register:
+ * @name: The name of the extension point
*
- * 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.
+ * Registers an extension point.
*
- * Since: 2.22
+ * Returns: (transfer none): the new #GIOExtensionPoint. This object is
+ * owned by GIO and should not be freed.
*/
/**
- * g_file_open_readwrite_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * g_io_extension_point_set_required_type:
+ * @extension_point: a #GIOExtensionPoint
+ * @type: the #GType to require
*
- * Finishes an asynchronous file read operation started with
- * g_file_open_readwrite_async().
+ * Sets the required type for @extension_point to @type.
+ * All implementations must henceforth have this type.
+ */
+
+
+/**
+ * g_io_extension_ref_class:
+ * @extension: a #GIOExtension
*
- * Free the returned object with g_object_unref().
+ * Gets a reference to the class for the type that is
+ * associated with @extension.
*
- * Returns: (transfer full): a #GFileIOStream or %NULL on error.
- * Since: 2.22
+ * Returns: (transfer full): the #GTypeClass for the type of @extension
*/
/**
- * g_file_output_stream_get_etag:
- * @stream: a #GFileOutputStream.
+ * g_io_module_new:
+ * @filename: filename of the shared library module.
*
- * Gets the entity tag for the file when it has been written.
- * This must be called after the stream has been written
- * and closed, as the etag can change while writing.
+ * Creates a new GIOModule that will load the specific
+ * shared library when in use.
*
- * Returns: the entity tag for the stream.
+ * Returns: a #GIOModule from given @filename,
+ * or %NULL on error.
*/
/**
- * g_file_output_stream_query_info:
- * @stream: a #GFileOutputStream.
- * @attributes: a file attribute query string.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
- *
- * Queries a file output stream for the given @attributes.
- * This function blocks while querying the stream. For the asynchronous
- * version of this function, see g_file_output_stream_query_info_async().
- * While the stream is blocked, the stream will set the pending flag
- * internally, and any other operations on the stream will fail with
- * %G_IO_ERROR_PENDING.
- *
- * Can fail if the stream was already closed (with @error being set to
- * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
- * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
- * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
- * all cases of failure, %NULL will be returned.
+ * g_io_module_scope_block:
+ * @scope: a module loading scope
+ * @basename: the basename to block
*
- * 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 set, and %NULL will
- * be returned.
+ * Block modules with the given @basename from being loaded when
+ * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
+ * or g_io_modules_load_all_in_directory_with_scope().
*
- * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
+ * Since: 2.30
*/
/**
- * 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.
- * @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_io_module_scope_free:
+ * @scope: a module loading scope
*
- * Asynchronously queries the @stream for a #GFileInfo. When completed,
- * @callback will be called with a #GAsyncResult which can be used to
- * finish the operation with g_file_output_stream_query_info_finish().
+ * Free a module scope.
*
- * For the synchronous version of this function, see
- * g_file_output_stream_query_info().
+ * Since: 2.30
*/
/**
- * g_file_output_stream_query_info_finish:
- * @stream: a #GFileOutputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError, %NULL to ignore.
+ * g_io_module_scope_new:
+ * @flags: flags for the new scope
*
- * Finalizes the asynchronous query started
- * by g_file_output_stream_query_info_async().
+ * Create a new scope for loading of IO modules. A scope can be used for
+ * blocking duplicate modules, or blocking a module you don't want to load.
*
- * Returns: (transfer full): A #GFileInfo for the finished query.
+ * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
+ * which have the same base name as a module that has already been seen
+ * in this scope.
+ *
+ * Returns: (transfer full): the new module scope
+ * Since: 2.30
*/
/**
- * g_file_parse_name:
- * @parse_name: a file name or path to be parsed.
+ * g_io_modules_load_all_in_directory:
+ * @dirname: pathname for a directory containing modules to load.
*
- * 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.
+ * Loads all the modules in the specified directory.
*
- * Returns: (transfer full): a new #GFile.
+ * If don't require all modules to be initialized (and thus registering
+ * 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().
*/
/**
- * g_file_poll_mountable:
- * @file: input #GFile.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: 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.
+ * g_io_modules_load_all_in_directory_with_scope:
+ * @dirname: pathname for a directory containing modules to load.
+ * @scope: a scope to use when scanning the modules.
*
- * 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.
+ * Loads all the modules in the specified directory.
*
- * 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.
+ * If don't require all modules to be initialized (and thus registering
+ * all gtypes) then you can use g_io_modules_scan_all_in_directory()
+ * which allows delayed/lazy loading of modules.
*
- * Since: 2.22
+ * 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
*/
/**
- * g_file_poll_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * g_io_modules_scan_all_in_directory:
+ * @dirname: pathname for a directory containing modules to scan.
*
- * Finishes a poll operation. See g_file_poll_mountable() for details.
+ * Scans all the modules in the specified directory, ensuring that
+ * any extension point implemented by a module is registered.
*
- * Finish an asynchronous poll operation that was polled
- * with g_file_poll_mountable().
+ * This may not actually load and initialize all the types in each
+ * module, some modules may be lazily loaded and initialized when
+ * an extension point it implementes is used with e.g.
+ * g_io_extension_point_get_extensions() or
+ * g_io_extension_point_get_extension_by_name().
*
- * otherwise.
+ * If you need to guarantee that all types are loaded in all the modules,
+ * use g_io_modules_load_all_in_directory().
*
- * Returns: %TRUE if the operation finished successfully. %FALSE
- * Since: 2.22
+ * Since: 2.24
*/
/**
- * g_file_query_default_handler:
- * @file: a #GFile to open.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL
+ * g_io_modules_scan_all_in_directory_with_scope:
+ * @dirname: pathname for a directory containing modules to scan.
+ * @scope: a scope to use when scanning the modules
*
- * Returns the #GAppInfo that is registered as the default
- * application to handle the file specified by @file.
+ * Scans all the modules in the specified directory, ensuring that
+ * any extension point implemented by a module is registered.
*
- * 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.
+ * This may not actually load and initialize all the types in each
+ * module, some modules may be lazily loaded and initialized when
+ * an extension point it implementes is used with e.g.
+ * g_io_extension_point_get_extensions() or
+ * g_io_extension_point_get_extension_by_name().
*
- * When you are done with it, release it with g_object_unref()
+ * If you need to guarantee that all types are loaded in all the modules,
+ * use g_io_modules_load_all_in_directory().
*
- * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors.
+ * Since: 2.30
*/
/**
- * g_file_query_exists:
- * @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.
- *
- * Note that in many cases it is racy to first check for file existence
- * and then execute something based on the outcome of that, because the
- * file might have been created or removed in between the operations. The
- * general approach to handling that is to not check, but just do the
- * operation and handle the errors as they come.
+ * g_io_scheduler_cancel_all_jobs:
*
- * 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.
+ * Cancels all cancellable I/O jobs.
*
- * 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.
+ * A job is cancellable if a #GCancellable was passed into
+ * g_io_scheduler_push_job().
*
- * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled).
+ * Deprecated: You should never call this function, since you don't
+ * know how other libraries in your program might be making use of
+ * gioscheduler.
*/
/**
- * 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.
- *
- * 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.
+ * g_io_scheduler_job_send_to_mainloop:
+ * @job: a #GIOSchedulerJob
+ * @func: a #GSourceFunc callback that will be called in the original thread
+ * @user_data: data to pass to @func
+ * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
*
- * does not exist
+ * Used from an I/O job to send a callback to be run in the thread
+ * that the job was started from, waiting for the result (and thus
+ * blocking the I/O job).
*
- * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file
- * Since: 2.18
+ * Returns: The return value of @func
+ * Deprecated: Use g_main_context_invoke().
*/
/**
- * 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.
- *
- * 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.
+ * g_io_scheduler_job_send_to_mainloop_async:
+ * @job: a #GIOSchedulerJob
+ * @func: a #GSourceFunc callback that will be called in the original thread
+ * @user_data: data to pass to @func
+ * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL
*
- * 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.
+ * Used from an I/O job to send a callback to be run asynchronously in
+ * the thread that the job was started from. The callback will be run
+ * when the main loop is available, but at that time the I/O job might
+ * have finished. The return value from the callback is ignored.
*
- * Free the returned object with g_object_unref().
+ * Note that if you are passing the @user_data from g_io_scheduler_push_job()
+ * 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.
*
- * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
+ * Deprecated: Use g_main_context_invoke().
*/
/**
- * 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
- * @user_data: (closure): the data to pass to callback function
+ * g_io_scheduler_push_job:
+ * @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 [I/O priority][io-priority]
+ * of the request.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
*
- * Asynchronously gets the requested information about the filesystem
- * that the specified @file is on. The result is a #GFileInfo object
- * that contains key-value attributes (such as type or size for the
- * file).
+ * Schedules the I/O job to run in another thread.
*
- * For more details, see g_file_query_filesystem_info() which is the
- * synchronous version of this call.
+ * @notify will be called on @user_data after @job_func has returned,
+ * regardless whether the job was cancelled or has run to completion.
*
- * 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.
+ * 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_file_query_filesystem_info_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError.
- *
- * Finishes an asynchronous filesystem info query. See
- * g_file_query_filesystem_info_async().
+ * g_io_stream_clear_pending:
+ * @stream: a #GIOStream
*
- * Free the returned object with g_object_unref().
+ * Clears the pending flag on @stream.
*
- * Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
+ * Since: 2.22
*/
/**
- * 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.
+ * g_io_stream_close:
+ * @stream: a #GIOStream
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * 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).
+ * Closes the stream, releasing resources related to it. This will also
+ * closes the individual input and output streams, if they are not already
+ * closed.
*
- * 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.
+ * 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 @cancellable is not %NULL, then the operation can be cancelled by
+ * 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
+ * resources are released as early as possible.
+ *
+ * Some streams might keep the backing store of the stream (e.g. a file
+ * descriptor) open after the stream is closed. See the documentation for
+ * the individual stream for details.
+ *
+ * On failure the first error that happened will be reported, but the
+ * close operation will finish as much as possible. A stream that failed
+ * to close will still return %G_IO_ERROR_CLOSED for all operations.
+ * Still, it is important to check and report the error to the user,
+ * otherwise there might be a loss of data as all data might not be written.
+ *
+ * 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.
+ * Cancelling a close will still leave the stream closed, but some streams
+ * can use a faster close that doesn't block to e.g. check errors.
*
- * 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.
- *
- * 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.
- *
- * Free the returned object with g_object_unref().
+ * The default implementation of this method just calls close on the
+ * individual input/output streams.
*
- * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error.
+ * Returns: %TRUE on success, %FALSE on failure
+ * Since: 2.22
*/
/**
- * 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
+ * g_io_stream_close_async:
+ * @stream: a #GIOStream
+ * @io_priority: the 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
*
- * 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).
+ * Requests an asynchronous close of the stream, releasing resources
+ * related to it. When the operation is finished @callback will be
+ * called. You can then call g_io_stream_close_finish() to get
+ * the result of the operation.
*
- * For more details, see g_file_query_info() which is
- * the synchronous version of this call.
+ * For behaviour details see g_io_stream_close().
*
- * 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.
+ * The asynchronous methods have a default fallback that uses threads
+ * to implement asynchronicity, so they are optional for inheriting
+ * classes. However, if you override one you must override all.
+ *
+ * Since: 2.22
*/
/**
- * g_file_query_info_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError.
- *
- * Finishes an asynchronous file info query.
- * See g_file_query_info_async().
+ * g_io_stream_close_finish:
+ * @stream: a #GIOStream
+ * @result: a #GAsyncResult
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore
*
- * Free the returned object with g_object_unref().
+ * Closes a stream.
*
- * Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
+ * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_file_query_settable_attributes:
- * @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.
- *
- * 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_io_stream_get_input_stream:
+ * @stream: a #GIOStream
*
- * When you are done with it, release it with g_file_attribute_info_list_unref()
+ * Gets the input stream for this object. This is used
+ * for reading.
*
- * Returns: a #GFileAttributeInfoList describing the settable attributes.
+ * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
+ * Do not free.
+ * Since: 2.22
*/
/**
- * g_file_query_writable_namespaces:
- * @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
- * can be created by a user. An example of this is extended
- * attributes (in the "xattr" namespace).
- *
- * 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_io_stream_get_output_stream:
+ * @stream: a #GIOStream
*
- * When you are done with it, release it with g_file_attribute_info_list_unref()
+ * Gets the output stream for this object. This is used for
+ * writing.
*
- * Returns: a #GFileAttributeInfoList describing the writable namespaces.
+ * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
+ * Do not free.
+ * Since: 2.22
*/
/**
- * g_file_read:
- * @file: #GFile to read.
- * @cancellable: (allow-none): a #GCancellable
- * @error: a #GError, or %NULL
- *
- * Opens a file for reading. The result is a #GFileInputStream that
- * can be used to read 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 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.
+ * g_io_stream_has_pending:
+ * @stream: a #GIOStream
*
- * Free the returned object with g_object_unref().
+ * Checks if a stream has pending actions.
*
- * Virtual: read_fn
- * Returns: (transfer full): #GFileInputStream or %NULL on error.
+ * Returns: %TRUE if @stream has pending actions.
+ * Since: 2.22
*/
/**
- * 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
- * @user_data: (closure): the data to pass to callback function
- *
- * Asynchronously opens @file for reading.
+ * g_io_stream_is_closed:
+ * @stream: a #GIOStream
*
- * For more details, see g_file_read() which is
- * the synchronous version of this call.
+ * Checks if a stream is closed.
*
- * When the operation is finished, @callback will be called. You can then call
- * g_file_read_finish() to get the result of the operation.
+ * Returns: %TRUE if the stream is closed.
+ * Since: 2.22
*/
/**
- * g_file_read_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes an asynchronous file read operation started with
- * g_file_read_async().
+ * g_io_stream_set_pending:
+ * @stream: a #GIOStream
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore
*
- * Free the returned object with g_object_unref().
+ * Sets @stream to have actions pending. If the pending flag is
+ * already set or @stream is closed, it will return %FALSE and set
+ * @error.
*
- * Returns: (transfer full): a #GFileInputStream or %NULL on error.
+ * Returns: %TRUE if pending was previously unset and is now set.
+ * Since: 2.22
*/
/**
- * 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.
+ * g_io_stream_splice_async:
+ * @stream1: a #GIOStream.
+ * @stream2: a #GIOStream.
+ * @flags: a set of #GIOStreamSpliceFlags.
+ * @io_priority: the io priority of the request.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL
- *
- * Returns an output stream for overwriting the file, possibly
- * creating a backup copy of the file first. If the file doesn't exist,
- * it will be created.
- *
- * This will try to replace the file in the safest way possible so
- * that any errors during the writing will not affect an already
- * existing copy of the file. For instance, for local files it
- * may write to a temporary file and then atomically rename over
- * the destination when the stream is closed.
- *
- * 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 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.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @user_data: (closure): user data passed to @callback.
*
- * 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.
+ * Asyncronously splice the output stream of @stream1 to the input stream of
+ * @stream2, and splice the output stream of @stream2 to the input stream of
+ * @stream1.
*
- * Free the returned object with g_object_unref().
+ * When the operation is finished @callback will be called.
+ * You can then call g_io_stream_splice_finish() to get the
+ * result of the operation.
*
- * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
+ * Since: 2.28
*/
/**
- * 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
- * @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.
+ * g_io_stream_splice_finish:
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * For more details, see g_file_replace() which is
- * the synchronous version of this call.
+ * Finishes an asynchronous io stream splice 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.
+ * Returns: %TRUE on success, %FALSE otherwise.
+ * Since: 2.28
*/
/**
- * 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.
- * @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.
+ * 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
*
- * If @make_backup is %TRUE, this function will attempt to make a backup of @file.
+ * Creates a keyfile-backed #GSettingsBackend.
*
- * 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 filename of the keyfile to use is given by @filename.
*
- * The returned @new_etag can be used to verify that the file hasn't changed the
- * next time it is saved over.
+ * All settings read to or written from the backend must fall under the
+ * path given in @root_path (which must start and end with a slash and
+ * not contain two consecutive slashes). @root_path may be "/".
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
+ * If @root_group is non-%NULL then it specifies the name of the keyfile
+ * group used for keys that are written directly below @root_path. For
+ * example, if @root_path is "/apps/example/" and @root_group is
+ * "toplevel", then settings the key "/apps/example/enabled" to a value
+ * of %TRUE will cause the following to appear in the keyfile:
*
- * Returns: %TRUE if successful. If an error
- */
-
-
-/**
- * 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.
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied
- * @user_data: the data to pass to callback function
+ * |[
+ * [toplevel]
+ * enabled=true
+ * ]|
*
- * Starts an asynchronous replacement of @file with the given
- * @contents of @length bytes. @etag will replace the document's
- * current entity tag.
+ * If @root_group is %NULL then it is not permitted to store keys
+ * directly below the @root_path.
*
- * 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().
+ * For keys not stored directly below @root_path (ie: in a sub-path),
+ * the name of the subpath (with the final slash stripped) is used as
+ * the name of the keyfile group. To continue the example, if
+ * "/apps/example/profiles/default/font-size" were set to
+ * 12 then the following would appear in the keyfile:
*
- * 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.
+ * |[
+ * [profiles/default]
+ * font-size=12
+ * ]|
*
- * If @make_backup is %TRUE, this function will attempt to
- * make a backup of @file.
- */
-
-
-/**
- * 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
+ * The backend will refuse writes (and return writability as being
+ * %FALSE) for keys outside of @root_path and, in the event that
+ * @root_group is %NULL, also for keys directly under @root_path.
+ * Writes will also be refused if the backend detects that it has the
+ * inability to rewrite the keyfile (ie: the containing directory is not
+ * writable).
*
- * 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.
+ * There is no checking done for your key namespace clashing with the
+ * syntax of the key file format. For example, if you have '[' or ']'
+ * characters in your path names or '=' in your key names you may be in
+ * trouble.
*
- * Returns: %TRUE on success, %FALSE on failure.
+ * Returns: (transfer full): a keyfile-backed #GSettingsBackend
*/
/**
- * g_file_replace_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * g_list_model_get_item: (skip)
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
*
- * Finishes an asynchronous file replace operation started with
- * g_file_replace_async().
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
*
- * Free the returned object with g_object_unref().
+ * %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): a #GFileOutputStream, or %NULL on error.
+ * Returns: (transfer full) (nullable) (type GObject): the item at @position.
+ * Since: 2.44
*/
/**
- * 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
- * @make_backup: %TRUE if a backup should be created
- * @flags: a set of #GFileCreateFlags
- * @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.
+ * g_list_model_get_item_type:
+ * @list: a #GListModel
*
- * 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.
+ * 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.
*
- * Free the returned object with g_object_unref().
+ * The item type of a #GListModel can not change during the life of the
+ * model.
*
- * Returns: (transfer full): a #GFileIOStream or %NULL on error.
- * Since: 2.22
+ * Returns: the #GType of the items contained in @list.
+ * Since: 2.44
*/
/**
- * 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
- * @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.
+ * g_list_model_get_n_items:
+ * @list: a #GListModel
*
- * For more details, see g_file_replace_readwrite() which is
- * the synchronous version of this call.
+ * Gets the number of items in @list.
*
- * 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.
+ * 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.
*
- * Since: 2.22
+ * Returns: the number of items in @list.
+ * Since: 2.44
*/
/**
- * g_file_replace_readwrite_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * g_list_model_get_object: (rename-to g_list_model_get_item)
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
*
- * Finishes an asynchronous file replace operation started with
- * g_file_replace_readwrite_async().
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
*
- * Free the returned object with g_object_unref().
+ * %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): a #GFileIOStream, or %NULL on error.
- * Since: 2.22
+ * Returns: (transfer full) (nullable): the object at @position.
+ * Since: 2.44
*/
/**
- * g_file_resolve_relative_path:
- * @file: input #GFile.
- * @relative_path: a given relative path string.
+ * 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
*
- * Resolves a relative path for @file to an absolute path.
+ * Emits the #GListModel::items-changed signal on @list.
*
- * This call does no blocking i/o.
+ * 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.
*
- * is %NULL or if @file is invalid.
- * Free the returned object with g_object_unref().
+ * 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.
*
- * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path
+ * 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_file_set_attribute:
- * @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.
- * @error: a #GError, or %NULL
+ * g_list_store_append:
+ * @store: a #GListStore
+ * @item: the new item
*
- * Sets an attribute in the file with attribute name @attribute to @value.
+ * Appends @item to @store. @item must be of type #GListStore:item-type.
*
- * Some attributes can be unset by setting @attribute to
- * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
+ * This function takes a ref on @item.
*
- * 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.
+ * Use g_list_store_splice() to append multiple items at the same time
+ * efficiently.
*
- * Returns: %TRUE if the attribute was set, %FALSE otherwise.
+ * Since: 2.44
*/
/**
- * 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.
- * @error: a #GError, or %NULL
+ * g_list_store_insert:
+ * @store: a #GListStore
+ * @position: the position at which to insert the new item
+ * @item: the new item
*
- * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
- * If @attribute is of a different type, this operation will fail,
- * returning %FALSE.
+ * 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.
*
- * 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.
+ * This function takes a ref on @item.
*
- * in the @file, %FALSE otherwise.
+ * Use g_list_store_splice() to insert multiple items at the same time
+ * efficiently.
*
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Since: 2.44
*/
/**
- * 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.
- * @error: a #GError, or %NULL
+ * 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
*
- * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
- * If @attribute is of a different type, this operation will fail.
+ * Inserts @item into @store at a position to be determined by the
+ * @compare_func.
*
- * 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 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.
*
- * in the @file, %FALSE otherwise.
+ * This function takes a ref on @item.
*
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Returns: the position at which @item was inserted
+ * Since: 2.44
*/
/**
- * 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.
- * @error: a #GError, or %NULL
- *
- * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
- * If @attribute is of a different type, this operation will fail.
+ * g_list_store_new:
+ * @item_type: the #GType of items in the list
*
- * 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.
+ * Creates a new #GListStore with items of type @item_type. @item_type
+ * must be a subclass of #GObject.
*
- * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
+ * Returns: a new #GListStore
+ * Since: 2.44
*/
/**
- * 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.
- * @error: a #GError, or %NULL
+ * g_list_store_remove:
+ * @store: a #GListStore
+ * @position: the position of the item that is to be removed
*
- * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
- * If @attribute is of a different type, this operation will fail.
+ * Removes the item from @store that is at @position. @position must be
+ * smaller than the current length of the list.
*
- * 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.
+ * Use g_list_store_splice() to remove multiple items at the same time
+ * efficiently.
*
- * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
+ * Since: 2.44
*/
/**
- * 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.
- * @error: a #GError, or %NULL
- *
- * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
- * If @attribute is of a different type, this operation 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.
+ * g_list_store_remove_all:
+ * @store: a #GListStore
*
- * in the @file, %FALSE otherwise.
+ * Removes all items from @store.
*
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Since: 2.44
*/
/**
- * 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.
- * @error: a #GError, or %NULL
+ * 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
*
- * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
- * If @attribute is of a different type, this operation will fail.
+ * 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.
*
- * 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.
+ * 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.
*
- * in the @file, %FALSE otherwise.
+ * This function takes a ref on each item in @additions.
*
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * 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_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.
+ * 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.
*
- * Asynchronously sets the attributes of @file with @info.
+ * Loads a loadable icon. For the asynchronous version of this function,
+ * see g_loadable_icon_load_async().
*
- * For more details, see g_file_set_attributes_from_info() which is
- * the synchronous version of this call.
+ * 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
*
- * 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.
+ * 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_file_set_attributes_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @info: (out) (transfer full): a #GFileInfo.
- * @error: a #GError, or %NULL
+ * 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 setting an attribute started in g_file_set_attributes_async().
+ * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
*
- * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
+ * Returns: (transfer full): a #GInputStream to read the icon from.
*/
/**
- * g_file_set_attributes_from_info:
- * @file: input #GFile.
- * @info: a #GFileInfo.
- * @flags: #GFileQueryInfoFlags
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL
+ * g_local_vfs_new:
*
- * Tries to set all attributes in the #GFileInfo on the target values,
- * not stopping on the first error.
+ * Returns a new #GVfs handle for a local vfs.
*
- * 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.
+ * Returns: a new #GVfs handle.
+ */
+
+
+/**
+ * g_memory_input_stream_add_bytes:
+ * @stream: a #GMemoryInputStream
+ * @bytes: input data
*
- * 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.
+ * Appends @bytes to data that can be read from the input stream.
*
- * Returns: %TRUE if there was any error, %FALSE otherwise.
+ * Since: 2.34
*/
/**
- * g_file_set_display_name:
- * @file: input #GFile.
- * @display_name: a string.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, or %NULL
+ * 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
*
- * Renames @file to the specified display name.
+ * Appends @data to data that can be read from the input stream
+ */
+
+
+/**
+ * g_memory_input_stream_new:
*
- * The display name is converted from UTF8 to the correct encoding for the target
- * filesystem if possible and the @file is renamed to this.
+ * Creates a new empty #GMemoryInputStream.
*
- * 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().
+ * Returns: a new #GInputStream
+ */
+
+
+/**
+ * g_memory_input_stream_new_from_bytes:
+ * @bytes: a #GBytes
*
- * On success the resulting converted filename is returned.
+ * Creates a new #GMemoryInputStream with data from the given @bytes.
*
- * 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: new #GInputStream read from @bytes
+ * Since: 2.34
+ */
+
+
+/**
+ * g_memory_input_stream_new_from_data:
+ * @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
*
- * if there was an error.
- * Free the returned object with g_object_unref().
+ * Creates a new #GMemoryInputStream with data in memory of a given size.
*
- * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL
+ * Returns: new #GInputStream read from @data of @len bytes.
*/
/**
- * 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
- * @user_data: (closure): the data to pass to callback function
+ * g_memory_output_stream_get_data:
+ * @ostream: a #GMemoryOutputStream
*
- * Asynchronously sets the display name for a given #GFile.
+ * Gets any loaded data from the @ostream.
*
- * For more details, see g_file_set_display_name() which is
- * the synchronous version of this call.
+ * Note that the returned pointer may become invalid on the next
+ * write or truncate operation on the stream.
*
- * 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.
+ * Returns: (transfer none): pointer to the stream's data
*/
/**
- * g_file_set_display_name_finish:
- * @file: input #GFile.
- * @res: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes setting a display name started with
- * g_file_set_display_name_async().
+ * g_memory_output_stream_get_data_size:
+ * @ostream: a #GMemoryOutputStream
*
- * Free the returned object with g_object_unref().
+ * 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: (transfer full): a #GFile or %NULL on error.
+ * Returns: the number of bytes written to the stream
+ * Since: 2.18
*/
/**
- * g_file_start_mountable:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @start_operation: a #GMountOperation, or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: the data to pass to callback function
+ * g_memory_output_stream_get_size:
+ * @ostream: a #GMemoryOutputStream
*
- * Starts a file of type G_FILE_TYPE_MOUNTABLE.
- * Using @start_operation, you can request callbacks when, for instance,
- * passwords are needed during authentication.
+ * Gets the size of the currently allocated data area (available from
+ * g_memory_output_stream_get_data()).
*
- * 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.
+ * 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.
*
- * 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.
+ * 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.
*
- * Since: 2.22
+ * 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_file_start_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
+ * 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
*
- * Finishes a start operation. See g_file_start_mountable() for details.
+ * Creates a new #GMemoryOutputStream.
*
- * Finish an asynchronous start operation that was started
- * with g_file_start_mountable().
+ * In most cases this is not the function you want. See
+ * g_memory_output_stream_new_resizable() instead.
+ *
+ * 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
+ * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
+ *
+ * // a fixed-size stream
+ * data = malloc (200);
+ * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
+ * ]|
+ *
+ * Returns: A newly created #GMemoryOutputStream object.
+ */
+
+
+/**
+ * g_memory_output_stream_new_resizable:
*
- * otherwise.
+ * Creates a new #GMemoryOutputStream, using g_realloc() and g_free()
+ * for memory allocation.
*
- * Returns: %TRUE if the operation finished successfully. %FALSE
- * Since: 2.22
+ * Since: 2.36
*/
/**
- * g_file_stop_mountable:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: the data to pass to callback function
+ * g_memory_output_stream_steal_as_bytes:
+ * @ostream: a #GMemoryOutputStream
*
- * Stops a file of type G_FILE_TYPE_MOUNTABLE.
+ * Returns data from the @ostream as a #GBytes. @ostream must be
+ * closed before calling this function.
*
- * 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): the stream's data
+ * Since: 2.34
+ */
+
+
+/**
+ * g_memory_output_stream_steal_data:
+ * @ostream: a #GMemoryOutputStream
*
- * 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.
+ * Gets any loaded data from the @ostream. Ownership of the data
+ * is transferred to the caller; when no longer needed it must be
+ * freed using the free function set in @ostream's
+ * #GMemoryOutputStream:destroy-function property.
*
- * Since: 2.22
+ * @ostream must be closed before calling this function.
+ *
+ * Returns: (transfer full): the stream's data
+ * Since: 2.26
*/
/**
- * g_file_stop_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes an stop operation, see g_file_stop_mountable() for details.
+ * g_memory_settings_backend_new:
*
- * Finish an asynchronous stop operation that was started
- * with g_file_stop_mountable().
+ * Creates a memory-backed #GSettingsBackend.
*
- * otherwise.
+ * This backend allows changes to settings, but does not write them
+ * to any backing storage, so the next time you run your application,
+ * the memory backend will start out with the default values again.
*
- * Returns: %TRUE if the operation finished successfully. %FALSE
- * Since: 2.22
+ * Returns: (transfer full): a newly created #GSettingsBackend
+ * Since: 2.28
*/
/**
- * g_file_supports_thread_contexts:
- * @file: a #GFile.
+ * g_menu_append:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
*
- * 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.
+ * Convenience function for appending a normal menu item to the end of
+ * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
+ * flexible alternative.
*
- * Returns: Whether or not @file supports thread-default contexts.
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_file_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
- * deleting it, but the user can recover it before emptying the trashcan.
- * Not all file systems support trashing, so this call can return the
- * %G_IO_ERROR_NOT_SUPPORTED error.
+ * g_menu_append_item:
+ * @menu: a #GMenu
+ * @item: a #GMenuItem to append
*
+ * Appends @item to the end of @menu.
*
- * 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.
+ * See g_menu_insert_item() for more information.
*
- * Returns: %TRUE on successful trash, %FALSE otherwise.
+ * Since: 2.32
*/
/**
- * g_file_unmount_mountable:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: (closure): the data to pass to callback function
+ * g_menu_append_section:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
*
- * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
+ * Convenience function for appending a section menu item to the end of
+ * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
+ * more flexible alternative.
*
- * 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.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_append_submenu:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
*
- * 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.
+ * Convenience function for appending a submenu menu item to the end of
+ * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
+ * more flexible alternative.
*
- * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
+ * Since: 2.32
*/
/**
- * g_file_unmount_mountable_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes an unmount operation, see g_file_unmount_mountable() for details.
+ * g_menu_attribute_iter_get_name:
+ * @iter: a #GMenuAttributeIter
*
- * Finish an asynchronous unmount operation that was started
- * with g_file_unmount_mountable().
+ * Gets the name of the attribute at the current iterator position, as
+ * a string.
*
- * otherwise.
+ * The iterator is not advanced.
*
- * Returns: %TRUE if the operation finished successfully. %FALSE
- * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead.
+ * Returns: the name of the attribute
+ * Since: 2.32
*/
/**
- * g_file_unmount_mountable_with_operation:
- * @file: input #GFile.
- * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
- * @user_data: (closure): the data to pass to callback function
+ * g_menu_attribute_iter_get_next:
+ * @iter: a #GMenuAttributeIter
+ * @out_name: (out) (allow-none) (transfer none): the type of the attribute
+ * @value: (out) (allow-none) (transfer full): the attribute value
*
- * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
+ * This function combines g_menu_attribute_iter_next() with
+ * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
*
- * 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.
+ * First the iterator is advanced to the next (possibly first) attribute.
+ * If that fails, then %FALSE is returned and there are no other
+ * effects.
*
- * 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.
+ * If successful, @name and @value are set to the name and value of the
+ * attribute that has just been advanced to. At this point,
+ * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
+ * return the same values again.
*
- * Since: 2.22
+ * The value returned in @name remains valid for as long as the iterator
+ * 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
+ * Since: 2.32
*/
/**
- * g_file_unmount_mountable_with_operation_finish:
- * @file: input #GFile.
- * @result: a #GAsyncResult.
- * @error: a #GError, or %NULL
- *
- * Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details.
+ * g_menu_attribute_iter_get_value:
+ * @iter: a #GMenuAttributeIter
*
- * Finish an asynchronous unmount operation that was started
- * with g_file_unmount_mountable_with_operation().
+ * Gets the value of the attribute at the current iterator position.
*
- * otherwise.
+ * The iterator is not advanced.
*
- * Returns: %TRUE if the operation finished successfully. %FALSE
- * Since: 2.22
+ * Returns: (transfer full): the value of the current attribute
+ * Since: 2.32
*/
/**
- * g_filename_completer_get_completion_suffix:
- * @completer: the filename completer.
- * @initial_text: text to be completed.
+ * g_menu_attribute_iter_next:
+ * @iter: a #GMenuAttributeIter
*
- * Obtains a completion for @initial_text from @completer.
+ * Attempts to advance the iterator to the next (possibly first)
+ * attribute.
*
- * This string is not owned by GIO, so remember to g_free() it
- * when finished.
+ * %TRUE is returned on success, or %FALSE if there are no more
+ * attributes.
*
- * Returns: a completed string, or %NULL if no completion exists.
+ * You must call this function when you first acquire the iterator
+ * to advance it to the first attribute (and determine if the first
+ * attribute exists at all).
+ *
+ * Returns: %TRUE on success, or %FALSE when there are no more attributes
+ * Since: 2.32
*/
/**
- * g_filename_completer_get_completions:
- * @completer: the filename completer.
- * @initial_text: text to be completed.
+ * g_menu_freeze:
+ * @menu: a #GMenu
*
- * Gets an array of completion strings for a given initial text.
+ * Marks @menu as frozen.
*
- * This array must be freed by g_strfreev() when finished.
+ * After the menu is frozen, it is an error to attempt to make any
+ * changes to it. In effect this means that the #GMenu API must no
+ * longer be used.
*
- * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
+ * This function causes g_menu_model_is_mutable() to begin returning
+ * %FALSE, which has some positive performance implications.
+ *
+ * Since: 2.32
*/
/**
- * g_filename_completer_new:
+ * g_menu_insert:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
*
- * Creates a new filename completer.
+ * Convenience function for inserting a normal menu item into @menu.
+ * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible
+ * alternative.
*
- * Returns: a #GFilenameCompleter.
+ * Since: 2.32
*/
/**
- * g_filename_completer_set_dirs_only:
- * @completer: the filename completer.
- * @dirs_only: a #gboolean.
+ * g_menu_insert_item:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @item: the #GMenuItem to insert
*
- * If @dirs_only is %TRUE, @completer will only
- * complete directory names, and not file names.
+ * Inserts @item into @menu.
+ *
+ * The "insertion" is actually done by copying all of the attribute and
+ * link values of @item and using them to form a new item within @menu.
+ * As such, @item itself is not really inserted, but rather, a menu item
+ * that is exactly the same as the one presently described by @item.
+ *
+ * This means that @item is essentially useless after the insertion
+ * occurs. Any changes you make to it are ignored unless it is inserted
+ * again (at which point its updated values will be copied).
+ *
+ * You should probably just free @item once you're done.
+ *
+ * There are many convenience functions to take care of common cases.
+ * See g_menu_insert(), g_menu_insert_section() and
+ * g_menu_insert_submenu() as well as "prepend" and "append" variants of
+ * each of these functions.
+ *
+ * Since: 2.32
*/
/**
- * g_filter_input_stream_get_base_stream:
- * @stream: a #GFilterInputStream.
+ * g_menu_insert_section:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
*
- * Gets the base stream for the filter stream.
+ * Convenience function for inserting a section menu item into @menu.
+ * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
+ * flexible alternative.
*
- * Returns: (transfer none): a #GInputStream.
+ * Since: 2.32
*/
/**
- * g_filter_input_stream_get_close_base_stream:
- * @stream: a #GFilterInputStream.
+ * g_menu_insert_submenu:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
*
- * Returns whether the base stream will be closed when @stream is
- * closed.
+ * Convenience function for inserting a submenu menu item into @menu.
+ * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
+ * flexible alternative.
*
- * Returns: %TRUE if the base stream will be closed.
+ * Since: 2.32
*/
/**
- * g_filter_input_stream_set_close_base_stream:
- * @stream: a #GFilterInputStream.
- * @close_base: %TRUE to close the base stream.
+ * 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
*
- * Sets whether the base stream will be closed when @stream is closed.
- */
-
-
-/**
- * g_filter_output_stream_get_base_stream:
- * @stream: a #GFilterOutputStream.
+ * Queries the named @attribute on @menu_item.
*
- * Gets the base stream for the filter stream.
+ * 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.
*
- * Returns: (transfer none): a #GOutputStream.
+ * 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_filter_output_stream_get_close_base_stream:
- * @stream: a #GFilterOutputStream.
+ * 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
*
- * Returns whether the base stream will be closed when @stream is
- * closed.
+ * Queries the named @attribute on @menu_item.
*
- * Returns: %TRUE if the base stream will be closed.
+ * 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_filter_output_stream_set_close_base_stream:
- * @stream: a #GFilterOutputStream.
- * @close_base: %TRUE to close the base stream.
+ * g_menu_item_get_link:
+ * @menu_item: a #GMenuItem
+ * @link: the link name to query
*
- * Sets whether the base stream will be closed when @stream is closed.
+ * Queries the named @link on @menu_item.
+ *
+ * Returns: (transfer full): the link, or %NULL
+ * Since: 2.34
*/
/**
- * g_icon_equal:
- * @icon1: pointer to the first #GIcon.
- * @icon2: pointer to the second #GIcon.
+ * g_menu_item_new:
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
*
- * Checks if two icons are equal.
+ * Creates a new #GMenuItem.
*
- * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
+ * If @label is non-%NULL it is used to set the "label" attribute of the
+ * new item.
+ *
+ * If @detailed_action is non-%NULL it is used to set the "action" and
+ * possibly the "target" attribute of the new item. See
+ * g_menu_item_set_detailed_action() for more information.
+ *
+ * Returns: a new #GMenuItem
+ * Since: 2.32
*/
/**
- * g_icon_hash:
- * @icon: #gconstpointer to an icon object.
+ * g_menu_item_new_from_model:
+ * @model: a #GMenuModel
+ * @item_index: the index of an item in @model
*
- * Gets a hash for an icon.
+ * Creates a #GMenuItem as an exact copy of an existing menu item in a
+ * #GMenuModel.
*
- * use in a #GHashTable or similar data structure.
+ * @item_index must be valid (ie: be sure to call
+ * g_menu_model_get_n_items() first).
*
- * Virtual: hash
- * Returns: a #guint containing a hash for the @icon, suitable for
+ * Returns: a new #GMenuItem.
+ * Since: 2.34
*/
/**
- * g_icon_new_for_string:
- * @str: A string obtained via g_icon_to_string().
- * @error: Return location for error.
+ * g_menu_item_new_section:
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
*
- * Generate a #GIcon instance from @str. This function can fail if
- * @str is not valid - see g_icon_to_string() for discussion.
+ * Creates a new #GMenuItem representing a section.
*
- * 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().
+ * This is a convenience API around g_menu_item_new() and
+ * g_menu_item_set_section().
*
- * interface or %NULL if @error is set.
+ * The effect of having one menu appear as a section of another is
+ * exactly as it sounds: the items from @section become a direct part of
+ * the menu that @menu_item is added to.
*
- * Returns: (transfer full): An object implementing the #GIcon
- * Since: 2.20
+ * Visual separation is typically displayed between two non-empty
+ * sections. If @label is non-%NULL then it will be encorporated into
+ * this visual indication. This allows for labeled subsections of a
+ * menu.
+ *
+ * As a simple example, consider a typical "Edit" menu from a simple
+ * program. It probably contains an "Undo" and "Redo" item, followed by
+ * a separator, followed by "Cut", "Copy" and "Paste".
+ *
+ * This would be accomplished by creating three #GMenu instances. The
+ * first would be populated with the "Undo" and "Redo" items, and the
+ * 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:
+ * |[
+ * <menu id='edit-menu'>
+ * <section>
+ * <item label='Undo'/>
+ * <item label='Redo'/>
+ * </section>
+ * <section>
+ * <item label='Cut'/>
+ * <item label='Copy'/>
+ * <item label='Paste'/>
+ * </section>
+ * </menu>
+ * ]|
+ *
+ * The following example is exactly equivalent. It is more illustrative
+ * of the exact relationship between the menus and items (keeping in
+ * mind that the 'link' element defines a new menu that is linked to the
+ * 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).
+ * |[
+ * <menu id='edit-menu'>
+ * <item>
+ * <link name='section'>
+ * <item label='Undo'/>
+ * <item label='Redo'/>
+ * </link>
+ * </item>
+ * <item>
+ * <link name='section'>
+ * <item label='Cut'/>
+ * <item label='Copy'/>
+ * <item label='Paste'/>
+ * </link>
+ * </item>
+ * </menu>
+ * ]|
+ *
+ * Returns: a new #GMenuItem
+ * Since: 2.32
*/
/**
- * g_icon_to_string:
- * @icon: a #GIcon.
+ * g_menu_item_new_submenu:
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
*
- * Generates a textual representation of @icon that can be used for
- * serialization such as when passing @icon to a different process or
- * saving it to persistent storage. Use g_icon_new_for_string() to
- * get @icon back from the returned string.
+ * Creates a new #GMenuItem representing a submenu.
*
- * The encoding of the returned string is proprietary to #GIcon except
- * in the following two cases
+ * This is a convenience API around g_menu_item_new() and
+ * g_menu_item_set_submenu().
*
- * <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>
- *
- * be serialized. Use g_free() to free.
- *
- * Virtual: to_tokens
- * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
- * Since: 2.20
+ * Returns: a new #GMenuItem
+ * Since: 2.32
*/
/**
- * g_inet_address_equal:
- * @address: A #GInetAddress.
- * @other_address: Another #GInetAddress.
+ * g_menu_item_set_action_and_target:
+ * @menu_item: a #GMenuItem
+ * @action: (allow-none): the name of the action for this item
+ * @format_string: (allow-none): a GVariant format string
+ * @...: positional parameters, as per @format_string
*
- * Checks if two #GInetAddress instances are equal, e.g. the same address.
+ * Sets or unsets the "action" and "target" attributes of @menu_item.
*
- * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
- * Since: 2.30
+ * If @action is %NULL then both the "action" and "target" attributes
+ * are unset (and @format_string is ignored along with the positional
+ * parameters).
+ *
+ * If @action is non-%NULL then the "action" attribute is set.
+ * @format_string is then inspected. If it is non-%NULL then the proper
+ * position parameters are collected to create a #GVariant instance to
+ * use as the target value. If it is %NULL then the positional
+ * parameters are ignored and the "target" attribute is unset.
+ *
+ * See also g_menu_item_set_action_and_target_value() for an equivalent
+ * call that directly accepts a #GVariant. See
+ * g_menu_item_set_detailed_action() for a more convenient version that
+ * works with string-typed targets.
+ *
+ * See also g_menu_item_set_action_and_target_value() for a
+ * description of the semantics of the action and target attributes.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_family:
- * @address: a #GInetAddress
+ * g_menu_item_set_action_and_target_value:
+ * @menu_item: a #GMenuItem
+ * @action: (allow-none): the name of the action for this item
+ * @target_value: (allow-none): a #GVariant to use as the action target
*
- * Gets @address's family
+ * Sets or unsets the "action" and "target" attributes of @menu_item.
*
- * Returns: @address's family
- * Since: 2.22
+ * If @action is %NULL then both the "action" and "target" attributes
+ * are unset (and @target_value is ignored).
+ *
+ * If @action is non-%NULL then the "action" attribute is set. The
+ * "target" attribute is then set to the value of @target_value if it is
+ * non-%NULL or unset otherwise.
+ *
+ * Normal menu items (ie: not submenu, section or other custom item
+ * types) are expected to have the "action" attribute set to identify
+ * the action that they are associated with. The state type of the
+ * action help to determine the disposition of the menu item. See
+ * #GAction and #GActionGroup for an overview of actions.
+ *
+ * In general, clicking on the menu item will result in activation of
+ * the named action with the "target" attribute given as the parameter
+ * to the action invocation. If the "target" attribute is not set then
+ * the action is invoked with no parameter.
+ *
+ * If the action has no state then the menu item is usually drawn as a
+ * plain menu item (ie: with no additional decoration).
+ *
+ * If the action has a boolean state then the menu item is usually drawn
+ * as a toggle menu item (ie: with a checkmark or equivalent
+ * indication). The item should be marked as 'toggled' or 'checked'
+ * when the boolean state is %TRUE.
+ *
+ * If the action has a string state then the menu item is usually drawn
+ * as a radio menu item (ie: with a radio bullet or equivalent
+ * indication). The item should be marked as 'selected' when the string
+ * state is equal to the value of the @target property.
+ *
+ * See g_menu_item_set_action_and_target() or
+ * g_menu_item_set_detailed_action() for two equivalent calls that are
+ * probably more convenient for most uses.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_any:
- * @address: a #GInetAddress
+ * g_menu_item_set_attribute:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute to set
+ * @format_string: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as per @format_string
*
- * Tests whether @address is the "any" address for its family.
+ * Sets or unsets an attribute on @menu_item.
*
- * Returns: %TRUE if @address is the "any" address for its family.
- * Since: 2.22
+ * The attribute to set or unset is specified by @attribute. This
+ * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+ * attribute name.
+ * Attribute names are restricted to lowercase characters, numbers
+ * and '-'. Furthermore, the names must begin with a lowercase character,
+ * must not end with a '-', and must not contain consecutive dashes.
+ *
+ * If @format_string is non-%NULL then the proper position parameters
+ * are collected to create a #GVariant instance to use as the attribute
+ * value. If it is %NULL then the positional parameterrs are ignored
+ * and the named attribute is unset.
+ *
+ * See also g_menu_item_set_attribute_value() for an equivalent call
+ * that directly accepts a #GVariant.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_link_local:
- * @address: a #GInetAddress
+ * g_menu_item_set_attribute_value:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute to set
+ * @value: (allow-none): a #GVariant to use as the value, or %NULL
*
- * Tests whether @address is a link-local address (that is, if it
- * identifies a host on a local network that is not connected to the
- * Internet).
+ * Sets or unsets an attribute on @menu_item.
+ *
+ * The attribute to set or unset is specified by @attribute. This
+ * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
+ * attribute name.
+ * Attribute names are restricted to lowercase characters, numbers
+ * and '-'. Furthermore, the names must begin with a lowercase character,
+ * must not end with a '-', and must not contain consecutive dashes.
+ *
+ * must consist only of lowercase
+ * ASCII characters, digits and '-'.
+ *
+ * If @value is non-%NULL then it is used as the new value for the
+ * attribute. If @value is %NULL then the attribute is unset. If
+ * the @value #GVariant is floating, it is consumed.
*
- * Returns: %TRUE if @address is a link-local address.
- * Since: 2.22
+ * See also g_menu_item_set_attribute() for a more convenient way to do
+ * the same.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_loopback:
- * @address: a #GInetAddress
+ * g_menu_item_set_detailed_action:
+ * @menu_item: a #GMenuItem
+ * @detailed_action: the "detailed" action string
*
- * Tests whether @address is the loopback address for its family.
+ * Sets the "action" and possibly the "target" attribute of @menu_item.
*
- * Returns: %TRUE if @address is the loopback address for its family.
- * Since: 2.22
- */
-
-
-/**
- * g_inet_address_get_is_mc_global:
- * @address: a #GInetAddress
+ * The format of @detailed_action is the same format parsed by
+ * g_action_parse_detailed_name().
*
- * Tests whether @address is a global multicast address.
+ * See g_menu_item_set_action_and_target() or
+ * g_menu_item_set_action_and_target_value() for more flexible (but
+ * slightly less convenient) alternatives.
*
- * Returns: %TRUE if @address is a global multicast address.
- * Since: 2.22
+ * See also g_menu_item_set_action_and_target_value() for a description of
+ * the semantics of the action and target attributes.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_mc_link_local:
- * @address: a #GInetAddress
+ * g_menu_item_set_icon:
+ * @menu_item: a #GMenuItem
+ * @icon: a #GIcon, or %NULL
*
- * Tests whether @address is a link-local multicast address.
+ * Sets (or unsets) the icon on @menu_item.
*
- * Returns: %TRUE if @address is a link-local multicast address.
- * Since: 2.22
- */
-
-
-/**
- * g_inet_address_get_is_mc_node_local:
- * @address: a #GInetAddress
+ * 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.
*
- * Tests whether @address is a node-local multicast address.
+ * 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').
*
- * Returns: %TRUE if @address is a node-local multicast address.
- * Since: 2.22
+ * If @icon is %NULL then the icon is unset.
+ *
+ * Since: 2.38
*/
/**
- * g_inet_address_get_is_mc_org_local:
- * @address: a #GInetAddress
+ * g_menu_item_set_label:
+ * @menu_item: a #GMenuItem
+ * @label: (allow-none): the label to set, or %NULL to unset
*
- * Tests whether @address is an organization-local multicast address.
+ * Sets or unsets the "label" attribute of @menu_item.
*
- * Returns: %TRUE if @address is an organization-local multicast address.
- * Since: 2.22
+ * If @label is non-%NULL it is used as the label for the menu item. If
+ * it is %NULL then the label attribute is unset.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_mc_site_local:
- * @address: a #GInetAddress
+ * g_menu_item_set_link:
+ * @menu_item: a #GMenuItem
+ * @link: type of link to establish or unset
+ * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
*
- * Tests whether @address is a site-local multicast address.
+ * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
*
- * Returns: %TRUE if @address is a site-local multicast address.
- * Since: 2.22
+ * Links are used to establish a relationship between a particular menu
+ * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
+ * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
+ * is used to create a section. Other types of link can be used, but there
+ * is no guarantee that clients will be able to make sense of them.
+ * Link types are restricted to lowercase characters, numbers
+ * and '-'. Furthermore, the names must begin with a lowercase character,
+ * must not end with a '-', and must not contain consecutive dashes.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_multicast:
- * @address: a #GInetAddress
+ * g_menu_item_set_section:
+ * @menu_item: a #GMenuItem
+ * @section: (allow-none): a #GMenuModel, or %NULL
*
- * Tests whether @address is a multicast address.
+ * Sets or unsets the "section" link of @menu_item to @section.
*
- * Returns: %TRUE if @address is a multicast address.
- * Since: 2.22
+ * The effect of having one menu appear as a section of another is
+ * exactly as it sounds: the items from @section become a direct part of
+ * the menu that @menu_item is added to. See g_menu_item_new_section()
+ * for more information about what it means for a menu item to be a
+ * section.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_is_site_local:
- * @address: a #GInetAddress
+ * g_menu_item_set_submenu:
+ * @menu_item: a #GMenuItem
+ * @submenu: (allow-none): a #GMenuModel, or %NULL
*
- * Tests whether @address is a site-local address such as 10.0.0.1
- * (that is, the address identifies a host on a local network that can
- * not be reached directly from the Internet, but which may have
- * outgoing Internet connectivity via a NAT or firewall).
+ * Sets or unsets the "submenu" link of @menu_item to @submenu.
*
- * Returns: %TRUE if @address is a site-local address.
- * Since: 2.22
+ * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
+ * link is unset.
+ *
+ * The effect of having one menu appear as a submenu of another is
+ * exactly as it sounds.
+ *
+ * Since: 2.32
*/
/**
- * g_inet_address_get_native_size:
- * @address: a #GInetAddress
+ * g_menu_link_iter_get_name:
+ * @iter: a #GMenuLinkIter
*
- * Gets the size of the native raw binary address for @address. This
- * is the size of the data that you get from g_inet_address_to_bytes().
+ * Gets the name of the link at the current iterator position.
*
- * Returns: the number of bytes used for the native version of @address.
- * Since: 2.22
+ * The iterator is not advanced.
+ *
+ * Returns: the type of the link
+ * Since: 2.32
*/
/**
- * g_inet_address_mask_equal:
- * @mask: a #GInetAddressMask
- * @mask2: another #GInetAddressMask
+ * g_menu_link_iter_get_next:
+ * @iter: a #GMenuLinkIter
+ * @out_link: (out) (allow-none) (transfer none): the name of the link
+ * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
*
- * Tests if @mask and @mask2 are the same mask.
+ * This function combines g_menu_link_iter_next() with
+ * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
*
- * Returns: whether @mask and @mask2 are the same mask
+ * First the iterator is advanced to the next (possibly first) link.
+ * If that fails, then %FALSE is returned and there are no other effects.
+ *
+ * If successful, @out_link and @value are set to the name and #GMenuModel
+ * of the link that has just been advanced to. At this point,
+ * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
+ * same values again.
+ *
+ * The value returned in @out_link remains valid for as long as the iterator
+ * remains at the current position. The value returned in @value must
+ * be unreffed using g_object_unref() when it is no longer in use.
+ *
+ * Returns: %TRUE on success, or %FALSE if there is no additional link
* Since: 2.32
*/
/**
- * g_inet_address_mask_get_address:
- * @mask: a #GInetAddressMask
+ * g_menu_link_iter_get_value:
+ * @iter: a #GMenuLinkIter
*
- * Gets @mask's base address
+ * Gets the linked #GMenuModel at the current iterator position.
*
- * Returns: (transfer none): @mask's base address
+ * The iterator is not advanced.
+ *
+ * Returns: (transfer full): the #GMenuModel that is linked to
* Since: 2.32
*/
/**
- * g_inet_address_mask_get_family:
- * @mask: a #GInetAddressMask
+ * g_menu_link_iter_next:
+ * @iter: a #GMenuLinkIter
*
- * Gets the #GSocketFamily of @mask's address
+ * Attempts to advance the iterator to the next (possibly first)
+ * link.
*
- * Returns: the #GSocketFamily of @mask's address
+ * %TRUE is returned on success, or %FALSE if there are no more links.
+ *
+ * You must call this function when you first acquire the iterator to
+ * advance it to the first link (and determine if the first link exists
+ * at all).
+ *
+ * Returns: %TRUE on success, or %FALSE when there are no more links
* Since: 2.32
*/
/**
- * g_inet_address_mask_get_length:
- * @mask: a #GInetAddressMask
+ * g_menu_model_get_item_attribute:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @attribute: the attribute to query
+ * @format_string: a #GVariant format string
+ * @...: positional parameters, as per @format_string
*
- * Gets @mask's length
+ * Queries item at position @item_index in @model for the attribute
+ * specified by @attribute.
*
- * Returns: @mask's length
+ * 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.
+ *
+ * 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
*/
/**
- * g_inet_address_mask_matches:
- * @mask: a #GInetAddressMask
- * @address: a #GInetAddress
+ * g_menu_model_get_item_attribute_value:
+ * @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
*
- * Tests if @address falls within the range described by @mask.
+ * Queries the item at position @item_index in @model for the attribute
+ * specified by @attribute.
*
- * @mask.
+ * If @expected_type is non-%NULL then it specifies the expected type of
+ * the attribute. If it is %NULL then any type will be accepted.
*
- * Returns: whether @address falls within the range described by
+ * If the attribute exists and matches @expected_type (or if the
+ * expected type is unspecified) then the value is returned.
+ *
+ * If the attribute does not exist, or does not match the expected type
+ * then %NULL is returned.
+ *
+ * Returns: (transfer full): the value of the attribute
* Since: 2.32
*/
/**
- * g_inet_address_mask_new:
- * @addr: a #GInetAddress
- * @length: number of bits of @addr to use
- * @error: return location for #GError, or %NULL
+ * g_menu_model_get_item_link:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @link: the link to query
*
- * Creates a new #GInetAddressMask representing all addresses whose
- * first @length bits match @addr.
+ * Queries the item at position @item_index in @model for the link
+ * specified by @link.
*
- * Returns: a new #GInetAddressMask, or %NULL on error
+ * If the link exists, the linked #GMenuModel is returned. If the link
+ * does not exist, %NULL is returned.
+ *
+ * Returns: (transfer full): the linked #GMenuModel, or %NULL
* Since: 2.32
*/
/**
- * g_inet_address_mask_new_from_string:
- * @mask_string: an IP address or address/length string
- * @error: return location for #GError, or %NULL
- *
- * Parses @mask_string as an IP address and (optional) length, and
- * creates a new #GInetAddressMask. The length, if present, is
- * delimited by a "/". If it is not present, then the length is
- * assumed to be the full length of the address.
+ * g_menu_model_get_n_items:
+ * @model: a #GMenuModel
*
- * on error.
+ * Query the number of items in @model.
*
- * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
+ * Returns: the number of items
* Since: 2.32
*/
/**
- * g_inet_address_mask_to_string:
- * @mask: a #GInetAddressMask
+ * g_menu_model_is_mutable:
+ * @model: a #GMenuModel
*
- * Converts @mask back to its corresponding string form.
+ * Queries if @model is mutable.
+ *
+ * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
+ * signal. Consumers of the model may make optimisations accordingly.
*
- * Returns: a string corresponding to @mask.
+ * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
+ * emitted).
* Since: 2.32
*/
/**
- * g_inet_address_new_any:
- * @family: the address family
+ * g_menu_model_items_changed:
+ * @model: a #GMenuModel
+ * @position: the position of the change
+ * @removed: the number of items removed
+ * @added: the number of items added
*
- * Creates a #GInetAddress for the "any" address (unassigned/"don't
- * care") for @family.
+ * Requests emission of the #GMenuModel::items-changed signal on @model.
*
- * for @family.
+ * This function should never be called except by #GMenuModel
+ * subclasses. Any other calls to this function will very likely lead
+ * to a violation of the interface of the model.
*
- * Returns: a new #GInetAddress corresponding to the "any" address
- * Since: 2.22
- */
-
-
-/**
- * g_inet_address_new_from_bytes:
- * @bytes: raw address data
- * @family: the address family of @bytes
+ * The implementation should update its internal representation of the
+ * menu before emitting the signal. The implementation should further
+ * expect to receive queries about the new state of the menu (and
+ * particularly added menu items) while signal handlers are running.
*
- * Creates a new #GInetAddress from the given @family and @bytes.
- * @bytes should be 4 bytes for %G_INET_ADDRESS_IPV4 and 16 bytes for
- * %G_INET_ADDRESS_IPV6.
+ * The implementation must dispatch this call directly from a mainloop
+ * entry and not in response to calls -- particularly those from the
+ * #GMenuModel API. Said another way: the menu must not change while
+ * user code is running without returning to the mainloop.
*
- * Returns: a new #GInetAddress corresponding to @family and @bytes.
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_inet_address_new_from_string:
- * @string: a string representation of an IP address
+ * g_menu_model_iterate_item_attributes:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
*
- * Parses @string as an IP address and creates a new #GInetAddress.
+ * Creates a #GMenuAttributeIter to iterate over the attributes of
+ * the item at position @item_index in @model.
*
- * @string could not be parsed.
+ * You must free the iterator with g_object_unref() when you are done.
*
- * Returns: a new #GInetAddress corresponding to @string, or %NULL if
- * Since: 2.22
+ * Returns: (transfer full): a new #GMenuAttributeIter
+ * Since: 2.32
*/
/**
- * g_inet_address_new_loopback:
- * @family: the address family
+ * g_menu_model_iterate_item_links:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
*
- * Creates a #GInetAddress for the loopback address for @family.
+ * Creates a #GMenuLinkIter to iterate over the links of the item at
+ * position @item_index in @model.
*
- * for @family.
+ * You must free the iterator with g_object_unref() when you are done.
*
- * Returns: a new #GInetAddress corresponding to the loopback address
- * Since: 2.22
+ * Returns: (transfer full): a new #GMenuLinkIter
+ * Since: 2.32
*/
/**
- * g_inet_address_to_bytes: (skip)
- * @address: a #GInetAddress
+ * g_menu_new:
*
- * Gets the raw binary address data from @address.
+ * Creates a new #GMenu.
*
- * which should not be modified, stored, or freed. The size of this
- * array can be gotten with g_inet_address_get_native_size().
+ * The new menu has no items.
*
- * Returns: a pointer to an internal array of the bytes in @address,
- * Since: 2.22
+ * Returns: a new #GMenu
+ * Since: 2.32
*/
/**
- * g_inet_address_to_string:
- * @address: a #GInetAddress
- *
- * Converts @address to string form.
+ * g_menu_prepend:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
*
- * freed after use.
+ * Convenience function for prepending a normal menu item to the start
+ * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more
+ * flexible alternative.
*
- * Returns: a representation of @address as a string, which should be
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_inet_socket_address_get_address:
- * @address: a #GInetSocketAddress
+ * g_menu_prepend_item:
+ * @menu: a #GMenu
+ * @item: a #GMenuItem to prepend
*
- * Gets @address's #GInetAddress.
+ * Prepends @item to the start of @menu.
*
- * g_object_ref()'d if it will be stored
+ * See g_menu_insert_item() for more information.
*
- * Returns: (transfer none): the #GInetAddress for @address, which must be
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_inet_socket_address_get_port:
- * @address: a #GInetSocketAddress
+ * g_menu_prepend_section:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
*
- * Gets @address's port.
+ * Convenience function for prepending a section menu item to the start
+ * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
+ * a more flexible alternative.
*
- * Returns: the port for @address
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_inet_socket_address_new:
- * @address: a #GInetAddress
- * @port: a port number
+ * g_menu_prepend_submenu:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
*
- * Creates a new #GInetSocketAddress for @address and @port.
+ * Convenience function for prepending a submenu menu item to the start
+ * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
+ * a more flexible alternative.
*
- * Returns: a new #GInetSocketAddress
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * 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.
+ * g_menu_remove:
+ * @menu: a #GMenu
+ * @position: the position of the item to remove
*
- * Initializes the object implementing the interface.
+ * Removes an item from the menu.
*
- * The object must be initialized before any real use after initial
- * construction, either with this function or g_async_initable_init_async().
+ * @position gives the index of the item to remove.
*
- * Implementations may also support cancellation. If @cancellable is not %NULL,
- * then initialization 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 and
- * the object doesn't support cancellable initialization the error
- * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+ * It is an error if position is not in range the range from 0 to one
+ * less than the number of items in the menu.
*
- * 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.
+ * It is not possible to remove items by identity since items are added
+ * to the menu simply by copying their links and attributes (ie:
+ * identity of the item itself is not preserved).
*
- * Implementations of this method must be idempotent, i.e. multiple calls
- * to this function with the same argument should return the same results.
- * Only the first call initializes the object, further calls return the result
- * of the first call. This is so that it's safe to implement the singleton
- * pattern in the GObject constructor function.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_menu_remove_all:
+ * @menu: a #GMenu
*
- * return %FALSE and set @error appropriately if present.
+ * Removes all items in the menu.
*
- * Returns: %TRUE if successful. If an error has occurred, this function will
- * Since: 2.22
+ * Since: 2.38
*/
/**
- * 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: 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.
+ * g_mount_can_eject:
+ * @mount: a #GMount.
*
- * Helper function for constructing #GInitiable object. This is
- * similar to g_object_new() but also initializes the object
- * and returns %NULL, setting an error on failure.
+ * Checks if @mount can be eject.
*
- * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
- * Since: 2.22
+ * Returns: %TRUE if the @mount can be ejected.
*/
/**
- * 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.
- * @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.
+ * g_mount_can_unmount:
+ * @mount: a #GMount.
*
- * Helper function for constructing #GInitiable object. This is
- * similar to g_object_new_valist() but also initializes the object
- * and returns %NULL, setting an error on failure.
+ * Checks if @mount can be mounted.
*
- * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
- * Since: 2.22
+ * Returns: %TRUE if the @mount can be unmounted.
*/
/**
- * g_initable_newv:
- * @object_type: a #GType supporting #GInitable.
- * @n_parameters: the number of parameters in @parameters
- * @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.
+ * g_mount_eject:
+ * @mount: a #GMount.
+ * @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.
+ * @user_data: user data passed to @callback.
*
- * Helper function for constructing #GInitiable object. This is
- * similar to g_object_newv() but also initializes the object
- * and returns %NULL, setting an error on failure.
+ * Ejects a mount. This is an asynchronous operation, and is
+ * finished by calling g_mount_eject_finish() with the @mount
+ * and #GAsyncResult data returned in the @callback.
*
- * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
- * Since: 2.22
+ * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
*/
/**
- * g_input_stream_clear_pending:
- * @stream: input stream
+ * g_mount_eject_finish:
+ * @mount: a #GMount.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Clears the pending flag on @stream.
+ * Finishes ejecting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
+ *
+ * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
+ * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
*/
/**
- * g_input_stream_close:
- * @stream: A #GInputStream.
+ * 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.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @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.
- *
- * Streams will be automatically closed when the last reference
- * is dropped, but you might want to call this function to make sure
- * resources are released as early as possible.
- *
- * Some streams might keep the backing store of the stream (e.g. a file descriptor)
- * open after the stream is closed. See the documentation for the individual
- * stream for details.
- *
- * On failure the first error that happened will be reported, but the close
- * operation will finish as much as possible. A stream that failed to
- * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
- * is important to check and report the error to the user.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @user_data: user data passed to @callback.
*
- * 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.
- * Cancelling a close will still leave the stream closed, but some streams
- * can use a faster close that doesn't block to e.g. check errors.
+ * Ejects a mount. This is an asynchronous operation, and is
+ * finished by calling g_mount_eject_with_operation_finish() with the @mount
+ * and #GAsyncResult data returned in the @callback.
*
- * Returns: %TRUE on success, %FALSE on failure
+ * 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.
- * @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
- *
- * Requests an asynchronous closes of the stream, releasing resources related to it.
- * When the operation is finished @callback will be called.
- * You can then call g_input_stream_close_finish() to get the result of the
- * operation.
+ * 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.
*
- * For behaviour details see g_input_stream_close().
+ * Finishes ejecting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
- * The asyncronous methods have a default fallback that uses threads to implement
- * asynchronicity, so they are optional for inheriting classes. However, if you
- * override one you must override all.
+ * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_input_stream_close_finish:
- * @stream: a #GInputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_mount_get_default_location:
+ * @mount: a #GMount.
*
- * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
+ * Gets the default location of @mount. The default location of the given
+ * @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: %TRUE if the stream was closed successfully.
+ * Returns: (transfer full): a #GFile.
+ * The returned object should be unreffed with
+ * g_object_unref() when no longer needed.
*/
/**
- * g_input_stream_has_pending:
- * @stream: input stream.
+ * g_mount_get_drive:
+ * @mount: a #GMount.
*
- * Checks if an input stream has pending actions.
+ * Gets the drive for the @mount.
*
- * Returns: %TRUE if @stream has pending actions.
+ * 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.
*/
/**
- * g_input_stream_is_closed:
- * @stream: input stream.
+ * g_mount_get_icon:
+ * @mount: a #GMount.
*
- * Checks if an input stream is closed.
+ * Gets the icon for @mount.
*
- * Returns: %TRUE if the stream is closed.
+ * Returns: (transfer full): a #GIcon.
+ * The returned object should be unreffed with
+ * g_object_unref() when no longer needed.
*/
/**
- * g_input_stream_read:
- * @stream: a #GInputStream.
- * @buffer: 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
- *
- * Tries to read @count bytes from the stream into the buffer starting at
- * @buffer. Will block during this read.
- *
- * If count is zero returns zero and does nothing. A value of @count
- * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
- *
- * On success, the number of bytes read into the buffer is returned.
- * It is not an error if this is not the same as the requested size, as it
- * 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.
- *
- * 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.
+ * g_mount_get_name:
+ * @mount: a #GMount.
*
- * On error -1 is returned and @error is set accordingly.
+ * Gets the name of @mount.
*
- * Returns: Number of bytes read, or -1 on error
+ * Returns: the name for the given @mount.
+ * The returned string should be freed with g_free()
+ * when no longer needed.
*/
/**
- * g_input_stream_read_all:
- * @stream: a #GInputStream.
- * @buffer: 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.
- * @error: location to store the error occurring, or %NULL to ignore
- *
- * Tries to read @count bytes from the stream into the buffer starting at
- * @buffer. Will block during this read.
- *
- * This function is similar to g_input_stream_read(), except it tries to
- * read as many bytes as requested, only stopping on an error or end of stream.
- *
- * On a successful read of @count bytes, or if we reached the end of the
- * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
- * read into @buffer.
+ * g_mount_get_root:
+ * @mount: a #GMount.
*
- * 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.
+ * Gets the root directory on @mount.
*
- * Returns: %TRUE on success, %FALSE if there was an error
+ * Returns: (transfer full): a #GFile.
+ * The returned object should be unreffed with
+ * g_object_unref() when no longer needed.
*/
/**
- * g_input_stream_read_async:
- * @stream: A #GInputStream.
- * @buffer: 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.
- * @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_mount_get_sort_key:
+ * @mount: A #GMount.
*
- * Request an asynchronous read of @count bytes from the stream into the buffer
- * starting at @buffer. When the operation is finished @callback will be called.
- * You can then call g_input_stream_read_finish() to get the result of the
- * operation.
+ * Gets the sort key for @mount, if any.
*
- * During an async request no other sync and async calls are allowed on @stream, and will
- * result in %G_IO_ERROR_PENDING errors.
+ * Returns: Sorting key for @mount or %NULL if no such key is available.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_mount_get_symbolic_icon:
+ * @mount: a #GMount.
*
- * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ * Gets the symbolic icon for @mount.
*
- * On success, the number of bytes read into the buffer 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. near the end of a file, but generally we try to read
- * as many bytes as requested. Zero is returned on end of file
- * (or if @count is zero), but never otherwise.
+ * 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.
*
- * 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.
+ * Gets the UUID for the @mount. The reference is typically based on
+ * the file system UUID for the mount in question and should be
+ * considered an opaque string. Returns %NULL if there is no UUID
+ * available.
*
- * The asyncronous methods have a default fallback that uses threads to implement
- * asynchronicity, so they are optional for inheriting classes. However, if you
- * override one you must override all.
+ * 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.
*/
/**
- * g_input_stream_read_finish:
- * @stream: a #GInputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_mount_get_volume:
+ * @mount: a #GMount.
*
- * Finishes an asynchronous stream read operation.
+ * Gets the volume for the @mount.
*
- * Returns: number of bytes read in, or -1 on error.
+ * 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_input_stream_set_pending:
- * @stream: input stream
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * 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
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: a #GAsyncReadyCallback
+ * @user_data: user data passed to @callback
*
- * Sets @stream to have actions pending. If the pending flag is
- * already set or @stream is closed, it will return %FALSE and set
- * @error.
+ * 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
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+ * specification for more on x-content types.
*
- * Returns: %TRUE if pending was previously unset and is now set.
+ * This is an asynchronous operation (see
+ * g_mount_guess_content_type_sync() for the synchronous version), and
+ * is finished by calling g_mount_guess_content_type_finish() with the
+ * @mount and #GAsyncResult data returned in the @callback.
+ *
+ * Since: 2.18
*/
/**
- * g_input_stream_skip:
- * @stream: a #GInputStream.
- * @count: the number of bytes that will be skipped from the stream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: location to store the error occurring, or %NULL to ignore
+ * 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
*
- * Tries to skip @count bytes from the stream. Will block during the operation.
+ * Finishes guessing content types of @mount. If any errors occurred
+ * during the operation, @error will be set to contain the errors and
+ * %FALSE will be returned. In particular, you may get an
+ * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
+ * guessing.
*
- * This is identical to g_input_stream_read(), from a behaviour standpoint,
- * but the bytes that are skipped are not returned to the user. Some
- * streams have an implementation that is more efficient than reading the data.
+ * 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
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore
*
- * This function is optional for inherited classes, as the default implementation
- * emulates it using read.
+ * 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
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
+ * specification for more on x-content types.
*
- * 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.
+ * This is an synchronous operation and as such may block doing IO;
+ * see g_mount_guess_content_type() for the asynchronous version.
*
- * Returns: Number of bytes skipped, or -1 on error
+ * 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_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.
- * @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 skip of @count bytes from the stream.
- * When the operation is finished @callback will be called.
- * You can then call g_input_stream_skip_finish() to get the result
- * of the operation.
+ * g_mount_is_shadowed:
+ * @mount: A #GMount.
*
- * During an async request no other sync and async calls are allowed,
- * and will result in %G_IO_ERROR_PENDING errors.
+ * Determines if @mount is shadowed. Applications or libraries should
+ * avoid displaying @mount in the user interface if it is shadowed.
*
- * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ * A mount is said to be shadowed if there exists one or more user
+ * visible objects (currently #GMount objects) with a root that is
+ * inside the root of @mount.
*
- * On success, the number of bytes skipped 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. near the end of a file, but generally we try to skip
- * as many bytes as requested. Zero is returned on end of file
- * (or if @count is zero), but never otherwise.
+ * One application of shadow mounts is when exposing a single file
+ * system that is used to address several logical volumes. In this
+ * 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 `gphoto2://[usb:001,002]/store1/`
+ * and `gphoto2://[usb:001,002]/store2/`. When the
+ * underlying mount (with root
+ * `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.
*
- * 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.
+ * The proxy monitor in GVfs 2.26 and later, automatically creates and
+ * manage shadow mounts (and shadows the underlying mount) if the
+ * activation root on a #GVolume is set.
*
- * The asynchronous methods have a default fallback that uses threads to
- * implement asynchronicity, so they are optional for inheriting classes.
- * However, if you override one, you must override all.
+ * Returns: %TRUE if @mount is shadowed.
+ * Since: 2.20
*/
/**
- * g_input_stream_skip_finish:
- * @stream: a #GInputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_mount_operation_get_anonymous:
+ * @op: a #GMountOperation.
*
- * Finishes a stream skip operation.
+ * Check to see whether the mount operation is being used
+ * for an anonymous user.
*
- * Returns: the size of the bytes skipped, or %-1 on error.
+ * Returns: %TRUE if mount operation is anonymous.
*/
/**
- * g_io_error_from_errno:
- * @err_no: Error number as defined in errno.h.
+ * g_mount_operation_get_choice:
+ * @op: a #GMountOperation.
*
- * Converts errno.h error codes into GIO error codes.
+ * Gets a choice from the mount operation.
*
- * Returns: #GIOErrorEnum value for the given errno.h error number.
+ * Returns: an integer containing an index of the user's choice from
+ * the choice's list, or %0.
*/
/**
- * g_io_error_from_win32_error:
- * @error_code: Windows error number.
+ * g_mount_operation_get_domain:
+ * @op: a #GMountOperation.
*
- * Converts some common error codes into GIO error codes. The
- * fallback value G_IO_ERROR_FAILED is returned for error codes not
- * handled.
+ * Gets the domain of the mount operation.
*
- * Returns: #GIOErrorEnum value for the given error number.
- * Since: 2.26
+ * Returns: a string set to the domain.
*/
/**
- * g_io_error_quark:
+ * g_mount_operation_get_password:
+ * @op: a #GMountOperation.
*
- * Gets the GIO Error Quark.
+ * Gets a password from the mount operation.
*
- * Returns: a #GQuark.
+ * Returns: a string containing the password within @op.
*/
/**
- * g_io_extension_get_name:
- * @extension: a #GIOExtension
- *
- * Gets the name under which @extension was registered.
+ * g_mount_operation_get_password_save:
+ * @op: a #GMountOperation.
*
- * Note that the same type may be registered as extension
- * for multiple extension points, under different names.
+ * Gets the state of saving passwords for the mount operation.
*
- * Returns: the name of @extension.
+ * Returns: a #GPasswordSave flag.
*/
/**
- * g_io_extension_get_priority:
- * @extension: a #GIOExtension
+ * g_mount_operation_get_username:
+ * @op: a #GMountOperation.
*
- * Gets the priority with which @extension was registered.
+ * Get the user name from the mount operation.
*
- * Returns: the priority of @extension
+ * Returns: a string containing the user name.
*/
/**
- * g_io_extension_get_type:
- * @extension: a #GIOExtension
+ * g_mount_operation_new:
*
- * Gets the type associated with @extension.
+ * Creates a new mount operation.
*
- * Returns: the type of @extension
+ * Returns: a #GMountOperation.
*/
/**
- * g_io_extension_point_get_extension_by_name:
- * @extension_point: a #GIOExtensionPoint
- * @name: the name of the extension to get
- *
- * Finds a #GIOExtension for an extension point by name.
- *
- * given name, or %NULL if there is no extension with that name
+ * g_mount_operation_reply:
+ * @op: a #GMountOperation
+ * @result: a #GMountOperationResult
*
- * Returns: (transfer none): the #GIOExtension for @extension_point that has the
+ * Emits the #GMountOperation::reply signal.
*/
/**
- * g_io_extension_point_get_extensions:
- * @extension_point: a #GIOExtensionPoint
- *
- * Gets a list of all extensions that implement this extension point.
- * The list is sorted by priority, beginning with the highest priority.
- *
- * #GIOExtension<!-- -->s. The list is owned by GIO and should not be
- * modified.
+ * g_mount_operation_set_anonymous:
+ * @op: a #GMountOperation.
+ * @anonymous: boolean value.
*
- * Returns: (element-type GIOExtension) (transfer none): a #GList of
+ * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
*/
/**
- * g_io_extension_point_get_required_type:
- * @extension_point: a #GIOExtensionPoint
- *
- * Gets the required type for @extension_point.
- *
- * or #G_TYPE_INVALID if the extension point has no required type
+ * g_mount_operation_set_choice:
+ * @op: a #GMountOperation.
+ * @choice: an integer.
*
- * Returns: the #GType that all implementations must have,
+ * Sets a default choice for the mount operation.
*/
/**
- * g_io_extension_point_implement:
- * @extension_point_name: the name of the extension point
- * @type: the #GType to register as extension
- * @extension_name: the name for the extension
- * @priority: the priority for the extension
- *
- * Registers @type as extension for the extension point with name
- * @extension_point_name.
- *
- * If @type has already been registered as an extension for this
- * extension point, the existing #GIOExtension object is returned.
+ * g_mount_operation_set_domain:
+ * @op: a #GMountOperation.
+ * @domain: the domain to set.
*
- * Returns: (transfer none): a #GIOExtension object for #GType
+ * Sets the mount operation's domain.
*/
/**
- * g_io_extension_point_lookup:
- * @name: the name of the extension point
- *
- * Looks up an existing extension point.
- *
- * is no registered extension point with the given name.
+ * g_mount_operation_set_password:
+ * @op: a #GMountOperation.
+ * @password: password to set.
*
- * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
+ * Sets the mount operation's password to @password.
*/
/**
- * g_io_extension_point_register:
- * @name: The name of the extension point
- *
- * Registers an extension point.
- *
- * owned by GIO and should not be freed.
+ * g_mount_operation_set_password_save:
+ * @op: a #GMountOperation.
+ * @save: a set of #GPasswordSave flags.
*
- * Returns: (transfer none): the new #GIOExtensionPoint. This object is
+ * Sets the state of saving passwords for the mount operation.
*/
/**
- * g_io_extension_point_set_required_type:
- * @extension_point: a #GIOExtensionPoint
- * @type: the #GType to require
+ * g_mount_operation_set_username:
+ * @op: a #GMountOperation.
+ * @username: input username.
*
- * Sets the required type for @extension_point to @type.
- * All implementations must henceforth have this type.
+ * Sets the user name within @op to @username.
*/
/**
- * g_io_extension_ref_class:
- * @extension: a #GIOExtension
+ * g_mount_remount:
+ * @mount: a #GMount.
+ * @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.
+ * @user_data: user data passed to @callback.
*
- * Gets a reference to the class for the type that is
- * associated with @extension.
+ * Remounts a mount. This is an asynchronous operation, and is
+ * finished by calling g_mount_remount_finish() with the @mount
+ * and #GAsyncResults data returned in the @callback.
*
- * Returns: (transfer full): the #GTypeClass for the type of @extension
+ * Remounting is useful when some setting affecting the operation
+ * of the volume has been changed, as these may need a remount to
+ * take affect. While this is semantically equivalent with unmounting
+ * and then remounting not all backends might need to actually be
+ * unmounted.
*/
/**
- * g_io_module_load:
- * @module: a #GIOModule.
+ * g_mount_remount_finish:
+ * @mount: a #GMount.
+ * @result: a #GAsyncResult.
+ * @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.
*
- * Required API for GIO modules to implement.
- * This function is ran after the module has been loaded into GIO,
- * to initialize the module.
+ * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
*/
/**
- * g_io_module_new:
- * @filename: filename of the shared library module.
+ * g_mount_shadow:
+ * @mount: A #GMount.
*
- * Creates a new GIOModule that will load the specific
- * shared library when in use.
+ * Increments the shadow count on @mount. Usually used by
+ * #GVolumeMonitor implementations when creating a shadow mount for
+ * @mount, see g_mount_is_shadowed() for more information. The caller
+ * will need to emit the #GMount::changed signal on @mount manually.
*
- * or %NULL on error.
+ * Since: 2.20
+ */
+
+
+/**
+ * g_mount_unmount:
+ * @mount: a #GMount.
+ * @flags: flags affecting the operation
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @user_data: user data passed to @callback.
*
- * Returns: a #GIOModule from given @filename,
+ * Unmounts a mount. This is an asynchronous operation, and is
+ * finished by calling g_mount_unmount_finish() with the @mount
+ * and #GAsyncResult data returned in the @callback.
+ *
+ * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
*/
/**
- * g_io_module_query:
+ * g_mount_unmount_finish:
+ * @mount: a #GMount.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Optional API for GIO modules to implement.
+ * Finishes unmounting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
- * Should return a list of all the extension points that may be
- * implemented in this module.
+ * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+ * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
+ */
+
+
+/**
+ * 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.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @user_data: user data passed to @callback.
*
- * This method will not be called in normal use, however it may be
- * called when probing existing modules and recording which extension
- * points that this model is used for. This means we won't have to
- * load and initialze this module unless its needed.
+ * Unmounts a mount. This is an asynchronous operation, and is
+ * finished by calling g_mount_unmount_with_operation_finish() with the @mount
+ * and #GAsyncResult data returned in the @callback.
*
- * If this function is not implemented by the module the module will
- * always be loaded, initialized and then unloaded on application startup
- * so that it can register its extension points during init.
+ * Since: 2.22
+ */
+
+
+/**
+ * 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.
*
- * Note that a module need not actually implement all the extension points
- * that g_io_module_query returns, since the exact list of extension may
- * depend on runtime issues. However all extension points actually implemented
- * must be returned by g_io_module_query() (if defined).
+ * Finishes unmounting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
- * When installing a module that implements g_io_module_query you must
- * run gio-querymodules in order to build the cache files required for
- * lazy loading.
+ * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_mount_unshadow:
+ * @mount: A #GMount.
*
- * extension points of the module. The array must be suitable for
- * freeing with g_strfreev().
+ * Decrements the shadow count on @mount. Usually used by
+ * #GVolumeMonitor implementations when destroying a shadow mount for
+ * @mount, see g_mount_is_shadowed() for more information. The caller
+ * will need to emit the #GMount::changed signal on @mount manually.
*
- * Returns: (transfer full): A %NULL-terminated array of strings, listing the supported
- * Since: 2.24
+ * Since: 2.20
*/
/**
- * g_io_module_scope_block:
- * @scope: a module loading scope
- * @basename: the basename to block
+ * g_network_address_get_hostname:
+ * @addr: a #GNetworkAddress
*
- * Block modules with the given @basename from being loaded when
- * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
- * or g_io_modules_load_all_in_directory_with_scope().
+ * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
+ * depending on what @addr was created with.
*
- * Since: 2.30
+ * Returns: @addr's hostname
+ * Since: 2.22
*/
/**
- * g_io_module_scope_free:
- * @scope: a module loading scope
+ * g_network_address_get_port:
+ * @addr: a #GNetworkAddress
*
- * Free a module scope.
+ * Gets @addr's port number
*
- * Since: 2.30
+ * Returns: @addr's port (which may be 0)
+ * Since: 2.22
*/
/**
- * g_io_module_scope_new:
- * @flags: flags for the new scope
- *
- * Create a new scope for loading of IO modules. A scope can be used for
- * blocking duplicate modules, or blocking a module you don't want to load.
+ * g_network_address_get_scheme:
+ * @addr: a #GNetworkAddress
*
- * Specify the %G_IO_MODULES_SCOPE_BLOCK_DUPLICATES flag to block modules
- * which have the same base name as a module that has already been seen
- * in this scope.
+ * Gets @addr's scheme
*
- * Returns: (transfer full): the new module scope
- * Since: 2.30
+ * Returns: @addr's scheme (%NULL if not built from URI)
+ * Since: 2.26
*/
/**
- * g_io_module_unload:
- * @module: a #GIOModule.
+ * g_network_address_new:
+ * @hostname: the hostname
+ * @port: the port
+ *
+ * Creates a new #GSocketConnectable for connecting to the given
+ * @hostname and @port.
*
- * Required API for GIO modules to implement.
- * This function is ran when the module is being unloaded from GIO,
- * to finalize the module.
+ * 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_io_modules_load_all_in_directory:
- * @dirname: pathname for a directory containing modules to load.
+ * g_network_address_new_loopback:
+ * @port: the port
*
- * Loads all the modules in the specified directory.
+ * 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.
*
- * If don't require all modules to be initialized (and thus registering
- * all gtypes) then you can use g_io_modules_scan_all_in_directory()
- * which allows delayed/lazy loading of modules.
+ * 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`.
*
- * 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().
+ * g_network_address_get_hostname() will always return `localhost` for
+ * #GNetworkAddresses created with this constructor.
*
- * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
+ * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
+ * Since: 2.44
*/
/**
- * g_io_modules_load_all_in_directory_with_scope:
- * @dirname: pathname for a directory containing modules to load.
- * @scope: a scope to use when scanning the modules.
+ * g_network_address_parse:
+ * @host_and_port: the hostname and optionally a port
+ * @default_port: the default port if not in @host_and_port
+ * @error: a pointer to a #GError, or %NULL
*
- * Loads all the modules in the specified directory.
+ * Creates a new #GSocketConnectable for connecting to the given
+ * @hostname and @port. May fail and return %NULL in case
+ * parsing @host_and_port fails.
*
- * If don't require all modules to be initialized (and thus registering
- * all gtypes) then you can use g_io_modules_scan_all_in_directory()
- * which allows delayed/lazy loading of modules.
+ * @host_and_port may be in any of a number of recognised formats; an IPv6
+ * address, an IPv4 address, or a domain name (in which case a DNS
+ * lookup is performed). Quoting with [] is supported for all address
+ * types. A port override may be specified in the usual way with a
+ * colon.
*
- * 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().
+ * If no port is specified in @host_and_port then @default_port will be
+ * used as the port number to connect to.
*
- * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
- * Since: 2.30
+ * In general, @host_and_port is expected to be provided by the user
+ * (allowing them to give the hostname, and a port overide if necessary)
+ * and @default_port is expected to be provided by the application.
+ *
+ * (The port component of @host_and_port can also be specified as a
+ * service name rather than as a numeric port, but this functionality
+ * is deprecated, because it depends on the contents of /etc/services,
+ * which is generally quite sparse on platforms other than Linux.)
+ *
+ * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
+ * Since: 2.22
*/
/**
- * g_io_modules_scan_all_in_directory:
- * @dirname: pathname for a directory containing modules to scan.
- *
- * Scans all the modules in the specified directory, ensuring that
- * any extension point implemented by a module is registered.
+ * g_network_address_parse_uri:
+ * @uri: the hostname and optionally a port
+ * @default_port: The default port if none is found in the URI
+ * @error: a pointer to a #GError, or %NULL
*
- * This may not actually load and initialize all the types in each
- * module, some modules may be lazily loaded and initialized when
- * an extension point it implementes is used with e.g.
- * g_io_extension_point_get_extensions() or
- * g_io_extension_point_get_extension_by_name().
+ * Creates a new #GSocketConnectable for connecting to the given
+ * @uri. May fail and return %NULL in case parsing @uri fails.
*
- * If you need to guarantee that all types are loaded in all the modules,
- * use g_io_modules_load_all_in_directory().
+ * Using this rather than g_network_address_new() or
+ * g_network_address_parse() allows #GSocketClient to determine
+ * when to use application-specific proxy protocols.
*
- * Since: 2.24
+ * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
+ * Since: 2.26
*/
/**
- * g_io_modules_scan_all_in_directory_with_scope:
- * @dirname: pathname for a directory containing modules to scan.
- * @scope: a scope to use when scanning the modules
- *
- * Scans all the modules in the specified directory, ensuring that
- * any extension point implemented by a module is registered.
- *
- * This may not actually load and initialize all the types in each
- * module, some modules may be lazily loaded and initialized when
- * an extension point it implementes is used with e.g.
- * g_io_extension_point_get_extensions() or
- * g_io_extension_point_get_extension_by_name().
+ * g_network_monitor_base_add_network:
+ * @monitor: the #GNetworkMonitorBase
+ * @network: a #GInetAddressMask
*
- * If you need to guarantee that all types are loaded in all the modules,
- * use g_io_modules_load_all_in_directory().
+ * Adds @network to @monitor's list of available networks.
*
- * Since: 2.30
+ * Since: 2.32
*/
/**
- * g_io_scheduler_cancel_all_jobs:
+ * g_network_monitor_base_remove_network:
+ * @monitor: the #GNetworkMonitorBase
+ * @network: a #GInetAddressMask
*
- * Cancels all cancellable I/O jobs.
+ * Removes @network from @monitor's list of available networks.
*
- * A job is cancellable if a #GCancellable was passed into
- * g_io_scheduler_push_job().
+ * Since: 2.32
*/
/**
- * g_io_scheduler_job_send_to_mainloop:
- * @job: a #GIOSchedulerJob
- * @func: a #GSourceFunc callback that will be called in the original thread
- * @user_data: data to pass to @func
- * @notify: a #GDestroyNotify for @user_data, or %NULL
- *
- * Used from an I/O job to send a callback to be run in the thread
- * that the job was started from, waiting for the result (and thus
- * blocking the I/O job).
+ * g_network_monitor_base_set_networks:
+ * @monitor: the #GNetworkMonitorBase
+ * @networks: (array length=length): an array of #GInetAddressMask
+ * @length: length of @networks
*
- * Returns: The return value of @func
+ * Drops @monitor's current list of available networks and replaces
+ * it with @networks.
*/
/**
- * g_io_scheduler_job_send_to_mainloop_async:
- * @job: a #GIOSchedulerJob
- * @func: a #GSourceFunc callback that will be called in the original thread
- * @user_data: data to pass to @func
- * @notify: a #GDestroyNotify for @user_data, or %NULL
+ * g_network_monitor_can_reach:
+ * @monitor: a #GNetworkMonitor
+ * @connectable: a #GSocketConnectable
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * Used from an I/O job to send a callback to be run asynchronously in
- * the thread that the job was started from. The callback will be run
- * when the main loop is available, but at that time the I/O job might
- * have finished. The return value from the callback is ignored.
+ * Attempts to determine whether or not the host pointed to by
+ * @connectable can be reached, without actually trying to connect to
+ * it.
*
- * Note that if you are passing the @user_data from g_io_scheduler_push_job()
- * 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.
+ * This may return %TRUE even when #GNetworkMonitor:network-available
+ * is %FALSE, if, for example, @monitor can determine that
+ * @connectable refers to a host on a local network.
+ *
+ * If @monitor believes that an attempt to connect to @connectable
+ * will succeed, it will return %TRUE. Otherwise, it will return
+ * %FALSE and set @error to an appropriate error (such as
+ * %G_IO_ERROR_HOST_UNREACHABLE).
+ *
+ * Note that although this does not attempt to connect to
+ * @connectable, it may still block for a brief period of time (eg,
+ * trying to do multicast DNS on the local network), so if you do not
+ * want to block, you should use g_network_monitor_can_reach_async().
+ *
+ * Returns: %TRUE if @connectable is reachable, %FALSE if not.
+ * Since: 2.32
*/
/**
- * g_io_scheduler_push_job:
- * @job_func: a #GIOSchedulerJobFunc.
- * @user_data: data to pass to @job_func
- * @notify: a #GDestroyNotify for @user_data, or %NULL
- * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * g_network_monitor_can_reach_async:
+ * @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
+ * @user_data: (closure): the data to pass to callback function
*
- * Schedules the I/O job to run in another thread.
+ * Asynchronously attempts to determine whether or not the host
+ * pointed to by @connectable can be reached, without actually
+ * trying to connect to it.
*
- * @notify will be called on @user_data after @job_func has returned,
- * regardless whether the job was cancelled or has run to completion.
+ * For more details, see g_network_monitor_can_reach().
*
- * 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().
+ * When the operation is finished, @callback will be called.
+ * You can then call g_network_monitor_can_reach_finish()
+ * to get the result of the operation.
*/
/**
- * g_io_stream_clear_pending:
- * @stream: a #GIOStream
+ * g_network_monitor_can_reach_finish:
+ * @monitor: a #GNetworkMonitor
+ * @result: a #GAsyncResult
+ * @error: return location for errors, or %NULL
*
- * Clears the pending flag on @stream.
+ * Finishes an async network connectivity test.
+ * See g_network_monitor_can_reach_async().
*
- * Since: 2.22
+ * Returns: %TRUE if network is reachable, %FALSE if not.
*/
/**
- * g_io_stream_close:
- * @stream: a #GIOStream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: location to store the error occurring, or %NULL to ignore
- *
- * Closes the stream, releasing resources related to it. This will also
- * closes the individual input and output streams, if they are not already
- * closed.
- *
- * 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
- * resources are released as early as possible.
+ * g_network_monitor_get_connectivity:
+ * @monitor: the #GNetworkMonitor
*
- * Some streams might keep the backing store of the stream (e.g. a file
- * descriptor) open after the stream is closed. See the documentation for
- * the individual stream for details.
+ * Gets a more detailed networking state than
+ * g_network_monitor_get_network_available().
*
- * On failure the first error that happened will be reported, but the
- * close operation will finish as much as possible. A stream that failed
- * to close will still return %G_IO_ERROR_CLOSED for all operations.
- * Still, it is important to check and report the error to the user,
- * otherwise there might be a loss of data as all data might not be written.
+ * If #GNetworkMonitor:network-available is %FALSE, then the
+ * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
*
- * 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.
- * Cancelling a close will still leave the stream closed, but some streams
- * can use a faster close that doesn't block to e.g. check errors.
+ * 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).
*
- * The default implementation of this method just calls close on the
- * individual input/output streams.
+ * 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: %TRUE on success, %FALSE on failure
- * Since: 2.22
+ * Returns: the network connectivity state
+ * Since: 2.44
*/
/**
- * g_io_stream_close_async:
- * @stream: a #GIOStream
- * @io_priority: the 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
- *
- * Requests an asynchronous close of the stream, releasing resources
- * related to it. When the operation is finished @callback will be
- * called. You can then call g_io_stream_close_finish() to get
- * the result of the operation.
- *
- * For behaviour details see g_io_stream_close().
+ * g_network_monitor_get_default:
*
- * The asynchronous methods have a default fallback that uses threads
- * to implement asynchronicity, so they are optional for inheriting
- * classes. However, if you override one you must override all.
+ * Gets the default #GNetworkMonitor for the system.
*
- * Since: 2.22
+ * Returns: (transfer none): a #GNetworkMonitor
+ * Since: 2.32
*/
/**
- * g_io_stream_close_finish:
- * @stream: a #GIOStream
- * @result: a #GAsyncResult
- * @error: a #GError location to store the error occurring, or %NULL to ignore
+ * g_network_monitor_get_network_available:
+ * @monitor: the #GNetworkMonitor
*
- * Closes a stream.
+ * Checks if the network is available. "Available" here means that the
+ * system has a default route available for at least one of IPv4 or
+ * IPv6. It does not necessarily imply that the public Internet is
+ * reachable. See #GNetworkMonitor:network-available for more details.
*
- * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
- * Since: 2.22
+ * Returns: whether the network is available
+ * Since: 2.32
*/
/**
- * g_io_stream_get_input_stream:
- * @stream: a #GIOStream
- *
- * Gets the input stream for this object. This is used
- * for reading.
+ * g_network_service_get_domain:
+ * @srv: a #GNetworkService
*
- * Do not free.
+ * Gets the domain that @srv serves. This might be either UTF-8 or
+ * ASCII-encoded, depending on what @srv was created with.
*
- * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
+ * Returns: @srv's domain name
* Since: 2.22
*/
/**
- * g_io_stream_get_output_stream:
- * @stream: a #GIOStream
- *
- * Gets the output stream for this object. This is used for
- * writing.
+ * g_network_service_get_protocol:
+ * @srv: a #GNetworkService
*
- * Do not free.
+ * Gets @srv's protocol name (eg, "tcp").
*
- * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
+ * Returns: @srv's protocol name
* Since: 2.22
*/
/**
- * g_io_stream_has_pending:
- * @stream: a #GIOStream
+ * g_network_service_get_scheme:
+ * @srv: a #GNetworkService
*
- * Checks if a stream has pending actions.
+ * Get's the URI scheme used to resolve proxies. By default, the service name
+ * is used as scheme.
*
- * Returns: %TRUE if @stream has pending actions.
- * Since: 2.22
+ * Returns: @srv's scheme name
+ * Since: 2.26
*/
/**
- * g_io_stream_is_closed:
- * @stream: a #GIOStream
+ * g_network_service_get_service:
+ * @srv: a #GNetworkService
*
- * Checks if a stream is closed.
+ * Gets @srv's service name (eg, "ldap").
*
- * Returns: %TRUE if the stream is closed.
+ * Returns: @srv's service name
* Since: 2.22
*/
/**
- * g_io_stream_set_pending:
- * @stream: a #GIOStream
- * @error: a #GError location to store the error occurring, or %NULL to ignore
+ * g_network_service_new:
+ * @service: the service type to look up (eg, "ldap")
+ * @protocol: the networking protocol to use for @service (eg, "tcp")
+ * @domain: the DNS domain to look up the service in
*
- * Sets @stream to have actions pending. If the pending flag is
- * already set or @stream is closed, it will return %FALSE and set
- * @error.
+ * Creates a new #GNetworkService representing the given @service,
+ * @protocol, and @domain. This will initially be unresolved; use the
+ * #GSocketConnectable interface to resolve it.
*
- * Returns: %TRUE if pending was previously unset and is now set.
+ * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
* Since: 2.22
*/
/**
- * g_io_stream_splice_async:
- * @stream1: a #GIOStream.
- * @stream2: a #GIOStream.
- * @flags: a set of #GIOStreamSpliceFlags.
- * @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): user data passed to @callback.
- *
- * Asyncronously splice the output stream of @stream1 to the input stream of
- * @stream2, and splice the output stream of @stream2 to the input stream of
- * @stream1.
+ * g_network_service_set_scheme:
+ * @srv: a #GNetworkService
+ * @scheme: a URI scheme
*
- * When the operation is finished @callback will be called.
- * You can then call g_io_stream_splice_finish() to get the
- * result of the operation.
+ * Set's the URI scheme used to resolve proxies. By default, the service name
+ * is used as scheme.
*
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * g_io_stream_splice_finish:
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_networking_init:
*
- * Finishes an asynchronous io stream splice operation.
+ * 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: %TRUE on success, %FALSE otherwise.
- * Since: 2.28
+ * Since: 2.36
*/
/**
- * 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
- *
- * Creates a keyfile-backed #GSettingsBackend.
- *
- * The filename of the keyfile to use is given by @filename.
- *
- * All settings read to or written from the backend must fall under the
- * path given in @root_path (which must start and end with a slash and
- * not contain two consecutive slashes). @root_path may be "/".
- *
- * If @root_group is non-%NULL then it specifies the name of the keyfile
- * group used for keys that are written directly below @root_path. For
- * example, if @root_path is "/apps/example/" and @root_group is
- * "toplevel", then settings the key "/apps/example/enabled" to a value
- * of %TRUE will cause the following to appear in the keyfile:
- *
- * |[
- * [toplevel]
- * enabled=true
- * ]|
- *
- * If @root_group is %NULL then it is not permitted to store keys
- * directly below the @root_path.
- *
- * For keys not stored directly below @root_path (ie: in a sub-path),
- * the name of the subpath (with the final slash stripped) is used as
- * the name of the keyfile group. To continue the example, if
- * "/apps/example/profiles/default/font-size" were set to
- * 12 then the following would appear in the keyfile:
- *
- * |[
- * [profiles/default]
- * font-size=12
- * ]|
+ * g_notification_add_button:
+ * @notification: a #GNotification
+ * @label: label of the button
+ * @detailed_action: a detailed action name
*
- * The backend will refuse writes (and return writability as being
- * %FALSE) for keys outside of @root_path and, in the event that
- * @root_group is %NULL, also for keys directly under @root_path.
- * Writes will also be refused if the backend detects that it has the
- * inability to rewrite the keyfile (ie: the containing directory is not
- * writable).
+ * 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.
*
- * There is no checking done for your key namespace clashing with the
- * syntax of the key file format. For example, if you have '[' or ']'
- * characters in your path names or '=' in your key names you may be in
- * trouble.
+ * See g_action_parse_detailed_name() for a description of the format
+ * for @detailed_action.
*
- * Returns: (transfer full): a keyfile-backed #GSettingsBackend
+ * Since: 2.40
*/
/**
- * 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_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
*
- * Loads a loadable icon. For the asynchronous version of this function,
- * see g_loadable_icon_load_async().
+ * Adds a button to @notification that activates @action when clicked.
+ * @action must be an application-wide action (it must start with "app.").
*
- * Returns: (transfer full): a #GInputStream to read the icon from.
+ * If @target_format is given, it is used to collect remaining
+ * positional parameters into a #GVariant instance, similar to
+ * g_variant_new(). @action will be activated with that #GVariant as its
+ * parameter.
+ *
+ * Since: 2.40
*/
/**
- * g_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_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
*
- * 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().
+ * 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_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_notification_new:
+ * @title: the title of the notification
*
- * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+ * Creates a new #GNotification with @title as its title.
*
- * Returns: (transfer full): a #GInputStream to read the icon from.
+ * 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_local_vfs_new:
+ * g_notification_set_body:
+ * @notification: a #GNotification
+ * @body: (allow-none): the new body for @notification, or %NULL
*
- * Returns a new #GVfs handle for a local vfs.
+ * Sets the body of @notification to @body.
*
- * Returns: a new #GVfs handle.
+ * Since: 2.40
*/
/**
- * g_main_destroy:
- * @loop: a #GMainLoop
+ * 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.
*
- * Frees the memory allocated for the #GMainLoop.
+ * 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.
*
- * Deprecated: 2.2: Use g_main_loop_unref() instead
+ * When no default action is set, the application that the notification
+ * was sent on is activated.
+ *
+ * Since: 2.40
*/
/**
- * g_main_is_running:
- * @loop: a #GMainLoop
+ * 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.").
*
- * Checks if the main loop is running.
+ * 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.
*
- * Returns: %TRUE if the main loop is running
- * Deprecated: 2.2: Use g_main_loop_is_running() instead
+ * When no default action is set, the application that the notification
+ * was sent on is activated.
+ *
+ * Since: 2.40
*/
/**
- * g_main_iteration:
- * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed.
+ * 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.").
*
- * Runs a single iteration for the default #GMainContext.
+ * If @target is non-%NULL, @action will be activated with @target as
+ * its parameter.
*
- * Returns: %TRUE if more events are pending.
- * Deprecated: 2.2: Use g_main_context_iteration() instead.
+ * When no default action is set, the application that the notification
+ * was sent on is activated.
+ *
+ * Since: 2.40
*/
/**
- * g_main_new:
- * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway.
+ * g_notification_set_icon:
+ * @notification: a #GNotification
+ * @icon: the icon to be shown in @notification, as a #GIcon
*
- * Creates a new #GMainLoop for th default main context.
+ * Sets the icon of @notification to @icon.
*
- * Returns: a new #GMainLoop
- * Deprecated: 2.2: Use g_main_loop_new() instead
+ * Since: 2.40
*/
/**
- * g_main_pending:
- *
- * Checks if any events are pending for the default #GMainContext
- * (i.e. ready to be processed).
- *
- *
- * Deprected: 2.2: Use g_main_context_pending() instead.
+ * g_notification_set_priority:
+ * @notification: a #GNotification
+ * @priority: a #GNotificationPriority
*
- * Returns: %TRUE if any events are pending.
+ * Sets the priority of @notification to @priority. See
+ * #GNotificationPriority for possible values.
*/
/**
- * g_main_quit:
- * @loop: a #GMainLoop
+ * g_notification_set_title:
+ * @notification: a #GNotification
+ * @title: the new title for @notification
*
- * Stops the #GMainLoop.
- * If g_main_run() was called to run the #GMainLoop, it will now return.
+ * Sets the title of @notification to @title.
*
- * Deprecated: 2.2: Use g_main_loop_quit() instead
+ * Since: 2.40
*/
/**
- * g_main_run:
- * @loop: a #GMainLoop
+ * g_notification_set_urgent:
+ * @notification: a #GNotification
+ * @urgent: %TRUE if @notification is urgent
*
- * Runs a main loop until it stops running.
+ * Deprecated in favor of g_notification_set_priority().
*
- * Deprecated: 2.2: Use g_main_loop_run() instead
+ * Since: 2.40
*/
/**
- * g_main_set_poll_func:
- * @func: the function to call to poll all file descriptors
+ * g_null_settings_backend_new:
+ *
+ * Creates a readonly #GSettingsBackend.
*
- * Sets the function to use for the handle polling of file descriptors
- * for the default main context.
+ * This backend does not allow changes to settings, so all settings
+ * will always have their default values.
*
- * Deprecated: 2.2: Use g_main_context_set_poll_func() again
+ * Returns: (transfer full): a newly created #GSettingsBackend
+ * Since: 2.28
*/
/**
- * g_memory_input_stream_add_data:
- * @stream: a #GMemoryInputStream
- * @data: (array length=len) (element-type guint8): 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_output_stream_clear_pending:
+ * @stream: output stream
*
- * Appends @data to data that can be read from the input stream
+ * Clears the pending flag on @stream.
*/
/**
- * g_memory_input_stream_new:
+ * g_output_stream_close:
+ * @stream: A #GOutputStream.
+ * @cancellable: (allow-none): optional cancellable object
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Creates a new empty #GMemoryInputStream.
+ * Closes the stream, releasing resources related to it.
*
- * Returns: a new #GInputStream
- */
-
-
-/**
- * g_memory_input_stream_new_from_data:
- * @data: (array length=len) (element-type guint8): 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
+ * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
+ * Closing a stream multiple times will not return an error.
*
- * Creates a new #GMemoryInputStream with data in memory of a given size.
+ * Closing a stream will automatically flush any outstanding buffers in the
+ * stream.
*
- * Returns: new #GInputStream read from @data of @len bytes.
+ * Streams will be automatically closed when the last reference
+ * is dropped, but you might want to call this function to make sure
+ * resources are released as early as possible.
+ *
+ * Some streams might keep the backing store of the stream (e.g. a file descriptor)
+ * open after the stream is closed. See the documentation for the individual
+ * stream for details.
+ *
+ * On failure the first error that happened will be reported, but the close
+ * operation will finish as much as possible. A stream that failed to
+ * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
+ * is important to check and report the error to the user, otherwise
+ * there might be a loss of data as all data might not be written.
+ *
+ * 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.
+ * Cancelling a close will still leave the stream closed, but there some streams
+ * can use a faster close that doesn't block to e.g. check errors. On
+ * cancellation (as with any error) there is no guarantee that all written
+ * data will reach the target.
+ *
+ * Returns: %TRUE on success, %FALSE on failure
*/
/**
- * g_memory_output_stream_get_data:
- * @ostream: a #GMemoryOutputStream
+ * g_output_stream_close_async:
+ * @stream: A #GOutputStream.
+ * @io_priority: the 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
*
- * Gets any loaded data from the @ostream.
+ * Requests an asynchronous close of the stream, releasing resources
+ * related to it. When the operation is finished @callback will be
+ * called. You can then call g_output_stream_close_finish() to get
+ * the result of the operation.
*
- * Note that the returned pointer may become invalid on the next
- * write or truncate operation on the stream.
+ * For behaviour details see g_output_stream_close().
*
- * Returns: (transfer none): pointer to the stream's data
+ * The asyncronous methods have a default fallback that uses threads
+ * to implement asynchronicity, so they are optional for inheriting
+ * classes. However, if you override one you must override all.
*/
/**
- * g_memory_output_stream_get_data_size:
- * @ostream: a #GMemoryOutputStream
+ * g_output_stream_close_finish:
+ * @stream: a #GOutputStream.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Returns the number of bytes from the start up
- * to including the last byte written in the stream
- * that has not been truncated away.
+ * Closes an output stream.
*
- * Returns: the number of bytes written to the stream
- * Since: 2.18
+ * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
*/
/**
- * g_memory_output_stream_get_size:
- * @ostream: a #GMemoryOutputStream
+ * g_output_stream_flush:
+ * @stream: a #GOutputStream.
+ * @cancellable: (allow-none): optional cancellable object
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * 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.
+ * Forces a write of all user-space buffered data for the given
+ * @stream. Will block during the operation. Closing the stream will
+ * implicitly cause a flush.
*
- * Note that for growable streams the returned size may become invalid on
- * the next write or truncate operation on the stream.
+ * This function is optional for inherited classes.
*
- * If you want the number of bytes currently written to the stream, use
- * g_memory_output_stream_get_data_size().
+ * 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: the number of bytes allocated for the data buffer
+ * Returns: %TRUE on success, %FALSE on error
*/
/**
- * g_memory_output_stream_new: (skip)
- * @data: pointer to a chunk of memory to use, or %NULL
- * @size: the size of @data
- * @realloc_function: a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL
- * @destroy_function: 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.
- *
- * |[
- * /* a stream that can grow */
- * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
- *
- * /* another stream that can grow */
- * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
+ * g_output_stream_flush_async:
+ * @stream: a #GOutputStream.
+ * @io_priority: the 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
*
- * /* a fixed-size stream */
- * data = malloc (200);
- * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
- * ]|
+ * Forces an asynchronous write of all user-space buffered data for
+ * the given @stream.
+ * For behaviour details see g_output_stream_flush().
*
- * Returns: A newly created #GMemoryOutputStream object.
+ * When the operation is finished @callback will be
+ * called. You can then call g_output_stream_flush_finish() to get the
+ * result of the operation.
*/
/**
- * g_memory_output_stream_steal_data:
- * @ostream: a #GMemoryOutputStream
- *
- * Gets any loaded data from the @ostream. Ownership of the data
- * is transferred to the caller; when no longer needed it must be
- * freed using the free function set in @ostream's
- * #GMemoryOutputStream:destroy-function property.
+ * g_output_stream_flush_finish:
+ * @stream: a #GOutputStream.
+ * @result: a GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * @ostream must be closed before calling this function.
+ * Finishes flushing an output stream.
*
- * Returns: (transfer full): the stream's data
- * Since: 2.26
+ * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
*/
/**
- * g_memory_settings_backend_new:
- *
- * Creates a memory-backed #GSettingsBackend.
+ * g_output_stream_has_pending:
+ * @stream: a #GOutputStream.
*
- * This backend allows changes to settings, but does not write them
- * to any backing storage, so the next time you run your application,
- * the memory backend will start out with the default values again.
+ * Checks if an ouput stream has pending actions.
*
- * Returns: (transfer full): a newly created #GSettingsBackend
- * Since: 2.28
+ * Returns: %TRUE if @stream has pending actions.
*/
/**
- * g_menu_append:
- * @menu: a #GMenu
- * @label: (allow-none): the section label, or %NULL
- * @detailed_action: (allow-none): the detailed action string, or %NULL
+ * g_output_stream_is_closed:
+ * @stream: a #GOutputStream.
*
- * Convenience function for appending a normal menu item to the end of
- * @menu. Combine g_menu_new() and g_menu_insert_item() for a more
- * flexible alternative.
+ * Checks if an output stream has already been closed.
*
- * Since: 2.32
+ * Returns: %TRUE if @stream is closed. %FALSE otherwise.
*/
/**
- * g_menu_append_item:
- * @menu: a #GMenu
- * @item: a #GMenuItem to append
- *
- * Appends @item to the end of @menu.
+ * g_output_stream_is_closing:
+ * @stream: a #GOutputStream.
*
- * See g_menu_insert_item() for more information.
+ * Checks if an output stream is being closed. This can be
+ * used inside e.g. a flush implementation to see if the
+ * flush (or other i/o operation) is called from within
+ * the closing operation.
*
- * Since: 2.32
+ * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
+ * Since: 2.24
*/
/**
- * g_menu_append_section:
- * @menu: a #GMenu
- * @label: (allow-none): the section label, or %NULL
- * @section: a #GMenuModel with the items of the section
+ * 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
*
- * Convenience function for appending a section menu item to the end of
- * @menu. Combine g_menu_new_section() and g_menu_insert_item() for a
- * more flexible alternative.
+ * 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.
*
- * Since: 2.32
+ * 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_menu_append_submenu:
- * @menu: a #GMenu
- * @label: (allow-none): the section label, or %NULL
- * @submenu: a #GMenuModel with the items of the submenu
+ * g_output_stream_set_pending:
+ * @stream: a #GOutputStream.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Convenience function for appending a submenu menu item to the end of
- * @menu. Combine g_menu_new_submenu() and g_menu_insert_item() for a
- * more flexible alternative.
+ * Sets @stream to have actions pending. If the pending flag is
+ * already set or @stream is closed, it will return %FALSE and set
+ * @error.
*
- * Since: 2.32
+ * Returns: %TRUE if pending was previously unset and is now set.
*/
/**
- * g_menu_attribute_iter_get_name:
- * @iter: a #GMenuAttributeIter
- *
- * Gets the name of the attribute at the current iterator position, as
- * a string.
+ * g_output_stream_splice:
+ * @stream: a #GOutputStream.
+ * @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.
*
- * The iterator is not advanced.
+ * Splices an input stream into an output stream.
*
- * Returns: the name of the attribute
- * Since: 2.32
+ * 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_menu_attribute_iter_get_next:
- * @iter: a #GMenuAttributeIter
- * @out_name: (out) (allow-none) (transfer none): the type of the attribute
- * @value: (out) (allow-none) (transfer full): the attribute value
- *
- * This function combines g_menu_attribute_iter_next() with
- * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
- *
- * First the iterator is advanced to the next (possibly first) attribute.
- * If that fails, then %FALSE is returned and there are no other
- * effects.
- *
- * If successful, @name and @value are set to the name and value of the
- * attribute that has just been advanced to. At this point,
- * g_menu_item_get_name() and g_menu_item_get_value() will return the
- * same values again.
- *
- * The value returned in @name remains valid for as long as the iterator
- * remains at the current position. The value returned in @value must
- * be unreffed using g_variant_unref() when it is no longer in use.
+ * g_output_stream_splice_async:
+ * @stream: a #GOutputStream.
+ * @source: a #GInputStream.
+ * @flags: a set of #GOutputStreamSpliceFlags.
+ * @io_priority: the io priority of the request.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @user_data: (closure): user data passed to @callback.
*
- * attribute
+ * Splices a stream asynchronously.
+ * When the operation is finished @callback will be called.
+ * You can then call g_output_stream_splice_finish() to get the
+ * result of the operation.
*
- * Returns: %TRUE on success, or %FALSE if there is no additional
- * Since: 2.32
+ * For the synchronous, blocking version of this function, see
+ * g_output_stream_splice().
*/
/**
- * g_menu_attribute_iter_get_value:
- * @iter: a #GMenuAttributeIter
- *
- * Gets the value of the attribute at the current iterator position.
+ * g_output_stream_splice_finish:
+ * @stream: a #GOutputStream.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * The iterator is not advanced.
+ * Finishes an asynchronous stream splice operation.
*
- * Returns: (transfer full): the value of the current attribute
- * Since: 2.32
+ * 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_menu_attribute_iter_next:
- * @iter: a #GMenuAttributeIter
+ * 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
*
- * Attempts to advance the iterator to the next (possibly first)
- * attribute.
+ * 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.
*
- * %TRUE is returned on success, or %FALSE if there are no more
- * attributes.
+ * See the documentation of g_output_stream_write_all() about the
+ * behavior of the actual write operation.
*
- * You must call this function when you first acquire the iterator
- * to advance it to the first attribute (and determine if the first
- * attribute exists at all).
+ * 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().
*
- * Returns: %TRUE on success, or %FALSE when there are no more attributes
- * Since: 2.32
+ * Since: 2.40
+ * Returns: %TRUE on success, %FALSE if there was an error
*/
/**
- * g_menu_freeze:
- * @menu: a #GMenu
+ * 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
+ * @cancellable: (allow-none): optional cancellable object
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Marks @menu as frozen.
+ * Tries to write @count bytes from @buffer into the stream. Will block
+ * during the operation.
*
- * After the menu is frozen, it is an error to attempt to make any
- * changes to it. In effect this means that the #GMenu API must no
- * longer be used.
+ * If count is 0, returns 0 and does nothing. A value of @count
+ * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
*
- * This function causes g_menu_model_is_mutable() to begin returning
- * %FALSE, which has some positive performance implications.
+ * 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
+ * @count is 0).
*
- * Since: 2.32
- */
-
-
-/**
- * g_menu_insert:
- * @menu: a #GMenu
- * @position: the position at which to insert the item
- * @label: (allow-none): the section label, or %NULL
- * @detailed_action: (allow-none): the detailed action string, or %NULL
+ * 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.
*
- * Convenience function for inserting a normal menu item into @menu.
- * Combine g_menu_new() and g_menu_insert_item() for a more flexible
- * alternative.
+ * On error -1 is returned and @error is set accordingly.
*
- * Since: 2.32
+ * Returns: Number of bytes written, or -1 on error
*/
/**
- * g_menu_insert_item:
- * @menu: a #GMenu
- * @position: the position at which to insert the item
- * @item: the #GMenuItem to insert
- *
- * Inserts @item into @menu.
+ * g_output_stream_write_all:
+ * @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
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * The "insertion" is actually done by copying all of the attribute and
- * link values of @item and using them to form a new item within @menu.
- * As such, @item itself is not really inserted, but rather, a menu item
- * that is exactly the same as the one presently described by @item.
+ * Tries to write @count bytes from @buffer into the stream. Will block
+ * during the operation.
*
- * This means that @item is essentially useless after the insertion
- * occurs. Any changes you make to it are ignored unless it is inserted
- * again (at which point its updated values will be copied).
+ * This function is similar to g_output_stream_write(), except it tries to
+ * write as many bytes as requested, only stopping on an error.
*
- * You should probably just free @item once you're done.
+ * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
+ * is set to @count.
*
- * There are many convenience functions to take care of common cases.
- * See g_menu_insert(), g_menu_insert_section() and
- * g_menu_insert_submenu() as well as "prepend" and "append" variants of
- * each of these functions.
+ * If there is an error during the operation %FALSE is returned and @error
+ * 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().
*
- * Since: 2.32
+ * Returns: %TRUE on success, %FALSE if there was an error
*/
/**
- * g_menu_insert_section:
- * @menu: a #GMenu
- * @position: the position at which to insert the item
- * @label: (allow-none): the section label, or %NULL
- * @section: a #GMenuModel with the items of the section
+ * 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
*
- * Convenience function for inserting a section menu item into @menu.
- * Combine g_menu_new_section() and g_menu_insert_item() for a more
- * flexible alternative.
+ * 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.
*
- * Since: 2.32
- */
-
-
-/**
- * g_menu_insert_submenu:
- * @menu: a #GMenu
- * @position: the position at which to insert the item
- * @label: (allow-none): the section label, or %NULL
- * @submenu: a #GMenuModel with the items of the submenu
+ * This is the asynchronous version of g_output_stream_write_all().
*
- * Convenience function for inserting a submenu menu item into @menu.
- * Combine g_menu_new_submenu() and g_menu_insert_item() for a more
- * flexible alternative.
+ * Call g_output_stream_write_all_finish() to collect the result.
*
- * Since: 2.32
+ * 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_menu_item_new:
- * @label: (allow-none): the section label, or %NULL
- * @detailed_action: (allow-none): the detailed action string, or %NULL
- *
- * Creates a new #GMenuItem.
+ * 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.
*
- * If @label is non-%NULL it is used to set the "label" attribute of the
- * new item.
+ * Finishes an asynchronous stream write operation started with
+ * g_output_stream_write_all_async().
*
- * If @detailed_action is non-%NULL it is used to set the "action" and
- * possibly the "target" attribute of the new item. See
- * g_menu_item_set_detailed_action() for more information.
+ * 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: a new #GMenuItem
- * Since: 2.32
+ * Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
*/
/**
- * g_menu_item_new_section:
- * @label: (allow-none): the section label, or %NULL
- * @section: a #GMenuModel with the items of the section
- *
- * Creates a new #GMenuItem representing a section.
+ * g_output_stream_write_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
*
- * This is a convenience API around g_menu_item_new() and
- * g_menu_item_set_section().
+ * 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_finish() to get the result of the
+ * operation.
*
- * The effect of having one menu appear as a section of another is
- * exactly as it sounds: the items from @section become a direct part of
- * the menu that @menu_item is added to.
+ * During an async request no other sync and async calls are allowed,
+ * and will result in %G_IO_ERROR_PENDING errors.
*
- * Visual separation is typically displayed between two non-empty
- * sections. If @label is non-%NULL then it will be encorporated into
- * this visual indication. This allows for labeled subsections of a
- * menu.
+ * A value of @count larger than %G_MAXSSIZE will cause a
+ * %G_IO_ERROR_INVALID_ARGUMENT error.
*
- * As a simple example, consider a typical "Edit" menu from a simple
- * program. It probably contains an "Undo" and "Redo" item, followed by
- * a separator, followed by "Cut", "Copy" and "Paste".
+ * 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.
*
- * This would be accomplished by creating three #GMenu instances. The
- * first would be populated with the "Undo" and "Redo" items, and the
- * 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:
+ * 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.
*
- * <informalexample><programlisting><![CDATA[
- * <menu id='edit-menu'>
- * <section>
- * <item label='Undo'/>
- * <item label='Redo'/>
- * </section>
- * <section>
- * <item label='Cut'/>
- * <item label='Copy'/>
- * <item label='Paste'/>
- * </section>
- * </menu>
- * ]]></programlisting></informalexample>
+ * 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.
*
- * The following example is exactly equivalent. It is more illustrative
- * of the exact relationship between the menus and items (keeping in
- * mind that the 'link' element defines a new menu that is linked to the
- * 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).
+ * The asyncronous methods have a default fallback that uses threads
+ * to implement asynchronicity, so they are optional for inheriting
+ * classes. However, if you override one you must override all.
*
- * <informalexample><programlisting><![CDATA[
- * <menu id='edit-menu'>
- * <item>
- * <link name='section'>
- * <item label='Undo'/>
- * <item label='Redo'/>
- * </link>
- * </item>
- * <item>
- * <link name='section'>
- * <item label='Cut'/>
- * <item label='Copy'/>
- * <item label='Paste'/>
- * </link>
- * </item>
- * </menu>
- * ]]></programlisting></informalexample>
+ * For the synchronous, blocking version of this function, see
+ * g_output_stream_write().
*
- * Returns: a new #GMenuItem
- * Since: 2.32
+ * 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.
*/
/**
- * g_menu_item_new_submenu:
- * @label: (allow-none): the section label, or %NULL
- * @submenu: a #GMenuModel with the items of the submenu
+ * g_output_stream_write_bytes:
+ * @stream: a #GOutputStream.
+ * @bytes: the #GBytes to write
+ * @cancellable: (allow-none): optional cancellable object
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Creates a new #GMenuItem representing a submenu.
+ * 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.
*
- * This is a convenience API around g_menu_item_new() and
- * g_menu_item_set_submenu().
+ * 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: a new #GMenuItem
- * Since: 2.32
+ * Returns: Number of bytes written, or -1 on error
*/
/**
- * g_menu_item_set_action_and_target:
- * @menu_item: a #GMenuItem
- * @action: (allow-none): the name of the action for this item
- * @format_string: (allow-none): a GVariant format string
- * @...: positional parameters, as per @format_string
- *
- * Sets or unsets the "action" and "target" attributes of @menu_item.
+ * g_output_stream_write_bytes_async:
+ * @stream: A #GOutputStream.
+ * @bytes: The 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
*
- * If @action is %NULL then both the "action" and "target" attributes
- * are unset (and @format_string is ignored along with the positional
- * parameters).
+ * 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.
*
- * If @action is non-%NULL then the "action" attribute is set.
- * @format_string is then inspected. If it is non-%NULL then the proper
- * position parameters are collected to create a #GVariant instance to
- * use as the target value. If it is %NULL then the positional
- * parameters are ignored and the "target" attribute is unset.
+ * 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.
*
- * See also g_menu_item_set_action_and_target_value() for an equivalent
- * call that directly accepts a #GVariant. See
- * g_menu_item_set_detailed_action() for a more convenient version that
- * works with string-typed targets.
+ * 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.
*
- * See also g_menu_item_set_action_and_target_value() for a
- * description of the semantics of the action and target attributes.
+ * Finishes a stream write-from-#GBytes operation.
*
- * Since: 2.32
+ * Returns: a #gssize containing the number of bytes written to the stream.
*/
/**
- * g_menu_item_set_action_and_target_value:
- * @menu_item: a #GMenuItem
- * @action: (allow-none): the name of the action for this item
- * @target_value: (allow-none): a #GVariant to use as the action target
+ * g_output_stream_write_finish:
+ * @stream: a #GOutputStream.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Sets or unsets the "action" and "target" attributes of @menu_item.
+ * Finishes a stream write operation.
*
- * If @action is %NULL then both the "action" and "target" attributes
- * are unset (and @target_value is ignored).
+ * Returns: a #gssize containing the number of bytes written to the stream.
+ */
+
+
+/**
+ * g_permission_acquire:
+ * @permission: a #GPermission instance
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
*
- * If @action is non-%NULL then the "action" attribute is set. The
- * "target" attribute is then set to the value of @target_value if it is
- * non-%NULL or unset otherwise.
+ * Attempts to acquire the permission represented by @permission.
*
- * Normal menu items (ie: not submenu, section or other custom item
- * types) are expected to have the "action" attribute set to identify
- * the action that they are associated with. The state type of the
- * action help to determine the disposition of the menu item. See
- * #GAction and #GActionGroup for an overview of actions.
+ * The precise method by which this happens depends on the permission
+ * and the underlying authentication mechanism. A simple example is
+ * that a dialog may appear asking the user to enter their password.
*
- * In general, clicking on the menu item will result in activation of
- * the named action with the "target" attribute given as the parameter
- * to the action invocation. If the "target" attribute is not set then
- * the action is invoked with no parameter.
+ * You should check with g_permission_get_can_acquire() before calling
+ * this function.
*
- * If the action has no state then the menu item is usually drawn as a
- * plain menu item (ie: with no additional decoration).
+ * If the permission is acquired then %TRUE is returned. Otherwise,
+ * %FALSE is returned and @error is set appropriately.
*
- * If the action has a boolean state then the menu item is usually drawn
- * as a toggle menu item (ie: with a checkmark or equivalent
- * indication). The item should be marked as 'toggled' or 'checked'
- * when the boolean state is %TRUE.
+ * This call is blocking, likely for a very long time (in the case that
+ * user interaction is required). See g_permission_acquire_async() for
+ * the non-blocking version.
+ *
+ * Returns: %TRUE if the permission was successfully acquired
+ * Since: 2.26
+ */
+
+
+/**
+ * g_permission_acquire_async:
+ * @permission: a #GPermission instance
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: the #GAsyncReadyCallback to call when done
+ * @user_data: the user data to pass to @callback
*
- * If the action has a string state then the menu item is usually drawn
- * as a radio menu item (ie: with a radio bullet or equivalent
- * indication). The item should be marked as 'selected' when the string
- * state is equal to the value of the @target property.
+ * Attempts to acquire the permission represented by @permission.
*
- * See g_menu_item_set_action_and_target() or
- * g_menu_item_set_detailed_action() for two equivalent calls that are
- * probably more convenient for most uses.
+ * This is the first half of the asynchronous version of
+ * g_permission_acquire().
*
- * Since: 2.32
+ * Since: 2.26
*/
/**
- * g_menu_item_set_attribute:
- * @menu_item: a #GMenuItem
- * @attribute: the attribute to set
- * @format_string: (allow-none): a #GVariant format string, or %NULL
- * @...: positional parameters, as per @format_string
+ * g_permission_acquire_finish:
+ * @permission: a #GPermission instance
+ * @result: the #GAsyncResult given to the #GAsyncReadyCallback
+ * @error: a pointer to a %NULL #GError, or %NULL
*
- * Sets or unsets an attribute on @menu_item.
+ * Collects the result of attempting to acquire the permission
+ * represented by @permission.
*
- * The attribute to set or unset is specified by @attribute. This
- * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
- * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
- * attribute name.
- * Attribute names are restricted to lowercase characters, numbers
- * and '-'. Furthermore, the names must begin with a lowercase character,
- * must not end with a '-', and must not contain consecutive dashes.
+ * This is the second half of the asynchronous version of
+ * g_permission_acquire().
*
- * If @format_string is non-%NULL then the proper position parameters
- * are collected to create a #GVariant instance to use as the attribute
- * value. If it is %NULL then the positional parameterrs are ignored
- * and the named attribute is unset.
+ * Returns: %TRUE if the permission was successfully acquired
+ * Since: 2.26
+ */
+
+
+/**
+ * g_permission_get_allowed:
+ * @permission: a #GPermission instance
*
- * See also g_menu_item_set_attribute_value() for an equivalent call
- * that directly accepts a #GVariant.
+ * Gets the value of the 'allowed' property. This property is %TRUE if
+ * the caller currently has permission to perform the action that
+ * @permission represents the permission to perform.
*
- * Since: 2.32
+ * Returns: the value of the 'allowed' property
+ * Since: 2.26
*/
/**
- * g_menu_item_set_attribute_value:
- * @menu_item: a #GMenuItem
- * @attribute: the attribute to set
- * @value: (allow-none): a #GVariant to use as the value, or %NULL
+ * g_permission_get_can_acquire:
+ * @permission: a #GPermission instance
*
- * Sets or unsets an attribute on @menu_item.
+ * Gets the value of the 'can-acquire' property. This property is %TRUE
+ * if it is generally possible to acquire the permission by calling
+ * g_permission_acquire().
*
- * The attribute to set or unset is specified by @attribute. This
- * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
- * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
- * attribute name.
- * Attribute names are restricted to lowercase characters, numbers
- * and '-'. Furthermore, the names must begin with a lowercase character,
- * must not end with a '-', and must not contain consecutive dashes.
+ * Returns: the value of the 'can-acquire' property
+ * Since: 2.26
+ */
+
+
+/**
+ * g_permission_get_can_release:
+ * @permission: a #GPermission instance
*
- * must consist only of lowercase
- * ASCII characters, digits and '-'.
+ * Gets the value of the 'can-release' property. This property is %TRUE
+ * if it is generally possible to release the permission by calling
+ * g_permission_release().
*
- * If @value is non-%NULL then it is used as the new value for the
- * attribute. If @value is %NULL then the attribute is unset. If
- * the @value #GVariant is floating, it is consumed.
+ * Returns: the value of the 'can-release' property
+ * Since: 2.26
+ */
+
+
+/**
+ * g_permission_impl_update:
+ * @permission: a #GPermission instance
+ * @allowed: the new value for the 'allowed' property
+ * @can_acquire: the new value for the 'can-acquire' property
+ * @can_release: the new value for the 'can-release' property
*
- * See also g_menu_item_set_attribute() for a more convenient way to do
- * the same.
+ * This function is called by the #GPermission implementation to update
+ * the properties of the permission. You should never call this
+ * function except from a #GPermission implementation.
*
- * Since: 2.32
+ * GObject notify signals are generated, as appropriate.
+ *
+ * Since: 2.26
*/
/**
- * g_menu_item_set_detailed_action:
- * @menu_item: a #GMenuItem
- * @detailed_action: the "detailed" action string
+ * g_permission_release:
+ * @permission: a #GPermission instance
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
*
- * Sets the "action" and possibly the "target" attribute of @menu_item.
+ * Attempts to release the permission represented by @permission.
*
- * 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
- * g_menu_item_set_target_value() with a string-type #GVariant
- * containing the part following the "::".
+ * The precise method by which this happens depends on the permission
+ * and the underlying authentication mechanism. In most cases the
+ * permission will be dropped immediately without further action.
*
- * If @detailed_action doesn't contain "::" then the action is set to
- * the given string (verbatim) and the target value is unset.
+ * You should check with g_permission_get_can_release() before calling
+ * this function.
*
- * See g_menu_item_set_action_and_target() or
- * g_menu_item_set_action_and_target_value() for more flexible (but
- * slightly less convenient) alternatives.
+ * If the permission is released then %TRUE is returned. Otherwise,
+ * %FALSE is returned and @error is set appropriately.
*
- * See also g_menu_set_action_and_target_value() for a description of
- * the semantics of the action and target attributes.
+ * This call is blocking, likely for a very long time (in the case that
+ * user interaction is required). See g_permission_release_async() for
+ * the non-blocking version.
*
- * Since: 2.32
+ * Returns: %TRUE if the permission was successfully released
+ * Since: 2.26
*/
/**
- * g_menu_item_set_label:
- * @menu_item: a #GMenuItem
- * @label: (allow-none): the label to set, or %NULL to unset
+ * g_permission_release_async:
+ * @permission: a #GPermission instance
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: the #GAsyncReadyCallback to call when done
+ * @user_data: the user data to pass to @callback
*
- * Sets or unsets the "label" attribute of @menu_item.
+ * Attempts to release the permission represented by @permission.
*
- * If @label is non-%NULL it is used as the label for the menu item. If
- * it is %NULL then the label attribute is unset.
+ * This is the first half of the asynchronous version of
+ * g_permission_release().
*
- * Since: 2.32
+ * Since: 2.26
*/
/**
- * g_menu_item_set_link:
- * @menu_item: a #GMenuItem
- * @link: type of link to establish or unset
- * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
+ * g_permission_release_finish:
+ * @permission: a #GPermission instance
+ * @result: the #GAsyncResult given to the #GAsyncReadyCallback
+ * @error: a pointer to a %NULL #GError, or %NULL
*
- * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
+ * Collects the result of attempting to release the permission
+ * represented by @permission.
*
- * Links are used to establish a relationship between a particular menu
- * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
- * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
- * is used to create a section. Other types of link can be used, but there
- * is no guarantee that clients will be able to make sense of them.
- * Link types are restricted to lowercase characters, numbers
- * and '-'. Furthermore, the names must begin with a lowercase character,
- * must not end with a '-', and must not contain consecutive dashes.
+ * This is the second half of the asynchronous version of
+ * g_permission_release().
*
- * Since: 2.32
+ * Returns: %TRUE if the permission was successfully released
+ * Since: 2.26
*/
/**
- * g_menu_item_set_section:
- * @menu_item: a #GMenuItem
- * @section: (allow-none): a #GMenuModel, or %NULL
- *
- * Sets or unsets the "section" link of @menu_item to @section.
+ * g_poll_file_monitor_new:
+ * @file: a #GFile.
*
- * The effect of having one menu appear as a section of another is
- * exactly as it sounds: the items from @section become a direct part of
- * the menu that @menu_item is added to. See g_menu_item_new_section()
- * for more information about what it means for a menu item to be a
- * section.
+ * Polls @file for changes.
*
- * Since: 2.32
+ * Returns: a new #GFileMonitor for the given #GFile.
*/
/**
- * g_menu_item_set_submenu:
- * @menu_item: a #GMenuItem
- * @submenu: (allow-none): a #GMenuModel, or %NULL
- *
- * Sets or unsets the "submenu" link of @menu_item to @submenu.
+ * g_pollable_input_stream_can_poll:
+ * @stream: a #GPollableInputStream.
*
- * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
- * link is unset.
+ * Checks if @stream is actually pollable. Some classes may implement
+ * #GPollableInputStream but have only certain instances of that class
+ * be pollable. If this method returns %FALSE, then the behavior of
+ * other #GPollableInputStream methods is undefined.
*
- * The effect of having one menu appear as a submenu of another is
- * exactly as it sounds.
+ * For any given stream, the value returned by this method is constant;
+ * a stream cannot switch from pollable to non-pollable or vice versa.
*
- * Since: 2.32
+ * Returns: %TRUE if @stream is pollable, %FALSE if not.
+ * Since: 2.28
*/
/**
- * g_menu_link_iter_get_name:
- * @iter: a #GMenuLinkIter
+ * g_pollable_input_stream_create_source:
+ * @stream: a #GPollableInputStream.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
*
- * Gets the name of the link at the current iterator position.
+ * Creates a #GSource that triggers when @stream can be read, or
+ * @cancellable is triggered or an error occurs. The callback on the
+ * source is of the #GPollableSourceFunc type.
*
- * The iterator is not advanced.
+ * As with g_pollable_input_stream_is_readable(), it is possible that
+ * the stream may not actually be readable even after the source
+ * triggers, so you should use g_pollable_input_stream_read_nonblocking()
+ * rather than g_input_stream_read() from the callback.
*
- * Returns: the type of the link
- * Since: 2.32
+ * Returns: (transfer full): a new #GSource
+ * Since: 2.28
*/
/**
- * g_menu_link_iter_get_next:
- * @iter: a #GMenuLinkIter
- * @out_link: (out) (allow-none) (transfer none): the name of the link
- * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
- *
- * This function combines g_menu_link_iter_next() with
- * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
- *
- * First the iterator is advanced to the next (possibly first) link.
- * If that fails, then %FALSE is returned and there are no other effects.
+ * g_pollable_input_stream_is_readable:
+ * @stream: a #GPollableInputStream.
*
- * If successful, @out_link and @value are set to the name and #GMenuModel
- * of the link that has just been advanced to. At this point,
- * g_menu_item_get_name() and g_menu_item_get_value() will return the
- * same values again.
+ * Checks if @stream can be read.
*
- * The value returned in @out_link remains valid for as long as the iterator
- * remains at the current position. The value returned in @value must
- * be unreffed using g_object_unref() when it is no longer in use.
+ * Note that some stream types may not be able to implement this 100%
+ * reliably, and it is possible that a call to g_input_stream_read()
+ * after this returns %TRUE would still block. To guarantee
+ * non-blocking behavior, you should always use
+ * g_pollable_input_stream_read_nonblocking(), which will return a
+ * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
*
- * Returns: %TRUE on success, or %FALSE if there is no additional link
- * Since: 2.32
+ * 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_menu_link_iter_get_value:
- * @iter: a #GMenuLinkIter
+ * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
+ * @stream: a #GPollableInputStream
+ * @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.
*
- * Gets the linked #GMenuModel at the current iterator position.
+ * Attempts to read up to @count bytes from @stream into @buffer, as
+ * with g_input_stream_read(). If @stream is not currently readable,
+ * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
+ * use g_pollable_input_stream_create_source() to create a #GSource
+ * that will be triggered when @stream is readable.
*
- * The iterator is not advanced.
+ * Note that since this method never blocks, you cannot actually
+ * use @cancellable to cancel it. However, it will return an error
+ * if @cancellable has already been cancelled when you call, which
+ * may happen if you call this method after a source triggers due
+ * to having been cancelled.
*
- * Returns: (transfer full): the #GMenuModel that is linked to
- * Since: 2.32
+ * Returns: the number of bytes read, or -1 on error (including
+ * %G_IO_ERROR_WOULD_BLOCK).
*/
/**
- * g_menu_link_iter_next:
- * @iter: a #GMenuLinkIter
- *
- * Attempts to advance the iterator to the next (possibly first)
- * link.
+ * g_pollable_output_stream_can_poll:
+ * @stream: a #GPollableOutputStream.
*
- * %TRUE is returned on success, or %FALSE if there are no more links.
+ * Checks if @stream is actually pollable. Some classes may implement
+ * #GPollableOutputStream but have only certain instances of that
+ * class be pollable. If this method returns %FALSE, then the behavior
+ * of other #GPollableOutputStream methods is undefined.
*
- * You must call this function when you first acquire the iterator to
- * advance it to the first link (and determine if the first link exists
- * at all).
+ * For any given stream, the value returned by this method is constant;
+ * a stream cannot switch from pollable to non-pollable or vice versa.
*
- * Returns: %TRUE on success, or %FALSE when there are no more links
- * Since: 2.32
+ * Returns: %TRUE if @stream is pollable, %FALSE if not.
+ * Since: 2.28
*/
/**
- * g_menu_markup_parser_end:
- * @context: a #GMarkupParseContext
- *
- * Stop the parsing of a set of menus and return the #GHashTable.
+ * g_pollable_output_stream_create_source:
+ * @stream: a #GPollableOutputStream.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
*
- * The #GHashTable maps strings to #GObject instances. The parser only
- * adds #GMenu instances to the table, but it may contain other types if
- * a table was provided to g_menu_markup_parser_start().
+ * Creates a #GSource that triggers when @stream can be written, or
+ * @cancellable is triggered or an error occurs. The callback on the
+ * source is of the #GPollableSourceFunc type.
*
- * This call should be matched with g_menu_markup_parser_start().
- * See that function for more information
+ * As with g_pollable_output_stream_is_writable(), it is possible that
+ * the stream may not actually be writable even after the source
+ * triggers, so you should use g_pollable_output_stream_write_nonblocking()
+ * rather than g_output_stream_write() from the callback.
*
- * Returns: (transfer full): the #GHashTable containing the objects
- * Since: 2.32
+ * Returns: (transfer full): a new #GSource
+ * Since: 2.28
*/
/**
- * g_menu_markup_parser_end_menu:
- * @context: a #GMarkupParseContext
+ * g_pollable_output_stream_is_writable:
+ * @stream: a #GPollableOutputStream.
*
- * Stop the parsing of a menu and return the newly-created #GMenu.
+ * Checks if @stream can be written.
*
- * This call should be matched with g_menu_markup_parser_start_menu().
- * See that function for more information
+ * Note that some stream types may not be able to implement this 100%
+ * reliably, and it is possible that a call to g_output_stream_write()
+ * after this returns %TRUE would still block. To guarantee
+ * non-blocking behavior, you should always use
+ * g_pollable_output_stream_write_nonblocking(), which will return a
+ * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
*
- * Returns: (transfer full): the newly-created #GMenu
- * Since: 2.32
+ * 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_menu_markup_parser_start:
- * @context: a #GMarkupParseContext
- * @domain: (allow-none): translation domain for labels, or %NULL
- * @objects: (allow-none): a #GHashTable for the objects, or %NULL
- *
- * Begin parsing a group of menus in XML form.
- *
- * If @domain is not %NULL, it will be used to translate attributes
- * that are marked as translatable, using gettext().
- *
- * If @objects is specified then it must be a #GHashTable that was
- * created using g_hash_table_new_full() with g_str_hash(),
- * g_str_equal(), g_free() and g_object_unref(). Any named menus (ie:
- * those with an id='' attribute) that are encountered while parsing
- * will be added to this table. Each toplevel menu must be named.
+ * 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
+ * @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.
*
- * If @objects is %NULL then an empty hash table will be created.
+ * Attempts to write up to @count bytes from @buffer to @stream, as
+ * with g_output_stream_write(). If @stream is not currently writable,
+ * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
+ * use g_pollable_output_stream_create_source() to create a #GSource
+ * that will be triggered when @stream is writable.
*
- * This function should be called from the start_element function for
- * the element representing the group containing the menus. In other
- * words, the content inside of this element is expected to be a list of
- * menus.
+ * Note that since this method never blocks, you cannot actually
+ * use @cancellable to cancel it. However, it will return an error
+ * if @cancellable has already been cancelled when you call, which
+ * may happen if you call this method after a source triggers due
+ * to having been cancelled.
*
- * Since: 2.32
+ * Returns: the number of bytes written, or -1 on error (including
+ * %G_IO_ERROR_WOULD_BLOCK).
*/
/**
- * g_menu_markup_parser_start_menu:
- * @context: a #GMarkupParseContext
- * @domain: (allow-none): translation domain for labels, or %NULL
- * @objects: (allow-none): a #GHashTable for the objects, or %NULL
- *
- * Begin parsing the XML definition of a menu.
- *
- * This function should be called from the start_element function for
- * the element representing the menu itself. In other words, the
- * content inside of this element is expected to be a list of items.
- *
- * If @domain is not %NULL, it will be used to translate attributes
- * that are marked as translatable, using gettext().
- *
- * If @objects is specified then it must be a #GHashTable that was
- * created using g_hash_table_new_full() with g_str_hash(),
- * g_str_equal(), g_free() and g_object_unref(). Any named menus (ie:
- * those with an * id='' attribute) that are encountered while parsing
- * will be added to this table.
- *
- * If @objects is %NULL then named menus will not be supported.
+ * g_pollable_source_new:
+ * @pollable_stream: the stream associated with the new source
*
- * You should call g_menu_markup_parser_end_menu() from the
- * corresponding end_element function in order to collect the newly
- * parsed menu.
+ * Utility method for #GPollableInputStream and #GPollableOutputStream
+ * implementations. Creates a new #GSource that expects a callback of
+ * type #GPollableSourceFunc. The new source does not actually do
+ * anything on its own; use g_source_add_child_source() to add other
+ * sources to it to cause it to trigger.
*
- * Since: 2.32
+ * Returns: (transfer full): the new #GSource.
+ * Since: 2.28
*/
/**
- * g_menu_markup_print_stderr:
- * @model: a #GMenuModel
+ * g_pollable_source_new_full:
+ * @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
*
- * Print @model to stderr for debugging purposes.
+ * Utility method for #GPollableInputStream and #GPollableOutputStream
+ * implementations. Creates a new #GSource, as with
+ * g_pollable_source_new(), but also attaching @child_source (with a
+ * dummy callback), and @cancellable, if they are non-%NULL.
*
- * This debugging function will be removed in the future.
+ * Returns: (transfer full): the new #GSource.
+ * Since: 2.34
*/
/**
- * g_menu_markup_print_string:
- * @string: a #GString
- * @model: the #GMenuModel to print
- * @indent: the intentation level to start at
- * @tabstop: how much to indent each level
+ * g_pollable_stream_read:
+ * @stream: a #GInputStream
+ * @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.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Print the contents of @model to @string.
- * Note that you have to provide the containing
- * <tag class="starttag">menu</tag> element yourself.
+ * Tries to read from @stream, as with g_input_stream_read() (if
+ * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking()
+ * (if @blocking is %FALSE). This can be used to more easily share
+ * code between blocking and non-blocking implementations of a method.
*
- * Returns: @string
- * Since: 2.32
+ * If @blocking is %FALSE, then @stream must be a
+ * #GPollableInputStream for which g_pollable_input_stream_can_poll()
+ * returns %TRUE, or else the behavior is undefined. If @blocking is
+ * %TRUE, then @stream does not need to be a #GPollableInputStream.
+ *
+ * Returns: the number of bytes read, or -1 on error.
+ * Since: 2.34
*/
/**
- * g_menu_model_get_item_attribute:
- * @model: a #GMenuModel
- * @item_index: the index of the item
- * @attribute: the attribute to query
- * @format_string: a #GVariant format string
- * @...: positional parameters, as per @format_string
- *
- * Queries item at position @item_index in @model for the attribute
- * specified by @attribute.
- *
- * 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.
+ * g_pollable_stream_write:
+ * @stream: a #GOutputStream.
+ * @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.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * 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.
+ * Tries to write to @stream, as with g_output_stream_write() (if
+ * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking()
+ * (if @blocking is %FALSE). This can be used to more easily share
+ * code between blocking and non-blocking implementations of a method.
*
- * type
+ * If @blocking is %FALSE, then @stream must be a
+ * #GPollableOutputStream for which
+ * g_pollable_output_stream_can_poll() returns %TRUE or else the
+ * behavior is undefined. If @blocking is %TRUE, then @stream does not
+ * need to be a #GPollableOutputStream.
*
- * Returns: %TRUE if the named attribute was found with the expected
- * Since: 2.32
+ * Returns: the number of bytes written, or -1 on error.
+ * Since: 2.34
*/
/**
- * g_menu_model_get_item_attribute_value:
- * @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
+ * g_pollable_stream_write_all:
+ * @stream: a #GOutputStream.
+ * @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
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
*
- * Queries the item at position @item_index in @model for the attribute
- * specified by @attribute.
+ * Tries to write @count bytes to @stream, as with
+ * g_output_stream_write_all(), but using g_pollable_stream_write()
+ * rather than g_output_stream_write().
*
- * If @expected_type is non-%NULL then it specifies the expected type of
- * the attribute. If it is %NULL then any type will be accepted.
+ * On a successful write of @count bytes, %TRUE is returned, and
+ * @bytes_written is set to @count.
*
- * If the attribute exists and matches @expected_type (or if the
- * expected type is unspecified) then the value is returned.
+ * If there is an error during the operation (including
+ * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %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.
*
- * If the attribute does not exist, or does not match the expected type
- * then %NULL is returned.
+ * As with g_pollable_stream_write(), if @blocking is %FALSE, then
+ * @stream must be a #GPollableOutputStream for which
+ * g_pollable_output_stream_can_poll() returns %TRUE or else the
+ * behavior is undefined. If @blocking is %TRUE, then @stream does not
+ * need to be a #GPollableOutputStream.
*
- * Returns: (transfer full): the value of the attribute
- * Since: 2.32
+ * Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.34
*/
/**
- * g_menu_model_get_item_link:
- * @model: a #GMenuModel
- * @item_index: the index of the item
- * @link: the link to query
+ * 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
*
- * Queries the item at position @item_index in @model for the link
- * specified by @link.
+ * Creates a #GAction corresponding to the value of property
+ * @property_name on @object.
*
- * If the link exists, the linked #GMenuModel is returned. If the link
- * does not exist, %NULL is returned.
+ * The property must be existent and readable and writable (and not
+ * construct-only).
*
- * Returns: (transfer full): the linked #GMenuModel, or %NULL
- * Since: 2.32
+ * 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_menu_model_get_n_items:
- * @model: a #GMenuModel
+ * g_proxy_address_get_destination_hostname:
+ * @proxy: a #GProxyAddress
*
- * Query the number of items in @model.
+ * Gets @proxy's destination hostname; that is, the name of the host
+ * that will be connected to via the proxy, not the name of the proxy
+ * itself.
*
- * Returns: the number of items
- * Since: 2.32
+ * Returns: the @proxy's destination hostname
+ * Since: 2.26
*/
/**
- * g_menu_model_is_mutable:
- * @model: a #GMenuModel
- *
- * Queries if @model is mutable.
- *
- * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
- * signal. Consumers of the model may make optimisations accordingly.
+ * g_proxy_address_get_destination_port:
+ * @proxy: a #GProxyAddress
*
- * emitted).
+ * Gets @proxy's destination port; that is, the port on the
+ * destination host that will be connected to via the proxy, not the
+ * port number of the proxy itself.
*
- * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
- * Since: 2.32
+ * Returns: the @proxy's destination port
+ * Since: 2.26
*/
/**
- * g_menu_model_items_changed:
- * @model: a #GMenuModel
- * @position: the position of the change
- * @removed: the number of items removed
- * @added: the number of items added
- *
- * Requests emission of the #GMenuModel::items-changed signal on @model.
- *
- * This function should never be called except by #GMenuModel
- * subclasses. Any other calls to this function will very likely lead
- * to a violation of the interface of the model.
- *
- * The implementation should update its internal representation of the
- * menu before emitting the signal. The implementation should further
- * expect to receive queries about the new state of the menu (and
- * particularly added menu items) while signal handlers are running.
+ * g_proxy_address_get_destination_protocol:
+ * @proxy: a #GProxyAddress
*
- * The implementation must dispatch this call directly from a mainloop
- * entry and not in response to calls -- particularly those from the
- * #GMenuModel API. Said another way: the menu must not change while
- * user code is running without returning to the mainloop.
+ * Gets the protocol that is being spoken to the destination
+ * server; eg, "http" or "ftp".
*
- * Since: 2.32
+ * Returns: the @proxy's destination protocol
+ * Since: 2.34
*/
/**
- * g_menu_model_iterate_item_attributes:
- * @model: a #GMenuModel
- * @item_index: the index of the item
- *
- * Creates a #GMenuAttributeIter to iterate over the attributes of
- * the item at position @item_index in @model.
+ * g_proxy_address_get_password:
+ * @proxy: a #GProxyAddress
*
- * You must free the iterator with g_object_unref() when you are done.
+ * Gets @proxy's password.
*
- * Returns: (transfer full): a new #GMenuAttributeIter
- * Since: 2.32
+ * Returns: the @proxy's password
+ * Since: 2.26
*/
/**
- * g_menu_model_iterate_item_links:
- * @model: a #GMenuModel
- * @item_index: the index of the item
- *
- * Creates a #GMenuLinkIter to iterate over the links of the item at
- * position @item_index in @model.
+ * g_proxy_address_get_protocol:
+ * @proxy: a #GProxyAddress
*
- * You must free the iterator with g_object_unref() when you are done.
+ * Gets @proxy's protocol. eg, "socks" or "http"
*
- * Returns: (transfer full): a new #GMenuLinkIter
- * Since: 2.32
+ * Returns: the @proxy's protocol
+ * Since: 2.26
*/
/**
- * g_menu_new:
- *
- * Creates a new #GMenu.
+ * g_proxy_address_get_uri:
+ * @proxy: a #GProxyAddress
*
- * The new menu has no items.
+ * Gets the proxy URI that @proxy was constructed from.
*
- * Returns: a new #GMenu
- * Since: 2.32
+ * Returns: the @proxy's URI, or %NULL if unknown
+ * Since: 2.34
*/
/**
- * g_menu_prepend:
- * @menu: a #GMenu
- * @label: (allow-none): the section label, or %NULL
- * @detailed_action: (allow-none): the detailed action string, or %NULL
+ * g_proxy_address_get_username:
+ * @proxy: a #GProxyAddress
*
- * Convenience function for prepending a normal menu item to the start
- * of @menu. Combine g_menu_new() and g_menu_insert_item() for a more
- * flexible alternative.
+ * Gets @proxy's username.
*
- * Since: 2.32
+ * Returns: the @proxy's username
+ * Since: 2.26
*/
/**
- * g_menu_prepend_item:
- * @menu: a #GMenu
- * @item: a #GMenuItem to prepend
+ * g_proxy_address_new:
+ * @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 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).
*
- * Prepends @item to the start of @menu.
+ * Creates a new #GProxyAddress for @inetaddr with @protocol that should
+ * tunnel through @dest_hostname and @dest_port.
*
- * See g_menu_insert_item() for more information.
+ * (Note that this method doesn't set the #GProxyAddress:uri or
+ * #GProxyAddress:destination-protocol fields; use g_object_new()
+ * directly if you want to set those.)
*
- * Since: 2.32
+ * Returns: a new #GProxyAddress
+ * Since: 2.26
*/
/**
- * g_menu_prepend_section:
- * @menu: a #GMenu
- * @label: (allow-none): the section label, or %NULL
- * @section: a #GMenuModel with the items of the section
+ * g_proxy_connect:
+ * @proxy: a #GProxy
+ * @connection: a #GIOStream
+ * @proxy_address: a #GProxyAddress
+ * @cancellable: (allow-none): a #GCancellable
+ * @error: return #GError
*
- * Convenience function for prepending a section menu item to the start
- * of @menu. Combine g_menu_new_section() and g_menu_insert_item() for
- * a more flexible alternative.
+ * Given @connection to communicate with a proxy (eg, a
+ * #GSocketConnection that is connected to the proxy server), this
+ * does the necessary handshake to connect to @proxy_address, and if
+ * required, wraps the #GIOStream to handle proxy payload.
*
- * Since: 2.32
+ * 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
*/
/**
- * g_menu_prepend_submenu:
- * @menu: a #GMenu
- * @label: (allow-none): the section label, or %NULL
- * @submenu: a #GMenuModel with the items of the submenu
+ * g_proxy_connect_async:
+ * @proxy: a #GProxy
+ * @connection: a #GIOStream
+ * @proxy_address: a #GProxyAddress
+ * @cancellable: (allow-none): a #GCancellable
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): callback data
*
- * Convenience function for prepending a submenu menu item to the start
- * of @menu. Combine g_menu_new_submenu() and g_menu_insert_item() for
- * a more flexible alternative.
+ * Asynchronous version of g_proxy_connect().
*
- * Since: 2.32
+ * Since: 2.26
*/
/**
- * g_menu_remove:
- * @menu: a #GMenu
- * @position: the position of the item to remove
- *
- * Removes an item from the menu.
- *
- * @position gives the index of the item to remove.
- *
- * It is an error if position is not in range the range from 0 to one
- * less than the number of items in the menu.
+ * g_proxy_connect_finish:
+ * @proxy: a #GProxy
+ * @result: a #GAsyncResult
+ * @error: return #GError
*
- * It is not possible to remove items by identity since items are added
- * to the menu simply by copying their links and attributes (ie:
- * identity of the item itself is not preserved).
+ * See g_proxy_connect().
*
- * Since: 2.32
+ * Returns: (transfer full): a #GIOStream.
+ * Since: 2.26
*/
/**
- * g_mount_can_eject:
- * @mount: a #GMount.
+ * g_proxy_get_default_for_protocol:
+ * @protocol: the proxy protocol name (e.g. http, socks, etc)
*
- * Checks if @mount can be eject.
+ * Lookup "gio-proxy" extension point for a proxy implementation that supports
+ * specified protocol.
*
- * Returns: %TRUE if the @mount can be ejected.
+ * Returns: (transfer full): return a #GProxy or NULL if protocol
+ * is not supported.
+ * Since: 2.26
*/
/**
- * g_mount_can_unmount:
- * @mount: a #GMount.
+ * g_proxy_resolver_get_default:
*
- * Checks if @mount can be mounted.
+ * Gets the default #GProxyResolver for the system.
*
- * Returns: %TRUE if the @mount can be unmounted.
+ * Returns: (transfer none): the default #GProxyResolver.
+ * Since: 2.26
*/
/**
- * g_mount_eject:
- * @mount: a #GMount.
- * @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.
- * @user_data: user data passed to @callback.
+ * g_proxy_resolver_is_supported:
+ * @resolver: a #GProxyResolver
*
- * Ejects a mount. This is an asynchronous operation, and is
- * finished by calling g_mount_eject_finish() with the @mount
- * and #GAsyncResult data returned in the @callback.
+ * Checks if @resolver can be used on this system. (This is used
+ * internally; g_proxy_resolver_get_default() will only return a proxy
+ * resolver that returns %TRUE for this method.)
*
- * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
+ * Returns: %TRUE if @resolver is supported.
+ * Since: 2.26
*/
/**
- * g_mount_eject_finish:
- * @mount: a #GMount.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_proxy_resolver_lookup:
+ * @resolver: a #GProxyResolver
+ * @uri: a URI representing the destination to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * Finishes ejecting a mount. If any errors occurred during the operation,
- * @error will be set to contain the errors and %FALSE will be returned.
+ * 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 `<protocol>://[user[:password]@]host:port` or
+ * `direct://`, where <protocol> could be http, rtsp, socks
+ * or other proxying protocol.
*
- * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
- * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
- */
-
-
-/**
- * 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.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
- * @user_data: user data passed to @callback.
+ * If you don't know what network protocol is being used on the
+ * 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).
*
- * Ejects a mount. This is an asynchronous operation, and is
- * finished by calling g_mount_eject_with_operation_finish() with the @mount
- * and #GAsyncResult data returned in the @callback.
+ * `direct://` is used when no proxy is needed.
+ * Direct connection should not be attempted unless it is part of the
+ * returned array of proxies.
*
- * Since: 2.22
+ * Returns: (transfer full) (array zero-terminated=1): A
+ * NULL-terminated array of proxy URIs. Must be freed
+ * with g_strfreev().
+ * Since: 2.26
*/
/**
- * 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.
+ * g_proxy_resolver_lookup_async:
+ * @resolver: a #GProxyResolver
+ * @uri: a URI representing the destination to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): callback to call after resolution completes
+ * @user_data: (closure): data for @callback
*
- * Finishes ejecting a mount. If any errors occurred during the operation,
- * @error will be set to contain the errors and %FALSE will be returned.
+ * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
+ * details.
*
- * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * g_mount_get_default_location:
- * @mount: a #GMount.
- *
- * Gets the default location of @mount. The default location of the given
- * @mount is a path that reflects the main entry point for the user (e.g.
- * the home directory, or the root of the volume).
+ * g_proxy_resolver_lookup_finish:
+ * @resolver: a #GProxyResolver
+ * @result: the result passed to your #GAsyncReadyCallback
+ * @error: return location for a #GError, or %NULL
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
+ * Call this function to obtain the array of proxy URIs when
+ * g_proxy_resolver_lookup_async() is complete. See
+ * g_proxy_resolver_lookup() for more details.
*
- * Returns: (transfer full): a #GFile.
+ * Returns: (transfer full) (array zero-terminated=1): A
+ * NULL-terminated array of proxy URIs. Must be freed
+ * with g_strfreev().
+ * Since: 2.26
*/
/**
- * g_mount_get_drive:
- * @mount: a #GMount.
- *
- * Gets the drive for the @mount.
- *
- * This is a convenience method for getting the #GVolume and then
- * using that object to get the #GDrive.
+ * g_proxy_supports_hostname:
+ * @proxy: a #GProxy
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
+ * Some proxy protocols expect to be passed a hostname, which they
+ * will resolve to an IP address themselves. Others, like SOCKS4, do
+ * not allow this. This function will return %FALSE if @proxy is
+ * implementing such a protocol. When %FALSE is returned, the caller
+ * should resolve the destination hostname first, and then pass a
+ * #GProxyAddress containing the stringified IP address to
+ * g_proxy_connect() or g_proxy_connect_async().
*
- * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
+ * Returns: %TRUE if hostname resolution is supported.
+ * Since: 2.26
*/
/**
- * g_mount_get_icon:
- * @mount: a #GMount.
+ * g_remote_action_group_activate_action_full:
+ * @remote: a #GDBusActionGroup
+ * @action_name: the name of the action to activate
+ * @parameter: (allow-none): the optional parameter to the activation
+ * @platform_data: the platform data to send
*
- * Gets the icon for @mount.
+ * Activates the remote action.
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
+ * This is the same as g_action_group_activate_action() except that it
+ * allows for provision of "platform data" to be sent along with the
+ * activation request. This typically contains details such as the user
+ * interaction timestamp or startup notification information.
*
- * Returns: (transfer full): a #GIcon.
+ * @platform_data must be non-%NULL and must have the type
+ * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
+ *
+ * Since: 2.32
*/
/**
- * g_mount_get_name:
- * @mount: a #GMount.
+ * g_remote_action_group_change_action_state_full:
+ * @remote: a #GRemoteActionGroup
+ * @action_name: the name of the action to change the state of
+ * @value: the new requested value for the state
+ * @platform_data: the platform data to send
*
- * Gets the name of @mount.
+ * Changes the state of a remote action.
+ *
+ * This is the same as g_action_group_change_action_state() except that
+ * it allows for provision of "platform data" to be sent along with the
+ * state change request. This typically contains details such as the
+ * user interaction timestamp or startup notification information.
*
- * The returned string should be freed with g_free()
- * when no longer needed.
+ * @platform_data must be non-%NULL and must have the type
+ * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
*
- * Returns: the name for the given @mount.
+ * Since: 2.32
*/
/**
- * g_mount_get_root:
- * @mount: a #GMount.
- *
- * Gets the root directory on @mount.
+ * g_resolver_error_quark:
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
+ * Gets the #GResolver Error Quark.
*
- * Returns: (transfer full): a #GFile.
+ * Returns: a #GQuark.
+ * Since: 2.22
*/
/**
- * g_mount_get_sort_key:
- * @mount: A #GMount.
+ * g_resolver_free_addresses: (skip)
+ * @addresses: a #GList of #GInetAddress
*
- * Gets the sort key for @mount, if any.
+ * Frees @addresses (which should be the return value from
+ * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
+ * (This is a convenience method; you can also simply free the results
+ * by hand.)
*
- * Returns: Sorting key for @mount or %NULL if no such key is available.
- * Since: 2.32
+ * Since: 2.22
*/
/**
- * g_mount_get_uuid:
- * @mount: a #GMount.
- *
- * Gets the UUID for the @mount. The reference is typically based on
- * the file system UUID for the mount in question and should be
- * considered an opaque string. Returns %NULL if there is no UUID
- * available.
+ * g_resolver_free_targets: (skip)
+ * @targets: a #GList of #GSrvTarget
*
- * The returned string should be freed with g_free()
- * when no longer needed.
+ * Frees @targets (which should be the return value from
+ * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
+ * (This is a convenience method; you can also simply free the
+ * results by hand.)
*
- * Returns: the UUID for @mount or %NULL if no UUID can be computed.
+ * Since: 2.22
*/
/**
- * g_mount_get_volume:
- * @mount: a #GMount.
- *
- * Gets the volume for the @mount.
+ * g_resolver_get_default:
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
+ * Gets the default #GResolver. You should unref it when you are done
+ * with it. #GResolver may use its reference count as a hint about how
+ * many threads it should allocate for concurrent DNS resolutions.
*
- * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
+ * Returns: (transfer full): the default #GResolver.
+ * Since: 2.22
*/
/**
- * 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
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: a #GAsyncReadyCallback
- * @user_data: user data passed to @callback
+ * g_resolver_lookup_by_address:
+ * @resolver: a #GResolver
+ * @address: the address to reverse-resolve
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * 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>
- * specification for more on x-content types.
+ * Synchronously reverse-resolves @address to determine its
+ * associated hostname.
*
- * This is an asynchronous operation (see
- * g_mount_guess_content_type_sync() for the synchronous version), and
- * is finished by calling g_mount_guess_content_type_finish() with the
- * @mount and #GAsyncResult data returned in the @callback.
+ * If the DNS resolution fails, @error (if non-%NULL) will be set to
+ * a value from #GResolverError.
*
- * Since: 2.18
+ * 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: a hostname (either ASCII-only, or in ASCII-encoded
+ * form), or %NULL on error.
+ * Since: 2.22
*/
/**
- * 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
- *
- * Finishes guessing content types of @mount. If any errors occurred
- * during the operation, @error will be set to contain the errors and
- * %FALSE will be returned. In particular, you may get an
- * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
- * guessing.
+ * g_resolver_lookup_by_address_async:
+ * @resolver: a #GResolver
+ * @address: the address to reverse-resolve
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): callback to call after resolution completes
+ * @user_data: (closure): data for @callback
*
- * Caller should free this array with g_strfreev() when done with it.
+ * Begins asynchronously reverse-resolving @address to determine its
+ * associated hostname, and eventually calls @callback, which must
+ * call g_resolver_lookup_by_address_finish() to get the final result.
*
- * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
- * Since: 2.18
+ * Since: 2.22
*/
/**
- * 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
- * @cancellable: (allow-none): optional #GCancellable object, %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>
- * specification for more on x-content types.
+ * g_resolver_lookup_by_address_finish:
+ * @resolver: a #GResolver
+ * @result: the result passed to your #GAsyncReadyCallback
+ * @error: return location for a #GError, or %NULL
*
- * This is an synchronous operation and as such may block doing IO;
- * see g_mount_guess_content_type() for the asynchronous version.
+ * Retrieves the result of a previous call to
+ * g_resolver_lookup_by_address_async().
*
- * Caller should free this array with g_strfreev() when done with it.
+ * 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: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
- * Since: 2.18
+ * Returns: a hostname (either ASCII-only, or in ASCII-encoded
+ * form), or %NULL on error.
+ * Since: 2.22
*/
/**
- * g_mount_is_shadowed:
- * @mount: A #GMount.
+ * g_resolver_lookup_by_name:
+ * @resolver: a #GResolver
+ * @hostname: the hostname to look up
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * Determines if @mount is shadowed. Applications or libraries should
- * avoid displaying @mount in the user interface if it is shadowed.
+ * Synchronously resolves @hostname to determine its associated IP
+ * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
+ * the textual form of an IP address (in which case this just becomes
+ * a wrapper around g_inet_address_new_from_string()).
*
- * A mount is said to be shadowed if there exists one or more user
- * visible objects (currently #GMount objects) with a root that is
- * inside the root of @mount.
+ * 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
+ * first, then the second if the first fails, etc. If you are using
+ * the result to listen on a socket, it is appropriate to add each
+ * result using e.g. g_socket_listener_add_address().
*
- * One application of shadow mounts is when exposing a single file
- * system that is used to address several logical volumes. In this
- * 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
- * underlying mount (with root
- * <literal>gphoto2://[usb:001,002]/</literal>) 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.
+ * If the DNS resolution fails, @error (if non-%NULL) will be set to a
+ * value from #GResolverError and %NULL will be returned.
*
- * The proxy monitor in GVfs 2.26 and later, automatically creates and
- * manage shadow mounts (and shadows the underlying mount) if the
- * activation root on a #GVolume is set.
+ * 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: %TRUE if @mount is shadowed.
- * Since: 2.20
+ * If you are planning to connect to a socket on the resolved IP
+ * address, it may be easier to create a #GNetworkAddress and use its
+ * #GSocketConnectable interface.
+ *
+ * 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
*/
/**
- * g_mount_operation_get_anonymous:
- * @op: a #GMountOperation.
+ * g_resolver_lookup_by_name_async:
+ * @resolver: a #GResolver
+ * @hostname: the hostname to look up the address of
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): callback to call after resolution completes
+ * @user_data: (closure): data for @callback
*
- * Check to see whether the mount operation is being used
- * for an anonymous user.
+ * Begins asynchronously resolving @hostname to determine its
+ * associated IP address(es), and eventually calls @callback, which
+ * must call g_resolver_lookup_by_name_finish() to get the result.
+ * See g_resolver_lookup_by_name() for more details.
*
- * Returns: %TRUE if mount operation is anonymous.
+ * Since: 2.22
*/
/**
- * g_mount_operation_get_choice:
- * @op: a #GMountOperation.
+ * g_resolver_lookup_by_name_finish:
+ * @resolver: a #GResolver
+ * @result: the result passed to your #GAsyncReadyCallback
+ * @error: return location for a #GError, or %NULL
*
- * Gets a choice from the mount operation.
+ * Retrieves the result of a call to
+ * g_resolver_lookup_by_name_async().
*
- * the choice's list, or %0.
+ * 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: an integer containing an index of the user's choice from
+ * 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
*/
/**
- * g_mount_operation_get_domain:
- * @op: a #GMountOperation.
+ * g_resolver_lookup_records:
+ * @resolver: a #GResolver
+ * @rrname: the DNS name to lookup the record for
+ * @record_type: the type of DNS record to lookup
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * Gets the domain of the mount operation.
+ * Synchronously performs a DNS record lookup for the given @rrname and returns
+ * a list of records as #GVariant tuples. See #GResolverRecordType for
+ * information on what the records contain for each @record_type.
*
- * Returns: a string set to the domain.
+ * If the DNS resolution fails, @error (if non-%NULL) will be set to
+ * 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 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
*/
/**
- * g_mount_operation_get_password:
- * @op: a #GMountOperation.
+ * g_resolver_lookup_records_async:
+ * @resolver: a #GResolver
+ * @rrname: the DNS name to lookup the record for
+ * @record_type: the type of DNS record to lookup
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): callback to call after resolution completes
+ * @user_data: (closure): data for @callback
*
- * Gets a password from the mount operation.
+ * Begins asynchronously performing a DNS lookup for the given
+ * @rrname, and eventually calls @callback, which must call
+ * g_resolver_lookup_records_finish() to get the final result. See
+ * g_resolver_lookup_records() for more details.
*
- * Returns: a string containing the password within @op.
+ * Since: 2.34
*/
/**
- * g_mount_operation_get_password_save:
- * @op: a #GMountOperation.
+ * g_resolver_lookup_records_finish:
+ * @resolver: a #GResolver
+ * @result: the result passed to your #GAsyncReadyCallback
+ * @error: return location for a #GError, or %NULL
*
- * Gets the state of saving passwords for the mount operation.
+ * Retrieves the result of a previous call to
+ * g_resolver_lookup_records_async(). Returns a non-empty list of records as
+ * #GVariant tuples. See #GResolverRecordType for information on what the
+ * records contain.
*
- * Returns: a #GPasswordSave flag.
+ * 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 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
*/
/**
- * g_mount_operation_get_username:
- * @op: a #GMountOperation.
+ * g_resolver_lookup_service:
+ * @resolver: a #GResolver
+ * @service: the service type to look up (eg, "ldap")
+ * @protocol: the networking protocol to use for @service (eg, "tcp")
+ * @domain: the DNS domain to look up the service in
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * Get the user name from the mount operation.
+ * 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 do not include the leading underscore
+ * that appears in the actual DNS entry.
*
- * Returns: a string containing the user name.
+ * 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 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.
+ *
+ * If you are planning to connect to the service, it is usually easier
+ * to create a #GNetworkService and use its #GSocketConnectable
+ * interface.
+ *
+ * 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
*/
/**
- * g_mount_operation_new:
+ * g_resolver_lookup_service_async:
+ * @resolver: a #GResolver
+ * @service: the service type to look up (eg, "ldap")
+ * @protocol: the networking protocol to use for @service (eg, "tcp")
+ * @domain: the DNS domain to look up the service in
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): callback to call after resolution completes
+ * @user_data: (closure): data for @callback
*
- * Creates a new mount operation.
+ * Begins asynchronously performing a DNS SRV lookup for the given
+ * @service and @protocol in the given @domain, and eventually calls
+ * @callback, which must call g_resolver_lookup_service_finish() to
+ * get the final result. See g_resolver_lookup_service() for more
+ * details.
*
- * Returns: a #GMountOperation.
+ * Since: 2.22
*/
/**
- * g_mount_operation_reply:
- * @op: a #GMountOperation
- * @result: a #GMountOperationResult
+ * g_resolver_lookup_service_finish:
+ * @resolver: a #GResolver
+ * @result: the result passed to your #GAsyncReadyCallback
+ * @error: return location for a #GError, or %NULL
*
- * Emits the #GMountOperation::reply signal.
+ * Retrieves the result of a previous call to
+ * g_resolver_lookup_service_async().
+ *
+ * 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 GSrvTarget) (transfer full): a non-empty #GList of
+ * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
+ * details.
+ * Since: 2.22
*/
/**
- * g_mount_operation_set_anonymous:
- * @op: a #GMountOperation.
- * @anonymous: boolean value.
+ * g_resolver_set_default:
+ * @resolver: the new default #GResolver
*
- * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
+ * Sets @resolver to be the application's default resolver (reffing
+ * @resolver, and unreffing the previous default resolver, if any).
+ * Future calls to g_resolver_get_default() will return this resolver.
+ *
+ * This can be used if an application wants to perform any sort of DNS
+ * caching or "pinning"; it can implement its own #GResolver that
+ * calls the original default resolver for DNS operations, and
+ * implements its own cache policies on top of that, and then set
+ * itself as the default resolver for all later code to use.
+ *
+ * Since: 2.22
*/
/**
- * g_mount_operation_set_choice:
- * @op: a #GMountOperation.
- * @choice: an integer.
+ * g_resource_enumerate_children:
+ * @resource: A #GResource
+ * @path: A pathname inside the resource
+ * @lookup_flags: A #GResourceLookupFlags
+ * @error: return location for a #GError, or %NULL
*
- * Sets a default choice for the mount operation.
+ * Returns all the names of children at the specified @path in the resource.
+ * The return result is a %NULL terminated list of strings which should
+ * be released with g_strfreev().
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
+ * Since: 2.32
*/
/**
- * g_mount_operation_set_domain:
- * @op: a #GMountOperation.
- * @domain: the domain to set.
+ * g_resource_error_quark:
*
- * Sets the mount operation's domain.
+ * Gets the #GResource Error Quark.
+ *
+ * Returns: a #GQuark
+ * Since: 2.32
*/
/**
- * g_mount_operation_set_password:
- * @op: a #GMountOperation.
- * @password: password to set.
+ * g_resource_get_info:
+ * @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
+ * @error: return location for a #GError, or %NULL
*
- * Sets the mount operation's password to @password.
+ * Looks for a file at the specified @path in the resource and
+ * if found returns information about it.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: %TRUE if the file was found. %FALSE if there were errors
+ * Since: 2.32
*/
/**
- * g_mount_operation_set_password_save:
- * @op: a #GMountOperation.
- * @save: a set of #GPasswordSave flags.
+ * g_resource_load:
+ * @filename: (type filename): the path of a filename to load, in the GLib filename encoding
+ * @error: return location for a #GError, or %NULL
*
- * Sets the state of saving passwords for the mount operation.
+ * Loads a binary resource bundle and creates a #GResource representation of it, allowing
+ * you to query it for data.
+ *
+ * If you want to use this resource in the global resource namespace you need
+ * to register it with g_resources_register().
+ *
+ * Returns: (transfer full): a new #GResource, or %NULL on error
+ * Since: 2.32
*/
/**
- * g_mount_operation_set_username:
- * @op: a #GMountOperation.
- * @username: input username.
+ * g_resource_lookup_data:
+ * @resource: A #GResource
+ * @path: A pathname inside the resource
+ * @lookup_flags: A #GResourceLookupFlags
+ * @error: return location for a #GError, or %NULL
*
- * Sets the user name within @op to @username.
+ * Looks for a file at the specified @path in the resource and
+ * returns a #GBytes that lets you directly access the data in
+ * memory.
+ *
+ * The data is always followed by a zero byte, so you
+ * can safely use the data as a C string. However, that byte
+ * is not included in the size of the GBytes.
+ *
+ * For uncompressed resource files this is a pointer directly into
+ * the resource bundle, which is typically in some readonly data section
+ * in the program binary. For compressed files we allocate memory on
+ * the heap and automatically uncompress the data.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GBytes or %NULL on error.
+ * Free the returned object with g_bytes_unref()
+ * Since: 2.32
*/
/**
- * g_mount_remount:
- * @mount: a #GMount.
- * @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.
- * @user_data: user data passed to @callback.
+ * g_resource_new_from_data:
+ * @data: A #GBytes
+ * @error: return location for a #GError, or %NULL
*
- * Remounts a mount. This is an asynchronous operation, and is
- * finished by calling g_mount_remount_finish() with the @mount
- * and #GAsyncResults data returned in the @callback.
+ * Creates a GResource from a reference to the binary resource bundle.
+ * This will keep a reference to @data while the resource lives, so
+ * the data should not be modified or freed.
*
- * Remounting is useful when some setting affecting the operation
- * of the volume has been changed, as these may need a remount to
- * take affect. While this is semantically equivalent with unmounting
- * and then remounting not all backends might need to actually be
- * unmounted.
+ * If you want to use this resource in the global resource namespace you need
+ * to register it with g_resources_register().
+ *
+ * Returns: (transfer full): a new #GResource, or %NULL on error
+ * Since: 2.32
*/
/**
- * g_mount_remount_finish:
- * @mount: a #GMount.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_resource_open_stream:
+ * @resource: A #GResource
+ * @path: A pathname inside the resource
+ * @lookup_flags: A #GResourceLookupFlags
+ * @error: return location for a #GError, or %NULL
*
- * Finishes remounting a mount. If any errors occurred during the operation,
- * @error will be set to contain the errors and %FALSE will be returned.
+ * Looks for a file at the specified @path in the resource and
+ * returns a #GInputStream that lets you read the data.
*
- * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GInputStream or %NULL on error.
+ * Free the returned object with g_object_unref()
+ * Since: 2.32
*/
/**
- * g_mount_shadow:
- * @mount: A #GMount.
+ * g_resource_ref:
+ * @resource: A #GResource
*
- * Increments the shadow count on @mount. Usually used by
- * #GVolumeMonitor implementations when creating a shadow mount for
- * @mount, see g_mount_is_shadowed() for more information. The caller
- * will need to emit the #GMount::changed signal on @mount manually.
+ * Atomically increments the reference count of @array by one. This
+ * function is MT-safe and may be called from any thread.
*
- * Since: 2.20
+ * Returns: The passed in #GResource
+ * Since: 2.32
*/
/**
- * g_mount_unmount:
- * @mount: a #GMount.
- * @flags: flags affecting the operation
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
- * @user_data: user data passed to @callback.
+ * g_resource_unref:
+ * @resource: A #GResource
*
- * Unmounts a mount. This is an asynchronous operation, and is
- * finished by calling g_mount_unmount_finish() with the @mount
- * and #GAsyncResult data returned in the @callback.
+ * Atomically decrements the reference count of @resource by one. If the
+ * reference count drops to 0, all memory allocated by the array is
+ * released. This function is MT-safe and may be called from any
+ * thread.
*
- * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
+ * Since: 2.32
*/
/**
- * g_mount_unmount_finish:
- * @mount: a #GMount.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_resources_enumerate_children:
+ * @path: A pathname inside the resource
+ * @lookup_flags: A #GResourceLookupFlags
+ * @error: return location for a #GError, or %NULL
*
- * Finishes unmounting a mount. If any errors occurred during the operation,
- * @error will be set to contain the errors and %FALSE will be returned.
+ * Returns all the names of children at the specified @path in the set of
+ * globally registered resources.
+ * The return result is a %NULL terminated list of strings which should
+ * be released with g_strfreev().
*
- * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
- * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
+ * Since: 2.32
*/
/**
- * 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.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
- * @user_data: user data passed to @callback.
+ * 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
+ * @error: return location for a #GError, or %NULL
*
- * Unmounts a mount. This is an asynchronous operation, and is
- * finished by calling g_mount_unmount_with_operation_finish() with the @mount
- * and #GAsyncResult data returned in the @callback.
+ * Looks for a file at the specified @path in the set of
+ * globally registered resources and if found returns information about it.
*
- * Since: 2.22
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: %TRUE if the file was found. %FALSE if there were errors
+ * Since: 2.32
*/
/**
- * 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.
+ * g_resources_lookup_data:
+ * @path: A pathname inside the resource
+ * @lookup_flags: A #GResourceLookupFlags
+ * @error: return location for a #GError, or %NULL
*
- * Finishes unmounting a mount. If any errors occurred during the operation,
- * @error will be set to contain the errors and %FALSE will be returned.
+ * Looks for a file at the specified @path in the set of
+ * globally registered resources and returns a #GBytes that
+ * lets you directly access the data in memory.
*
- * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
- * Since: 2.22
+ * The data is always followed by a zero byte, so you
+ * can safely use the data as a C string. However, that byte
+ * is not included in the size of the GBytes.
+ *
+ * For uncompressed resource files this is a pointer directly into
+ * the resource bundle, which is typically in some readonly data section
+ * in the program binary. For compressed files we allocate memory on
+ * the heap and automatically uncompress the data.
+ *
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GBytes or %NULL on error.
+ * Free the returned object with g_bytes_unref()
+ * Since: 2.32
*/
/**
- * g_mount_unshadow:
- * @mount: A #GMount.
+ * g_resources_open_stream:
+ * @path: A pathname inside the resource
+ * @lookup_flags: A #GResourceLookupFlags
+ * @error: return location for a #GError, or %NULL
*
- * Decrements the shadow count on @mount. Usually used by
- * #GVolumeMonitor implementations when destroying a shadow mount for
- * @mount, see g_mount_is_shadowed() for more information. The caller
- * will need to emit the #GMount::changed signal on @mount manually.
+ * Looks for a file at the specified @path in the set of
+ * globally registered resources and returns a #GInputStream
+ * that lets you read the data.
*
- * Since: 2.20
+ * @lookup_flags controls the behaviour of the lookup.
+ *
+ * Returns: (transfer full): #GInputStream or %NULL on error.
+ * Free the returned object with g_object_unref()
+ * Since: 2.32
*/
/**
- * g_network_address_get_hostname:
- * @addr: a #GNetworkAddress
+ * g_resources_register:
+ * @resource: A #GResource
*
- * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
- * depending on what @addr was created with.
+ * Registers the resource with the process-global set of resources.
+ * Once a resource is registered the files in it can be accessed
+ * with the global resource lookup functions like g_resources_lookup_data().
*
- * Returns: @addr's hostname
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_network_address_get_port:
- * @addr: a #GNetworkAddress
+ * g_resources_unregister:
+ * @resource: A #GResource
*
- * Gets @addr's port number
+ * Unregisters the resource from the process-global set of resources.
*
- * Returns: @addr's port (which may be 0)
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_network_address_get_scheme:
- * @addr: a #GNetworkAddress
+ * g_seekable_can_seek:
+ * @seekable: a #GSeekable.
*
- * Gets @addr's scheme
+ * Tests if the stream supports the #GSeekableIface.
*
- * Returns: @addr's scheme (%NULL if not built from URI)
- * Since: 2.26
+ * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
*/
/**
- * g_network_address_new:
- * @hostname: the hostname
- * @port: the port
+ * g_seekable_can_truncate:
+ * @seekable: a #GSeekable.
*
- * Creates a new #GSocketConnectable for connecting to the given
- * @hostname and @port.
+ * Tests if the stream can be truncated.
*
- * Returns: (transfer full): the new #GNetworkAddress
- * Since: 2.22
+ * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
*/
/**
- * g_network_address_parse:
- * @host_and_port: the hostname and optionally a port
- * @default_port: the default port if not in @host_and_port
- * @error: a pointer to a #GError, or %NULL
- *
- * Creates a new #GSocketConnectable for connecting to the given
- * @hostname and @port. May fail and return %NULL in case
- * parsing @host_and_port fails.
+ * g_seekable_seek:
+ * @seekable: a #GSeekable.
+ * @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.
*
- * @host_and_port may be in any of a number of recognised formats; an IPv6
- * address, an IPv4 address, or a domain name (in which case a DNS
- * lookup is performed). Quoting with [] is supported for all address
- * types. A port override may be specified in the usual way with a
- * colon.
+ * Seeks in the stream by the given @offset, modified by @type.
*
- * If no port is specified in @host_and_port then @default_port will be
- * used as the port number to connect to.
+ * 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.
*
- * In general, @host_and_port is expected to be provided by the user
- * (allowing them to give the hostname, and a port overide if necessary)
- * and @default_port is expected to be provided by the application.
+ * Any operation that would result in a negative offset will fail.
*
- * (The port component of @host_and_port can also be specified as a
- * service name rather than as a numeric port, but this functionality
- * is deprecated, because it depends on the contents of /etc/services,
- * which is generally quite sparse on platforms other than Linux.)
+ * 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): the new #GNetworkAddress, or %NULL on error
- * Since: 2.22
+ * Returns: %TRUE if successful. If an error
+ * has occurred, this function will return %FALSE and set @error
+ * appropriately if present.
*/
/**
- * g_network_address_parse_uri:
- * @uri: the hostname and optionally a port
- * @default_port: The default port if none is found in the URI
- * @error: a pointer to a #GError, or %NULL
- *
- * Creates a new #GSocketConnectable for connecting to the given
- * @uri. May fail and return %NULL in case parsing @uri fails.
+ * g_seekable_tell:
+ * @seekable: a #GSeekable.
*
- * Using this rather than g_network_address_new() or
- * g_network_address_parse_host() allows #GSocketClient to determine
- * when to use application-specific proxy protocols.
+ * Tells the current position within the stream.
*
- * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
- * Since: 2.26
+ * Returns: the offset from the beginning of the buffer.
*/
/**
- * g_network_monitor_base_add_network:
- * @monitor: the #GNetworkMonitorBase
- * @network: a #GInetAddressMask
- *
- * Adds @network to @monitor's list of available networks.
+ * 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.
*
- * Since: 2.32
- */
-
-
-/**
- * g_network_monitor_base_remove_network:
- * @monitor: the #GNetworkMonitorBase
- * @network: a #GInetAddressMask
+ * Truncates a stream with a given #offset.
*
- * Removes @network from @monitor's list of available networks.
+ * 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.
*
- * Since: 2.32
+ * Returns: %TRUE if successful. If an error
+ * has occurred, this function will return %FALSE and set @error
+ * appropriately if present.
*/
/**
- * g_network_monitor_base_set_networks:
- * @monitor: the #GNetworkMonitorBase
- * @networks: (array length=length): an array of #GInetAddressMask
- * @length: length of @networks
+ * g_settings_apply:
+ * @settings: a #GSettings instance
*
- * Drops @monitor's current list of available networks and replaces
- * it with @networks.
+ * Applies any changes that have been made to the settings. This
+ * function does nothing unless @settings is in 'delay-apply' mode;
+ * see g_settings_delay(). In the normal case settings are always
+ * applied immediately.
*/
/**
- * g_network_monitor_can_reach:
- * @monitor: a #GNetworkMonitor
- * @connectable: a #GSocketConnectable
- * @cancellable: a #GCancellable, or %NULL
- * @error: return location for a #GError, or %NULL
+ * g_settings_backend_changed:
+ * @backend: a #GSettingsBackend implementation
+ * @key: the name of the key
+ * @origin_tag: the origin tag
*
- * Attempts to determine whether or not the host pointed to by
- * @connectable can be reached, without actually trying to connect to
- * it.
+ * Signals that a single key has possibly changed. Backend
+ * implementations should call this if a key has possibly changed its
+ * value.
*
- * This may return %TRUE even when #GNetworkMonitor:network-available
- * is %FALSE, if, for example, @monitor can determine that
- * @connectable refers to a host on a local network.
+ * @key must be a valid key (ie starting with a slash, not containing
+ * '//', and not ending with a slash).
*
- * If @monitor believes that an attempt to connect to @connectable
- * will succeed, it will return %TRUE. Otherwise, it will return
- * %FALSE and set @error to an appropriate error (such as
- * %G_IO_ERROR_HOST_UNREACHABLE).
+ * The implementation must call this function during any call to
+ * g_settings_backend_write(), before the call returns (except in the
+ * case that no keys are actually changed and it cares to detect this
+ * fact). It may not rely on the existence of a mainloop for
+ * dispatching the signal later.
*
- * Note that although this does not attempt to connect to
- * @connectable, it may still block for a brief period of time (eg,
- * trying to do multicast DNS on the local network), so if you do not
- * want to block, you should use g_network_monitor_can_reach_async().
+ * The implementation may call this function at any other time it likes
+ * in response to other events (such as changes occurring outside of the
+ * program). These calls may originate from a mainloop or may originate
+ * in response to any other action (including from calls to
+ * g_settings_backend_write()).
*
- * Returns: %TRUE if @connectable is reachable, %FALSE if not.
- * Since: 2.32
+ * In the case that this call is in response to a call to
+ * g_settings_backend_write() then @origin_tag must be set to the same
+ * value that was passed to that call.
+ *
+ * Since: 2.26
*/
/**
- * g_network_monitor_get_default:
+ * g_settings_backend_changed_tree:
+ * @backend: a #GSettingsBackend implementation
+ * @tree: a #GTree containing the changes
+ * @origin_tag: the origin tag
*
- * Gets the default #GNetworkMonitor for the system.
+ * This call is a convenience wrapper. It gets the list of changes from
+ * @tree, computes the longest common prefix and calls
+ * g_settings_backend_changed().
*
- * Returns: (transfer none): a #GNetworkMonitor
- * Since: 2.32
+ * Since: 2.26
*/
/**
- * g_network_monitor_get_network_available:
- * @monitor: the #GNetworkMonitor
+ * 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
*
- * Checks if the network is available. "Available" here means that the
- * system has a default route available for at least one of IPv4 or
- * IPv6. It does not necessarily imply that the public Internet is
- * reachable. See #GNetworkMonitor:network-available for more details.
+ * 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,
+ * optionally, the value to store at each of those keys.
*
- * Returns: whether the network is available
- * Since: 2.32
+ * You must free the value returned in @path, @keys and @values using
+ * g_free(). You should not attempt to free or unref the contents of
+ * @keys or @values.
+ *
+ * Since: 2.26
*/
/**
- * g_network_service_get_domain:
- * @srv: a #GNetworkService
+ * g_settings_backend_get_default:
*
- * Gets the domain that @srv serves. This might be either UTF-8 or
- * ASCII-encoded, depending on what @srv was created with.
+ * Returns the default #GSettingsBackend. It is possible to override
+ * the default by setting the `GSETTINGS_BACKEND` environment variable
+ * to the name of a settings backend.
*
- * Returns: @srv's domain name
- * Since: 2.22
+ * The user gets a reference to the backend.
+ *
+ * Returns: (transfer full): the default #GSettingsBackend
+ * Since: 2.28
*/
/**
- * g_network_service_get_protocol:
- * @srv: a #GNetworkService
+ * g_settings_backend_keys_changed:
+ * @backend: a #GSettingsBackend implementation
+ * @path: the path containing the changes
+ * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
+ * @origin_tag: the origin tag
*
- * Gets @srv's protocol name (eg, "tcp").
+ * Signals that a list of keys have possibly changed. Backend
+ * implementations should call this if keys have possibly changed their
+ * values.
*
- * Returns: @srv's protocol name
- * Since: 2.22
- */
-
-
-/**
- * g_network_service_get_scheme:
- * @srv: a #GNetworkService
+ * @path must be a valid path (ie starting and ending with a slash and
+ * not containing '//'). Each string in @items must form a valid key
+ * name when @path is prefixed to it (ie: each item must not start or
+ * end with '/' and must not contain '//').
*
- * Get's the URI scheme used to resolve proxies. By default, the service name
- * is used as scheme.
+ * The meaning of this signal is that any of the key names resulting
+ * from the contatenation of @path with each item in @items may have
+ * changed.
+ *
+ * The same rules for when notifications must occur apply as per
+ * g_settings_backend_changed(). These two calls can be used
+ * interchangeably if exactly one item has changed (although in that
+ * case g_settings_backend_changed() is definitely preferred).
+ *
+ * For efficiency reasons, the implementation should strive for @path to
+ * be as long as possible (ie: the longest common prefix of all of the
+ * keys that were changed) but this is not strictly required.
*
- * Returns: @srv's scheme name
* Since: 2.26
*/
/**
- * g_network_service_get_service:
- * @srv: a #GNetworkService
+ * g_settings_backend_path_changed:
+ * @backend: a #GSettingsBackend implementation
+ * @path: the path containing the changes
+ * @origin_tag: the origin tag
*
- * Gets @srv's service name (eg, "ldap").
+ * Signals that all keys below a given path may have possibly changed.
+ * Backend implementations should call this if an entire path of keys
+ * have possibly changed their values.
*
- * Returns: @srv's service name
- * Since: 2.22
- */
-
-
-/**
- * g_network_service_new:
- * @service: the service type to look up (eg, "ldap")
- * @protocol: the networking protocol to use for @service (eg, "tcp")
- * @domain: the DNS domain to look up the service in
+ * @path must be a valid path (ie starting and ending with a slash and
+ * not containing '//').
*
- * Creates a new #GNetworkService representing the given @service,
- * @protocol, and @domain. This will initially be unresolved; use the
- * #GSocketConnectable interface to resolve it.
+ * The meaning of this signal is that any of the key which has a name
+ * starting with @path may have changed.
*
- * Returns: (transfer full): a new #GNetworkService
- * Since: 2.22
+ * The same rules for when notifications must occur apply as per
+ * g_settings_backend_changed(). This call might be an appropriate
+ * reasponse to a 'reset' call but implementations are also free to
+ * explicitly list the keys that were affected by that call if they can
+ * easily do so.
+ *
+ * For efficiency reasons, the implementation should strive for @path to
+ * be as long as possible (ie: the longest common prefix of all of the
+ * keys that were changed) but this is not strictly required. As an
+ * example, if this function is called with the path of "/" then every
+ * single key in the application will be notified of a possible change.
+ *
+ * Since: 2.26
*/
/**
- * g_network_service_set_scheme:
- * @srv: a #GNetworkService
- * @scheme: a URI scheme
+ * g_settings_backend_path_writable_changed:
+ * @backend: a #GSettingsBackend implementation
+ * @path: the name of the path
*
- * Set's the URI scheme used to resolve proxies. By default, the service name
- * is used as scheme.
+ * Signals that the writability of all keys below a given path may have
+ * changed.
+ *
+ * Since GSettings performs no locking operations for itself, this call
+ * will always be made in response to external events.
*
* Since: 2.26
*/
/**
- * g_new:
- * @struct_type: the type of the elements to allocate
- * @n_structs: the number of elements to allocate
+ * g_settings_backend_writable_changed:
+ * @backend: a #GSettingsBackend implementation
+ * @key: the name of the key
*
- * Allocates @n_structs elements of type @struct_type.
- * The returned pointer is cast to a pointer to the given type.
- * If @n_structs is 0 it returns %NULL.
- * Care is taken to avoid overflow when calculating the size of the allocated block.
+ * Signals that the writability of a single key has possibly changed.
*
- * Since the returned pointer is already casted to the right type,
- * it is normally unnecessary to cast it explicitly, and doing
- * so might hide memory allocation errors.
+ * Since GSettings performs no locking operations for itself, this call
+ * will always be made in response to external events.
*
- * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
+ * Since: 2.26
*/
/**
- * g_new0:
- * @struct_type: the type of the elements to allocate.
- * @n_structs: the number of elements to allocate.
+ * g_settings_bind:
+ * @settings: a #GSettings object
+ * @key: the key to bind
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of the property to bind
+ * @flags: flags for the binding
+ *
+ * Create a binding between the @key in the @settings object
+ * and the property @property of @object.
+ *
+ * The binding uses the default GIO mapping functions to map
+ * between the settings and property values. These functions
+ * handle booleans, numeric types and string types in a
+ * straightforward way. Use g_settings_bind_with_mapping() if
+ * you need a custom mapping, or map between types that are not
+ * supported by the default mapping functions.
*
- * Allocates @n_structs elements of type @struct_type, initialized to 0's.
- * The returned pointer is cast to a pointer to the given type.
- * If @n_structs is 0 it returns %NULL.
- * Care is taken to avoid overflow when calculating the size of the allocated block.
+ * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
+ * function also establishes a binding between the writability of
+ * @key and the "sensitive" property of @object (if @object has
+ * a boolean property by that name). See g_settings_bind_writable()
+ * for more details about writable bindings.
*
- * Since the returned pointer is already casted to the right type,
- * it is normally unnecessary to cast it explicitly, and doing
- * so might hide memory allocation errors.
+ * Note that the lifecycle of the binding is tied to the object,
+ * and that you can have only one binding per object property.
+ * If you bind the same property twice on the same object, the second
+ * binding overrides the first one.
*
- * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
+ * Since: 2.26
*/
/**
- * g_newa:
- * @struct_type: Type of memory chunks to be allocated
- * @n_structs: Number of chunks to be allocated
+ * g_settings_bind_with_mapping: (skip)
+ * @settings: a #GSettings object
+ * @key: the key to bind
+ * @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
+ * @user_data: data that gets passed to @get_mapping and @set_mapping
+ * @destroy: #GDestroyNotify function for @user_data
+ *
+ * Create a binding between the @key in the @settings object
+ * and the property @property of @object.
+ *
+ * The binding uses the provided mapping functions to map between
+ * settings and property values.
*
- * Wraps g_alloca() in a more typesafe manner.
+ * Note that the lifecycle of the binding is tied to the object,
+ * and that you can have only one binding per object property.
+ * If you bind the same property twice on the same object, the second
+ * binding overrides the first one.
*
- * Returns: Pointer to stack space for @n_structs chunks of type @struct_type
+ * Since: 2.26
*/
/**
- * g_node_append:
- * @parent: the #GNode to place the new #GNode under
- * @node: the #GNode to insert
+ * g_settings_bind_writable:
+ * @settings: a #GSettings object
+ * @key: the key to bind
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property to bind
+ * @inverted: whether to 'invert' the value
+ *
+ * Create a binding between the writability of @key in the
+ * @settings object and the property @property of @object.
+ * The property must be boolean; "sensitive" or "visible"
+ * properties of widgets are the most likely candidates.
*
- * Inserts a #GNode as the last child of the given parent.
+ * Writable bindings are always uni-directional; changes of the
+ * writability of the setting will be propagated to the object
+ * property, not the other way.
*
- * Returns: the inserted #GNode
- */
-
-
-/**
- * g_node_append_data:
- * @parent: the #GNode to place the new #GNode under
- * @data: the data for the new #GNode
+ * 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 not writable.
*
- * Inserts a new #GNode as the last child of the given parent.
+ * Note that the lifecycle of the binding is tied to the object,
+ * and that you can have only one binding per object property.
+ * If you bind the same property twice on the same object, the second
+ * binding overrides the first one.
*
- * Returns: the new #GNode
+ * Since: 2.26
*/
/**
- * g_node_first_child:
- * @node: a #GNode
+ * g_settings_create_action:
+ * @settings: a #GSettings
+ * @key: the name of a key in @settings
*
- * Gets the first child of a #GNode.
+ * Creates a #GAction corresponding to a given #GSettings key.
*
- * or has no children
+ * The action has the same name as the key.
*
- * Returns: the first child of @node, or %NULL if @node is %NULL
- */
-
-
-/**
- * g_node_insert_data:
- * @parent: the #GNode to place the new #GNode under
- * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent
- * @data: the data for the new #GNode
+ * The value of the key becomes the state of the action and the action
+ * is enabled when the key is writable. Changing the state of the
+ * action results in the key being written to. Changes to the value or
+ * writability of the key cause appropriate change notifications to be
+ * emitted for the action.
*
- * Inserts a new #GNode at the given position.
+ * For boolean-valued keys, action activations take no parameter and
+ * result in the toggling of the value. For all other types,
+ * activations take the new value for the key (which must have the
+ * correct type).
*
- * Returns: the new #GNode
+ * Returns: (transfer full): a new #GAction
+ * Since: 2.32
*/
/**
- * g_node_insert_data_before:
- * @parent: the #GNode to place the new #GNode under
- * @sibling: the sibling #GNode to place the new #GNode before
- * @data: the data for the new #GNode
+ * g_settings_delay:
+ * @settings: a #GSettings object
*
- * Inserts a new #GNode before the given sibling.
+ * Changes the #GSettings object into 'delay-apply' mode. In this
+ * mode, changes to @settings are not immediately propagated to the
+ * backend, but kept locally until g_settings_apply() is called.
*
- * Returns: the new #GNode
+ * Since: 2.26
*/
/**
- * g_node_next_sibling:
- * @node: a #GNode
- *
- * Gets the next sibling of a #GNode.
+ * g_settings_get:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
+ * @format: a #GVariant format string
+ * @...: arguments as per @format
*
- * or %NULL
+ * Gets the value that is stored at @key in @settings.
*
- * Returns: the next sibling of @node, or %NULL if @node is the last node
- */
-
-
-/**
- * g_node_prepend_data:
- * @parent: the #GNode to place the new #GNode under
- * @data: the data for the new #GNode
+ * A convenience function that combines g_settings_get_value() with
+ * g_variant_get().
*
- * Inserts a new #GNode as the first child of the given parent.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings or for the #GVariantType of @format to mismatch
+ * the type given in the schema.
*
- * Returns: the new #GNode
+ * Since: 2.26
*/
/**
- * g_node_prev_sibling:
- * @node: a #GNode
+ * g_settings_get_boolean:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
+ *
+ * Gets the value that is stored at @key in @settings.
*
- * Gets the previous sibling of a #GNode.
+ * A convenience variant of g_settings_get() for booleans.
*
- * node or %NULL
+ * It is a programmer error to give a @key that isn't specified as
+ * having a boolean type in the schema for @settings.
*
- * Returns: the previous sibling of @node, or %NULL if @node is the first
+ * Returns: a boolean
+ * Since: 2.26
*/
/**
- * g_null_settings_backend_new:
- *
- * Creates a readonly #GSettingsBackend.
+ * g_settings_get_child:
+ * @settings: a #GSettings object
+ * @name: the name of the child schema
*
- * This backend does not allow changes to settings, so all settings
- * will always have their default values.
+ * Creates a child settings object which has a base path of
+ * `base-path/@name`, where `base-path` is the base path of
+ * @settings.
*
- * Returns: (transfer full): a newly created #GSettingsBackend
- * Since: 2.28
- */
-
-
-/**
- * g_output_stream_clear_pending:
- * @stream: output stream
+ * The schema for the child settings object must have been declared
+ * in the schema of @settings using a <child> element.
*
- * Clears the pending flag on @stream.
+ * Returns: (transfer full): a 'child' settings object
+ * Since: 2.26
*/
/**
- * 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.
+ * g_settings_get_default_value:
+ * @settings: a #GSettings object
+ * @key: the key to get the default value for
*
- * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
- * Closing a stream multiple times will not return an error.
+ * Gets the "default value" of a key.
*
- * Closing a stream will automatically flush any outstanding buffers in the
- * stream.
+ * This is the value that would be read if g_settings_reset() were to be
+ * called on the key.
*
- * Streams will be automatically closed when the last reference
- * is dropped, but you might want to call this function to make sure
- * resources are released as early as possible.
+ * 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.
*
- * Some streams might keep the backing store of the stream (e.g. a file descriptor)
- * open after the stream is closed. See the documentation for the individual
- * stream for details.
+ * 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.
*
- * On failure the first error that happened will be reported, but the close
- * operation will finish as much as possible. A stream that failed to
- * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
- * is important to check and report the error to the user, otherwise
- * there might be a loss of data as all data might not be written.
+ * This function may be useful for adding an indication to a UI of what
+ * the default value was before the user set it.
*
- * 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.
- * Cancelling a close will still leave the stream closed, but there some streams
- * can use a faster close that doesn't block to e.g. check errors. On
- * cancellation (as with any error) there is no guarantee that all written
- * data will reach the target.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings.
*
- * Returns: %TRUE on success, %FALSE on failure
+ * Returns: (allow-none) (transfer full): the default value
+ * Since: 2.40
*/
/**
- * g_output_stream_close_async:
- * @stream: A #GOutputStream.
- * @io_priority: the 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
- *
- * Requests an asynchronous close of the stream, releasing resources
- * related to it. When the operation is finished @callback will be
- * called. You can then call g_output_stream_close_finish() to get
- * the result of the operation.
+ * g_settings_get_double:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * For behaviour details see g_output_stream_close().
+ * Gets the value that is stored at @key in @settings.
*
- * The asyncronous methods have a default fallback that uses threads
- * to implement asynchronicity, so they are optional for inheriting
- * classes. However, if you override one you must override all.
- */
-
-
-/**
- * g_output_stream_close_finish:
- * @stream: a #GOutputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * A convenience variant of g_settings_get() for doubles.
*
- * Closes an output stream.
+ * 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 stream was successfully closed, %FALSE otherwise.
+ * Returns: a double
+ * Since: 2.26
*/
/**
- * g_output_stream_flush:
- * @stream: a #GOutputStream.
- * @cancellable: (allow-none): optional cancellable object
- * @error: location to store the error occurring, or %NULL to ignore
+ * g_settings_get_enum:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * Forces a write of all user-space buffered data for the given
- * @stream. Will block during the operation. Closing the stream will
- * implicitly cause a flush.
+ * Gets the value that is stored in @settings for @key and converts it
+ * to the enum value that it represents.
*
- * This function is optional for inherited classes.
+ * In order to use this function the type of the value must be a string
+ * and it must be marked in the schema file as an enumerated type.
*
- * 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.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings or is not marked as an enumerated type.
*
- * Returns: %TRUE on success, %FALSE on error
+ * If the value stored in the configuration database is not a valid
+ * value for the enumerated type then this function will return the
+ * default value.
+ *
+ * Returns: the enum value
+ * Since: 2.26
*/
/**
- * g_output_stream_flush_async:
- * @stream: a #GOutputStream.
- * @io_priority: the 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_settings_get_flags:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * Forces an asynchronous write of all user-space buffered data for
- * the given @stream.
- * For behaviour details see g_output_stream_flush().
+ * Gets the value that is stored in @settings for @key and converts it
+ * to the flags value that it represents.
*
- * When the operation is finished @callback will be
- * called. You can then call g_output_stream_flush_finish() to get the
- * result of the operation.
- */
-
-
-/**
- * g_output_stream_flush_finish:
- * @stream: a #GOutputStream.
- * @result: a GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * In order to use this function the type of the value must be an array
+ * of strings and it must be marked in the schema file as an flags type.
*
- * Finishes flushing an output stream.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings or is not marked as a flags type.
*
- * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
+ * If the value stored in the configuration database is not a valid
+ * value for the flags type then this function will return the default
+ * value.
+ *
+ * Returns: the flags value
+ * Since: 2.26
*/
/**
- * g_output_stream_has_pending:
- * @stream: a #GOutputStream.
+ * g_settings_get_has_unapplied:
+ * @settings: a #GSettings object
*
- * Checks if an ouput stream has pending actions.
+ * Returns whether the #GSettings object has any unapplied
+ * changes. This can only be the case if it is in 'delayed-apply' mode.
*
- * Returns: %TRUE if @stream has pending actions.
+ * Returns: %TRUE if @settings has unapplied changes
+ * Since: 2.26
*/
/**
- * g_output_stream_is_closed:
- * @stream: a #GOutputStream.
+ * g_settings_get_int:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * Checks if an output stream has already been closed.
+ * Gets the value that is stored at @key in @settings.
*
- * Returns: %TRUE if @stream is closed. %FALSE otherwise.
- */
-
-
-/**
- * g_output_stream_is_closing:
- * @stream: a #GOutputStream.
+ * A convenience variant of g_settings_get() for 32-bit integers.
*
- * Checks if an output stream is being closed. This can be
- * used inside e.g. a flush implementation to see if the
- * flush (or other i/o operation) is called from within
- * the closing operation.
+ * 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 @stream is being closed. %FALSE otherwise.
- * Since: 2.24
+ * Returns: an integer
+ * Since: 2.26
*/
/**
- * g_output_stream_set_pending:
- * @stream: a #GOutputStream.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * 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
+ * @user_data: user data for @mapping
*
- * Sets @stream to have actions pending. If the pending flag is
- * already set or @stream is closed, it will return %FALSE and set
- * @error.
+ * Gets the value that is stored at @key in @settings, subject to
+ * application-level validation/mapping.
+ *
+ * You should use this function when the application needs to perform
+ * some processing on the value of the key (for example, parsing). The
+ * @mapping function performs that processing. If the function
+ * indicates that the processing was unsuccessful (due to a parse error,
+ * for example) then the mapping is tried again with another value.
*
- * Returns: %TRUE if pending was previously unset and is now set.
- */
-
-
-/**
- * g_output_stream_splice:
- * @stream: a #GOutputStream.
- * @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.
+ * This allows a robust 'fall back to defaults' behaviour to be
+ * implemented somewhat automatically.
*
- * Splices an input stream into an output stream.
+ * The first value that is tried is the user's setting for the key. If
+ * the mapping function fails to map this value, other values may be
+ * tried in an unspecified order (system or site defaults, translated
+ * schema default values, untranslated schema default values, etc).
*
- * -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.
+ * If the mapping function fails for all possible values, one additional
+ * attempt is made: the mapping function is called with a %NULL value.
+ * If the mapping function still indicates failure at this point then
+ * the application will be aborted.
*
- * Returns: a #gssize containing the size of the data spliced, or
+ * The result parameter for the @mapping function is pointed to a
+ * #gpointer which is initially set to %NULL. The same pointer is given
+ * to each invocation of @mapping. The final value of that #gpointer is
+ * what is returned by this function. %NULL is valid; it is returned
+ * just as any other value would be.
+ *
+ * Returns: (transfer full): the result, which may be %NULL
*/
/**
- * g_output_stream_splice_async:
- * @stream: a #GOutputStream.
- * @source: a #GInputStream.
- * @flags: a set of #GOutputStreamSpliceFlags.
- * @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): user data passed to @callback.
+ * g_settings_get_range:
+ * @settings: a #GSettings
+ * @key: the key to query the range of
*
- * Splices a stream asynchronously.
- * When the operation is finished @callback will be called.
- * You can then call g_output_stream_splice_finish() to get the
- * result of the operation.
+ * Queries the range of a key.
*
- * For the synchronous, blocking version of this function, see
- * g_output_stream_splice().
+ * Since: 2.28
+ * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead.
*/
/**
- * g_output_stream_splice_finish:
- * @stream: a #GOutputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_settings_get_string:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * Finishes an asynchronous stream splice operation.
+ * Gets the value that is stored at @key in @settings.
+ *
+ * A convenience variant of g_settings_get() for strings.
*
- * 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.
+ * It is a programmer error to give a @key that isn't specified as
+ * having a string type in the schema for @settings.
*
- * Returns: a #gssize of the number of bytes spliced. Note that if the
+ * Returns: a newly-allocated string
+ * Since: 2.26
*/
/**
- * g_output_stream_write:
- * @stream: a #GOutputStream.
- * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
- * @count: the number of bytes to write
- * @cancellable: (allow-none): optional cancellable object
- * @error: location to store the error occurring, or %NULL to ignore
- *
- * Tries to write @count bytes from @buffer into the stream. Will block
- * during the operation.
- *
- * If count is 0, returns 0 and does nothing. A value of @count
- * 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
- * @count is 0).
+ * g_settings_get_strv:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * 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 convenience variant of g_settings_get() for string arrays.
*
- * On error -1 is returned and @error is set accordingly.
+ * 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: Number of bytes written, or -1 on error
+ * 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_output_stream_write_all:
- * @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
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: location to store the error occurring, or %NULL to ignore
- *
- * Tries to write @count bytes from @buffer into the stream. Will block
- * during the operation.
+ * g_settings_get_uint:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * This function is similar to g_output_stream_write(), except it tries to
- * write as many bytes as requested, only stopping on an error.
+ * Gets the value that is stored at @key in @settings.
*
- * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
- * is set to @count.
+ * A convenience variant of g_settings_get() for 32-bit unsigned
+ * integers.
*
- * 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.
+ * 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 on success, %FALSE if there was an error
+ * Returns: an unsigned integer
+ * Since: 2.30
*/
/**
- * g_output_stream_write_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_finish() to get the result of the
- * operation.
+ * g_settings_get_user_value:
+ * @settings: a #GSettings object
+ * @key: the key to get the user value for
*
- * During an async request no other sync and async calls are allowed,
- * and will result in %G_IO_ERROR_PENDING errors.
+ * Checks the "user value" of a key, if there is one.
*
- * A value of @count larger than %G_MAXSSIZE will cause a
- * %G_IO_ERROR_INVALID_ARGUMENT error.
+ * The user value of a key is the last value that was set by the user.
*
- * 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.
+ * After calling g_settings_reset() this function should always return
+ * %NULL (assuming something is not wrong with the system
+ * configuration).
*
- * 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.
+ * 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.
*
- * 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.
+ * This function may be useful for adding a "reset" option to a UI or
+ * for providing indication that a particular value has been changed.
*
- * The asyncronous methods have a default fallback that uses threads
- * to implement asynchronicity, so they are optional for inheriting
- * classes. However, if you override one you must override all.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings.
*
- * For the synchronous, blocking version of this function, see
- * g_output_stream_write().
+ * Returns: (allow-none) (transfer full): the user's value, if set
+ * Since: 2.40
*/
/**
- * g_output_stream_write_finish:
- * @stream: a #GOutputStream.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * g_settings_get_value:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
*
- * Finishes a stream write operation.
+ * Gets the value that is stored in @settings for @key.
*
- * Returns: a #gssize containing the number of bytes written to the stream.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings.
+ *
+ * Returns: a new #GVariant
+ * Since: 2.26
*/
/**
- * g_permission_acquire:
- * @permission: a #GPermission instance
- * @cancellable: a #GCancellable, or %NULL
- * @error: a pointer to a %NULL #GError, or %NULL
- *
- * Attempts to acquire the permission represented by @permission.
- *
- * The precise method by which this happens depends on the permission
- * and the underlying authentication mechanism. A simple example is
- * that a dialog may appear asking the user to enter their password.
- *
- * You should check with g_permission_get_can_acquire() before calling
- * this function.
- *
- * If the permission is acquired then %TRUE is returned. Otherwise,
- * %FALSE is returned and @error is set appropriately.
+ * g_settings_is_writable:
+ * @settings: a #GSettings object
+ * @name: the name of a key
*
- * This call is blocking, likely for a very long time (in the case that
- * user interaction is required). See g_permission_acquire_async() for
- * the non-blocking version.
+ * Finds out if a key can be written or not
*
- * Returns: %TRUE if the permission was successfully acquired
+ * Returns: %TRUE if the key @name is writable
* Since: 2.26
*/
/**
- * g_permission_acquire_async:
- * @permission: a #GPermission instance
- * @cancellable: a #GCancellable, or %NULL
- * @callback: the #GAsyncReadyCallback to call when done
- * @user_data: the user data to pass to @callback
+ * g_settings_list_children:
+ * @settings: a #GSettings object
*
- * Attempts to acquire the permission represented by @permission.
+ * Gets the list of children on @settings.
*
- * This is the first half of the asynchronous version of
- * g_permission_acquire().
+ * The list is exactly the list of strings for which it is not an error
+ * to call g_settings_get_child().
*
- * Since: 2.26
- */
-
-
-/**
- * g_permission_acquire_finish:
- * @permission: a #GPermission instance
- * @result: the #GAsyncResult given to the #GAsyncReadyCallback
- * @error: a pointer to a %NULL #GError, or %NULL
+ * For GSettings objects that are lists, this value can change at any
+ * time and you should connect to the "children-changed" signal to watch
+ * for those changes. Note that there is a race condition here: you may
+ * request a child after listing it only for it to have been destroyed
+ * in the meantime. For this reason, g_settings_get_child() may return
+ * %NULL even for a child that was listed by this function.
*
- * Collects the result of attempting to acquire the permission
- * represented by @permission.
+ * For GSettings objects that are not lists, you should probably not be
+ * calling this function from "normal" code (since you should already
+ * know what children are in your schema). This function may still be
+ * useful there for introspection reasons, however.
*
- * This is the second half of the asynchronous version of
- * g_permission_acquire().
+ * You should free the return value with g_strfreev() when you are done
+ * with it.
*
- * Returns: %TRUE if the permission was successfully acquired
- * Since: 2.26
+ * Returns: (transfer full) (element-type utf8): a list of the children on @settings
*/
/**
- * g_permission_get_allowed:
- * @permission: a #GPermission instance
+ * g_settings_list_keys:
+ * @settings: a #GSettings object
*
- * Gets the value of the 'allowed' property. This property is %TRUE if
- * the caller currently has permission to perform the action that
- * @permission represents the permission to perform.
+ * Introspects the list of keys on @settings.
+ *
+ * You should probably not be calling this function from "normal" code
+ * (since you should already know what keys are in your schema). This
+ * function is intended for introspection reasons.
+ *
+ * You should free the return value with g_strfreev() when you are done
+ * with it.
*
- * Returns: the value of the 'allowed' property
- * Since: 2.26
+ * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
*/
/**
- * g_permission_get_can_acquire:
- * @permission: a #GPermission instance
+ * g_settings_list_relocatable_schemas:
*
- * Gets the value of the 'can-acquire' property. This property is %TRUE
- * if it is generally possible to acquire the permission by calling
- * g_permission_acquire().
+ * <!-- -->
*
- * Returns: the value of the 'can-acquire' property
- * Since: 2.26
+ * 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_permission_get_can_release:
- * @permission: a #GPermission instance
+ * g_settings_list_schemas:
*
- * Gets the value of the 'can-release' property. This property is %TRUE
- * if it is generally possible to release the permission by calling
- * g_permission_release().
+ * <!-- -->
*
- * Returns: the value of the 'can-release' property
+ * 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.
*/
/**
- * g_permission_impl_update:
- * @permission: a #GPermission instance
- * @allowed: the new value for the 'allowed' property
- * @can_acquire: the new value for the 'can-acquire' property
- * @can_release: the new value for the 'can-release' property
+ * g_settings_new:
+ * @schema_id: the id of the schema
*
- * This function is called by the #GPermission implementation to update
- * the properties of the permission. You should never call this
- * function except from a #GPermission implementation.
+ * Creates a new #GSettings object with the schema specified by
+ * @schema_id.
*
- * GObject notify signals are generated, as appropriate.
+ * Signals on the newly created #GSettings object will be dispatched
+ * via the thread-default #GMainContext in effect at the time of the
+ * call to g_settings_new(). The new #GSettings will hold a reference
+ * on the context. See g_main_context_push_thread_default().
*
+ * Returns: a new #GSettings object
* Since: 2.26
*/
/**
- * g_permission_release:
- * @permission: a #GPermission instance
- * @cancellable: a #GCancellable, or %NULL
- * @error: a pointer to a %NULL #GError, or %NULL
+ * g_settings_new_full:
+ * @schema: a #GSettingsSchema
+ * @backend: (allow-none): a #GSettingsBackend
+ * @path: (allow-none): the path to use
*
- * Attempts to release the permission represented by @permission.
+ * Creates a new #GSettings object with a given schema, backend and
+ * path.
*
- * The precise method by which this happens depends on the permission
- * and the underlying authentication mechanism. In most cases the
- * permission will be dropped immediately without further action.
+ * It should be extremely rare that you ever want to use this function.
+ * It is made available for advanced use-cases (such as plugin systems
+ * that want to provide access to schemas loaded from custom locations,
+ * etc).
*
- * You should check with g_permission_get_can_release() before calling
- * this function.
+ * At the most basic level, a #GSettings object is a pure composition of
+ * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
+ * backend, and a #GMainContext to which signals are dispatched.
*
- * If the permission is released then %TRUE is returned. Otherwise,
- * %FALSE is returned and @error is set appropriately.
+ * This constructor therefore gives you full control over constructing
+ * #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()).
*
- * This call is blocking, likely for a very long time (in the case that
- * user interaction is required). See g_permission_release_async() for
- * the non-blocking version.
+ * If @backend is %NULL then the default backend is used.
*
- * Returns: %TRUE if the permission was successfully released
- * Since: 2.26
+ * If @path is %NULL then the path from the schema is used. It is an
+ * 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.
+ *
+ * Returns: a new #GSettings object
+ * Since: 2.32
*/
/**
- * g_permission_release_async:
- * @permission: a #GPermission instance
- * @cancellable: a #GCancellable, or %NULL
- * @callback: the #GAsyncReadyCallback to call when done
- * @user_data: the user data to pass to @callback
+ * g_settings_new_with_backend:
+ * @schema_id: the id of the schema
+ * @backend: the #GSettingsBackend to use
*
- * Attempts to release the permission represented by @permission.
+ * Creates a new #GSettings object with the schema specified by
+ * @schema_id and a given #GSettingsBackend.
*
- * This is the first half of the asynchronous version of
- * g_permission_release().
+ * Creating a #GSettings object with a different backend allows accessing
+ * settings from a database other than the usual one. For example, it may make
+ * sense to pass a backend corresponding to the "defaults" settings database on
+ * the system to get a settings object that modifies the system default
+ * settings instead of the settings for this user.
*
+ * Returns: a new #GSettings object
* Since: 2.26
*/
/**
- * g_permission_release_finish:
- * @permission: a #GPermission instance
- * @result: the #GAsyncResult given to the #GAsyncReadyCallback
- * @error: a pointer to a %NULL #GError, or %NULL
+ * g_settings_new_with_backend_and_path:
+ * @schema_id: the id of the schema
+ * @backend: the #GSettingsBackend to use
+ * @path: the path to use
*
- * Collects the result of attempting to release the permission
- * represented by @permission.
+ * Creates a new #GSettings object with the schema specified by
+ * @schema_id and a given #GSettingsBackend and path.
*
- * This is the second half of the asynchronous version of
- * g_permission_release().
+ * This is a mix of g_settings_new_with_backend() and
+ * g_settings_new_with_path().
*
- * Returns: %TRUE if the permission was successfully released
+ * Returns: a new #GSettings object
* Since: 2.26
*/
/**
- * g_poll_file_monitor_new:
- * @file: a #GFile.
+ * g_settings_new_with_path:
+ * @schema_id: the id of the schema
+ * @path: the path to use
*
- * Polls @file for changes.
+ * Creates a new #GSettings object with the relocatable schema specified
+ * by @schema_id and a given path.
*
- * Returns: a new #GFileMonitor for the given #GFile.
+ * You only need to do this if you want to directly create a settings
+ * object with a schema that doesn't have a specified path of its own.
+ * That's quite rare.
+ *
+ * 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
*/
/**
- * g_pollable_input_stream_can_poll:
- * @stream: a #GPollableInputStream.
- *
- * Checks if @stream is actually pollable. Some classes may implement
- * #GPollableInputStream but have only certain instances of that class
- * be pollable. If this method returns %FALSE, then the behavior of
- * other #GPollableInputStream methods is undefined.
+ * g_settings_range_check:
+ * @settings: a #GSettings
+ * @key: the key to check
+ * @value: the value to check
*
- * For any given stream, the value returned by this method is constant;
- * a stream cannot switch from pollable to non-pollable or vice versa.
+ * Checks if the given @value is of the correct type and within the
+ * permitted range for @key.
*
- * Returns: %TRUE if @stream is pollable, %FALSE if not.
+ * Returns: %TRUE if @value is valid for @key
* Since: 2.28
+ * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead.
*/
/**
- * g_pollable_input_stream_create_source:
- * @stream: a #GPollableInputStream.
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- *
- * Creates a #GSource that triggers when @stream can be read, or
- * @cancellable is triggered or an error occurs. The callback on the
- * source is of the #GPollableSourceFunc type.
+ * g_settings_reset:
+ * @settings: a #GSettings object
+ * @key: the name of a key
*
- * As with g_pollable_input_stream_is_readable(), it is possible that
- * the stream may not actually be readable even after the source
- * triggers, so you should use g_pollable_input_stream_read_nonblocking()
- * rather than g_input_stream_read() from the callback.
+ * Resets @key to its default value.
*
- * Returns: (transfer full): a new #GSource
- * Since: 2.28
+ * This call resets the key, as much as possible, to its default value.
+ * That might the value specified in the schema or the one set by the
+ * administrator.
*/
/**
- * g_pollable_input_stream_is_readable:
- * @stream: a #GPollableInputStream.
+ * g_settings_revert:
+ * @settings: a #GSettings instance
*
- * Checks if @stream can be read.
+ * Reverts all non-applied changes to the settings. This function
+ * does nothing unless @settings is in 'delay-apply' mode; see
+ * g_settings_delay(). In the normal case settings are always applied
+ * immediately.
*
- * Note that some stream types may not be able to implement this 100%
- * reliably, and it is possible that a call to g_input_stream_read()
- * after this returns %TRUE would still block. To guarantee
- * non-blocking behavior, you should always use
- * g_pollable_input_stream_read_nonblocking(), which will return a
- * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+ * Change notifications will be emitted for affected keys.
+ */
+
+
+/**
+ * g_settings_schema_get_id:
+ * @schema: a #GSettingsSchema
*
- * 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.
+ * Get the ID of @schema.
*
- * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
- * Since: 2.28
+ * Returns: (transfer none): the ID
*/
/**
- * g_pollable_input_stream_read_nonblocking:
- * @stream: a #GPollableInputStream
- * @buffer: a buffer to read data into (which should be at least @size bytes long).
- * @size: the number of bytes you want to read
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: #GError for error reporting, or %NULL to ignore.
- *
- * Attempts to read up to @size bytes from @stream into @buffer, as
- * with g_input_stream_read(). If @stream is not currently readable,
- * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
- * use g_pollable_input_stream_create_source() to create a #GSource
- * that will be triggered when @stream is readable.
+ * g_settings_schema_get_key:
+ * @schema: a #GSettingsSchema
+ * @name: the name of a key
*
- * Note that since this method never blocks, you cannot actually
- * use @cancellable to cancel it. However, it will return an error
- * if @cancellable has already been cancelled when you call, which
- * may happen if you call this method after a source triggers due
- * to having been cancelled.
+ * Gets the key named @name from @schema.
*
- * %G_IO_ERROR_WOULD_BLOCK).
+ * It is a programmer error to request a key that does not exist. See
+ * g_settings_schema_list_keys().
*
- * Virtual: read_nonblocking
- * Returns: the number of bytes read, or -1 on error (including
+ * Returns: (transfer full): the #GSettingsSchemaKey for @name
+ * Since: 2.40
*/
/**
- * g_pollable_output_stream_can_poll:
- * @stream: a #GPollableOutputStream.
+ * g_settings_schema_get_path:
+ * @schema: a #GSettingsSchema
*
- * Checks if @stream is actually pollable. Some classes may implement
- * #GPollableOutputStream but have only certain instances of that
- * class be pollable. If this method returns %FALSE, then the behavior
- * of other #GPollableOutputStream methods is undefined.
+ * Gets the path associated with @schema, or %NULL.
*
- * For any given stream, the value returned by this method is constant;
- * a stream cannot switch from pollable to non-pollable or vice versa.
+ * Schemas may be single-instance or relocatable. Single-instance
+ * schemas correspond to exactly one set of keys in the backend
+ * database: those located at the path returned by this function.
*
- * Returns: %TRUE if @stream is pollable, %FALSE if not.
- * Since: 2.28
+ * Relocatable schemas can be referenced by other schemas and can
+ * threfore describe multiple sets of keys at different locations. For
+ * relocatable schemas, this function will return %NULL.
+ *
+ * Returns: (transfer none): the path of the schema, or %NULL
+ * Since: 2.32
*/
/**
- * g_pollable_output_stream_create_source:
- * @stream: a #GPollableOutputStream.
- * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * g_settings_schema_has_key:
+ * @schema: a #GSettingsSchema
+ * @name: the name of a key
*
- * Creates a #GSource that triggers when @stream can be written, or
- * @cancellable is triggered or an error occurs. The callback on the
- * source is of the #GPollableSourceFunc type.
+ * Checks if @schema has a key named @name.
*
- * As with g_pollable_output_stream_is_writable(), it is possible that
- * the stream may not actually be writable even after the source
- * triggers, so you should use g_pollable_output_stream_write_nonblocking()
- * rather than g_output_stream_write() from the callback.
+ * Returns: %TRUE if such a key exists
+ * Since: 2.40
+ */
+
+
+/**
+ * g_settings_schema_key_get_default_value:
+ * @key: a #GSettingsSchemaKey
*
- * Returns: (transfer full): a new #GSource
- * Since: 2.28
+ * 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_pollable_output_stream_is_writable:
- * @stream: a #GPollableOutputStream.
+ * g_settings_schema_key_get_description:
+ * @key: a #GSettingsSchemaKey
*
- * Checks if @stream can be written.
+ * Gets the description for @key.
*
- * Note that some stream types may not be able to implement this 100%
- * reliably, and it is possible that a call to g_output_stream_write()
- * after this returns %TRUE would still block. To guarantee
- * non-blocking behavior, you should always use
- * g_pollable_output_stream_write_nonblocking(), which will return a
- * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+ * If no description has been provided in the schema for @key, returns
+ * %NULL.
*
- * 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.
+ * 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.
*
- * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
- * Since: 2.28
+ * 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_pollable_output_stream_write_nonblocking:
- * @stream: a #GPollableOutputStream
- * @buffer: (array length=size) (element-type guint8): a buffer to write data from
- * @size: the number of bytes you want to write
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_settings_schema_key_get_name:
+ * @key: a #GSettingsSchemaKey
*
- * Attempts to write up to @size bytes from @buffer to @stream, as
- * with g_output_stream_write(). If @stream is not currently writable,
- * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
- * use g_pollable_output_stream_create_source() to create a #GSource
- * that will be triggered when @stream is writable.
+ * Gets the name of @key.
*
- * Note that since this method never blocks, you cannot actually
- * use @cancellable to cancel it. However, it will return an error
- * if @cancellable has already been cancelled when you call, which
- * may happen if you call this method after a source triggers due
- * to having been cancelled.
+ * Returns: the name of @key.
+ * Since: 2.44
+ */
+
+
+/**
+ * g_settings_schema_key_get_range:
+ * @key: a #GSettingsSchemaKey
*
- * %G_IO_ERROR_WOULD_BLOCK).
+ * Queries the range of a key.
*
- * Virtual: write_nonblocking
- * Returns: the number of bytes written, or -1 on error (including
+ * 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_pollable_source_new:
- * @pollable_stream: the stream associated with the new source
+ * g_settings_schema_key_get_summary:
+ * @key: a #GSettingsSchemaKey
*
- * Utility method for #GPollableInputStream and #GPollableOutputStream
- * implementations. Creates a new #GSource that expects a callback of
- * type #GPollableSourceFunc. The new source does not actually do
- * anything on its own; use g_source_add_child_source() to add other
- * sources to it to cause it to trigger.
+ * Gets the summary for @key.
*
- * Returns: (transfer full): the new #GSource.
- * Since: 2.28
+ * 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_proxy_address_get_destination_hostname:
- * @proxy: a #GProxyAddress
+ * g_settings_schema_key_get_value_type:
+ * @key: a #GSettingsSchemaKey
*
- * Gets @proxy's destination hostname.
+ * Gets the #GVariantType of @key.
*
- * Returns: the @proxy's destination hostname
- * Since: 2.26
+ * Returns: (transfer none): the type of @key
+ * Since: 2.40
*/
/**
- * g_proxy_address_get_destination_port:
- * @proxy: a #GProxyAddress
+ * 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.
*
- * Gets @proxy's destination port.
+ * It is a programmer error if @value is not of the correct type -- you
+ * must check for this first.
*
- * Returns: the @proxy's destination port
- * Since: 2.26
+ * Returns: %TRUE if @value is valid for @key
+ * Since: 2.40
*/
/**
- * g_proxy_address_get_password:
- * @proxy: a #GProxyAddress
+ * g_settings_schema_key_ref:
+ * @key: a #GSettingsSchemaKey
*
- * Gets @proxy's password.
+ * Increase the reference count of @key, returning a new reference.
*
- * Returns: the @proxy's password
- * Since: 2.26
+ * Returns: a new reference to @key
+ * Since: 2.40
*/
/**
- * g_proxy_address_get_protocol:
- * @proxy: a #GProxyAddress
+ * g_settings_schema_key_unref:
+ * @key: a #GSettingsSchemaKey
*
- * Gets @proxy's protocol.
+ * Decrease the reference count of @key, possibly freeing it.
*
- * Returns: the @proxy's protocol
- * Since: 2.26
+ * Since: 2.40
*/
/**
- * g_proxy_address_get_username:
- * @proxy: a #GProxyAddress
+ * g_settings_schema_list_children:
+ * @schema: a #GSettingsSchema
*
- * Gets @proxy's username.
+ * Gets the list of children in @schema.
*
- * Returns: the @proxy's username
- * Since: 2.26
+ * 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_proxy_address_new:
- * @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_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).
+ * g_settings_schema_ref:
+ * @schema: a #GSettingsSchema
*
- * Creates a new #GProxyAddress for @inetaddr with @protocol that should
- * tunnel through @dest_hostname and @dest_port.
+ * Increase the reference count of @schema, returning a new reference.
*
- * Returns: a new #GProxyAddress
- * Since: 2.26
+ * Returns: a new reference to @schema
+ * Since: 2.32
*/
/**
- * g_proxy_connect:
- * @proxy: a #GProxy
- * @connection: a #GIOStream
- * @proxy_address: a #GProxyAddress
- * @cancellable: (allow-none): a #GCancellable
- * @error: return #GError
+ * g_settings_schema_source_get_default:
*
- * Given @connection to communicate with a proxy (eg, a
- * #GSocketConnection that is connected to the proxy server), this
- * does the necessary handshake to connect to @proxy_address, and if
- * required, wraps the #GIOStream to handle proxy payload.
+ * Gets the default system schema source.
+ *
+ * This function is not required for normal uses of #GSettings but it
+ * may be useful to authors of plugin management systems or to those who
+ * want to introspect the content of schemas.
*
- * be the same as @connection, in which case a reference
- * will be added.
+ * If no schemas are installed, %NULL will be returned.
*
- * Returns: (transfer full): a #GIOStream that will replace @connection. This might
- * Since: 2.26
+ * The returned source may actually consist of multiple schema sources
+ * from different directories, depending on which directories were given
+ * 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
+ * Since: 2.32
*/
/**
- * g_proxy_connect_async:
- * @proxy: a #GProxy
- * @connection: a #GIOStream
- * @proxy_address: a #GProxyAddress
- * @cancellable: (allow-none): a #GCancellable
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): callback data
+ * 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
*
- * Asynchronous version of g_proxy_connect().
+ * Lists the schemas in a given source.
*
- * Since: 2.26
+ * 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_proxy_connect_finish:
- * @proxy: a #GProxy
- * @result: a #GAsyncResult
- * @error: return #GError
+ * g_settings_schema_source_lookup:
+ * @source: a #GSettingsSchemaSource
+ * @schema_id: a schema ID
+ * @recursive: %TRUE if the lookup should be recursive
*
- * See g_proxy_connect().
+ * Looks up a schema with the identifier @schema_id in @source.
*
- * Returns: (transfer full): a #GIOStream.
- * Since: 2.26
+ * This function is not required for normal uses of #GSettings but it
+ * may be useful to authors of plugin management systems or to those who
+ * want to introspect the content of schemas.
+ *
+ * If the schema isn't found directly in @source and @recursive is %TRUE
+ * then the parent sources will also be checked.
+ *
+ * If the schema isn't found, %NULL is returned.
+ *
+ * Returns: (nullable) (transfer full): a new #GSettingsSchema
+ * Since: 2.32
*/
/**
- * g_proxy_get_default_for_protocol:
- * @protocol: the proxy protocol name (e.g. http, socks, etc)
+ * g_settings_schema_source_new_from_directory:
+ * @directory: the filename of a directory
+ * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
+ * @trusted: %TRUE, if the directory is trusted
+ * @error: a pointer to a #GError pointer set to %NULL, or %NULL
*
- * Lookup "gio-proxy" extension point for a proxy implementation that supports
- * specified protocol.
+ * Attempts to create a new schema source corresponding to the contents
+ * of the given directory.
*
- * is not supported.
+ * This function is not required for normal uses of #GSettings but it
+ * may be useful to authors of plugin management systems.
*
- * Returns: (transfer full): return a #GProxy or NULL if protocol
- * Since: 2.26
+ * 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 `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.
+ *
+ * First, if g_settings_schema_source_lookup() is called with the
+ * @recursive flag set to %TRUE and the schema can not be found in the
+ * source, the lookup will recurse to the parent.
+ *
+ * Second, any references to other schemas specified within this
+ * 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
+ * returned by g_settings_schema_source_get_default().
+ *
+ * Since: 2.32
*/
/**
- * g_proxy_resolver_get_default:
+ * g_settings_schema_source_ref:
+ * @source: a #GSettingsSchemaSource
*
- * Gets the default #GProxyResolver for the system.
+ * Increase the reference count of @source, returning a new reference.
*
- * Returns: (transfer none): the default #GProxyResolver.
- * Since: 2.26
+ * Returns: a new reference to @source
+ * Since: 2.32
*/
/**
- * g_proxy_resolver_is_supported:
- * @resolver: a #GProxyResolver
+ * g_settings_schema_source_unref:
+ * @source: a #GSettingsSchemaSource
*
- * Checks if @resolver can be used on this system. (This is used
- * internally; g_proxy_resolver_get_default() will only return a proxy
- * resolver that returns %TRUE for this method.)
+ * Decrease the reference count of @source, possibly freeing it.
*
- * Returns: %TRUE if @resolver is supported.
- * Since: 2.26
+ * Since: 2.32
*/
/**
- * g_proxy_resolver_lookup:
- * @resolver: a #GProxyResolver
- * @uri: a URI representing the destination to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @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 you don't know what network protocol is being used on the
- * socket, you should use <literal>none</literal> 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 connection should not be attempted unless it is part of the
- * returned array of proxies.
+ * g_settings_schema_unref:
+ * @schema: a #GSettingsSchema
*
- * NULL-terminated array of proxy URIs. Must be freed
- * with g_strfreev().
+ * Decrease the reference count of @schema, possibly freeing it.
*
- * Returns: (transfer full) (array zero-terminated=1): A
- * Since: 2.26
+ * Since: 2.32
*/
/**
- * g_proxy_resolver_lookup_async:
- * @resolver: a #GProxyResolver
- * @uri: a URI representing the destination to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): callback to call after resolution completes
- * @user_data: (closure): data for @callback
+ * g_settings_set:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @format: a #GVariant format string
+ * @...: arguments as per @format
+ *
+ * Sets @key in @settings to @value.
+ *
+ * A convenience function that combines g_settings_set_value() with
+ * g_variant_new().
*
- * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
- * details.
+ * It is a programmer error to give a @key that isn't contained in the
+ * 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
* Since: 2.26
*/
/**
- * g_proxy_resolver_lookup_finish:
- * @resolver: a #GProxyResolver
- * @result: the result passed to your #GAsyncReadyCallback
- * @error: return location for a #GError, or %NULL
+ * g_settings_set_boolean:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: the value to set it to
*
- * Call this function to obtain the array of proxy URIs when
- * g_proxy_resolver_lookup_async() is complete. See
- * g_proxy_resolver_lookup() for more details.
+ * Sets @key in @settings to @value.
*
- * NULL-terminated array of proxy URIs. Must be freed
- * with g_strfreev().
+ * A convenience variant of g_settings_set() for booleans.
*
- * Returns: (transfer full) (array zero-terminated=1): A
+ * 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
* Since: 2.26
*/
/**
- * g_proxy_supports_hostname:
- * @proxy: a #GProxy
+ * g_settings_set_double:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: the value to set it to
*
- * Some proxy protocols expect to be passed a hostname, which they
- * will resolve to an IP address themselves. Others, like SOCKS4, do
- * not allow this. This function will return %FALSE if @proxy is
- * implementing such a protocol. When %FALSE is returned, the caller
- * should resolve the destination hostname first, and then pass a
- * #GProxyAddress containing the stringified IP address to
- * g_proxy_connect() or g_proxy_connect_async().
+ * Sets @key in @settings to @value.
*
- * Returns: %TRUE if hostname resolution is supported.
+ * A convenience variant of g_settings_set() for doubles.
+ *
+ * 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
* Since: 2.26
*/
/**
- * g_remote_action_group_activate_action_full:
- * @remote: a #GRemoteActionGroup
- * @action_name: the name of the action to change the state of
- * @value: the new requested value for the state
- * @platform_data: the platform data to send
+ * g_settings_set_enum:
+ * @settings: a #GSettings object
+ * @key: a key, within @settings
+ * @value: an enumerated value
*
- * Changes the state of a remote action.
+ * Looks up the enumerated type nick for @value and writes it to @key,
+ * within @settings.
*
- * This is the same as g_action_group_change_action_state() except that
- * it allows for provision of "platform data" to be sent along with the
- * state change request. This typically contains details such as the
- * user interaction timestamp or startup notification information.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings or is not marked as an enumerated type, or for
+ * @value not to be a valid value for the named type.
*
- * @platform_data must be non-%NULL and must have the type
- * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
+ * After performing the write, accessing @key directly with
+ * g_settings_get_string() will return the 'nick' associated with
+ * @value.
*
- * Since: 2.32
+ * Returns: %TRUE, if the set succeeds
*/
/**
- * g_renew:
- * @struct_type: the type of the elements to allocate
- * @mem: the currently allocated memory
- * @n_structs: the number of elements to allocate
+ * g_settings_set_flags:
+ * @settings: a #GSettings object
+ * @key: a key, within @settings
+ * @value: a flags value
*
- * Reallocates the memory pointed to by @mem, so that it now has space for
- * @n_structs elements of type @struct_type. It returns the new address of
- * the memory, which may have been moved.
- * Care is taken to avoid overflow when calculating the size of the allocated block.
+ * Looks up the flags type nicks for the bits specified by @value, puts
+ * them in an array of strings and writes the array to @key, within
+ * @settings.
*
- * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
- */
-
-
-/**
- * g_resolver_error_quark:
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings or is not marked as a flags type, or for @value
+ * to contain any bits that are not value for the named type.
*
- * Gets the #GResolver Error Quark.
+ * After performing the write, accessing @key directly with
+ * g_settings_get_strv() will return an array of 'nicks'; one for each
+ * bit in @value.
*
- * Returns: a #GQuark.
- * Since: 2.22
+ * Returns: %TRUE, if the set succeeds
*/
/**
- * g_resolver_free_addresses: (skip)
- * @addresses: a #GList of #GInetAddress
+ * g_settings_set_int:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: the value to set it to
*
- * Frees @addresses (which should be the return value from
- * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
- * (This is a convenience method; you can also simply free the results
- * by hand.)
+ * Sets @key in @settings to @value.
*
- * Since: 2.22
- */
-
-
-/**
- * g_resolver_free_targets: (skip)
- * @targets: a #GList of #GSrvTarget
+ * A convenience variant of g_settings_set() for 32-bit integers.
*
- * Frees @targets (which should be the return value from
- * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
- * (This is a convenience method; you can also simply free the
- * results by hand.)
+ * It is a programmer error to give a @key that isn't specified as
+ * having a int32 type in the schema for @settings.
*
- * Since: 2.22
+ * Returns: %TRUE if setting the key succeeded,
+ * %FALSE if the key was not writable
+ * Since: 2.26
*/
/**
- * g_resolver_get_default:
+ * g_settings_set_string:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: the value to set it to
*
- * Gets the default #GResolver. You should unref it when you are done
- * with it. #GResolver may use its reference count as a hint about how
- * many threads it should allocate for concurrent DNS resolutions.
+ * Sets @key in @settings to @value.
*
- * Returns: (transfer full): the default #GResolver.
- * Since: 2.22
+ * A convenience variant of g_settings_set() for strings.
+ *
+ * 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
+ * Since: 2.26
*/
/**
- * g_resolver_lookup_by_address:
- * @resolver: a #GResolver
- * @address: the address to reverse-resolve
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: return location for a #GError, or %NULL
- *
- * Synchronously reverse-resolves @address to determine its
- * associated hostname.
+ * g_settings_set_strv:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
*
- * If the DNS resolution fails, @error (if non-%NULL) will be set to
- * a value from #GResolverError.
+ * Sets @key in @settings to @value.
*
- * 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.
+ * A convenience variant of g_settings_set() for string arrays. If
+ * @value is %NULL, then @key is set to be the empty array.
*
- * form), or %NULL on error.
+ * 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: a hostname (either ASCII-only, or in ASCII-encoded
- * Since: 2.22
+ * Returns: %TRUE if setting the key succeeded,
+ * %FALSE if the key was not writable
+ * Since: 2.26
*/
/**
- * g_resolver_lookup_by_address_async:
- * @resolver: a #GResolver
- * @address: the address to reverse-resolve
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): callback to call after resolution completes
- * @user_data: (closure): data for @callback
+ * g_settings_set_uint:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: the value to set it to
*
- * Begins asynchronously reverse-resolving @address to determine its
- * associated hostname, and eventually calls @callback, which must
- * call g_resolver_lookup_by_address_finish() to get the final result.
+ * Sets @key in @settings to @value.
*
- * Since: 2.22
+ * A convenience variant of g_settings_set() for 32-bit unsigned
+ * integers.
+ *
+ * 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
+ * Since: 2.30
*/
/**
- * g_resolver_lookup_by_address_finish:
- * @resolver: a #GResolver
- * @result: the result passed to your #GAsyncReadyCallback
- * @error: return location for a #GError, or %NULL
+ * g_settings_set_value:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: a #GVariant of the correct type
*
- * Retrieves the result of a previous call to
- * g_resolver_lookup_by_address_async().
+ * Sets @key in @settings to @value.
*
- * 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.
+ * It is a programmer error to give a @key that isn't contained in the
+ * schema for @settings or for @value to have the incorrect type, per
+ * the schema.
*
- * form), or %NULL on error.
+ * If @value is floating then this function consumes the reference.
*
- * Returns: a hostname (either ASCII-only, or in ASCII-encoded
- * Since: 2.22
+ * Returns: %TRUE if setting the key succeeded,
+ * %FALSE if the key was not writable
+ * Since: 2.26
*/
/**
- * g_resolver_lookup_by_name:
- * @resolver: a #GResolver
- * @hostname: the hostname to look up
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: return location for a #GError, or %NULL
- *
- * Synchronously resolves @hostname to determine its associated IP
- * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
- * the textual form of an IP address (in which case this just becomes
- * a wrapper around g_inet_address_new_from_string()).
+ * g_settings_sync:
*
- * On success, g_resolver_lookup_by_name() will return a #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
- * first, then the second if the first fails, etc. If you are using
- * the result to listen on a socket, it is appropriate to add each
- * result using e.g. g_socket_listener_add_address().
+ * Ensures that all pending operations for the given are complete for
+ * the default backend.
*
- * If the DNS resolution fails, @error (if non-%NULL) will be set to a
- * value from #GResolverError.
+ * Writes made to a #GSettings are handled asynchronously. For this
+ * reason, it is very unlikely that the changes have it to disk by the
+ * time g_settings_set() returns.
*
- * 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.
+ * This call will block until all of the writes have made it to the
+ * backend. Since the mainloop is not running, no change notifications
+ * will be dispatched during this call (but some may be queued by the
+ * time the call is done).
+ */
+
+
+/**
+ * g_settings_unbind:
+ * @object: (type GObject.Object): the object
+ * @property: the property whose binding is removed
*
- * If you are planning to connect to a socket on the resolved IP
- * address, it may be easier to create a #GNetworkAddress and use its
- * #GSocketConnectable interface.
+ * Removes an existing binding for @property on @object.
*
- * 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.)
+ * Note that bindings are automatically removed when the
+ * object is finalized, so it is rarely necessary to call this
+ * function.
*
- * Returns: (element-type GInetAddress) (transfer full): a #GList
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * g_resolver_lookup_by_name_async:
- * @resolver: a #GResolver
- * @hostname: the hostname to look up the address of
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): callback to call after resolution completes
- * @user_data: (closure): data for @callback
+ * 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
+ * @n_entries: the length of @entries, or -1
+ * @user_data: the user data for signal connections
*
- * Begins asynchronously resolving @hostname to determine its
- * associated IP address(es), and eventually calls @callback, which
- * must call g_resolver_lookup_by_name_finish() to get the result.
- * See g_resolver_lookup_by_name() for more details.
+ * A convenience function for creating multiple #GSimpleAction instances
+ * and adding them to the action group.
*
- * Since: 2.22
+ * Since: 2.30
+ * Deprecated: 2.38: Use g_action_map_add_action_entries()
*/
/**
- * g_resolver_lookup_by_name_finish:
- * @resolver: a #GResolver
- * @result: the result passed to your #GAsyncReadyCallback
- * @error: return location for a #GError, or %NULL
+ * g_simple_action_group_insert:
+ * @simple: a #GSimpleActionGroup
+ * @action: a #GAction
*
- * Retrieves the result of a call to
- * g_resolver_lookup_by_name_async().
+ * Adds an action to the action group.
*
- * 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.
+ * If the action group already contains an action with the same name as
+ * @action then the old action is dropped from the group.
*
- * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
- * for more details.
+ * The action group takes its own reference on @action.
*
- * Returns: (element-type GInetAddress) (transfer full): a #GList
- * Since: 2.22
+ * Since: 2.28
+ * Deprecated: 2.38: Use g_action_map_add_action()
*/
/**
- * g_resolver_lookup_service:
- * @resolver: a #GResolver
- * @service: the service type to look up (eg, "ldap")
- * @protocol: the networking protocol to use for @service (eg, "tcp")
- * @domain: the DNS domain to look up the service in
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: return location for a #GError, or %NULL
- *
- * 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.
- *
- * On success, g_resolver_lookup_service() will return a #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.
- *
- * 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.
+ * g_simple_action_group_lookup:
+ * @simple: a #GSimpleActionGroup
+ * @action_name: the name of an action
*
- * If you are planning to connect to the service, it is usually easier
- * to create a #GNetworkService and use its #GSocketConnectable
- * interface.
+ * Looks up the action with the name @action_name in the group.
*
- * 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.)
+ * If no such action exists, returns %NULL.
*
- * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
- * Since: 2.22
+ * Returns: (transfer none): a #GAction, or %NULL
+ * Since: 2.28
+ * Deprecated: 2.38: Use g_action_map_lookup_action()
*/
/**
- * g_resolver_lookup_service_async:
- * @resolver: a #GResolver
- * @service: the service type to look up (eg, "ldap")
- * @protocol: the networking protocol to use for @service (eg, "tcp")
- * @domain: the DNS domain to look up the service in
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): callback to call after resolution completes
- * @user_data: (closure): data for @callback
+ * g_simple_action_group_new:
*
- * Begins asynchronously performing a DNS SRV lookup for the given
- * @service and @protocol in the given @domain, and eventually calls
- * @callback, which must call g_resolver_lookup_service_finish() to
- * get the final result. See g_resolver_lookup_service() for more
- * details.
+ * Creates a new, empty, #GSimpleActionGroup.
*
- * Since: 2.22
+ * Returns: a new #GSimpleActionGroup
+ * Since: 2.28
*/
/**
- * g_resolver_lookup_service_finish:
- * @resolver: a #GResolver
- * @result: the result passed to your #GAsyncReadyCallback
- * @error: return location for a #GError, or %NULL
- *
- * Retrieves the result of a previous call to
- * g_resolver_lookup_service_async().
+ * g_simple_action_group_remove:
+ * @simple: a #GSimpleActionGroup
+ * @action_name: the name of the action
*
- * 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.
+ * Removes the named action from the action group.
*
- * or %NULL on error. See g_resolver_lookup_service() for more details.
+ * If no action of this name is in the group then nothing happens.
*
- * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
- * Since: 2.22
+ * Since: 2.28
+ * Deprecated: 2.38: Use g_action_map_remove_action()
*/
/**
- * g_resolver_set_default:
- * @resolver: the new default #GResolver
+ * g_simple_action_new:
+ * @name: the name of the action
+ * @parameter_type: (allow-none): the type of parameter to the activate function
*
- * Sets @resolver to be the application's default resolver (reffing
- * @resolver, and unreffing the previous default resolver, if any).
- * Future calls to g_resolver_get_default() will return this resolver.
+ * Creates a new action.
*
- * This can be used if an application wants to perform any sort of DNS
- * caching or "pinning"; it can implement its own #GResolver that
- * calls the original default resolver for DNS operations, and
- * implements its own cache policies on top of that, and then set
- * itself as the default resolver for all later code to use.
+ * The created action is stateless. See g_simple_action_new_stateful().
*
- * Since: 2.22
+ * Returns: a new #GSimpleAction
+ * Since: 2.28
*/
/**
- * g_seekable_can_seek:
- * @seekable: a #GSeekable.
+ * g_simple_action_new_stateful:
+ * @name: the name of the action
+ * @parameter_type: (allow-none): the type of the parameter to the activate function
+ * @state: the initial state of the action
*
- * Tests if the stream supports the #GSeekableIface.
+ * Creates a new stateful action.
*
- * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
- */
-
-
-/**
- * g_seekable_can_truncate:
- * @seekable: a #GSeekable.
+ * @state is the initial state of the action. All future state values
+ * must have the same #GVariantType as the initial state.
*
- * Tests if the stream can be truncated.
+ * If the @state GVariant is floating, it is consumed.
*
- * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
+ * Returns: a new #GSimpleAction
+ * Since: 2.28
*/
/**
- * g_seekable_seek:
- * @seekable: a #GSeekable.
- * @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.
+ * g_simple_action_set_enabled:
+ * @simple: a #GSimpleAction
+ * @enabled: whether the action is enabled
*
- * Seeks in the stream by the given @offset, modified by @type.
+ * Sets the action as enabled or not.
*
- * 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.
+ * An action must be enabled in order to be activated or in order to
+ * have its state changed from outside callers.
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
+ * This should only be called by the implementor of the action. Users
+ * of the action should not attempt to modify its enabled flag.
*
- * Returns: %TRUE if successful. If an error
+ * Since: 2.28
*/
/**
- * g_seekable_tell:
- * @seekable: a #GSeekable.
+ * g_simple_action_set_state:
+ * @simple: a #GSimpleAction
+ * @value: the new #GVariant for the state
*
- * Tells the current position within the stream.
+ * Sets the state of the action.
*
- * Returns: the offset from the beginning of the buffer.
+ * This directly updates the 'state' property to the given value.
+ *
+ * This should only be called by the implementor of the action. Users
+ * of the action should not attempt to directly modify the 'state'
+ * 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_seekable_truncate:
- * @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.
- *
- * Truncates a stream with a given #offset.
+ * g_simple_action_set_state_hint:
+ * @simple: a #GSimpleAction
+ * @state_hint: (allow-none): a #GVariant representing the state hint
*
- * 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.
+ * Sets the state hint for the action.
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
+ * See g_action_get_state_hint() for more information about
+ * action state hints.
*
- * Virtual: truncate_fn
- * Returns: %TRUE if successful. If an error
+ * Since: 2.44
*/
/**
- * g_settings_apply:
- * @settings: a #GSettings instance
+ * g_simple_async_report_error_in_idle: (skip)
+ * @object: (allow-none): a #GObject, or %NULL.
+ * @callback: a #GAsyncReadyCallback.
+ * @user_data: user data passed to @callback.
+ * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
+ * @code: a specific error code.
+ * @format: a formatted error reporting string.
+ * @...: a list of variables to fill in @format.
*
- * Applies any changes that have been made to the settings. This
- * function does nothing unless @settings is in 'delay-apply' mode;
- * see g_settings_delay(). In the normal case settings are always
- * applied immediately.
+ * Reports an error in an asynchronous function in an idle function by
+ * directly setting the contents of the #GAsyncResult with the given error
+ * information.
*/
/**
- * g_settings_backend_changed:
- * @backend: a #GSettingsBackend implementation
- * @key: the name of the key
- * @origin_tag: the origin tag
- *
- * Signals that a single key has possibly changed. Backend
- * implementations should call this if a key has possibly changed its
- * value.
- *
- * @key must be a valid key (ie starting with a slash, not containing
- * '//', and not ending with a slash).
- *
- * The implementation must call this function during any call to
- * g_settings_backend_write(), before the call returns (except in the
- * case that no keys are actually changed and it cares to detect this
- * fact). It may not rely on the existence of a mainloop for
- * dispatching the signal later.
- *
- * The implementation may call this function at any other time it likes
- * in response to other events (such as changes occurring outside of the
- * program). These calls may originate from a mainloop or may originate
- * in response to any other action (including from calls to
- * g_settings_backend_write()).
- *
- * In the case that this call is in response to a call to
- * g_settings_backend_write() then @origin_tag must be set to the same
- * value that was passed to that call.
+ * g_simple_async_report_gerror_in_idle:
+ * @object: (allow-none): a #GObject, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @user_data: (closure): user data passed to @callback.
+ * @error: the #GError to report
*
- * Since: 2.26
+ * Reports an error in an idle function. Similar to
+ * g_simple_async_report_error_in_idle(), but takes a #GError rather
+ * than building a new one.
*/
/**
- * g_settings_backend_changed_tree:
- * @backend: a #GSettingsBackend implementation
- * @tree: a #GTree containing the changes
- * @origin_tag: the origin tag
+ * g_simple_async_report_take_gerror_in_idle: (skip)
+ * @object: (allow-none): a #GObject, or %NULL
+ * @callback: a #GAsyncReadyCallback.
+ * @user_data: user data passed to @callback.
+ * @error: the #GError to report
*
- * This call is a convenience wrapper. It gets the list of changes from
- * @tree, computes the longest common prefix and calls
- * g_settings_backend_changed().
+ * Reports an error in an idle function. Similar to
+ * g_simple_async_report_gerror_in_idle(), but takes over the caller's
+ * ownership of @error, so the caller does not have to free it any more.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * 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
- *
- * 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,
- * optionally, the value to store at each of those keys.
+ * g_simple_async_result_complete:
+ * @simple: a #GSimpleAsyncResult.
*
- * You must free the value returned in @path, @keys and @values using
- * g_free(). You should not attempt to free or unref the contents of
- * @keys or @values.
+ * Completes an asynchronous I/O job immediately. Must be called in
+ * the thread where the asynchronous result was to be delivered, as it
+ * invokes the callback directly. If you are in a different thread use
+ * g_simple_async_result_complete_in_idle().
*
- * Since: 2.26
+ * Calling this function takes a reference to @simple for as long as
+ * is needed to complete the call.
*/
/**
- * 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.
+ * g_simple_async_result_complete_in_idle:
+ * @simple: a #GSimpleAsyncResult.
*
- * The user gets a reference to the backend.
+ * 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).
*
- * Returns: (transfer full): the default #GSettingsBackend
- * Since: 2.28
+ * Calling this function takes a reference to @simple for as long as
+ * is needed to complete the call.
*/
/**
- * g_settings_backend_keys_changed:
- * @backend: a #GSettingsBackend implementation
- * @path: the path containing the changes
- * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
- * @origin_tag: the origin tag
- *
- * Signals that a list of keys have possibly changed. Backend
- * implementations should call this if keys have possibly changed their
- * values.
- *
- * @path must be a valid path (ie starting and ending with a slash and
- * not containing '//'). Each string in @items must form a valid key
- * name when @path is prefixed to it (ie: each item must not start or
- * end with '/' and must not contain '//').
- *
- * The meaning of this signal is that any of the key names resulting
- * from the contatenation of @path with each item in @items may have
- * changed.
- *
- * The same rules for when notifications must occur apply as per
- * g_settings_backend_changed(). These two calls can be used
- * interchangeably if exactly one item has changed (although in that
- * case g_settings_backend_changed() is definitely preferred).
+ * g_simple_async_result_get_op_res_gboolean:
+ * @simple: a #GSimpleAsyncResult.
*
- * For efficiency reasons, the implementation should strive for @path to
- * be as long as possible (ie: the longest common prefix of all of the
- * keys that were changed) but this is not strictly required.
+ * Gets the operation result boolean from within the asynchronous result.
*
- * Since: 2.26
+ * Returns: %TRUE if the operation's result was %TRUE, %FALSE
+ * if the operation's result was %FALSE.
*/
/**
- * g_settings_backend_path_changed:
- * @backend: a #GSettingsBackend implementation
- * @path: the path containing the changes
- * @origin_tag: the origin tag
- *
- * Signals that all keys below a given path may have possibly changed.
- * Backend implementations should call this if an entire path of keys
- * have possibly changed their values.
- *
- * @path must be a valid path (ie starting and ending with a slash and
- * not containing '//').
- *
- * The meaning of this signal is that any of the key which has a name
- * starting with @path may have changed.
- *
- * The same rules for when notifications must occur apply as per
- * g_settings_backend_changed(). This call might be an appropriate
- * reasponse to a 'reset' call but implementations are also free to
- * explicitly list the keys that were affected by that call if they can
- * easily do so.
+ * g_simple_async_result_get_op_res_gpointer: (skip)
+ * @simple: a #GSimpleAsyncResult.
*
- * For efficiency reasons, the implementation should strive for @path to
- * be as long as possible (ie: the longest common prefix of all of the
- * keys that were changed) but this is not strictly required. As an
- * example, if this function is called with the path of "/" then every
- * single key in the application will be notified of a possible change.
+ * Gets a pointer result as returned by the asynchronous function.
*
- * Since: 2.26
+ * Returns: a pointer from the result.
*/
/**
- * g_settings_backend_path_writable_changed:
- * @backend: a #GSettingsBackend implementation
- * @path: the name of the path
- *
- * Signals that the writability of all keys below a given path may have
- * changed.
+ * g_simple_async_result_get_op_res_gssize:
+ * @simple: a #GSimpleAsyncResult.
*
- * Since GSettings performs no locking operations for itself, this call
- * will always be made in response to external events.
+ * Gets a gssize from the asynchronous result.
*
- * Since: 2.26
+ * Returns: a gssize returned from the asynchronous function.
*/
/**
- * g_settings_backend_writable_changed:
- * @backend: a #GSettingsBackend implementation
- * @key: the name of the key
- *
- * Signals that the writability of a single key has possibly changed.
+ * g_simple_async_result_get_source_tag: (skip)
+ * @simple: a #GSimpleAsyncResult.
*
- * Since GSettings performs no locking operations for itself, this call
- * will always be made in response to external events.
+ * Gets the source tag for the #GSimpleAsyncResult.
*
- * Since: 2.26
+ * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
*/
/**
- * g_settings_bind:
- * @settings: a #GSettings object
- * @key: the key to bind
- * @object: (type GObject.Object): a #GObject
- * @property: the name of the property to bind
- * @flags: flags for the binding
- *
- * Create a binding between the @key in the @settings object
- * and the property @property of @object.
- *
- * The binding uses the default GIO mapping functions to map
- * between the settings and property values. These functions
- * handle booleans, numeric types and string types in a
- * straightforward way. Use g_settings_bind_with_mapping() if
- * you need a custom mapping, or map between types that are not
- * supported by the default mapping functions.
+ * g_simple_async_result_is_valid:
+ * @result: the #GAsyncResult passed to the _finish function.
+ * @source: (allow-none): the #GObject passed to the _finish function.
+ * @source_tag: (allow-none): the asynchronous function.
*
- * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
- * function also establishes a binding between the writability of
- * @key and the "sensitive" property of @object (if @object has
- * a boolean property by that name). See g_settings_bind_writable()
- * for more details about writable bindings.
+ * Ensures that the data passed to the _finish function of an async
+ * operation is consistent. Three checks are performed.
*
- * Note that the lifecycle of the binding is tied to the object,
- * and that you can have only one binding per object property.
- * If you bind the same property twice on the same object, the second
- * binding overrides the first one.
+ * 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 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.)
*
- * Since: 2.26
+ * Returns: #TRUE if all checks passed or #FALSE if any failed.
+ * Since: 2.20
*/
/**
- * g_settings_bind_with_mapping: (skip)
- * @settings: a #GSettings object
- * @key: the key to bind
- * @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
- * @user_data: data that gets passed to @get_mapping and @set_mapping
- * @destroy: #GDestroyNotify function for @user_data
+ * g_simple_async_result_new:
+ * @source_object: (allow-none): a #GObject, or %NULL.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @user_data: (closure): user data passed to @callback.
+ * @source_tag: the asynchronous function.
*
- * Create a binding between the @key in the @settings object
- * and the property @property of @object.
+ * Creates a #GSimpleAsyncResult.
*
- * The binding uses the provided mapping functions to map between
- * settings and property values.
+ * The common convention is to create the #GSimpleAsyncResult in the
+ * function that starts the asynchronous operation and use that same
+ * function as the @source_tag.
*
- * Note that the lifecycle of the binding is tied to the object,
- * and that you can have only one binding per object property.
- * If you bind the same property twice on the same object, the second
- * binding overrides the first one.
+ * If your operation supports cancellation with #GCancellable (which it
+ * probably should) then you should provide the user's cancellable to
+ * g_simple_async_result_set_check_cancellable() immediately after
+ * this function returns.
*
- * Since: 2.26
+ * Returns: a #GSimpleAsyncResult.
*/
/**
- * g_settings_bind_writable:
- * @settings: a #GSettings object
- * @key: the key to bind
- * @object: (type GObject.Object): a #GObject
- * @property: the name of a boolean property to bind
- * @inverted: whether to 'invert' the value
- *
- * Create a binding between the writability of @key in the
- * @settings object and the property @property of @object.
- * The property must be boolean; "sensitive" or "visible"
- * properties of widgets are the most likely candidates.
- *
- * Writable bindings are always uni-directional; changes of the
- * writability of the setting will be propagated to the object
- * property, not the other way.
- *
- * 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.
+ * g_simple_async_result_new_error:
+ * @source_object: (allow-none): a #GObject, or %NULL.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @user_data: (closure): user data passed to @callback.
+ * @domain: a #GQuark.
+ * @code: an error code.
+ * @format: a string with format characters.
+ * @...: a list of values to insert into @format.
*
- * Note that the lifecycle of the binding is tied to the object,
- * and that you can have only one binding per object property.
- * If you bind the same property twice on the same object, the second
- * binding overrides the first one.
+ * Creates a new #GSimpleAsyncResult with a set error.
*
- * Since: 2.26
+ * Returns: a #GSimpleAsyncResult.
*/
/**
- * g_settings_delay:
- * @settings: a #GSettings object
+ * g_simple_async_result_new_from_error:
+ * @source_object: (allow-none): a #GObject, or %NULL.
+ * @callback: (scope async): a #GAsyncReadyCallback.
+ * @user_data: (closure): user data passed to @callback.
+ * @error: a #GError
*
- * Changes the #GSettings object into 'delay-apply' mode. In this
- * mode, changes to @settings are not immediately propagated to the
- * backend, but kept locally until g_settings_apply() is called.
+ * Creates a #GSimpleAsyncResult from an error condition.
*
- * Since: 2.26
+ * Returns: a #GSimpleAsyncResult.
*/
/**
- * g_settings_get:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- * @format: a #GVariant format string
- * @...: arguments as per @format
- *
- * Gets the value that is stored at @key in @settings.
- *
- * A convenience function that combines g_settings_get_value() with
- * g_variant_get().
+ * g_simple_async_result_new_take_error: (skip)
+ * @source_object: (allow-none): a #GObject, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data passed to @callback
+ * @error: a #GError
*
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or for the #GVariantType of @format to mismatch
- * the type given in the schema.
+ * Creates a #GSimpleAsyncResult from an error condition, and takes over the
+ * caller's ownership of @error, so the caller does not need to free it anymore.
*
- * Since: 2.26
+ * Returns: a #GSimpleAsyncResult
+ * Since: 2.28
*/
/**
- * g_settings_get_boolean:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * Gets the value that is stored at @key in @settings.
+ * g_simple_async_result_propagate_error:
+ * @simple: a #GSimpleAsyncResult.
+ * @dest: (out): a location to propagate the error to.
*
- * A convenience variant of g_settings_get() for booleans.
+ * Propagates an error from within the simple asynchronous result to
+ * a given destination.
*
- * It is a programmer error to give a @key that isn't specified as
- * having a boolean type in the schema for @settings.
+ * If the #GCancellable given to a prior call to
+ * g_simple_async_result_set_check_cancellable() is cancelled then this
+ * function will return %TRUE with @dest set appropriately.
*
- * Returns: a boolean
- * Since: 2.26
+ * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
*/
/**
- * g_settings_get_child:
- * @settings: a #GSettings object
- * @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.
+ * g_simple_async_result_run_in_thread: (skip)
+ * @simple: a #GSimpleAsyncResult.
+ * @func: a #GSimpleAsyncThreadFunc.
+ * @io_priority: the io priority of the request.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
*
- * The schema for the child settings object must have been declared
- * in the schema of @settings using a <tag class="starttag">child</tag> element.
+ * Runs the asynchronous job in a separate thread and then calls
+ * g_simple_async_result_complete_in_idle() on @simple to return
+ * the result to the appropriate main loop.
*
- * Returns: (transfer full): a 'child' settings object
- * Since: 2.26
+ * Calling this function takes a reference to @simple for as long as
+ * is needed to run the job and report its completion.
*/
/**
- * g_settings_get_double:
- * @settings: a #GSettings object
- * @key: the key to get the value for
+ * g_simple_async_result_set_check_cancellable:
+ * @simple: a #GSimpleAsyncResult
+ * @check_cancellable: (allow-none): a #GCancellable to check, or %NULL to unset
*
- * Gets the value that is stored at @key in @settings.
+ * Sets a #GCancellable to check before dispatching results.
*
- * A convenience variant of g_settings_get() for doubles.
+ * This function has one very specific purpose: the provided cancellable
+ * is checked at the time of g_simple_async_result_propagate_error() If
+ * it is cancelled, these functions will return an "Operation was
+ * cancelled" error (%G_IO_ERROR_CANCELLED).
*
- * It is a programmer error to give a @key that isn't specified as
- * having a 'double' type in the schema for @settings.
+ * Implementors of cancellable asynchronous functions should use this in
+ * order to provide a guarantee to their callers that cancelling an
+ * async operation will reliably result in an error being returned for
+ * that operation (even if a positive result for the operation has
+ * already been sent as an idle to the main context to be dispatched).
*
- * Returns: a double
- * Since: 2.26
+ * The checking described above is done regardless of any call to the
+ * unrelated g_simple_async_result_set_handle_cancellation() function.
+ *
+ * Since: 2.32
*/
/**
- * g_settings_get_enum:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * Gets the value that is stored in @settings for @key and converts it
- * to the enum value that it represents.
- *
- * In order to use this function the type of the value must be a string
- * and it must be marked in the schema file as an enumerated type.
- *
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or is not marked as an enumerated type.
- *
- * If the value stored in the configuration database is not a valid
- * value for the enumerated type then this function will return the
- * default value.
+ * g_simple_async_result_set_error: (skip)
+ * @simple: a #GSimpleAsyncResult.
+ * @domain: a #GQuark (usually #G_IO_ERROR).
+ * @code: an error code.
+ * @format: a formatted error reporting string.
+ * @...: a list of variables to fill in @format.
*
- * Returns: the enum value
- * Since: 2.26
+ * Sets an error within the asynchronous result without a #GError.
*/
/**
- * g_settings_get_flags:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * Gets the value that is stored in @settings for @key and converts it
- * to the flags value that it represents.
- *
- * In order to use this function the type of the value must be an array
- * of strings and it must be marked in the schema file as an flags type.
- *
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or is not marked as a flags type.
- *
- * If the value stored in the configuration database is not a valid
- * value for the flags type then this function will return the default
- * value.
+ * g_simple_async_result_set_error_va: (skip)
+ * @simple: a #GSimpleAsyncResult.
+ * @domain: a #GQuark (usually #G_IO_ERROR).
+ * @code: an error code.
+ * @format: a formatted error reporting string.
+ * @args: va_list of arguments.
*
- * Returns: the flags value
- * Since: 2.26
+ * Sets an error within the asynchronous result without a #GError.
+ * Unless writing a binding, see g_simple_async_result_set_error().
*/
/**
- * g_settings_get_has_unapplied:
- * @settings: a #GSettings object
- *
- * Returns whether the #GSettings object has any unapplied
- * changes. This can only be the case if it is in 'delayed-apply' mode.
+ * g_simple_async_result_set_from_error:
+ * @simple: a #GSimpleAsyncResult.
+ * @error: #GError.
*
- * Returns: %TRUE if @settings has unapplied changes
- * Since: 2.26
+ * Sets the result from a #GError.
*/
/**
- * g_settings_get_int:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * Gets the value that is stored at @key in @settings.
- *
- * A convenience variant of g_settings_get() for 32-bit integers.
+ * g_simple_async_result_set_handle_cancellation:
+ * @simple: a #GSimpleAsyncResult.
+ * @handle_cancellation: a #gboolean.
*
- * It is a programmer error to give a @key that isn't specified as
- * having a int32 type in the schema for @settings.
+ * Sets whether to handle cancellation within the asynchronous operation.
*
- * Returns: an integer
- * Since: 2.26
+ * This function has nothing to do with
+ * g_simple_async_result_set_check_cancellable(). It only refers to the
+ * #GCancellable passed to g_simple_async_result_run_in_thread().
*/
/**
- * 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
- * @user_data: user data for @mapping
- *
- * Gets the value that is stored at @key in @settings, subject to
- * application-level validation/mapping.
- *
- * You should use this function when the application needs to perform
- * some processing on the value of the key (for example, parsing). The
- * @mapping function performs that processing. If the function
- * indicates that the processing was unsuccessful (due to a parse error,
- * for example) then the mapping is tried again with another value.
- *
- * This allows a robust 'fall back to defaults' behaviour to be
- * implemented somewhat automatically.
- *
- * The first value that is tried is the user's setting for the key. If
- * the mapping function fails to map this value, other values may be
- * tried in an unspecified order (system or site defaults, translated
- * schema default values, untranslated schema default values, etc).
- *
- * If the mapping function fails for all possible values, one additional
- * attempt is made: the mapping function is called with a %NULL value.
- * If the mapping function still indicates failure at this point then
- * the application will be aborted.
- *
- * The result parameter for the @mapping function is pointed to a
- * #gpointer which is initially set to %NULL. The same pointer is given
- * to each invocation of @mapping. The final value of that #gpointer is
- * what is returned by this function. %NULL is valid; it is returned
- * just as any other value would be.
+ * g_simple_async_result_set_op_res_gboolean:
+ * @simple: a #GSimpleAsyncResult.
+ * @op_res: a #gboolean.
*
- * Returns: (transfer full): the result, which may be %NULL
+ * Sets the operation result to a boolean within the asynchronous result.
*/
/**
- * g_settings_get_range:
- * @settings: a #GSettings
- * @key: the key to query the range of
- *
- * 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.
+ * g_simple_async_result_set_op_res_gpointer: (skip)
+ * @simple: a #GSimpleAsyncResult.
+ * @op_res: a pointer result from an asynchronous function.
+ * @destroy_op_res: a #GDestroyNotify function.
*
- * Returns: a #GVariant describing the range
- * Since: 2.28
+ * Sets the operation result within the asynchronous result to a pointer.
*/
/**
- * g_settings_get_string:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * Gets the value that is stored at @key in @settings.
- *
- * A convenience variant of g_settings_get() for strings.
- *
- * It is a programmer error to give a @key that isn't specified as
- * having a string type in the schema for @settings.
+ * g_simple_async_result_set_op_res_gssize:
+ * @simple: a #GSimpleAsyncResult.
+ * @op_res: a #gssize.
*
- * Returns: a newly-allocated string
- * Since: 2.26
+ * Sets the operation result within the asynchronous result to
+ * the given @op_res.
*/
/**
- * g_settings_get_strv:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * A convenience variant of g_settings_get() for string arrays.
- *
- * 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.
+ * g_simple_async_result_take_error: (skip)
+ * @simple: a #GSimpleAsyncResult
+ * @error: a #GError
*
- * newly-allocated, %NULL-terminated array of strings, the value that
- * is stored at @key in @settings.
+ * Sets the result from @error, and takes over the caller's ownership
+ * of @error, so the caller does not need to free it any more.
*
- * Returns: (array zero-terminated=1) (transfer full): a
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * g_settings_get_uint:
- * @settings: a #GSettings object
- * @key: the key to get the value for
- *
- * Gets the value that is stored at @key in @settings.
- *
- * A convenience variant of g_settings_get() for 32-bit unsigned
- * integers.
+ * g_simple_io_stream_new:
+ * @input_stream: a #GInputStream.
+ * @output_stream: a #GOutputStream.
*
- * It is a programmer error to give a @key that isn't specified as
- * having a uint32 type in the schema for @settings.
+ * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
+ * See also #GIOStream.
*
- * Returns: an unsigned integer
- * Since: 2.30
+ * Returns: a new #GSimpleIOStream instance.
+ * Since: 2.44
*/
/**
- * g_settings_get_value:
- * @settings: a #GSettings object
- * @key: the key to get the value for
+ * g_simple_permission_new:
+ * @allowed: %TRUE if the action is allowed
*
- * Gets the value that is stored in @settings for @key.
+ * Creates a new #GPermission instance that represents an action that is
+ * either always or never allowed.
+ *
+ * Returns: the #GSimplePermission, as a #GPermission
+ * Since: 2.26
+ */
+
+
+/**
+ * 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.
*
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings.
+ * Creates a new #GSimpleProxyResolver. See
+ * #GSimpleProxyResolver:default-proxy and
+ * #GSimpleProxyResolver:ignore-hosts for more details on how the
+ * arguments are interpreted.
*
- * Returns: a new #GVariant
- * Since: 2.26
+ * Returns: (transfer full): a new #GSimpleProxyResolver
+ * Since: 2.36
*/
/**
- * g_settings_is_writable:
- * @settings: a #GSettings object
- * @name: the name of a key
+ * g_simple_proxy_resolver_set_default_proxy:
+ * @resolver: a #GSimpleProxyResolver
+ * @default_proxy: the default proxy to use
*
- * Finds out if a key can be written or not
+ * 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().
*
- * Returns: %TRUE if the key @name is writable
- * Since: 2.26
+ * 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_settings_list_children:
- * @settings: a #GSettings object
+ * 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
*
- * Gets the list of children on @settings.
+ * Sets the list of ignored hosts.
*
- * The list is exactly the list of strings for which it is not an error
- * to call g_settings_get_child().
+ * See #GSimpleProxyResolver:ignore-hosts for more details on how the
+ * @ignore_hosts argument is interpreted.
*
- * For GSettings objects that are lists, this value can change at any
- * time and you should connect to the "children-changed" signal to watch
- * for those changes. Note that there is a race condition here: you may
- * request a child after listing it only for it to have been destroyed
- * in the meantime. For this reason, g_settings_get_child() may return
- * %NULL even for a child that was listed by this function.
+ * 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
*
- * For GSettings objects that are not lists, you should probably not be
- * calling this function from "normal" code (since you should already
- * know what children are in your schema). This function may still be
- * useful there for introspection reasons, however.
+ * 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.
*
- * You should free the return value with g_strfreev() when you are done
- * with it.
+ * 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.
*
- * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Since: 2.36
*/
/**
- * g_settings_list_keys:
- * @settings: a #GSettings object
+ * g_socket_accept:
+ * @socket: a #GSocket.
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Introspects the list of keys on @settings.
+ * Accept incoming connections on a connection-based socket. This removes
+ * the first outstanding connection request from the listening socket and
+ * creates a #GSocket object for it.
*
- * You should probably not be calling this function from "normal" code
- * (since you should already know what keys are in your schema). This
- * function is intended for introspection reasons.
+ * The @socket must be bound to a local address with g_socket_bind() and
+ * must be listening for incoming connections (g_socket_listen()).
*
- * You should free the return value with g_strfreev() when you are done
- * with it.
+ * If there are no outstanding connections then the operation will block
+ * 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) (element-type utf8): a list of the keys on @settings
+ * Returns: (transfer full): a new #GSocket, or %NULL on error.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
*/
/**
- * g_settings_list_relocatable_schemas:
+ * g_socket_address_enumerator_next:
+ * @enumerator: a #GSocketAddressEnumerator
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError.
*
- * 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.
+ * Retrieves the next #GSocketAddress from @enumerator. Note that this
+ * may block for some amount of time. (Eg, a #GNetworkAddress may need
+ * to do a DNS lookup before it can return an address.) Use
+ * g_socket_address_enumerator_next_async() if you need to avoid
+ * blocking.
*
- * The output of this function, taken together with the output of
- * g_settings_list_schemas() represents the complete list of all
- * installed schemas.
+ * If @enumerator is expected to yield addresses, but for some reason
+ * is unable to (eg, because of a DNS error), then the first call to
+ * g_socket_address_enumerator_next() will return an appropriate error
+ * in *@error. However, if the first call to
+ * g_socket_address_enumerator_next() succeeds, then any further
+ * internal errors (other than @cancellable being triggered) will be
+ * ignored.
*
- * #GSettings schemas that are available. The list must not be
- * modified or freed.
+ * 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
+ * @user_data: (closure): the data to pass to callback function
*
- * Returns: (element-type utf8) (transfer none): a list of relocatable
- * Since: 2.28
+ * Asynchronously retrieves the next #GSocketAddress from @enumerator
+ * and then calls @callback, which must call
+ * g_socket_address_enumerator_next_finish() to get the result.
*/
/**
- * g_settings_list_schemas:
+ * g_socket_address_enumerator_next_finish:
+ * @enumerator: a #GSocketAddressEnumerator
+ * @result: a #GAsyncResult
+ * @error: a #GError
*
- * 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.
+ * Retrieves the result of a completed call to
+ * g_socket_address_enumerator_next_async(). See
+ * g_socket_address_enumerator_next() for more information about
+ * error handling.
*
- * 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: (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_get_family:
+ * @address: a #GSocketAddress
*
- * schemas that are available. The list must not be modified or
- * freed.
+ * Gets the socket family type of @address.
*
- * Returns: (element-type utf8) (transfer none): a list of #GSettings
- * Since: 2.26
+ * Returns: the socket family type of @address
+ * Since: 2.22
*/
/**
- * g_settings_new:
- * @schema_id: the id of the schema
+ * g_socket_address_get_native_size:
+ * @address: a #GSocketAddress
*
- * Creates a new #GSettings object with the schema specified by
- * @schema_id.
+ * Gets the size of @address's native struct sockaddr.
+ * You can use this to allocate memory to pass to
+ * g_socket_address_to_native().
*
- * Signals on the newly created #GSettings object will be dispatched
- * via the thread-default #GMainContext in effect at the time of the
- * call to g_settings_new(). The new #GSettings will hold a reference
- * on the context. See g_main_context_push_thread_default().
+ * 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 struct sockaddr
+ * @len: the size of the memory location pointed to by @native
*
- * Returns: a new #GSettings object
- * Since: 2.26
+ * Creates a #GSocketAddress subclass corresponding to the native
+ * struct sockaddr @native.
+ *
+ * Returns: a new #GSocketAddress if @native could successfully
+ * be converted, otherwise %NULL
+ * Since: 2.22
*/
/**
- * g_settings_new_full:
- * @schema: a #GSettingsSchema
- * @backend: (allow-none): a #GSettingsBackend
- * @path: (allow-none): the path to use
+ * g_socket_address_to_native:
+ * @address: a #GSocketAddress
+ * @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
*
- * Creates a new #GSettings object with a given schema, backend and
- * path.
+ * Converts a #GSocketAddress to a native struct sockaddr, which can
+ * be passed to low-level functions like connect() or bind().
*
- * It should be extremely rare that you ever want to use this function.
- * It is made available for advanced use-cases (such as plugin systems
- * that want to provide access to schemas loaded from custom locations,
- * etc).
+ * 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.
*
- * At the most basic level, a #GSettings object is a pure composition of
- * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
- * backend, and a #GMainContext to which signals are dispatched.
+ * Returns: %TRUE if @dest was filled in, %FALSE on error
+ * Since: 2.22
+ */
+
+
+/**
+ * g_socket_bind:
+ * @socket: a #GSocket.
+ * @address: a #GSocketAddress specifying the local address.
+ * @allow_reuse: whether to allow reusing this address
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * This constructor therefore gives you full control over constructing
- * #GSettings instances. The first 4 parameters are given directly as
- * @schema, @backend and @path, and the main context is taken from the
- * thread-default (as per g_settings_new()).
+ * When a socket is created it is attached to an address family, but it
+ * doesn't have an address in this family. g_socket_bind() assigns the
+ * address (sometimes called name) of the socket.
*
- * If @backend is %NULL then the default backend is used.
+ * It is generally required to bind to a local address before you can
+ * receive connections. (See g_socket_listen() and g_socket_accept() ).
+ * In certain situations, you may also want to bind a socket that will be
+ * used to initiate connections, though this is not normally required.
*
- * 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
- * @path is non-%NULL and not equal to the path that the schema does
- * have.
+ * 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: a new #GSettings object
- * Since: 2.32
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.22
*/
/**
- * g_settings_new_with_backend:
- * @schema_id: the id of the schema
- * @backend: the #GSettingsBackend to use
- *
- * Creates a new #GSettings object with the schema specified by
- * @schema_id and a given #GSettingsBackend.
+ * g_socket_check_connect_result:
+ * @socket: a #GSocket
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Creating a #GSettings object with a different backend allows accessing
- * settings from a database other than the usual one. For example, it may make
- * sense to pass a backend corresponding to the "defaults" settings database on
- * the system to get a settings object that modifies the system default
- * settings instead of the settings for this user.
+ * Checks and resets the pending connect error for the socket.
+ * This is used to check for errors when g_socket_connect() is
+ * used in non-blocking mode.
*
- * Returns: a new #GSettings object
- * Since: 2.26
+ * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
+ * Since: 2.22
*/
/**
- * g_settings_new_with_backend_and_path:
- * @schema_id: the id of the schema
- * @backend: the #GSettingsBackend to use
- * @path: the path to use
+ * g_socket_client_add_application_proxy:
+ * @client: a #GSocketClient
+ * @protocol: The proxy protocol
*
- * Creates a new #GSettings object with the schema specified by
- * @schema_id and a given #GSettingsBackend and path.
+ * Enable proxy protocols to be handled by the application. When the
+ * indicated proxy protocol is returned by the #GProxyResolver,
+ * #GSocketClient will consider this protocol as supported but will
+ * not try to find a #GProxy instance to handle handshaking. The
+ * application must check for this case by calling
+ * g_socket_connection_get_remote_address() on the returned
+ * #GSocketConnection, and seeing if it's a #GProxyAddress of the
+ * appropriate type, to determine whether or not it needs to handle
+ * the proxy handshaking itself.
*
- * This is a mix of g_settings_new_with_backend() and
- * g_settings_new_with_path().
+ * This should be used for proxy protocols that are dialects of
+ * another protocol such as HTTP proxy. It also allows cohabitation of
+ * proxy protocols that are reused between protocols. A good example
+ * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
+ * be use as generic socket proxy through the HTTP CONNECT method.
*
- * Returns: a new #GSettings object
- * Since: 2.26
+ * When the proxy is detected as being an application proxy, TLS handshake
+ * will be skipped. This is required to let the application do the proxy
+ * specific handshake.
*/
/**
- * g_settings_new_with_path:
- * @schema_id: the id of the schema
- * @path: the path to use
+ * g_socket_client_connect:
+ * @client: a #GSocketClient.
+ * @connectable: a #GSocketConnectable specifying the remote address.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a new #GSettings object with the relocatable schema specified
- * by @schema_id and a given path.
+ * Tries to resolve the @connectable and make a network connection to it.
*
- * You only need to do this if you want to directly create a settings
- * object with a schema that doesn't have a specified path of its own.
- * That's quite rare.
+ * Upon a successful connection, a new #GSocketConnection is constructed
+ * and returned. The caller owns this new object and must drop their
+ * reference to it when finished with it.
+ *
+ * The type of the #GSocketConnection object returned depends on the type of
+ * the underlying socket that is used. For instance, for a TCP/IP connection
+ * it will be a #GTcpConnection.
+ *
+ * The socket created will be the same family as the address that the
+ * @connectable resolves to, unless family is set with g_socket_client_set_family()
+ * or indirectly via g_socket_client_set_local_address(). The socket type
+ * defaults to %G_SOCKET_TYPE_STREAM but can be set with
+ * g_socket_client_set_socket_type().
*
- * It is a programmer error to call this function for a schema that
- * has an explicitly specified path.
+ * If a local address is specified with g_socket_client_set_local_address() the
+ * socket will be bound to this address before connecting.
*
- * Returns: a new #GSettings object
- * Since: 2.26
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.22
*/
/**
- * g_settings_range_check:
- * @settings: a #GSettings
- * @key: the key to check
- * @value: the value to check
- *
- * Checks if the given @value is of the correct type and within the
- * permitted range for @key.
+ * g_socket_client_connect_async:
+ * @client: a #GSocketClient
+ * @connectable: a #GSocketConnectable specifying the remote address.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
*
- * 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.
+ * This is the asynchronous version of g_socket_client_connect().
*
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings.
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_client_connect_finish() to get
+ * the result of the operation.
*
- * Returns: %TRUE if @value is valid for @key
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * g_settings_reset:
- * @settings: a #GSettings object
- * @key: the name of a key
+ * g_socket_client_connect_finish:
+ * @client: a #GSocketClient.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL to
+ * ignore.
*
- * Resets @key to its default value.
+ * Finishes an async connect operation. See g_socket_client_connect_async()
*
- * This call resets the key, as much as possible, to its default value.
- * That might the value specified in the schema or the one set by the
- * administrator.
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.22
*/
/**
- * g_settings_revert:
- * @settings: a #GSettings instance
+ * g_socket_client_connect_to_host:
+ * @client: a #GSocketClient
+ * @host_and_port: the name and optionally port of the host to connect to
+ * @default_port: the default port to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a pointer to a #GError, or %NULL
*
- * Reverts all non-applied changes to the settings. This function
- * does nothing unless @settings is in 'delay-apply' mode; see
- * g_settings_delay(). In the normal case settings are always applied
- * immediately.
+ * This is a helper function for g_socket_client_connect().
*
- * Change notifications will be emitted for affected keys.
- */
-
-
-/**
- * g_settings_schema_get_id:
- * @schema: a #GSettingsSchema
+ * Attempts to create a TCP connection to the named host.
*
- * Get the ID of @schema.
+ * @host_and_port may be in any of a number of recognized formats; an IPv6
+ * address, an IPv4 address, or a domain name (in which case a DNS
+ * lookup is performed). Quoting with [] is supported for all address
+ * types. A port override may be specified in the usual way with a
+ * colon. Ports may be given as decimal numbers or symbolic names (in
+ * which case an /etc/services lookup is performed).
*
- * Returns: (transfer none): the ID
+ * If no port override is given in @host_and_port then @default_port will be
+ * used as the port number to connect to.
+ *
+ * In general, @host_and_port is expected to be provided by the user (allowing
+ * them to give the hostname, and a port override if necessary) and
+ * @default_port is expected to be provided by the application.
+ *
+ * In the case that an IP address is given, a single connection
+ * attempt is made. In the case that a name is given, multiple
+ * connection attempts may be made, in turn and according to the
+ * number of address records in DNS, until a connection succeeds.
+ *
+ * Upon a successful connection, a new #GSocketConnection is constructed
+ * and returned. The caller owns this new object and must drop their
+ * reference to it when finished with it.
+ *
+ * In the event of any failure (DNS error, service not found, no hosts
+ * connectable) %NULL is returned and @error (if non-%NULL) is set
+ * accordingly.
+ *
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.22
*/
/**
- * g_settings_schema_get_path:
- * @schema: a #GSettingsSchema
- *
- * Gets the path associated with @schema, or %NULL.
+ * g_socket_client_connect_to_host_async:
+ * @client: a #GSocketClient
+ * @host_and_port: the name and optionally the port of the host to connect to
+ * @default_port: the default port to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
*
- * Schemas may be single-instance or relocatable. Single-instance
- * schemas correspond to exactly one set of keys in the backend
- * database: those located at the path returned by this function.
+ * This is the asynchronous version of g_socket_client_connect_to_host().
*
- * Relocatable schemas can be referenced by other schemas and can
- * threfore describe multiple sets of keys at different locations. For
- * relocatable schemas, this function will return %NULL.
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_client_connect_to_host_finish() to get
+ * the result of the operation.
*
- * Returns: (transfer none): the path of the schema, or %NULL
- * Since: 2.32
+ * Since: 2.22
*/
/**
- * g_settings_schema_ref:
- * @schema: a #GSettingsSchema
+ * 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.
*
- * Increase the reference count of @schema, returning a new reference.
+ * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
*
- * Returns: a new reference to @schema
- * Since: 2.32
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.22
*/
/**
- * g_settings_schema_source_get_default:
+ * g_socket_client_connect_to_service:
+ * @client: a #GSocketConnection
+ * @domain: a domain name
+ * @service: the name of the service to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a pointer to a #GError, or %NULL
*
- * Gets the default system schema source.
+ * Attempts to create a TCP connection to a service.
*
- * This function is not required for normal uses of #GSettings but it
- * may be useful to authors of plugin management systems or to those who
- * want to introspect the content of schemas.
+ * This call looks up the SRV record for @service at @domain for the
+ * "tcp" protocol. It then attempts to connect, in turn, to each of
+ * the hosts providing the service until either a connection succeeds
+ * or there are no hosts remaining.
*
- * If no schemas are installed, %NULL will be returned.
+ * Upon a successful connection, a new #GSocketConnection is constructed
+ * and returned. The caller owns this new object and must drop their
+ * reference to it when finished with it.
*
- * 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
- * recursively.
+ * In the event of any failure (DNS error, service not found, no hosts
+ * connectable) %NULL is returned and @error (if non-%NULL) is set
+ * accordingly.
*
- * Returns: (transfer none): the default schema source
- * Since: 2.32
+ * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
*/
/**
- * g_settings_schema_source_lookup:
- * @source: a #GSettingsSchemaSource
- * @schema_id: a schema ID
- * @recursive: %TRUE if the lookup should be recursive
- *
- * Looks up a schema with the identifier @schema_id in @source.
- *
- * This function is not required for normal uses of #GSettings but it
- * may be useful to authors of plugin management systems or to those who
- * want to introspect the content of schemas.
- *
- * If the schema isn't found directly in @source and @recursive is %TRUE
- * then the parent sources will also be checked.
+ * g_socket_client_connect_to_service_async:
+ * @client: a #GSocketClient
+ * @domain: a domain name
+ * @service: the name of the service to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
*
- * If the schema isn't found, %NULL is returned.
+ * This is the asynchronous version of
+ * g_socket_client_connect_to_service().
*
- * Returns: (transfer full): a new #GSettingsSchema
- * Since: 2.32
+ * Since: 2.22
*/
/**
- * g_settings_schema_source_new_from_directory:
- * @directory: the filename of a directory
- * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
- * @trusted: %TRUE, if the directory is trusted
- * @error: a pointer to a #GError pointer set to %NULL, or %NULL
+ * 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.
*
- * Attempts to create a new schema source corresponding to the contents
- * of the given directory.
+ * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
*
- * This function is not required for normal uses of #GSettings but it
- * may be useful to authors of plugin management systems.
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_socket_client_connect_to_uri:
+ * @client: a #GSocketClient
+ * @uri: A network URI
+ * @default_port: the default port to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a pointer to a #GError, or %NULL
*
- * The directory should contain a file called
- * <filename>gschemas.compiled</filename> as produced by
- * <command>glib-compile-schemas</command>.
+ * This is a helper function for g_socket_client_connect().
*
- * 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.
+ * Attempts to create a TCP connection with a network URI.
*
- * If @parent is non-%NULL then there are two effects.
+ * @uri may be any valid URI containing an "authority" (hostname/port)
+ * component. If a port is not specified in the URI, @default_port
+ * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
+ * (#GSocketClient does not know to automatically assume TLS for
+ * certain URI schemes.)
*
- * First, if g_settings_schema_source_lookup() is called with the
- * @recursive flag set to %TRUE and the schema can not be found in the
- * source, the lookup will recurse to the parent.
+ * Using this rather than g_socket_client_connect() or
+ * g_socket_client_connect_to_host() allows #GSocketClient to
+ * determine when to use application-specific proxy protocols.
*
- * 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.
+ * Upon a successful connection, a new #GSocketConnection is constructed
+ * and returned. The caller owns this new object and must drop their
+ * reference to it when finished with it.
*
- * For this second reason, except in very unusual situations, the
- * @parent should probably be given as the default schema source, as
- * returned by g_settings_schema_source_get_default().
+ * In the event of any failure (DNS error, service not found, no hosts
+ * connectable) %NULL is returned and @error (if non-%NULL) is set
+ * accordingly.
*
- * Since: 2.32
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.26
*/
/**
- * g_settings_schema_source_ref:
- * @source: a #GSettingsSchemaSource
+ * g_socket_client_connect_to_uri_async:
+ * @client: a #GSocketClient
+ * @uri: a network uri
+ * @default_port: the default port to connect to
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
*
- * Increase the reference count of @source, returning a new reference.
+ * This is the asynchronous version of g_socket_client_connect_to_uri().
*
- * Returns: a new reference to @source
- * Since: 2.32
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_client_connect_to_uri_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.26
*/
/**
- * g_settings_schema_source_unref:
- * @source: a #GSettingsSchemaSource
+ * 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.
*
- * Decrease the reference count of @source, possibly freeing it.
+ * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
*
- * Since: 2.32
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.26
*/
/**
- * g_settings_schema_unref:
- * @schema: a #GSettingsSchema
+ * g_socket_client_get_enable_proxy:
+ * @client: a #GSocketClient.
*
- * Decrease the reference count of @schema, possibly freeing it.
+ * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
*
- * Since: 2.32
+ * Returns: whether proxying is enabled
+ * Since: 2.26
*/
/**
- * g_settings_set:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @format: a #GVariant format string
- * @...: arguments as per @format
- *
- * Sets @key in @settings to @value.
- *
- * A convenience function that combines g_settings_set_value() with
- * g_variant_new().
+ * g_socket_client_get_family:
+ * @client: a #GSocketClient.
*
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or for the #GVariantType of @format to mismatch
- * the type given in the schema.
+ * Gets the socket family of the socket client.
*
- * %FALSE if the key was not writable
+ * See g_socket_client_set_family() for details.
*
- * Returns: %TRUE if setting the key succeeded,
- * Since: 2.26
+ * Returns: a #GSocketFamily
+ * Since: 2.22
*/
/**
- * g_settings_set_boolean:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: the value to set it to
- *
- * Sets @key in @settings to @value.
- *
- * A convenience variant of g_settings_set() for booleans.
+ * g_socket_client_get_local_address:
+ * @client: a #GSocketClient.
*
- * It is a programmer error to give a @key that isn't specified as
- * having a boolean type in the schema for @settings.
+ * Gets the local address of the socket client.
*
- * %FALSE if the key was not writable
+ * See g_socket_client_set_local_address() for details.
*
- * Returns: %TRUE if setting the key succeeded,
- * Since: 2.26
+ * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
+ * Since: 2.22
*/
/**
- * g_settings_set_double:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: the value to set it to
- *
- * Sets @key in @settings to @value.
- *
- * A convenience variant of g_settings_set() for doubles.
+ * g_socket_client_get_protocol:
+ * @client: a #GSocketClient
*
- * It is a programmer error to give a @key that isn't specified as
- * having a 'double' type in the schema for @settings.
+ * Gets the protocol name type of the socket client.
*
- * %FALSE if the key was not writable
+ * See g_socket_client_set_protocol() for details.
*
- * Returns: %TRUE if setting the key succeeded,
- * Since: 2.26
+ * Returns: a #GSocketProtocol
+ * Since: 2.22
*/
/**
- * g_settings_set_enum:
- * @settings: a #GSettings object
- * @key: a key, within @settings
- * @value: an enumerated value
- *
- * Looks up the enumerated type nick for @value and writes it to @key,
- * within @settings.
- *
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or is not marked as an enumerated type, or for
- * @value not to be a valid value for the named type.
+ * g_socket_client_get_proxy_resolver:
+ * @client: a #GSocketClient.
*
- * After performing the write, accessing @key directly with
- * g_settings_get_string() will return the 'nick' associated with
- * @value.
+ * 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: %TRUE, if the set succeeds
+ * Returns: (transfer none): The #GProxyResolver being used by
+ * @client.
+ * Since: 2.36
*/
/**
- * g_settings_set_flags:
- * @settings: a #GSettings object
- * @key: a key, within @settings
- * @value: a flags value
- *
- * Looks up the flags type nicks for the bits specified by @value, puts
- * them in an array of strings and writes the array to @key, within
- * @settings.
+ * g_socket_client_get_socket_type:
+ * @client: a #GSocketClient.
*
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or is not marked as a flags type, or for @value
- * to contain any bits that are not value for the named type.
+ * Gets the socket type of the socket client.
*
- * After performing the write, accessing @key directly with
- * g_settings_get_strv() will return an array of 'nicks'; one for each
- * bit in @value.
+ * See g_socket_client_set_socket_type() for details.
*
- * Returns: %TRUE, if the set succeeds
+ * Returns: a #GSocketFamily
+ * Since: 2.22
*/
/**
- * g_settings_set_int:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: the value to set it to
- *
- * Sets @key in @settings to @value.
- *
- * A convenience variant of g_settings_set() for 32-bit integers.
+ * g_socket_client_get_timeout:
+ * @client: a #GSocketClient
*
- * It is a programmer error to give a @key that isn't specified as
- * having a int32 type in the schema for @settings.
+ * Gets the I/O timeout time for sockets created by @client.
*
- * %FALSE if the key was not writable
+ * See g_socket_client_set_timeout() for details.
*
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: the timeout in seconds
* Since: 2.26
*/
/**
- * g_settings_set_string:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: the value to set it to
- *
- * Sets @key in @settings to @value.
+ * g_socket_client_get_tls:
+ * @client: a #GSocketClient.
*
- * A convenience variant of g_settings_set() for strings.
+ * Gets whether @client creates TLS connections. See
+ * g_socket_client_set_tls() for details.
*
- * It is a programmer error to give a @key that isn't specified as
- * having a string type in the schema for @settings.
+ * Returns: whether @client uses TLS
+ * Since: 2.28
+ */
+
+
+/**
+ * g_socket_client_get_tls_validation_flags:
+ * @client: a #GSocketClient.
*
- * %FALSE if the key was not writable
+ * Gets the TLS validation flags used creating TLS connections via
+ * @client.
*
- * Returns: %TRUE if setting the key succeeded,
- * Since: 2.26
+ * Returns: the TLS validation flags
+ * Since: 2.28
*/
/**
- * g_settings_set_strv:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
+ * g_socket_client_new:
*
- * Sets @key in @settings to @value.
+ * Creates a new #GSocketClient with the default options.
*
- * A convenience variant of g_settings_set() for string arrays. If
- * @value is %NULL, then @key is set to be the empty array.
+ * Returns: a #GSocketClient.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
+ */
+
+
+/**
+ * g_socket_client_set_enable_proxy:
+ * @client: a #GSocketClient.
+ * @enable: whether to enable proxies
*
- * 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.
+ * Sets whether or not @client attempts to make connections via a
+ * proxy server. When enabled (the default), #GSocketClient will use a
+ * #GProxyResolver to determine if a proxy protocol such as SOCKS is
+ * needed, and automatically do the necessary proxy negotiation.
*
- * %FALSE if the key was not writable
+ * See also g_socket_client_set_proxy_resolver().
*
- * Returns: %TRUE if setting the key succeeded,
* Since: 2.26
*/
/**
- * g_settings_set_uint:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: the value to set it to
- *
- * Sets @key in @settings to @value.
- *
- * A convenience variant of g_settings_set() for 32-bit unsigned
- * integers.
+ * g_socket_client_set_family:
+ * @client: a #GSocketClient.
+ * @family: a #GSocketFamily
*
- * It is a programmer error to give a @key that isn't specified as
- * having a uint32 type in the schema for @settings.
+ * Sets the socket family of the socket client.
+ * If this is set to something other than %G_SOCKET_FAMILY_INVALID
+ * then the sockets created by this object will be of the specified
+ * family.
*
- * %FALSE if the key was not writable
+ * This might be useful for instance if you want to force the local
+ * connection to be an ipv4 socket, even though the address might
+ * be an ipv6 mapped to ipv4 address.
*
- * Returns: %TRUE if setting the key succeeded,
- * Since: 2.30
+ * Since: 2.22
*/
/**
- * g_settings_set_value:
- * @settings: a #GSettings object
- * @key: the name of the key to set
- * @value: a #GVariant of the correct type
- *
- * Sets @key in @settings to @value.
- *
- * It is a programmer error to give a @key that isn't contained in the
- * schema for @settings or for @value to have the incorrect type, per
- * the schema.
+ * g_socket_client_set_local_address:
+ * @client: a #GSocketClient.
+ * @address: (allow-none): a #GSocketAddress, or %NULL
*
- * If @value is floating then this function consumes the reference.
+ * Sets the local address of the socket client.
+ * The sockets created by this object will bound to the
+ * specified address (if not %NULL) before connecting.
*
- * %FALSE if the key was not writable
+ * This is useful if you want to ensure that the local
+ * side of the connection is on a specific port, or on
+ * a specific interface.
*
- * Returns: %TRUE if setting the key succeeded,
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * g_settings_sync:
+ * g_socket_client_set_protocol:
+ * @client: a #GSocketClient.
+ * @protocol: a #GSocketProtocol
*
- * Ensures that all pending operations for the given are complete for
- * the default backend.
+ * Sets the protocol of the socket client.
+ * The sockets created by this object will use of the specified
+ * protocol.
*
- * Writes made to a #GSettings are handled asynchronously. For this
- * reason, it is very unlikely that the changes have it to disk by the
- * time g_settings_set() returns.
+ * If @protocol is %0 that means to use the default
+ * protocol for the socket family and type.
*
- * This call will block until all of the writes have made it to the
- * backend. Since the mainloop is not running, no change notifications
- * will be dispatched during this call (but some may be queued by the
- * time the call is done).
+ * Since: 2.22
*/
/**
- * g_settings_unbind:
- * @object: the object
- * @property: the property whose binding is removed
+ * g_socket_client_set_proxy_resolver:
+ * @client: a #GSocketClient.
+ * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the
+ * default.
*
- * Removes an existing binding for @property on @object.
+ * 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 bindings are automatically removed when the
- * object is finalized, so it is rarely necessary to call this
- * function.
+ * 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.26
+ * Since: 2.36
*/
/**
- * g_signal_connect:
- * @instance: the instance to connect to.
- * @detailed_signal: a string of the form "signal-name::detail".
- * @c_handler: the #GCallback to connect.
- * @data: data to pass to @c_handler calls.
+ * g_socket_client_set_socket_type:
+ * @client: a #GSocketClient.
+ * @type: a #GSocketType
*
- * Connects a #GCallback function to a signal for a particular object.
+ * Sets the socket type of the socket client.
+ * The sockets created by this object will be of the specified
+ * type.
*
- * The handler will be called before the default handler of the signal.
+ * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
+ * as GSocketClient is used for connection oriented services.
*
- * Returns: the handler id
+ * Since: 2.22
*/
/**
- * g_signal_connect_after:
- * @instance: the instance to connect to.
- * @detailed_signal: a string of the form "signal-name::detail".
- * @c_handler: the #GCallback to connect.
- * @data: data to pass to @c_handler calls.
+ * g_socket_client_set_timeout:
+ * @client: a #GSocketClient.
+ * @timeout: the timeout
*
- * Connects a #GCallback function to a signal for a particular object.
+ * Sets the I/O timeout for sockets created by @client. @timeout is a
+ * time in seconds, or 0 for no timeout (the default).
*
- * The handler will be called after the default handler of the signal.
+ * The timeout value affects the initial connection attempt as well,
+ * so setting this may cause calls to g_socket_client_connect(), etc,
+ * to fail with %G_IO_ERROR_TIMED_OUT.
*
- * Returns: the handler id
+ * Since: 2.26
*/
/**
- * g_signal_connect_swapped:
- * @instance: the instance to connect to.
- * @detailed_signal: a string of the form "signal-name::detail".
- * @c_handler: the #GCallback to connect.
- * @data: data to pass to @c_handler calls.
+ * g_socket_client_set_tls:
+ * @client: a #GSocketClient.
+ * @tls: whether to use TLS
*
- * Connects a #GCallback function to a signal for a particular object.
+ * Sets whether @client creates TLS (aka SSL) connections. If @tls is
+ * %TRUE, @client will wrap its connections in a #GTlsClientConnection
+ * and perform a TLS handshake when connecting.
+ *
+ * Note that since #GSocketClient must return a #GSocketConnection,
+ * but #GTlsClientConnection is not a #GSocketConnection, this
+ * actually wraps the resulting #GTlsClientConnection in a
+ * #GTcpWrapperConnection when returning it. You can use
+ * g_tcp_wrapper_connection_get_base_io_stream() on the return value
+ * to extract the #GTlsClientConnection.
*
- * The instance on which the signal is emitted and @data will be swapped when
- * calling the handler.
+ * If you need to modify the behavior of the TLS handshake (eg, by
+ * setting a client-side certificate to use, or connecting to the
+ * #GTlsConnection::accept-certificate signal), you can connect to
+ * @client's #GSocketClient::event signal and wait for it to be
+ * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
+ * a chance to see the #GTlsClientConnection before the handshake
+ * starts.
*
- * Returns: the handler id
+ * Since: 2.28
*/
/**
- * g_signal_handlers_block_by_func:
- * @instance: The instance to block handlers from.
- * @func: The C closure callback of the handlers (useless for non-C closures).
- * @data: The closure data of the handlers' closures.
+ * g_socket_client_set_tls_validation_flags:
+ * @client: a #GSocketClient.
+ * @flags: the validation flags
*
- * Blocks all handlers on an instance that match @func and @data.
+ * Sets the TLS validation flags used when creating TLS connections
+ * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
*
- * Returns: The number of handlers that matched.
+ * Since: 2.28
*/
/**
- * g_signal_handlers_disconnect_by_func:
- * @instance: The instance to remove handlers from.
- * @func: The C closure callback of the handlers (useless for non-C closures).
- * @data: The closure data of the handlers' closures.
+ * g_socket_close:
+ * @socket: a #GSocket
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Closes the socket, shutting down any active connection.
+ *
+ * Closing a socket does not wait for all outstanding I/O operations
+ * to finish, so the caller should not rely on them to be guaranteed
+ * to complete even if the close returns with no error.
+ *
+ * Once the socket is closed, all other operations will return
+ * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
+ * return an error.
+ *
+ * Sockets will be automatically closed when the last reference
+ * is dropped, but you might want to call this function to make sure
+ * resources are released as early as possible.
*
- * Disconnects all handlers on an instance that match @func and @data.
+ * Beware that due to the way that TCP works, it is possible for
+ * recently-sent data to be lost if either you close a socket while the
+ * %G_IO_IN condition is set, or else if the remote connection tries to
+ * send something to you after you close the socket but before it has
+ * finished reading all of the data you sent. There is no easy generic
+ * way to avoid this problem; the easiest fix is to design the network
+ * protocol such that the client will never send data "out of turn".
+ * Another solution is for the server to half-close the connection by
+ * calling g_socket_shutdown() with only the @shutdown_write flag set,
+ * and then wait for the client to notice this and close its side of the
+ * connection, after which the server can safely call g_socket_close().
+ * (This is what #GTcpConnection does if you call
+ * g_tcp_connection_set_graceful_disconnect(). But of course, this
+ * only works if the client will close its connection after the server
+ * does.)
*
- * Returns: The number of handlers that matched.
+ * Returns: %TRUE on success, %FALSE on error
+ * Since: 2.22
*/
/**
- * g_signal_handlers_unblock_by_func:
- * @instance: The instance to unblock handlers from.
- * @func: The C closure callback of the handlers (useless for non-C closures).
- * @data: The closure data of the handlers' closures.
+ * g_socket_condition_check:
+ * @socket: a #GSocket
+ * @condition: a #GIOCondition mask to check
+ *
+ * Checks on the readiness of @socket to perform operations.
+ * The operations specified in @condition are checked for and masked
+ * against the currently-satisfied conditions on @socket. The result
+ * is returned.
+ *
+ * Note that on Windows, it is possible for an operation to return
+ * %G_IO_ERROR_WOULD_BLOCK even immediately after
+ * g_socket_condition_check() has claimed that the socket is ready for
+ * writing. Rather than calling g_socket_condition_check() and then
+ * writing to the socket if it succeeds, it is generally better to
+ * simply try writing to the socket right away, and try again later if
+ * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
+ *
+ * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
+ * these conditions will always be set in the output if they are true.
*
- * Unblocks all handlers on an instance that match @func and @data.
+ * This call never blocks.
*
- * Returns: The number of handlers that matched.
+ * Returns: the @GIOCondition mask of the current state
+ * Since: 2.22
*/
/**
- * g_simple_action_group_add_entries:
- * @simple: a #GSimpleActionGroup
- * @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
+ * g_socket_condition_timed_wait:
+ * @socket: a #GSocket
+ * @condition: a #GIOCondition mask to wait for
+ * @timeout: the maximum time (in microseconds) to wait, or -1
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a #GError pointer, or %NULL
*
- * A convenience function for creating multiple #GSimpleAction instances
- * and adding them to the action group.
+ * Waits for up to @timeout microseconds for @condition to become true
+ * on @socket. If the condition is met, %TRUE is returned.
*
- * Since: 2.30
+ * If @cancellable is cancelled before the condition is met, or if
+ * @timeout (or the socket's #GSocket:timeout) is reached before the
+ * condition is met, then %FALSE is returned and @error, if non-%NULL,
+ * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
+ * %G_IO_ERROR_TIMED_OUT).
+ *
+ * If you don't want a timeout, use g_socket_condition_wait().
+ * (Alternatively, you can pass -1 for @timeout.)
+ *
+ * Note that although @timeout is in microseconds for consistency with
+ * other GLib APIs, this function actually only has millisecond
+ * resolution, and the behavior is undefined if @timeout is not an
+ * exact number of milliseconds.
+ *
+ * Returns: %TRUE if the condition was met, %FALSE otherwise
+ * Since: 2.32
*/
/**
- * g_simple_action_group_insert:
- * @simple: a #GSimpleActionGroup
- * @action: a #GAction
+ * g_socket_condition_wait:
+ * @socket: a #GSocket
+ * @condition: a #GIOCondition mask to wait for
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: a #GError pointer, or %NULL
*
- * Adds an action to the action group.
+ * Waits for @condition to become true on @socket. When the condition
+ * is met, %TRUE is returned.
*
- * If the action group already contains an action with the same name as
- * @action then the old action is dropped from the group.
+ * If @cancellable is cancelled before the condition is met, or if the
+ * socket has a timeout set and it is reached before the condition is
+ * met, then %FALSE is returned and @error, if non-%NULL, is set to
+ * the appropriate value (%G_IO_ERROR_CANCELLED or
+ * %G_IO_ERROR_TIMED_OUT).
*
- * The action group takes its own reference on @action.
+ * See also g_socket_condition_timed_wait().
*
- * Since: 2.28
+ * Returns: %TRUE if the condition was met, %FALSE otherwise
+ * Since: 2.22
*/
/**
- * g_simple_action_group_lookup:
- * @simple: a #GSimpleActionGroup
- * @action_name: the name of an action
+ * g_socket_connect:
+ * @socket: a #GSocket.
+ * @address: a #GSocketAddress specifying the remote address.
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Looks up the action with the name @action_name in the group.
+ * Connect the socket to the specified remote address.
*
- * If no such action exists, returns %NULL.
+ * For connection oriented socket this generally means we attempt to make
+ * a connection to the @address. For a connection-less socket it sets
+ * the default address for g_socket_send() and discards all incoming datagrams
+ * from other sources.
*
- * Returns: (transfer none): a #GAction, or %NULL
- * Since: 2.28
+ * Generally connection oriented sockets can only connect once, but
+ * connection-less sockets can connect multiple times to change the
+ * default address.
+ *
+ * If the connect call needs to do network I/O it will block, unless
+ * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
+ * and the user can be notified of the connection finishing by waiting
+ * for the G_IO_OUT condition. The result of the connection must then be
+ * checked with g_socket_check_connect_result().
+ *
+ * Returns: %TRUE if connected, %FALSE on error.
+ * Since: 2.22
*/
/**
- * g_simple_action_group_new:
+ * g_socket_connectable_enumerate:
+ * @connectable: a #GSocketConnectable
*
- * Creates a new, empty, #GSimpleActionGroup.
+ * Creates a #GSocketAddressEnumerator for @connectable.
*
- * Returns: a new #GSimpleActionGroup
- * Since: 2.28
+ * Returns: (transfer full): a new #GSocketAddressEnumerator.
+ * Since: 2.22
*/
/**
- * g_simple_action_group_remove:
- * @simple: a #GSimpleActionGroup
- * @action_name: the name of the action
+ * g_socket_connectable_proxy_enumerate:
+ * @connectable: a #GSocketConnectable
*
- * Removes the named action from the action group.
+ * Creates a #GSocketAddressEnumerator for @connectable that will
+ * return #GProxyAddresses for addresses that you must connect
+ * to via a proxy.
*
- * If no action of this name is in the group then nothing happens.
+ * If @connectable does not implement
+ * g_socket_connectable_proxy_enumerate(), this will fall back to
+ * calling g_socket_connectable_enumerate().
*
- * Since: 2.28
+ * Returns: (transfer full): a new #GSocketAddressEnumerator.
+ * Since: 2.26
*/
/**
- * g_simple_action_new:
- * @name: the name of the action
- * @parameter_type: (allow-none): the type of parameter to the activate function
- *
- * Creates a new action.
+ * g_socket_connection_connect:
+ * @connection: a #GSocketConnection
+ * @address: a #GSocketAddress specifying the remote address.
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * The created action is stateless. See g_simple_action_new_stateful().
+ * Connect @connection to the specified remote address.
*
- * Returns: a new #GSimpleAction
- * Since: 2.28
+ * Returns: %TRUE if the connection succeeded, %FALSE on error
+ * Since: 2.32
*/
/**
- * g_simple_action_new_stateful:
- * @name: the name of the action
- * @parameter_type: (allow-none): the type of the parameter to the activate function
- * @state: the initial state of the action
+ * g_socket_connection_connect_async:
+ * @connection: a #GSocketConnection
+ * @address: a #GSocketAddress specifying the remote address.
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
*
- * Creates a new stateful action.
+ * Asynchronously connect @connection to the specified remote address.
*
- * @state is the initial state of the action. All future state values
- * must have the same #GVariantType as the initial state.
+ * This clears the #GSocket:blocking flag on @connection's underlying
+ * socket if it is currently set.
*
- * If the @state GVariant is floating, it is consumed.
+ * Use g_socket_connection_connect_finish() to retrieve the result.
*
- * Returns: a new #GSimpleAction
- * Since: 2.28
+ * Since: 2.32
*/
/**
- * g_simple_action_set_enabled:
- * @simple: a #GSimpleAction
- * @enabled: whether the action is enabled
- *
- * Sets the action as enabled or not.
- *
- * An action must be enabled in order to be activated or in order to
- * have its state changed from outside callers.
+ * g_socket_connection_connect_finish:
+ * @connection: a #GSocketConnection
+ * @result: the #GAsyncResult
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * This should only be called by the implementor of the action. Users
- * of the action should not attempt to modify its enabled flag.
+ * Gets the result of a g_socket_connection_connect_async() call.
*
- * Since: 2.28
+ * Returns: %TRUE if the connection succeeded, %FALSE on error
+ * Since: 2.32
*/
/**
- * g_simple_action_set_state:
- * @simple: a #GSimpleAction
- * @value: the new #GVariant for the state
- *
- * Sets the state of the action.
- *
- * This directly updates the 'state' property to the given value.
+ * g_socket_connection_factory_create_connection:
+ * @socket: a #GSocket
*
- * This should only be called by the implementor of the action. Users
- * of the action should not attempt to directly modify the 'state'
- * property. Instead, they should call g_action_change_state() to
- * request the change.
+ * Creates a #GSocketConnection subclass of the right type for
+ * @socket.
*
- * Since: 2.30
+ * Returns: (transfer full): a #GSocketConnection
+ * Since: 2.22
*/
/**
- * g_simple_async_report_error_in_idle: (skip)
- * @object: (allow-none): a #GObject, or %NULL.
- * @callback: a #GAsyncReadyCallback.
- * @user_data: user data passed to @callback.
- * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
- * @code: a specific error code.
- * @format: a formatted error reporting string.
- * @...: a list of variables to fill in @format.
+ * g_socket_connection_factory_lookup_type:
+ * @family: a #GSocketFamily
+ * @type: a #GSocketType
+ * @protocol_id: a protocol id
+ *
+ * Looks up the #GType to be used when creating socket connections on
+ * sockets with the specified @family, @type and @protocol_id.
*
- * Reports an error in an asynchronous function in an idle function by
- * directly setting the contents of the #GAsyncResult with the given error
- * information.
+ * If no type is registered, the #GSocketConnection base type is returned.
+ *
+ * Returns: a #GType
+ * Since: 2.22
*/
/**
- * g_simple_async_report_gerror_in_idle:
- * @object: (allow-none): a #GObject, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): user data passed to @callback.
- * @error: the #GError to report
+ * g_socket_connection_factory_register_type:
+ * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
+ * @family: a #GSocketFamily
+ * @type: a #GSocketType
+ * @protocol: a protocol id
*
- * Reports an error in an idle function. Similar to
- * g_simple_async_report_error_in_idle(), but takes a #GError rather
- * than building a new one.
+ * Looks up the #GType to be used when creating socket connections on
+ * sockets with the specified @family, @type and @protocol.
+ *
+ * If no type is registered, the #GSocketConnection base type is returned.
+ *
+ * Since: 2.22
*/
/**
- * g_simple_async_report_take_gerror_in_idle: (skip)
- * @object: (allow-none): a #GObject, or %NULL
- * @callback: a #GAsyncReadyCallback.
- * @user_data: user data passed to @callback.
- * @error: the #GError to report
+ * g_socket_connection_get_local_address:
+ * @connection: a #GSocketConnection
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Reports an error in an idle function. Similar to
- * g_simple_async_report_gerror_in_idle(), but takes over the caller's
- * ownership of @error, so the caller does not have to free it any more.
+ * Try to get the local address of a socket connection.
*
- * Since: 2.28
+ * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Free the returned object with g_object_unref().
+ * Since: 2.22
*/
/**
- * g_simple_async_result_complete:
- * @simple: a #GSimpleAsyncResult.
+ * g_socket_connection_get_remote_address:
+ * @connection: a #GSocketConnection
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Completes an asynchronous I/O job immediately. Must be called in
- * the thread where the asynchronous result was to be delivered, as it
- * invokes the callback directly. If you are in a different thread use
- * g_simple_async_result_complete_in_idle().
+ * Try to get the remote address of a socket connection.
*
- * Calling this function takes a reference to @simple for as long as
- * is needed to complete the call.
+ * 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
*/
/**
- * g_simple_async_result_complete_in_idle:
- * @simple: a #GSimpleAsyncResult.
+ * g_socket_connection_get_socket:
+ * @connection: a #GSocketConnection
*
- * 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
- * (and re-pushes that context around the invocation of the callback).
+ * Gets the underlying #GSocket object of the connection.
+ * This can be useful if you want to do something unusual on it
+ * not supported by the #GSocketConnection APIs.
*
- * Calling this function takes a reference to @simple for as long as
- * is needed to complete the call.
+ * Returns: (transfer none): a #GSocketAddress or %NULL on error.
+ * Since: 2.22
*/
/**
- * g_simple_async_result_get_op_res_gboolean:
- * @simple: a #GSimpleAsyncResult.
- *
- * Gets the operation result boolean from within the asynchronous result.
+ * g_socket_connection_is_connected:
+ * @connection: a #GSocketConnection
*
- * if the operation's result was %FALSE.
+ * Checks if @connection is connected. This is equivalent to calling
+ * g_socket_is_connected() on @connection's underlying #GSocket.
*
- * Returns: %TRUE if the operation's result was %TRUE, %FALSE
+ * Returns: whether @connection is connected
+ * Since: 2.32
*/
/**
- * g_simple_async_result_get_op_res_gpointer: (skip)
- * @simple: a #GSimpleAsyncResult.
+ * g_socket_control_message_deserialize:
+ * @level: a socket level
+ * @type: a socket control message type for the given @level
+ * @size: the size of the data in bytes
+ * @data: (array length=size) (element-type guint8): pointer to the message data
*
- * Gets a pointer result as returned by the asynchronous function.
+ * Tries to deserialize a socket control message of a given
+ * @level and @type. This will ask all known (to GType) subclasses
+ * of #GSocketControlMessage if they can understand this kind
+ * of message and if so deserialize it into a #GSocketControlMessage.
*
- * Returns: a pointer from the result.
+ * If there is no implementation for this kind of control message, %NULL
+ * will be returned.
+ *
+ * Returns: (transfer full): the deserialized message or %NULL
+ * Since: 2.22
*/
/**
- * g_simple_async_result_get_op_res_gssize:
- * @simple: a #GSimpleAsyncResult.
+ * g_socket_control_message_get_level:
+ * @message: a #GSocketControlMessage
*
- * Gets a gssize from the asynchronous result.
+ * Returns the "level" (i.e. the originating protocol) of the control message.
+ * This is often SOL_SOCKET.
*
- * Returns: a gssize returned from the asynchronous function.
+ * Returns: an integer describing the level
+ * Since: 2.22
*/
/**
- * g_simple_async_result_get_source_tag: (skip)
- * @simple: a #GSimpleAsyncResult.
+ * g_socket_control_message_get_msg_type:
+ * @message: a #GSocketControlMessage
*
- * Gets the source tag for the #GSimpleAsyncResult.
+ * Returns the protocol specific type of the control message.
+ * For instance, for UNIX fd passing this would be SCM_RIGHTS.
*
- * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
+ * Returns: an integer describing the type of control message
+ * Since: 2.22
*/
/**
- * 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.
- *
- * Ensures that the data passed to the _finish function of an async
- * operation is consistent. Three checks are performed.
+ * g_socket_control_message_get_size:
+ * @message: a #GSocketControlMessage
*
- * 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).
+ * Returns the space required for the control message, not including
+ * headers or alignment.
*
- * Returns: #TRUE if all checks passed or #FALSE if any failed.
- * Since: 2.20
+ * Returns: The number of bytes required.
+ * Since: 2.22
*/
/**
- * g_simple_async_result_new:
- * @source_object: (allow-none): a #GObject, or %NULL.
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): user data passed to @callback.
- * @source_tag: the asynchronous function.
+ * g_socket_control_message_serialize:
+ * @message: a #GSocketControlMessage
+ * @data: A buffer to write data to
*
- * Creates a #GSimpleAsyncResult.
+ * Converts the data in the message to bytes placed in the
+ * message.
*
- * Returns: a #GSimpleAsyncResult.
+ * @data is guaranteed to have enough space to fit the size
+ * returned by g_socket_control_message_get_size() on this
+ * object.
+ *
+ * Since: 2.22
*/
/**
- * g_simple_async_result_new_error:
- * @source_object: (allow-none): a #GObject, or %NULL.
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): user data passed to @callback.
- * @domain: a #GQuark.
- * @code: an error code.
- * @format: a string with format characters.
- * @...: a list of values to insert into @format.
+ * g_socket_create_source: (skip)
+ * @socket: a #GSocket
+ * @condition: a #GIOCondition mask to monitor
+ * @cancellable: (allow-none): a %GCancellable or %NULL
*
- * Creates a new #GSimpleAsyncResult with a set error.
+ * 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.
*
- * Returns: a #GSimpleAsyncResult.
+ * The callback on the source is of the #GSocketSourceFunc type.
+ *
+ * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
+ * these conditions will always be reported output if they are true.
+ *
+ * @cancellable if not %NULL can be used to cancel the source, which will
+ * cause the source to trigger, reporting the current condition (which
+ * is likely 0 unless cancellation happened at the same time as a
+ * condition change). You can check for this in the callback using
+ * g_cancellable_is_cancelled().
+ *
+ * If @socket has a timeout set, and it is reached before @condition
+ * occurs, the source will then trigger anyway, reporting %G_IO_IN or
+ * %G_IO_OUT depending on @condition. However, @socket will have been
+ * marked as having had a timeout, and so the next #GSocket I/O method
+ * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
+ *
+ * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
+ * Since: 2.22
*/
/**
- * g_simple_async_result_new_from_error:
- * @source_object: (allow-none): a #GObject, or %NULL.
- * @callback: (scope async): a #GAsyncReadyCallback.
- * @user_data: (closure): user data passed to @callback.
- * @error: a #GError
+ * g_socket_get_available_bytes:
+ * @socket: a #GSocket
*
- * Creates a #GSimpleAsyncResult from an error condition.
+ * Get the amount of data pending in the OS input buffer.
*
- * Returns: a #GSimpleAsyncResult.
+ * 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
*/
/**
- * g_simple_async_result_new_take_error: (skip)
- * @source_object: (allow-none): a #GObject, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): user data passed to @callback
- * @error: a #GError
+ * g_socket_get_blocking:
+ * @socket: a #GSocket.
*
- * Creates a #GSimpleAsyncResult from an error condition, and takes over the
- * caller's ownership of @error, so the caller does not need to free it anymore.
+ * Gets the blocking mode of the socket. For details on blocking I/O,
+ * see g_socket_set_blocking().
*
- * Returns: a #GSimpleAsyncResult
- * Since: 2.28
+ * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_simple_async_result_propagate_error:
- * @simple: a #GSimpleAsyncResult.
- * @dest: (out): a location to propagate the error to.
+ * g_socket_get_broadcast:
+ * @socket: a #GSocket.
*
- * Propagates an error from within the simple asynchronous result to
- * a given destination.
+ * Gets the broadcast setting on @socket; if %TRUE,
+ * it is possible to send packets to broadcast
+ * addresses.
*
- * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
+ * Returns: the broadcast setting on @socket
+ * Since: 2.32
*/
/**
- * g_simple_async_result_run_in_thread: (skip)
- * @simple: a #GSimpleAsyncResult.
- * @func: a #GSimpleAsyncThreadFunc.
- * @io_priority: the io priority of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * g_socket_get_credentials:
+ * @socket: a #GSocket.
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Runs the asynchronous job in a separate thread and then calls
- * g_simple_async_result_complete_in_idle() on @simple to return
- * the result to the appropriate main loop.
+ * Returns the credentials of the foreign process connected to this
+ * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
+ * sockets).
*
- * Calling this function takes a reference to @simple for as long as
- * is needed to run the job and report its completion.
+ * If this operation isn't supported on the OS, the method fails with
+ * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
+ * by reading the %SO_PEERCRED option on the underlying socket.
+ *
+ * Other ways to obtain credentials from a foreign peer includes the
+ * #GUnixCredentialsMessage type and
+ * 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().
+ * Since: 2.26
*/
/**
- * g_simple_async_result_set_error: (skip)
- * @simple: a #GSimpleAsyncResult.
- * @domain: a #GQuark (usually #G_IO_ERROR).
- * @code: an error code.
- * @format: a formatted error reporting string.
- * @...: a list of variables to fill in @format.
+ * g_socket_get_family:
+ * @socket: a #GSocket.
*
- * Sets an error within the asynchronous result without a #GError.
+ * Gets the socket family of the socket.
+ *
+ * Returns: a #GSocketFamily
+ * Since: 2.22
*/
/**
- * g_simple_async_result_set_error_va: (skip)
- * @simple: a #GSimpleAsyncResult.
- * @domain: a #GQuark (usually #G_IO_ERROR).
- * @code: an error code.
- * @format: a formatted error reporting string.
- * @args: va_list of arguments.
+ * g_socket_get_fd:
+ * @socket: a #GSocket.
*
- * Sets an error within the asynchronous result without a #GError.
- * Unless writing a binding, see g_simple_async_result_set_error().
+ * Returns the underlying OS socket object. On unix this
+ * 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.
+ *
+ * Returns: the file descriptor of the socket.
+ * Since: 2.22
*/
/**
- * g_simple_async_result_set_from_error:
- * @simple: a #GSimpleAsyncResult.
- * @error: #GError.
+ * g_socket_get_keepalive:
+ * @socket: a #GSocket.
*
- * Sets the result from a #GError.
+ * Gets the keepalive mode of the socket. For details on this,
+ * see g_socket_set_keepalive().
+ *
+ * Returns: %TRUE if keepalive is active, %FALSE otherwise.
+ * Since: 2.22
*/
/**
- * g_simple_async_result_set_handle_cancellation:
- * @simple: a #GSimpleAsyncResult.
- * @handle_cancellation: a #gboolean.
+ * g_socket_get_listen_backlog:
+ * @socket: a #GSocket.
*
- * Sets whether to handle cancellation within the asynchronous operation.
+ * Gets the listen backlog setting of the socket. For details on this,
+ * see g_socket_set_listen_backlog().
+ *
+ * Returns: the maximum number of pending connections.
+ * Since: 2.22
*/
/**
- * g_simple_async_result_set_op_res_gboolean:
- * @simple: a #GSimpleAsyncResult.
- * @op_res: a #gboolean.
+ * g_socket_get_local_address:
+ * @socket: a #GSocket.
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Sets the operation result to a boolean within the asynchronous result.
+ * Try to get the local address of a bound socket. This is only
+ * 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().
+ * Since: 2.22
*/
/**
- * g_simple_async_result_set_op_res_gpointer: (skip)
- * @simple: a #GSimpleAsyncResult.
- * @op_res: a pointer result from an asynchronous function.
- * @destroy_op_res: a #GDestroyNotify function.
+ * g_socket_get_multicast_loopback:
+ * @socket: a #GSocket.
*
- * Sets the operation result within the asynchronous result to a pointer.
+ * Gets the multicast loopback setting on @socket; if %TRUE (the
+ * default), outgoing multicast packets will be looped back to
+ * multicast listeners on the same host.
+ *
+ * Returns: the multicast loopback setting on @socket
+ * Since: 2.32
*/
/**
- * g_simple_async_result_set_op_res_gssize:
- * @simple: a #GSimpleAsyncResult.
- * @op_res: a #gssize.
+ * g_socket_get_multicast_ttl:
+ * @socket: a #GSocket.
*
- * Sets the operation result within the asynchronous result to
- * the given @op_res.
+ * Gets the multicast time-to-live setting on @socket; see
+ * g_socket_set_multicast_ttl() for more details.
+ *
+ * Returns: the multicast time-to-live setting on @socket
+ * Since: 2.32
*/
/**
- * g_simple_async_result_take_error: (skip)
- * @simple: a #GSimpleAsyncResult
- * @error: a #GError
+ * 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.
*
- * Sets the result from @error, and takes over the caller's ownership
- * of @error, so the caller does not need to free it any more.
+ * 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.)
*
- * Since: 2.28
+ * 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_simple_permission_new:
- * @allowed: %TRUE if the action is allowed
+ * g_socket_get_protocol:
+ * @socket: a #GSocket.
*
- * Creates a new #GPermission instance that represents an action that is
- * either always or never allowed.
+ * Gets the socket protocol id the socket was created with.
+ * In case the protocol is unknown, -1 is returned.
*
- * Returns: the #GSimplePermission, as a #GPermission
- * Since: 2.26
+ * Returns: a protocol id, or -1 if unknown
+ * Since: 2.22
*/
/**
- * g_socket_accept:
+ * g_socket_get_remote_address:
* @socket: a #GSocket.
- * @cancellable: (allow-none): a %GCancellable or %NULL
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Accept incoming connections on a connection-based socket. This removes
- * the first outstanding connection request from the listening socket and
- * creates a #GSocket object for it.
- *
- * The @socket must be bound to a local address with g_socket_bind() and
- * must be listening for incoming connections (g_socket_listen()).
- *
- * If there are no outstanding connections then the operation will block
- * 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.
- *
- * Free the returned object with g_object_unref().
+ * 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 new #GSocket, or %NULL on error.
+ * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Free the returned object with g_object_unref().
* Since: 2.22
*/
/**
- * g_socket_address_enumerator_next:
- * @enumerator: a #GSocketAddressEnumerator
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
- *
- * Retrieves the next #GSocketAddress from @enumerator. Note that this
- * may block for some amount of time. (Eg, a #GNetworkAddress may need
- * to do a DNS lookup before it can return an address.) Use
- * g_socket_address_enumerator_next_async() if you need to avoid
- * blocking.
- *
- * If @enumerator is expected to yield addresses, but for some reason
- * is unable to (eg, because of a DNS error), then the first call to
- * g_socket_address_enumerator_next() will return an appropriate error
- * in *@error. However, if the first call to
- * g_socket_address_enumerator_next() succeeds, then any further
- * internal errors (other than @cancellable being triggered) will be
- * ignored.
+ * g_socket_get_socket_type:
+ * @socket: a #GSocket.
*
- * error (in which case *@error will be set) or if there are no
- * more addresses.
+ * Gets the socket type of the socket.
*
- * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
+ * Returns: a #GSocketType
+ * Since: 2.22
*/
/**
- * 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
- * @user_data: (closure): the data to pass to callback function
+ * g_socket_get_timeout:
+ * @socket: a #GSocket.
*
- * Asynchronously retrieves the next #GSocketAddress from @enumerator
- * and then calls @callback, which must call
- * g_socket_address_enumerator_next_finish() to get the result.
+ * Gets the timeout setting of the socket. For details on this, see
+ * g_socket_set_timeout().
+ *
+ * Returns: the timeout in seconds
+ * Since: 2.26
*/
/**
- * g_socket_address_enumerator_next_finish:
- * @enumerator: a #GSocketAddressEnumerator
- * @result: a #GAsyncResult
- * @error: a #GError
- *
- * Retrieves the result of a completed call to
- * g_socket_address_enumerator_next_async(). See
- * g_socket_address_enumerator_next() for more information about
- * error handling.
+ * g_socket_get_ttl:
+ * @socket: a #GSocket.
*
- * error (in which case *@error will be set) or if there are no
- * more addresses.
+ * Gets the unicast time-to-live setting on @socket; see
+ * g_socket_set_ttl() for more details.
*
- * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
+ * Returns: the time-to-live setting on @socket
+ * Since: 2.32
*/
/**
- * g_socket_address_get_family:
- * @address: a #GSocketAddress
+ * g_socket_is_closed:
+ * @socket: a #GSocket
*
- * Gets the socket family type of @address.
+ * Checks whether a socket is closed.
*
- * Returns: the socket family type of @address.
+ * Returns: %TRUE if socket is closed, %FALSE otherwise
* Since: 2.22
*/
/**
- * g_socket_address_get_native_size:
- * @address: a #GSocketAddress
- *
- * Gets the size of @address's native <type>struct sockaddr</type>.
- * You can use this to allocate memory to pass to
- * g_socket_address_to_native().
+ * g_socket_is_connected:
+ * @socket: a #GSocket.
*
- * @address represents
+ * Check whether the socket is connected. This is only useful for
+ * connection-oriented sockets.
*
- * Returns: the size of the native <type>struct sockaddr</type> that
+ * Returns: %TRUE if socket is connected, %FALSE otherwise.
* Since: 2.22
*/
/**
- * g_socket_address_new_from_native:
- * @native: a pointer to a <type>struct sockaddr</type>
- * @len: the size of the memory location pointed to by @native
+ * g_socket_join_multicast_group:
+ * @socket: a #GSocket.
+ * @group: a #GInetAddress specifying the group address to join.
+ * @iface: (allow-none): Name of the interface to use, or %NULL
+ * @source_specific: %TRUE if source-specific multicast should be used
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a #GSocketAddress subclass corresponding to the native
- * <type>struct sockaddr</type> @native.
+ * Registers @socket to receive multicast messages sent to @group.
+ * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
+ * been bound to an appropriate interface and port with
+ * g_socket_bind().
*
- * otherwise %NULL.
+ * If @iface is %NULL, the system will automatically pick an interface
+ * to bind to based on @group.
*
- * Returns: a new #GSocketAddress if @native could successfully be converted,
- * Since: 2.22
+ * If @source_specific is %TRUE, source-specific multicast as defined
+ * in RFC 4604 is used. Note that on older platforms this may fail
+ * with a %G_IO_ERROR_NOT_SUPPORTED error.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.32
*/
/**
- * 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().
+ * g_socket_leave_multicast_group:
+ * @socket: a #GSocket.
+ * @group: a #GInetAddress specifying the group address to leave.
+ * @iface: (allow-none): Interface used
+ * @source_specific: %TRUE if source-specific multicast was used
* @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().
+ * Removes @socket from the multicast group defined by @group, @iface,
+ * and @source_specific (which must all have the same values they had
+ * when you joined the group).
*
- * 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.
+ * @socket remains bound to its address and port, and can still receive
+ * unicast messages after calling this.
*
- * Returns: %TRUE if @dest was filled in, %FALSE on error
- * Since: 2.22
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.32
*/
/**
- * g_socket_bind:
+ * g_socket_listen:
* @socket: a #GSocket.
- * @address: a #GSocketAddress specifying the local address.
- * @allow_reuse: whether to allow reusing this address
* @error: #GError for error reporting, or %NULL to ignore.
*
- * When a socket is created it is attached to an address family, but it
- * doesn't have an address in this family. g_socket_bind() assigns the
- * address (sometimes called name) of the socket.
+ * Marks the socket as a server socket, i.e. a socket that is used
+ * to accept incoming requests using g_socket_accept().
*
- * It is generally required to bind to a local address before you can
- * receive connections. (See g_socket_listen() and g_socket_accept() ).
- * In certain situations, you may also want to bind a socket that will be
- * used to initiate connections, though this is not normally required.
+ * Before calling this the socket must be bound to a local address using
+ * g_socket_bind().
*
- * @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.)
+ * To set the maximum amount of outstanding clients, use
+ * g_socket_set_listen_backlog().
*
* Returns: %TRUE on success, %FALSE on error.
* Since: 2.22
/**
- * g_socket_check_connect_result:
- * @socket: a #GSocket
+ * g_socket_listener_accept:
+ * @listener: a #GSocketListener
+ * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Checks and resets the pending connect error for the socket.
- * This is used to check for errors when g_socket_connect() is
- * used in non-blocking mode.
+ * Blocks waiting for a client to connect to any of the sockets added
+ * to the listener. Returns a #GSocketConnection for the socket that was
+ * accepted.
*
- * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
+ * If @source_object is not %NULL it will be filled out with the source
+ * object specified when the corresponding socket or address was added
+ * to the listener.
+ *
+ * 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 #GSocketConnection on success, %NULL on error.
* Since: 2.22
*/
/**
- * g_socket_client_add_application_proxy:
- * @client: a #GSocketClient
- * @protocol: The proxy protocol
+ * g_socket_listener_accept_async:
+ * @listener: a #GSocketListener
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): user data for the callback
*
- * Enable proxy protocols to be handled by the application. When the
- * indicated proxy protocol is returned by the #GProxyResolver,
- * #GSocketClient will consider this protocol as supported but will
- * not try to find a #GProxy instance to handle handshaking. The
- * application must check for this case by calling
- * g_socket_connection_get_remote_address() on the returned
- * #GSocketConnection, and seeing if it's a #GProxyAddress of the
- * appropriate type, to determine whether or not it needs to handle
- * the proxy handshaking itself.
+ * This is the asynchronous version of g_socket_listener_accept().
+ *
+ * When the operation is finished @callback will be
+ * called. You can then call g_socket_listener_accept_socket()
+ * to get the result of the operation.
+ *
+ * Since: 2.22
+ */
+
+
+/**
+ * g_socket_listener_accept_finish:
+ * @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.
*
- * This should be used for proxy protocols that are dialects of
- * another protocol such as HTTP proxy. It also allows cohabitation of
- * proxy protocols that are reused between protocols. A good example
- * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
- * be use as generic socket proxy through the HTTP CONNECT method.
+ * Finishes an async accept operation. See g_socket_listener_accept_async()
*
- * When the proxy is detected as being an application proxy, TLS handshake
- * will be skipped. This is required to let the application do the proxy
- * specific handshake.
+ * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Since: 2.22
*/
/**
- * g_socket_client_connect:
- * @client: a #GSocketClient.
- * @connectable: a #GSocketConnectable specifying the remote address.
+ * g_socket_listener_accept_socket:
+ * @listener: a #GSocketListener
+ * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Tries to resolve the @connectable and make a network connection to it.
- *
- * Upon a successful connection, a new #GSocketConnection is constructed
- * and returned. The caller owns this new object and must drop their
- * reference to it when finished with it.
+ * Blocks waiting for a client to connect to any of the sockets added
+ * to the listener. Returns the #GSocket that was accepted.
*
- * The type of the #GSocketConnection object returned depends on the type of
- * the underlying socket that is used. For instance, for a TCP/IP connection
- * it will be a #GTcpConnection.
+ * If you want to accept the high-level #GSocketConnection, not a #GSocket,
+ * which is often the case, then you should use g_socket_listener_accept()
+ * instead.
*
- * The socket created will be the same family as the address that the
- * @connectable resolves to, unless family is set with g_socket_client_set_family()
- * or indirectly via g_socket_client_set_local_address(). The socket type
- * defaults to %G_SOCKET_TYPE_STREAM but can be set with
- * g_socket_client_set_socket_type().
+ * If @source_object is not %NULL it will be filled out with the source
+ * object specified when the corresponding socket or address was added
+ * to the listener.
*
- * If a local address is specified with g_socket_client_set_local_address() the
- * socket will be bound to this address before connecting.
+ * 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 #GSocketConnection on success, %NULL on error.
+ * Returns: (transfer full): a #GSocket on success, %NULL on error.
* Since: 2.22
*/
/**
- * g_socket_client_connect_async:
- * @client: a #GSocketClient
- * @connectable: a #GSocketConnectable specifying the remote address.
+ * g_socket_listener_accept_socket_async:
+ * @listener: a #GSocketListener
* @cancellable: (allow-none): a #GCancellable, or %NULL
* @callback: (scope async): a #GAsyncReadyCallback
* @user_data: (closure): user data for the callback
*
- * This is the asynchronous version of g_socket_client_connect().
+ * This is the asynchronous version of g_socket_listener_accept_socket().
*
* When the operation is finished @callback will be
- * called. You can then call g_socket_client_connect_finish() to get
- * the result of the operation.
+ * called. You can then call g_socket_listener_accept_socket_finish()
+ * to get the result of the operation.
*
* Since: 2.22
*/
/**
- * g_socket_client_connect_finish:
- * @client: a #GSocketClient.
+ * g_socket_listener_accept_socket_finish:
+ * @listener: a #GSocketListener
* @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ * @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.
*
- * Finishes an async connect operation. See g_socket_client_connect_async()
+ * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Returns: (transfer full): a #GSocket on success, %NULL on error.
* Since: 2.22
*/
/**
- * g_socket_client_connect_to_host:
- * @client: a #GSocketClient
- * @host_and_port: the name and optionally port of the host to connect to
- * @default_port: the default port to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: a pointer to a #GError, or %NULL
+ * g_socket_listener_add_address:
+ * @listener: a #GSocketListener
+ * @address: a #GSocketAddress
+ * @type: a #GSocketType
+ * @protocol: a #GSocketProtocol
+ * @source_object: (allow-none): Optional #GObject identifying this source
+ * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * This is a helper function for g_socket_client_connect().
+ * Creates a socket of type @type and protocol @protocol, binds
+ * it to @address and adds it to the set of sockets we're accepting
+ * sockets from.
*
- * Attempts to create a TCP connection to the named host.
+ * Note that adding an IPv6 address, depending on the platform,
+ * may or may not result in a listener that also accepts IPv4
+ * connections. For more deterministic behavior, see
+ * g_socket_listener_add_inet_port().
*
- * @host_and_port may be in any of a number of recognized formats; an IPv6
- * address, an IPv4 address, or a domain name (in which case a DNS
- * lookup is performed). Quoting with [] is supported for all address
- * types. A port override may be specified in the usual way with a
- * colon. Ports may be given as decimal numbers or symbolic names (in
- * which case an /etc/services lookup is performed).
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * useful if you're listening on multiple addresses and do
+ * different things depending on what address is connected to.
*
- * If no port override is given in @host_and_port then @default_port will be
- * used as the port number to connect to.
+ * If successful and @effective_address is non-%NULL then it will
+ * be set to the address that the binding actually occurred at. This
+ * is helpful for determining the port number that was used for when
+ * requesting a binding to port 0 (ie: "any port"). This address, if
+ * requested, belongs to the caller and must be freed.
*
- * In general, @host_and_port is expected to be provided by the user (allowing
- * them to give the hostname, and a port override if necessary) and
- * @default_port is expected to be provided by the application.
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.22
+ */
+
+
+/**
+ * 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.
*
- * In the case that an IP address is given, a single connection
- * attempt is made. In the case that a name is given, multiple
- * connection attempts may be made, in turn and according to the
- * number of address records in DNS, until a connection succeeds.
+ * Listens for TCP connections on any available port number for both
+ * IPv6 and IPv4 (if each is available).
*
- * Upon a successful connection, a new #GSocketConnection is constructed
- * and returned. The caller owns this new object and must drop their
- * reference to it when finished with it.
+ * This is useful if you need to have a socket for incoming connections
+ * but don't care about the specific port number.
*
- * In the event of any failure (DNS error, service not found, no hosts
- * connectable) %NULL is returned and @error (if non-%NULL) is set
- * accordingly.
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * useful if you're listening on multiple addresses and do
+ * different things depending on what address is connected to.
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * Returns: the port number, or 0 in case of failure.
+ * Since: 2.24
+ */
+
+
+/**
+ * g_socket_listener_add_inet_port:
+ * @listener: a #GSocketListener
+ * @port: an IP port number (non-zero)
+ * @source_object: (allow-none): Optional #GObject identifying this source
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Helper function for g_socket_listener_add_address() that
+ * creates a TCP/IP socket listening on IPv4 and IPv6 (if
+ * supported) on the specified port on all interfaces.
+ *
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * useful if you're listening on multiple addresses and do
+ * different things depending on what address is connected to.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
* Since: 2.22
*/
/**
- * g_socket_client_connect_to_host_async:
- * @client: a #GSocketClient
- * @host_and_port: the name and optionally the port of the host to connect to
- * @default_port: the default port to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): user data for the callback
+ * g_socket_listener_add_socket:
+ * @listener: a #GSocketListener
+ * @socket: a listening #GSocket
+ * @source_object: (allow-none): Optional #GObject identifying this source
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * This is the asynchronous version of g_socket_client_connect_to_host().
+ * Adds @socket to the set of sockets that we try to accept
+ * new clients from. The socket must be bound to a local
+ * address and listened to.
*
- * When the operation is finished @callback will be
- * called. You can then call g_socket_client_connect_to_host_finish() to get
- * the result of the operation.
+ * @source_object will be passed out in the various calls
+ * to accept to identify this particular source, which is
+ * 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
*/
/**
- * 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.
+ * g_socket_listener_close:
+ * @listener: a #GSocketListener
*
- * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
+ * Closes all the sockets in the listener.
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
* Since: 2.22
*/
/**
- * g_socket_client_connect_to_service:
- * @client: a #GSocketConnection
- * @domain: a domain name
- * @service: the name of the service to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: a pointer to a #GError, or %NULL
+ * g_socket_listener_new:
*
- * Attempts to create a TCP connection to a service.
+ * Creates a new #GSocketListener with no sockets to listen for.
+ * New listeners can be added with e.g. g_socket_listener_add_address()
+ * or g_socket_listener_add_inet_port().
*
- * This call looks up the SRV record for @service at @domain for the
- * "tcp" protocol. It then attempts to connect, in turn, to each of
- * the hosts providing the service until either a connection succeeds
- * or there are no hosts remaining.
+ * Returns: a new #GSocketListener.
+ * Since: 2.22
+ */
+
+
+/**
+ * g_socket_listener_set_backlog:
+ * @listener: a #GSocketListener
+ * @listen_backlog: an integer
*
- * Upon a successful connection, a new #GSocketConnection is constructed
- * and returned. The caller owns this new object and must drop their
- * reference to it when finished with it.
+ * Sets the listen backlog on the sockets in the listener.
*
- * In the event of any failure (DNS error, service not found, no hosts
- * connectable) %NULL is returned and @error (if non-%NULL) is set
- * accordingly.
+ * See g_socket_set_listen_backlog() for details
*
- * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
+ * Since: 2.22
*/
/**
- * g_socket_client_connect_to_service_async:
- * @client: a #GSocketClient
- * @domain: a domain name
- * @service: the name of the service to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): user data for the callback
+ * g_socket_new:
+ * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
+ * @type: the socket type to use.
+ * @protocol: the id of the protocol to use, or 0 for default.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Creates a new #GSocket with the defined family, type and protocol.
+ * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
+ * for the family and type is used.
+ *
+ * The @protocol is a family and type specific int that specifies what
+ * kind of protocol to use. #GSocketProtocol lists several common ones.
+ * Many families only support one protocol, and use 0 for this, others
+ * support several and using 0 means to use the default protocol for
+ * the family and type.
*
- * This is the asynchronous version of
- * g_socket_client_connect_to_service().
+ * The protocol id is passed directly to the operating
+ * 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().
* Since: 2.22
*/
/**
- * 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.
+ * g_socket_new_from_fd:
+ * @fd: a native socket file descriptor.
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
+ * Creates a new #GSocket from a native file descriptor
+ * or winsock SOCKET handle.
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
+ * This reads all the settings from the file descriptor so that
+ * all properties should work. Note that the file descriptor
+ * 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().
* Since: 2.22
*/
/**
- * g_socket_client_connect_to_uri:
- * @client: a #GSocketClient
- * @uri: A network URI
- * @default_port: the default port to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: a pointer to a #GError, or %NULL
- *
- * This is a helper function for g_socket_client_connect().
+ * g_socket_receive:
+ * @socket: a #GSocket
+ * @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.
*
- * Attempts to create a TCP connection with a network URI.
+ * Receive data (up to @size bytes) from a socket. This is mainly used by
+ * connection-oriented sockets; it is identical to g_socket_receive_from()
+ * with @address set to %NULL.
*
- * @uri may be any valid URI containing an "authority" (hostname/port)
- * component. If a port is not specified in the URI, @default_port
- * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
- * (#GSocketClient does not know to automatically assume TLS for
- * certain URI schemes.)
+ * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
+ * g_socket_receive() will always read either 0 or 1 complete messages from
+ * the socket. If the received message is too large to fit in @buffer, then
+ * the data beyond @size bytes will be discarded, without any explicit
+ * indication that this has occurred.
*
- * Using this rather than g_socket_client_connect() or
- * g_socket_client_connect_to_host() allows #GSocketClient to
- * determine when to use application-specific proxy protocols.
+ * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
+ * number of bytes, up to @size. If more than @size bytes have been
+ * received, the additional data will be returned in future calls to
+ * g_socket_receive().
*
- * Upon a successful connection, a new #GSocketConnection is constructed
- * and returned. The caller owns this new object and must drop their
- * reference to it when finished with it.
+ * If the socket is in blocking mode the call will block until there
+ * is some data to receive, the connection is closed, or there is an
+ * error. If there is no data available and the socket is in
+ * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
+ * returned. To be notified when data is available, wait for the
+ * %G_IO_IN condition.
*
- * In the event of any failure (DNS error, service not found, no hosts
- * connectable) %NULL is returned and @error (if non-%NULL) is set
- * accordingly.
+ * On error -1 is returned and @error is set accordingly.
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
- * Since: 2.26
+ * Returns: Number of bytes read, or 0 if the connection was closed by
+ * the peer, or -1 on error
+ * Since: 2.22
*/
/**
- * g_socket_client_connect_to_uri_async:
- * @client: a #GSocketClient
- * @uri: a network uri
- * @default_port: the default port to connect to
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): user data for the callback
+ * 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).
+ * @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.
*
- * This is the asynchronous version of g_socket_client_connect_to_uri().
+ * Receive data (up to @size bytes) from a socket.
*
- * When the operation is finished @callback will be
- * called. You can then call g_socket_client_connect_to_uri_finish() to get
- * the result of the operation.
+ * If @address is non-%NULL then @address will be set equal to the
+ * source address of the received packet.
+ * @address is owned by the caller.
*
- * Since: 2.26
+ * 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
+ * Since: 2.22
*/
/**
- * 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.
+ * g_socket_receive_message:
+ * @socket: a #GSocket
+ * @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
+ * @flags: a pointer to an int containing #GSocketMsgFlags flags
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: a #GError pointer, or %NULL
*
- * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
+ * Receive data from a socket. This is the most complicated and
+ * fully-featured version of this call. For easier use, see
+ * g_socket_receive() and g_socket_receive_from().
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
- * Since: 2.26
- */
-
-
-/**
- * g_socket_client_get_enable_proxy:
- * @client: a #GSocketClient.
+ * If @address is non-%NULL then @address will be set equal to the
+ * source address of the received packet.
+ * @address is owned by the caller.
*
- * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
+ * @vector must point to an array of #GInputVector structs and
+ * @num_vectors must be the length of this array. These structs
+ * describe the buffers that received data will be scattered into.
+ * If @num_vectors is -1, then @vectors is assumed to be terminated
+ * by a #GInputVector with a %NULL buffer pointer.
*
- * Returns: whether proxying is enabled
- * Since: 2.26
- */
-
-
-/**
- * g_socket_client_get_family:
- * @client: a #GSocketClient.
+ * As a special case, if @num_vectors is 0 (in which case, @vectors
+ * may of course be %NULL), then a single byte is received and
+ * discarded. This is to facilitate the common practice of sending a
+ * single '\0' byte for the purposes of transferring ancillary data.
*
- * Gets the socket family of the socket client.
+ * @messages, if non-%NULL, will be set to point to a newly-allocated
+ * array of #GSocketControlMessage instances or %NULL if no such
+ * messages was received. These correspond to the control messages
+ * received from the kernel, one #GSocketControlMessage per message
+ * from the kernel. This array is %NULL-terminated and must be freed
+ * by the caller using g_free() after calling g_object_unref() on each
+ * element. If @messages is %NULL, any control messages received will
+ * be discarded.
*
- * See g_socket_client_set_family() for details.
+ * @num_messages, if non-%NULL, will be set to the number of control
+ * messages received.
*
- * Returns: a #GSocketFamily
+ * If both @messages and @num_messages are non-%NULL, then
+ * @num_messages gives the number of #GSocketControlMessage instances
+ * in @messages (ie: not including the %NULL terminator).
+ *
+ * @flags is an in/out parameter. 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
+ * (and g_socket_receive_message() may pass system-specific flags out).
+ *
+ * As with g_socket_receive(), data may be discarded if @socket is
+ * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
+ * provide enough buffer space to read a complete message. You can pass
+ * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
+ * removing it from the receive queue, but there is no portable way to find
+ * out the length of the message other than by reading it into a
+ * sufficiently-large buffer.
+ *
+ * If the socket is in blocking mode the call will block until there
+ * is some data to receive, the connection is closed, or there is an
+ * error. If there is no data available and the socket is in
+ * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
+ * returned. To be notified when data is available, wait for the
+ * %G_IO_IN condition.
+ *
+ * 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
* Since: 2.22
*/
/**
- * g_socket_client_get_local_address:
- * @client: a #GSocketClient.
- *
- * Gets the local address of the socket client.
+ * g_socket_receive_with_blocking:
+ * @socket: a #GSocket
+ * @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
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * See g_socket_client_set_local_address() for details.
+ * This behaves exactly the same as g_socket_receive(), except that
+ * the choice of blocking or non-blocking behavior is determined by
+ * the @blocking argument rather than by @socket's properties.
*
- * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
- * Since: 2.22
+ * Returns: Number of bytes read, or 0 if the connection was closed by
+ * the peer, or -1 on error
+ * Since: 2.26
*/
/**
- * g_socket_client_get_protocol:
- * @client: a #GSocketClient
+ * g_socket_send:
+ * @socket: a #GSocket
+ * @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.
*
- * Gets the protocol name type of the socket client.
+ * Tries to send @size bytes from @buffer on the socket. This is
+ * mainly used by connection-oriented sockets; it is identical to
+ * g_socket_send_to() with @address set to %NULL.
*
- * See g_socket_client_set_protocol() for details.
+ * If the socket is in blocking mode the call will block until there is
+ * space for 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. 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.)
*
- * Returns: a #GSocketProtocol
+ * 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
* Since: 2.22
*/
/**
- * g_socket_client_get_socket_type:
- * @client: a #GSocketClient.
+ * g_socket_send_message:
+ * @socket: a #GSocket
+ * @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.
+ * @num_messages: number of elements in @messages, or -1.
+ * @flags: an int containing #GSocketMsgFlags flags
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Gets the socket type of the socket client.
+ * Send data to @address on @socket. This is the most complicated and
+ * fully-featured version of this call. For easier use, see
+ * g_socket_send() and g_socket_send_to().
+ *
+ * If @address is %NULL then the message is sent to the default receiver
+ * (set by g_socket_connect()).
+ *
+ * @vectors must point to an array of #GOutputVector structs and
+ * @num_vectors must be the length of this array. (If @num_vectors is -1,
+ * 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
+ * #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().
*
- * See g_socket_client_set_socket_type() for details.
+ * @messages, if non-%NULL, is taken to point to an array of @num_messages
+ * #GSocketControlMessage instances. These correspond to the control
+ * messages to be sent on the socket.
+ * If @num_messages is -1 then @messages is treated as a %NULL-terminated
+ * array.
*
- * Returns: a #GSocketFamily
- * Since: 2.22
- */
-
-
-/**
- * g_socket_client_get_timeout:
- * @client: a #GSocketClient
+ * @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.
*
- * Gets the I/O timeout time for sockets created by @client.
+ * If the socket is in blocking mode the call will block until there is
+ * space for 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. 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.)
*
- * See g_socket_client_set_timeout() for details.
+ * On error -1 is returned and @error is set accordingly.
*
- * Returns: the timeout in seconds
- * Since: 2.26
+ * Returns: Number of bytes written (which may be less than @size), or -1
+ * on error
+ * Since: 2.22
*/
/**
- * g_socket_client_get_tls:
- * @client: a #GSocketClient.
+ * 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.
*
- * Gets whether @client creates TLS connections. See
- * g_socket_client_set_tls() for details.
+ * 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.
*
- * Returns: whether @client uses TLS
- * Since: 2.28
- */
-
-
-/**
- * g_socket_client_get_tls_validation_flags:
- * @client: a #GSocketClient.
+ * @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.
*
- * Gets the TLS validation flags used creating TLS connections via
- * @client.
+ * 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.)
*
- * Returns: the TLS validation flags
- * Since: 2.28
+ * 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_client_new:
+ * 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.
+ * @size: the number of bytes to send
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a new #GSocketClient with the default options.
+ * Tries to send @size bytes from @buffer to @address. If @address is
+ * %NULL then the message is sent to the default receiver (set by
+ * g_socket_connect()).
*
- * Free the returned object with g_object_unref().
+ * See g_socket_send() for additional information.
*
- * Returns: a #GSocketClient.
+ * Returns: Number of bytes written (which may be less than @size), or -1
+ * on error
* Since: 2.22
*/
/**
- * g_socket_client_set_enable_proxy:
- * @client: a #GSocketClient.
- * @enable: whether to enable proxies
+ * g_socket_send_with_blocking:
+ * @socket: a #GSocket
+ * @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
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Sets whether or not @client attempts to make connections via a
- * proxy server. When enabled (the default), #GSocketClient will use a
- * #GProxyResolver to determine if a proxy protocol such as SOCKS is
- * needed, and automatically do the necessary proxy negotiation.
+ * This behaves exactly the same as g_socket_send(), except that
+ * 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
* Since: 2.26
*/
/**
- * g_socket_client_set_family:
- * @client: a #GSocketClient.
- * @family: a #GSocketFamily
- *
- * Sets the socket family of the socket client.
- * If this is set to something other than %G_SOCKET_FAMILY_INVALID
- * then the sockets created by this object will be of the specified
- * family.
+ * g_socket_service_is_active:
+ * @service: a #GSocketService
*
- * This might be useful for instance if you want to force the local
- * connection to be an ipv4 socket, even though the address might
- * be an ipv6 mapped to ipv4 address.
+ * Check whether the service is active or not. An active
+ * service will accept new clients that connect, while
+ * a non-active service will let connecting clients queue
+ * up until the service is started.
*
+ * Returns: %TRUE if the service is active, %FALSE otherwise
* Since: 2.22
*/
/**
- * g_socket_client_set_local_address:
- * @client: a #GSocketClient.
- * @address: a #GSocketAddress, or %NULL
- *
- * Sets the local address of the socket client.
- * The sockets created by this object will bound to the
- * specified address (if not %NULL) before connecting.
+ * g_socket_service_new:
*
- * This is useful if you want to ensure that the local
- * side of the connection is on a specific port, or on
- * a specific interface.
+ * Creates a new #GSocketService with no sockets to listen for.
+ * New listeners can be added with e.g. g_socket_listener_add_address()
+ * or g_socket_listener_add_inet_port().
*
+ * Returns: a new #GSocketService.
* Since: 2.22
*/
/**
- * g_socket_client_set_protocol:
- * @client: a #GSocketClient.
- * @protocol: a #GSocketProtocol
+ * g_socket_service_start:
+ * @service: a #GSocketService
*
- * Sets the protocol of the socket client.
- * The sockets created by this object will use of the specified
- * protocol.
+ * Starts the service, i.e. start accepting connections
+ * from the added sockets when the mainloop runs.
*
- * If @protocol is %0 that means to use the default
- * protocol for the socket family and type.
+ * This call is thread-safe, so it may be called from a thread
+ * handling an incoming client request.
*
* Since: 2.22
*/
/**
- * g_socket_client_set_socket_type:
- * @client: a #GSocketClient.
- * @type: a #GSocketType
+ * g_socket_service_stop:
+ * @service: a #GSocketService
*
- * Sets the socket type of the socket client.
- * The sockets created by this object will be of the specified
- * type.
+ * Stops the service, i.e. stops accepting connections
+ * from the added sockets when the mainloop runs.
*
- * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
- * as GSocketClient is used for connection oriented services.
+ * 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_client_set_timeout:
- * @client: a #GSocketClient.
- * @timeout: the timeout
+ * g_socket_set_blocking:
+ * @socket: a #GSocket.
+ * @blocking: Whether to use blocking I/O or not.
*
- * Sets the I/O timeout for sockets created by @client. @timeout is a
- * time in seconds, or 0 for no timeout (the default).
+ * Sets the blocking mode of the socket. In blocking mode
+ * all operations block until they succeed or there is an error. In
+ * non-blocking mode all functions return results immediately or
+ * with a %G_IO_ERROR_WOULD_BLOCK error.
*
- * The timeout value affects the initial connection attempt as well,
- * so setting this may cause calls to g_socket_client_connect(), etc,
- * to fail with %G_IO_ERROR_TIMED_OUT.
+ * All sockets are created in blocking mode. However, note that the
+ * platform level socket is always non-blocking, and blocking mode
+ * is a GSocket level feature.
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * g_socket_client_set_tls:
- * @client: a #GSocketClient.
- * @tls: whether to use TLS
- *
- * Sets whether @client creates TLS (aka SSL) connections. If @tls is
- * %TRUE, @client will wrap its connections in a #GTlsClientConnection
- * and perform a TLS handshake when connecting.
+ * g_socket_set_broadcast:
+ * @socket: a #GSocket.
+ * @broadcast: whether @socket should allow sending to broadcast
+ * addresses
*
- * Note that since #GSocketClient must return a #GSocketConnection,
- * but #GTlsClientConnection is not a #GSocketConnection, this
- * actually wraps the resulting #GTlsClientConnection in a
- * #GTcpWrapperConnection when returning it. You can use
- * g_tcp_wrapper_connection_get_base_io_stream() on the return value
- * to extract the #GTlsClientConnection.
+ * Sets whether @socket should allow sending to broadcast addresses.
+ * This is %FALSE by default.
*
- * Since: 2.28
+ * Since: 2.32
*/
/**
- * g_socket_client_set_tls_validation_flags:
- * @client: a #GSocketClient.
- * @flags: the validation flags
+ * g_socket_set_keepalive:
+ * @socket: a #GSocket.
+ * @keepalive: Value for the keepalive flag
*
- * Sets the TLS validation flags used when creating TLS connections
- * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
+ * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
+ * this flag is set on a socket, the system will attempt to verify that the
+ * remote socket endpoint is still present if a sufficiently long period of
+ * time passes with no data being exchanged. If the system is unable to
+ * verify the presence of the remote endpoint, it will automatically close
+ * the connection.
*
- * Since: 2.28
+ * This option is only functional on certain kinds of sockets. (Notably,
+ * %G_SOCKET_PROTOCOL_TCP sockets.)
+ *
+ * The exact time between pings is system- and protocol-dependent, but will
+ * normally be at least two hours. Most commonly, you would set this flag
+ * on a server socket if you want to allow clients to remain idle for long
+ * periods of time, but also want to ensure that connections are eventually
+ * garbage-collected if clients crash or become unreachable.
+ *
+ * Since: 2.22
*/
/**
- * g_socket_close:
- * @socket: a #GSocket
- * @error: #GError for error reporting, or %NULL to ignore.
- *
- * Closes the socket, shutting down any active connection.
- *
- * Closing a socket does not wait for all outstanding I/O operations
- * to finish, so the caller should not rely on them to be guaranteed
- * to complete even if the close returns with no error.
- *
- * Once the socket is closed, all other operations will return
- * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
- * return an error.
- *
- * Sockets will be automatically closed when the last reference
- * is dropped, but you might want to call this function to make sure
- * resources are released as early as possible.
- *
- * Beware that due to the way that TCP works, it is possible for
- * recently-sent data to be lost if either you close a socket while the
- * %G_IO_IN condition is set, or else if the remote connection tries to
- * send something to you after you close the socket but before it has
- * finished reading all of the data you sent. There is no easy generic
- * way to avoid this problem; the easiest fix is to design the network
- * protocol such that the client will never send data "out of turn".
- * Another solution is for the server to half-close the connection by
- * calling g_socket_shutdown() with only the @shutdown_write flag set,
- * and then wait for the client to notice this and close its side of the
- * connection, after which the server can safely call g_socket_close().
- * (This is what #GTcpConnection does if you call
- * g_tcp_connection_set_graceful_disconnect(). But of course, this
- * only works if the client will close its connection after the server
- * does.)
+ * g_socket_set_listen_backlog:
+ * @socket: a #GSocket.
+ * @backlog: the maximum number of pending connections.
+ *
+ * Sets the maximum number of outstanding connections allowed
+ * when listening on this socket. If more clients than this are
+ * connecting to the socket and the application is not handling them
+ * on time then the new connections will be refused.
+ *
+ * Note that this must be called before g_socket_listen() and has no
+ * effect if called after that.
*
- * Returns: %TRUE on success, %FALSE on error
* Since: 2.22
*/
/**
- * g_socket_condition_check:
- * @socket: a #GSocket
- * @condition: a #GIOCondition mask to check
- *
- * Checks on the readiness of @socket to perform operations.
- * The operations specified in @condition are checked for and masked
- * against the currently-satisfied conditions on @socket. The result
- * is returned.
+ * g_socket_set_multicast_loopback:
+ * @socket: a #GSocket.
+ * @loopback: whether @socket should receive messages sent to its
+ * multicast groups from the local host
*
- * Note that on Windows, it is possible for an operation to return
- * %G_IO_ERROR_WOULD_BLOCK even immediately after
- * g_socket_condition_check() has claimed that the socket is ready for
- * writing. Rather than calling g_socket_condition_check() and then
- * writing to the socket if it succeeds, it is generally better to
- * simply try writing to the socket right away, and try again later if
- * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
+ * Sets whether outgoing multicast packets will be received by sockets
+ * listening on that multicast address on the same host. This is %TRUE
+ * by default.
*
- * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
- * these conditions will always be set in the output if they are true.
+ * Since: 2.32
+ */
+
+
+/**
+ * g_socket_set_multicast_ttl:
+ * @socket: a #GSocket.
+ * @ttl: the time-to-live value for all multicast datagrams on @socket
*
- * This call never blocks.
+ * Sets the time-to-live for outgoing multicast datagrams on @socket.
+ * By default, this is 1, meaning that multicast packets will not leave
+ * the local network.
*
- * Returns: the @GIOCondition mask of the current state
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_socket_condition_wait:
+ * g_socket_set_option:
* @socket: a #GSocket
- * @condition: a #GIOCondition mask to wait for
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @error: a #GError pointer, or %NULL
+ * @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.
*
- * Waits for @condition to become true on @socket. When the condition
- * is met, %TRUE is returned.
+ * 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.)
*
- * If @cancellable is cancelled before the condition is met, or if the
- * socket has a timeout set and it is reached before the condition is
- * met, then %FALSE is returned and @error, if non-%NULL, is set to
- * the appropriate value (%G_IO_ERROR_CANCELLED or
- * %G_IO_ERROR_TIMED_OUT).
+ * 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: %TRUE if the condition was met, %FALSE otherwise
- * Since: 2.22
+ * 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_connect:
+ * g_socket_set_timeout:
* @socket: a #GSocket.
- * @address: a #GSocketAddress specifying the remote address.
- * @cancellable: (allow-none): a %GCancellable or %NULL
- * @error: #GError for error reporting, or %NULL to ignore.
+ * @timeout: the timeout for @socket, in seconds, or 0 for none
*
- * Connect the socket to the specified remote address.
+ * Sets the time in seconds after which I/O operations on @socket will
+ * time out if they have not yet completed.
*
- * For connection oriented socket this generally means we attempt to make
- * a connection to the @address. For a connection-less socket it sets
- * the default address for g_socket_send() and discards all incoming datagrams
- * from other sources.
+ * On a blocking socket, this means that any blocking #GSocket
+ * operation will time out after @timeout seconds of inactivity,
+ * returning %G_IO_ERROR_TIMED_OUT.
*
- * Generally connection oriented sockets can only connect once, but
- * connection-less sockets can connect multiple times to change the
- * default address.
+ * On a non-blocking socket, calls to g_socket_condition_wait() will
+ * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
+ * created with g_socket_create_source() will trigger after
+ * @timeout seconds of inactivity, with the requested condition
+ * set, at which point calling g_socket_receive(), g_socket_send(),
+ * g_socket_check_connect_result(), etc, will fail with
+ * %G_IO_ERROR_TIMED_OUT.
*
- * If the connect call needs to do network I/O it will block, unless
- * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
- * and the user can be notified of the connection finishing by waiting
- * for the G_IO_OUT condition. The result of the connection must then be
- * checked with g_socket_check_connect_result().
+ * If @timeout is 0 (the default), operations will never time out
+ * on their own.
*
- * Returns: %TRUE if connected, %FALSE on error.
- * Since: 2.22
+ * Note that if an I/O operation is interrupted by a signal, this may
+ * cause the timeout to be reset.
+ *
+ * Since: 2.26
*/
/**
- * g_socket_connectable_enumerate:
- * @connectable: a #GSocketConnectable
+ * g_socket_set_ttl:
+ * @socket: a #GSocket.
+ * @ttl: the time-to-live value for all unicast packets on @socket
*
- * Creates a #GSocketAddressEnumerator for @connectable.
+ * Sets the time-to-live for outgoing unicast packets on @socket.
+ * By default the platform-specific default value is used.
*
- * Returns: (transfer full): a new #GSocketAddressEnumerator.
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_socket_connectable_proxy_enumerate:
- * @connectable: a #GSocketConnectable
+ * g_socket_shutdown:
+ * @socket: a #GSocket
+ * @shutdown_read: whether to shut down the read side
+ * @shutdown_write: whether to shut down the write side
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a #GSocketAddressEnumerator for @connectable that will
- * return #GProxyAddress<!-- -->es for addresses that you must connect
- * to via a proxy.
+ * Shut down part of a full-duplex connection.
*
- * If @connectable does not implement
- * g_socket_connectable_proxy_enumerate(), this will fall back to
- * calling g_socket_connectable_enumerate().
+ * If @shutdown_read is %TRUE then the receiving side of the connection
+ * is shut down, and further reading is disallowed.
*
- * Returns: (transfer full): a new #GSocketAddressEnumerator.
- * Since: 2.26
+ * If @shutdown_write is %TRUE then the sending side of the connection
+ * is shut down, and further writing is disallowed.
+ *
+ * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
+ *
+ * One example where this is used is graceful disconnect for TCP connections
+ * where you close the sending side, then wait for the other side to close
+ * the connection, thus ensuring that the other side saw all sent data.
+ *
+ * Returns: %TRUE on success, %FALSE on error
+ * Since: 2.22
*/
/**
- * g_socket_connection_factory_create_connection:
+ * g_socket_speaks_ipv4:
* @socket: a #GSocket
*
- * Creates a #GSocketConnection subclass of the right type for
- * @socket.
+ * Checks if a socket is capable of speaking IPv4.
*
- * Returns: (transfer full): a #GSocketConnection
+ * IPv4 sockets are capable of speaking IPv4. On some operating systems
+ * and under some combinations of circumstances IPv6 sockets are also
+ * capable of speaking IPv4. See RFC 3493 section 3.7 for more
+ * information.
+ *
+ * No other types of sockets are currently considered as being capable
+ * of speaking IPv4.
+ *
+ * Returns: %TRUE if this socket can be used with IPv4.
* Since: 2.22
*/
/**
- * g_socket_connection_factory_lookup_type:
- * @family: a #GSocketFamily
- * @type: a #GSocketType
- * @protocol_id: a protocol id
- *
- * Looks up the #GType to be used when creating socket connections on
- * sockets with the specified @family, @type and @protocol_id.
+ * g_srv_target_copy:
+ * @target: a #GSrvTarget
*
- * If no type is registered, the #GSocketConnection base type is returned.
+ * Copies @target
*
- * Returns: a #GType
+ * Returns: a copy of @target
* Since: 2.22
*/
/**
- * g_socket_connection_factory_register_type:
- * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
- * @family: a #GSocketFamily
- * @type: a #GSocketType
- * @protocol: a protocol id
- *
- * Looks up the #GType to be used when creating socket connections on
- * sockets with the specified @family, @type and @protocol.
+ * g_srv_target_free:
+ * @target: a #GSrvTarget
*
- * If no type is registered, the #GSocketConnection base type is returned.
+ * Frees @target
*
* Since: 2.22
*/
/**
- * g_socket_connection_get_local_address:
- * @connection: a #GSocketConnection
- * @error: #GError for error reporting, or %NULL to ignore.
- *
- * Try to get the local address of a socket connection.
+ * g_srv_target_get_hostname:
+ * @target: a #GSrvTarget
*
- * Free the returned object with g_object_unref().
+ * 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: (transfer full): a #GSocketAddress or %NULL on error.
+ * Returns: @target's hostname
* Since: 2.22
*/
/**
- * g_socket_connection_get_remote_address:
- * @connection: a #GSocketConnection
- * @error: #GError for error reporting, or %NULL to ignore.
- *
- * Try to get the remote address of a socket connection.
+ * g_srv_target_get_port:
+ * @target: a #GSrvTarget
*
- * Free the returned object with g_object_unref().
+ * Gets @target's port
*
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Returns: @target's port
* Since: 2.22
*/
/**
- * g_socket_connection_get_socket:
- * @connection: a #GSocketConnection
+ * g_srv_target_get_priority:
+ * @target: a #GSrvTarget
*
- * Gets the underlying #GSocket object of the connection.
- * This can be useful if you want to do something unusual on it
- * not supported by the #GSocketConnection APIs.
+ * 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: (transfer none): a #GSocketAddress or %NULL on error.
+ * Returns: @target's priority
* Since: 2.22
*/
/**
- * g_socket_control_message_deserialize:
- * @level: a socket level
- * @type: a socket control message type for the given @level
- * @size: the size of the data in bytes
- * @data: (array length=size) (element-type guint8): pointer to the message data
- *
- * Tries to deserialize a socket control message of a given
- * @level and @type. This will ask all known (to GType) subclasses
- * of #GSocketControlMessage if they can understand this kind
- * of message and if so deserialize it into a #GSocketControlMessage.
+ * g_srv_target_get_weight:
+ * @target: a #GSrvTarget
*
- * If there is no implementation for this kind of control message, %NULL
- * will be returned.
+ * 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: (transfer full): the deserialized message or %NULL
+ * Returns: @target's weight
* Since: 2.22
*/
/**
- * g_socket_control_message_get_level:
- * @message: a #GSocketControlMessage
+ * g_srv_target_list_sort: (skip)
+ * @targets: a #GList of #GSrvTarget
*
- * Returns the "level" (i.e. the originating protocol) of the control message.
- * This is often SOL_SOCKET.
+ * Sorts @targets in place according to the algorithm in RFC 2782.
*
- * Returns: an integer describing the level
+ * Returns: (transfer full): the head of the sorted list.
* Since: 2.22
*/
/**
- * g_socket_control_message_get_msg_type:
- * @message: a #GSocketControlMessage
+ * 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
*
- * Returns the protocol specific type of the control message.
- * For instance, for UNIX fd passing this would be SCM_RIGHTS.
+ * Creates a new #GSrvTarget with the given parameters.
*
- * Returns: an integer describing the type of control message
+ * You should not need to use this; normally #GSrvTargets are
+ * created by #GResolver.
+ *
+ * Returns: a new #GSrvTarget.
* Since: 2.22
*/
/**
- * g_socket_control_message_get_size:
- * @message: a #GSocketControlMessage
+ * g_static_resource_fini:
+ * @static_resource: pointer to a static #GStaticResource
*
- * Returns the space required for the control message, not including
- * headers or alignment.
+ * 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: The number of bytes required.
- * Since: 2.22
+ * Returns: (transfer none): a #GResource
+ * Since: 2.32
*/
/**
- * g_socket_control_message_serialize:
- * @message: a #GSocketControlMessage
- * @data: A buffer to write data to
+ * g_static_resource_init:
+ * @static_resource: pointer to a static #GStaticResource
*
- * Converts the data in the message to bytes placed in the
- * message.
+ * Initializes a GResource from static data using a
+ * GStaticResource.
*
- * @data is guaranteed to have enough space to fit the size
- * returned by g_socket_control_message_get_size() on this
- * object.
+ * This is normally used by code generated by
+ * [glib-compile-resources][glib-compile-resources]
+ * and is not typically used by other code.
*
- * Since: 2.22
+ * Since: 2.32
*/
/**
- * g_socket_create_source: (skip)
- * @socket: a #GSocket
- * @condition: a #GIOCondition mask to monitor
- * @cancellable: (allow-none): a %GCancellable or %NULL
+ * 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
*
- * Creates a %GSource that can be attached to a %GMainContext to monitor
- * for the availibility of the specified @condition on the socket.
+ * Communicate with the subprocess until it terminates, and all input
+ * and output has been completed.
*
- * The callback on the source is of the #GSocketSourceFunc type.
+ * 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).
*
- * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
- * these conditions will always be reported output if they are true.
+ * 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.
*
- * @cancellable if not %NULL can be used to cancel the source, which will
- * cause the source to trigger, reporting the current condition (which
- * is likely 0 unless cancellation happened at the same time as a
- * condition change). You can check for this in the callback using
- * g_cancellable_is_cancelled().
+ * 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.
*
- * If @socket has a timeout set, and it is reached before @condition
- * occurs, the source will then trigger anyway, reporting %G_IO_IN or
- * %G_IO_OUT depending on @condition. However, @socket will have been
- * marked as having had a timeout, and so the next #GSocket I/O method
- * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
+ * As usual, any output variable may be given as %NULL to ignore it.
*
- * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
- * Since: 2.22
+ * 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_socket_get_blocking:
- * @socket: a #GSocket.
- *
- * Gets the blocking mode of the socket. For details on blocking I/O,
- * see g_socket_set_blocking().
+ * g_subprocess_communicate_async:
+ * @subprocess: Self
+ * @stdin_buf: (allow-none): Input data, or %NULL
+ * @cancellable: (allow-none): Cancellable
+ * @callback: Callback
+ * @user_data: User data
*
- * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
- * Since: 2.22
+ * Asynchronous version of g_subprocess_communicate(). Complete
+ * invocation with g_subprocess_communicate_finish().
*/
/**
- * g_socket_get_credentials:
- * @socket: a #GSocket.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * 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
*
- * Returns the credentials of the foreign process connected to this
- * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
- * sockets).
- *
- * If this operation isn't supported on the OS, the method fails with
- * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
- * by reading the %SO_PEERCRED option on the underlying socket.
- *
- * Other ways to obtain credentials from a foreign peer includes the
- * #GUnixCredentialsMessage type and
- * g_unix_connection_send_credentials() /
- * g_unix_connection_receive_credentials() functions.
- *
- * that must be freed with g_object_unref().
+ * 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
*
- * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
- * Since: 2.26
+ * Like g_subprocess_communicate(), but validates the output of the
+ * process as UTF-8, and returns it as a regular NUL terminated string.
*/
/**
- * g_socket_get_family:
- * @socket: a #GSocket.
+ * g_subprocess_communicate_utf8_async:
+ * @subprocess: Self
+ * @stdin_buf: (allow-none): Input data, or %NULL
+ * @cancellable: Cancellable
+ * @callback: Callback
+ * @user_data: User data
*
- * Gets the socket family of the socket.
+ * 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
*
- * Returns: a #GSocketFamily
- * Since: 2.22
+ * Complete an invocation of g_subprocess_communicate_utf8_async().
*/
/**
- * g_socket_get_fd:
- * @socket: a #GSocket.
+ * g_subprocess_force_exit:
+ * @subprocess: a #GSubprocess
*
- * Returns the underlying OS socket object. On unix this
- * 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.
+ * 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.
*
- * Returns: the file descriptor of the socket.
- * Since: 2.22
+ * On Unix, this function sends %SIGKILL.
+ *
+ * Since: 2.40
*/
/**
- * g_socket_get_keepalive:
- * @socket: a #GSocket.
+ * g_subprocess_get_exit_status:
+ * @subprocess: a #GSubprocess
*
- * Gets the keepalive mode of the socket. For details on this,
- * see g_socket_set_keepalive().
+ * 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.
*
- * Returns: %TRUE if keepalive is active, %FALSE otherwise.
- * Since: 2.22
+ * 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_socket_get_listen_backlog:
- * @socket: a #GSocket.
- *
- * Gets the listen backlog setting of the socket. For details on this,
- * see g_socket_set_listen_backlog().
+ * g_subprocess_get_identifier:
+ * @subprocess: a #GSubprocess
*
- * Returns: the maximum number of pending connections.
- * Since: 2.22
+ * On UNIX, returns the process ID as a decimal string.
+ * On Windows, returns the result of GetProcessId() also as a string.
*/
/**
- * g_socket_get_local_address:
- * @socket: a #GSocket.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_get_if_exited:
+ * @subprocess: a #GSubprocess
*
- * Try to get the local address of a bound socket. This is only
- * useful if the socket has been bound to a local address,
- * either explicitly or implicitly when connecting.
+ * Check if the given subprocess exited normally (ie: by way of exit()
+ * or return from main()).
*
- * Free the returned object with g_object_unref().
+ * This is equivalent to the system WIFEXITED macro.
*
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
- * Since: 2.22
+ * 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_socket_get_protocol:
- * @socket: a #GSocket.
+ * g_subprocess_get_if_signaled:
+ * @subprocess: a #GSubprocess
*
- * Gets the socket protocol id the socket was created with.
- * In case the protocol is unknown, -1 is returned.
+ * Check if the given subprocess terminated in response to a signal.
*
- * Returns: a protocol id, or -1 if unknown
- * Since: 2.22
+ * 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_socket_get_remote_address:
- * @socket: a #GSocket.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_get_status:
+ * @subprocess: a #GSubprocess
*
- * Try to get the remove address of a connected socket. This is only
- * useful for connection oriented sockets that have been connected.
+ * Gets the raw status code of the process, as from waitpid().
*
- * Free the returned object with g_object_unref().
+ * 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().
*
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
- * Since: 2.22
+ * 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_socket_get_socket_type:
- * @socket: a #GSocket.
+ * g_subprocess_get_stderr_pipe:
+ * @subprocess: a #GSubprocess
*
- * Gets the socket type of the socket.
+ * Gets the #GInputStream from which to read the stderr output of
+ * @subprocess.
*
- * Returns: a #GSocketType
- * Since: 2.22
+ * The process must have been created with
+ * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
+ *
+ * Returns: (transfer none): the stderr pipe
+ * Since: 2.40
*/
/**
- * g_socket_get_timeout:
- * @socket: a #GSocket.
+ * g_subprocess_get_stdin_pipe:
+ * @subprocess: a #GSubprocess
*
- * Gets the timeout setting of the socket. For details on this, see
- * g_socket_set_timeout().
+ * Gets the #GOutputStream that you can write to in order to give data
+ * to the stdin of @subprocess.
*
- * Returns: the timeout in seconds
- * Since: 2.26
+ * The process must have been created with
+ * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
+ *
+ * Returns: (transfer none): the stdout pipe
+ * Since: 2.40
*/
/**
- * g_socket_is_closed:
- * @socket: a #GSocket
+ * g_subprocess_get_stdout_pipe:
+ * @subprocess: a #GSubprocess
*
- * Checks whether a socket is closed.
+ * Gets the #GInputStream from which to read the stdout output of
+ * @subprocess.
*
- * Returns: %TRUE if socket is closed, %FALSE otherwise
- * Since: 2.22
+ * The process must have been created with
+ * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
+ *
+ * Returns: (transfer none): the stdout pipe
+ * Since: 2.40
*/
/**
- * g_socket_is_connected:
- * @socket: a #GSocket.
+ * g_subprocess_get_successful:
+ * @subprocess: a #GSubprocess
*
- * Check whether the socket is connected. This is only useful for
- * connection-oriented sockets.
+ * 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().
*
- * Returns: %TRUE if socket is connected, %FALSE otherwise.
- * Since: 2.22
+ * 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_socket_listen:
- * @socket: a #GSocket.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_get_term_sig:
+ * @subprocess: a #GSubprocess
*
- * Marks the socket as a server socket, i.e. a socket that is used
- * to accept incoming requests using g_socket_accept().
+ * Get the signal number that caused the subprocess to terminate, given
+ * that it terminated due to a signal.
*
- * Before calling this the socket must be bound to a local address using
- * g_socket_bind().
+ * This is equivalent to the system WTERMSIG macro.
*
- * To set the maximum amount of outstanding clients, use
- * g_socket_set_listen_backlog().
+ * It is an error to call this function before g_subprocess_wait() and
+ * unless g_subprocess_get_if_signaled() returned %TRUE.
*
- * Returns: %TRUE on success, %FALSE on error.
- * Since: 2.22
+ * Returns: the signal causing termination
+ * Since: 2.40
*/
/**
- * g_socket_listener_accept:
- * @listener: a #GSocketListener
- * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_launcher_getenv:
+ * @self: a #GSubprocess
+ * @variable: the environment variable to get
*
- * Blocks waiting for a client to connect to any of the sockets added
- * to the listener. Returns a #GSocketConnection for the socket that was
- * accepted.
+ * Returns the value of the environment variable @variable in the
+ * environment of processes launched from this launcher.
*
- * If @source_object is not %NULL it will be filled out with the source
- * object specified when the corresponding socket or address was added
- * to the listener.
+ * 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.
*
- * 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: the value of the environment variable, %NULL if unset
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_new:
+ * @flags: #GSubprocessFlags
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
- * Since: 2.22
+ * 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_socket_listener_accept_async:
- * @listener: a #GSocketListener
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): user data for the callback
+ * 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
*
- * This is the asynchronous version of g_socket_listener_accept().
+ * Sets up a child setup function.
*
- * When the operation is finished @callback will be
- * called. You can then call g_socket_listener_accept_socket()
- * to get the result of the operation.
+ * The child setup function will be called after fork() but before
+ * exec() on the child's side.
*
- * Since: 2.22
+ * @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_socket_listener_accept_finish:
- * @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.
+ * g_subprocess_launcher_set_cwd:
+ * @self: a #GSubprocess
+ * @cwd: the cwd for launched processes
*
- * Finishes an async accept operation. See g_socket_listener_accept_async()
+ * Sets the current working directory that processes will be launched
+ * with.
*
- * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
- * Since: 2.22
+ * By default processes are launched with the current working directory
+ * of the launching process at the time of launch.
+ *
+ * Since: 2.40
*/
/**
- * g_socket_listener_accept_socket:
- * @listener: a #GSocketListener
- * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_launcher_set_environ:
+ * @self: a #GSubprocess
+ * @env: the replacement environment
*
- * Blocks waiting for a client to connect to any of the sockets added
- * to the listener. Returns the #GSocket that was accepted.
+ * Replace the entire environment of processes launched from this
+ * launcher with the given 'environ' variable.
*
- * If you want to accept the high-level #GSocketConnection, not a #GSocket,
- * which is often the case, then you should use g_socket_listener_accept()
- * instead.
+ * 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.
*
- * If @source_object is not %NULL it will be filled out with the source
- * object specified when the corresponding socket or address was added
- * to the listener.
+ * As an alternative, you can use g_subprocess_launcher_setenv(),
+ * g_subprocess_launcher_unsetenv(), etc.
*
- * 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.
+ * 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.
*
- * Returns: (transfer full): a #GSocket on success, %NULL on error.
- * Since: 2.22
+ * Since: 2.40
*/
/**
- * g_socket_listener_accept_socket_async:
- * @listener: a #GSocketListener
- * @cancellable: (allow-none): a #GCancellable, or %NULL
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): user data for the callback
+ * g_subprocess_launcher_set_flags:
+ * @self: a #GSubprocessLauncher
+ * @flags: #GSubprocessFlags
*
- * This is the asynchronous version of g_socket_listener_accept_socket().
+ * Sets the flags on the launcher.
*
- * When the operation is finished @callback will be
- * called. You can then call g_socket_listener_accept_socket_finish()
- * to get the result of the operation.
+ * The default flags are %G_SUBPROCESS_FLAGS_NONE.
*
- * Since: 2.22
+ * 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_socket_listener_accept_socket_finish:
- * @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.
+ * g_subprocess_launcher_set_stderr_file_path:
+ * @self: a #GSubprocessLauncher
+ * @path: a filename or %NULL
*
- * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
+ * 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.
*
- * Returns: (transfer full): a #GSocket on success, %NULL on error.
- * Since: 2.22
+ * Since: 2.40
*/
/**
- * g_socket_listener_add_address:
- * @listener: a #GSocketListener
- * @address: a #GSocketAddress
- * @type: a #GSocketType
- * @protocol: a #GSocketProtocol
- * @source_object: (allow-none): Optional #GObject identifying this source
- * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_launcher_set_stdin_file_path:
+ * @self: a #GSubprocessLauncher
+ * @path: a filename or %NULL
*
- * Creates a socket of type @type and protocol @protocol, binds
- * it to @address and adds it to the set of sockets we're accepting
- * sockets from.
+ * Sets the file path to use as the stdin for spawned processes.
*
- * Note that adding an IPv6 address, depending on the platform,
- * may or may not result in a listener that also accepts IPv4
- * connections. For more deterministic behavior, see
- * g_socket_listener_add_inet_port().
+ * If @path is %NULL then any previously given path is unset.
*
- * @source_object will be passed out in the various calls
- * to accept to identify this particular source, which is
- * useful if you're listening on multiple addresses and do
- * different things depending on what address is connected to.
+ * The file must exist or spawning the process will fail.
*
- * If successful and @effective_address is non-%NULL then it will
- * be set to the address that the binding actually occurred at. This
- * is helpful for determining the port number that was used for when
- * requesting a binding to port 0 (ie: "any port"). This address, if
- * requested, belongs to the caller and must be freed.
+ * 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.
*
- * Returns: %TRUE on success, %FALSE on error.
- * Since: 2.22
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
*/
/**
- * 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.
+ * g_subprocess_launcher_set_stdout_file_path:
+ * @self: a #GSubprocessLauncher
+ * @path: a filename or %NULL
*
- * Listens for TCP connections on any available port number for both
- * IPv6 and IPv4 (if each is available).
+ * Sets the file path to use as the stdout for spawned processes.
*
- * This is useful if you need to have a socket for incoming connections
- * but don't care about the specific port number.
+ * If @path is %NULL then any previously given path is unset.
*
- * @source_object will be passed out in the various calls
- * to accept to identify this particular source, which is
- * useful if you're listening on multiple addresses and do
- * different things depending on what address is connected to.
+ * The file will be created or truncated when the process is spawned, as
+ * would be the case if using '>' at the shell.
*
- * Returns: the port number, or 0 in case of failure.
- * Since: 2.24
+ * 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_socket_listener_add_inet_port:
- * @listener: a #GSocketListener
- * @port: an IP port number (non-zero)
- * @source_object: (allow-none): Optional #GObject identifying this source
- * @error: #GError for error reporting, or %NULL to ignore.
+ * 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
*
- * Helper function for g_socket_listener_add_address() that
- * creates a TCP/IP socket listening on IPv4 and IPv6 (if
- * supported) on the specified port on all interfaces.
+ * Sets the environment variable @variable in the environment of
+ * processes launched from this launcher.
*
- * @source_object will be passed out in the various calls
- * to accept to identify this particular source, which is
- * useful if you're listening on multiple addresses and do
- * different things depending on what address is connected to.
+ * 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.
*
- * Returns: %TRUE on success, %FALSE on error.
- * Since: 2.22
+ * Since: 2.40
*/
/**
- * g_socket_listener_add_socket:
- * @listener: a #GSocketListener
- * @socket: a listening #GSocket
- * @source_object: (allow-none): Optional #GObject identifying this source
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_launcher_spawn:
+ * @self: a #GSubprocessLauncher
+ * @error: Error
+ * @argv0: Command line arguments
+ * @...: Continued arguments, %NULL terminated
*
- * Adds @socket to the set of sockets that we try to accept
- * new clients from. The socket must be bound to a local
- * address and listened to.
- *
- * @source_object will be passed out in the various calls
- * to accept to identify this particular source, which is
- * useful if you're listening on multiple addresses and do
- * different things depending on what address is connected to.
+ * Creates a #GSubprocess given a provided varargs list of arguments.
*
- * Returns: %TRUE on success, %FALSE on error.
- * Since: 2.22
+ * Since: 2.40
+ * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
*/
/**
- * g_socket_listener_close:
- * @listener: a #GSocketListener
+ * g_subprocess_launcher_spawnv:
+ * @self: a #GSubprocessLauncher
+ * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
+ * @error: Error
*
- * Closes all the sockets in the listener.
+ * Creates a #GSubprocess given a provided array of arguments.
*
- * Since: 2.22
+ * Since: 2.40
+ * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
*/
/**
- * g_socket_listener_new:
+ * g_subprocess_launcher_take_fd:
+ * @self: a #GSubprocessLauncher
+ * @source_fd: File descriptor in parent process
+ * @target_fd: Target descriptor for child process
*
- * Creates a new #GSocketListener with no sockets to listen for.
- * New listeners can be added with e.g. g_socket_listener_add_address()
- * or g_socket_listener_add_inet_port().
+ * 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.
*
- * Returns: a new #GSocketListener.
- * Since: 2.22
+ * 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_socket_listener_set_backlog:
- * @listener: a #GSocketListener
- * @listen_backlog: an integer
+ * g_subprocess_launcher_take_stderr_fd:
+ * @self: a #GSubprocessLauncher
+ * @fd: a file descriptor, or -1
*
- * Sets the listen backlog on the sockets in the listener.
+ * Sets the file descriptor to use as the stderr for spawned processes.
*
- * See g_socket_set_listen_backlog() for details
+ * If @fd is -1 then any previously given fd is unset.
*
- * Since: 2.22
+ * 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_socket_new:
- * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
- * @type: the socket type to use.
- * @protocol: the id of the protocol to use, or 0 for default.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_launcher_take_stdin_fd:
+ * @self: a #GSubprocessLauncher
+ * @fd: a file descriptor, or -1
*
- * Creates a new #GSocket with the defined family, type and protocol.
- * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
- * for the family and type is used.
+ * Sets the file descriptor to use as the stdin for spawned processes.
*
- * The @protocol is a family and type specific int that specifies what
- * kind of protocol to use. #GSocketProtocol lists several common ones.
- * Many families only support one protocol, and use 0 for this, others
- * support several and using 0 means to use the default protocol for
- * the family and type.
+ * If @fd is -1 then any previously given fd is unset.
*
- * The protocol id is passed directly to the operating
- * system, so you can use protocols not listed in #GSocketProtocol if you
- * know the protocol number used for it.
+ * 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.
*
- * Free the returned object with g_object_unref().
+ * 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.
*
- * Returns: a #GSocket or %NULL on error.
- * Since: 2.22
+ * 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_socket_new_from_fd:
- * @fd: a native socket file descriptor.
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_subprocess_launcher_take_stdout_fd:
+ * @self: a #GSubprocessLauncher
+ * @fd: a file descriptor, or -1
*
- * Creates a new #GSocket from a native file descriptor
- * or winsock SOCKET handle.
+ * Sets the file descriptor to use as the stdout for spawned processes.
*
- * This reads all the settings from the file descriptor so that
- * all properties should work. Note that the file descriptor
- * will be set to non-blocking mode, independent on the blocking
- * mode of the #GSocket.
+ * If @fd is -1 then any previously given fd is unset.
*
- * Free the returned object with g_object_unref().
+ * Note that the default behaviour is to pass stdout through to the
+ * stdout of the parent process.
*
- * Returns: a #GSocket or %NULL on error.
- * Since: 2.22
+ * 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_socket_receive:
- * @socket: a #GSocket
- * @buffer: 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.
- *
- * Receive data (up to @size bytes) from a socket. This is mainly used by
- * connection-oriented sockets; it is identical to g_socket_receive_from()
- * with @address set to %NULL.
+ * g_subprocess_launcher_unsetenv:
+ * @self: a #GSubprocess
+ * @variable: the environment variable to unset, must not contain '='
*
- * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
- * g_socket_receive() will always read either 0 or 1 complete messages from
- * the socket. If the received message is too large to fit in @buffer, then
- * the data beyond @size bytes will be discarded, without any explicit
- * indication that this has occurred.
+ * Removes the environment variable @variable from the environment of
+ * processes launched from this launcher.
*
- * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
- * number of bytes, up to @size. If more than @size bytes have been
- * received, the additional data will be returned in future calls to
- * g_socket_receive().
+ * 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.
*
- * If the socket is in blocking mode the call will block until there
- * is some data to receive, the connection is closed, or there is an
- * error. If there is no data available and the socket is in
- * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
- * returned. To be notified when data is available, wait for the
- * %G_IO_IN condition.
+ * 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
*
- * On error -1 is returned and @error is set accordingly.
+ * 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 peer, or -1 on error
+ * The argument list must be terminated with %NULL.
*
- * Returns: Number of bytes read, or 0 if the connection was closed by
- * Since: 2.22
+ * Returns: A newly created #GSubprocess, or %NULL on error (and @error
+ * will be set)
+ * Since: 2.40
*/
/**
- * g_socket_receive_from:
- * @socket: a #GSocket
- * @address: a pointer to a #GSocketAddress pointer, or %NULL
- * @buffer: 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.
+ * 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
*
- * Receive data (up to @size bytes) from a socket.
+ * Create a new process with the given flags and argument list.
*
- * If @address is non-%NULL then @address will be set equal to the
- * source address of the received packet.
- * @address is owned by the caller.
+ * The argument list is expected to be %NULL-terminated.
*
- * See g_socket_receive() for additional information.
+ * 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
*
- * the peer, or -1 on error
+ * Sends the UNIX signal @signal_num to the subprocess, if it is still
+ * running.
*
- * Returns: Number of bytes read, or 0 if the connection was closed by
- * Since: 2.22
+ * 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_socket_receive_message:
- * @socket: a #GSocket
- * @address: 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
- * @flags: a pointer to an int containing #GSocketMsgFlags flags
- * @cancellable: (allow-none): a %GCancellable or %NULL
- * @error: a #GError pointer, or %NULL
+ * g_subprocess_wait:
+ * @subprocess: a #GSubprocess
+ * @cancellable: a #GCancellable
+ * @error: a #GError
*
- * Receive data from a socket. This is the most complicated and
- * fully-featured version of this call. For easier use, see
- * g_socket_receive() and g_socket_receive_from().
+ * Synchronously wait for the subprocess to terminate.
*
- * If @address is non-%NULL then @address will be set equal to the
- * source address of the received packet.
- * @address is owned by the caller.
+ * 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().
*
- * @vector must point to an array of #GInputVector structs and
- * @num_vectors must be the length of this array. These structs
- * describe the buffers that received data will be scattered into.
- * If @num_vectors is -1, then @vectors is assumed to be terminated
- * by a #GInputVector with a %NULL buffer pointer.
+ * This function does not fail in the case of the subprocess having
+ * abnormal termination. See g_subprocess_wait_check() for that.
*
- * As a special case, if @num_vectors is 0 (in which case, @vectors
- * may of course be %NULL), then a single byte is received and
- * discarded. This is to facilitate the common practice of sending a
- * single '\0' byte for the purposes of transferring ancillary data.
+ * Cancelling @cancellable doesn't kill the subprocess. Call
+ * g_subprocess_force_exit() if it is desirable.
*
- * @messages, if non-%NULL, will be set to point to a newly-allocated
- * array of #GSocketControlMessage instances or %NULL if no such
- * messages was received. These correspond to the control messages
- * received from the kernel, one #GSocketControlMessage per message
- * from the kernel. This array is %NULL-terminated and must be freed
- * by the caller using g_free() after calling g_object_unref() on each
- * element. If @messages is %NULL, any control messages received will
- * be discarded.
+ * 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
*
- * @num_messages, if non-%NULL, will be set to the number of control
- * messages received.
+ * Wait for the subprocess to terminate.
*
- * If both @messages and @num_messages are non-%NULL, then
- * @num_messages gives the number of #GSocketControlMessage instances
- * in @messages (ie: not including the %NULL terminator).
+ * This is the asynchronous version of g_subprocess_wait().
*
- * @flags is an in/out parameter. 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
- * (and g_socket_receive_message() may pass system-specific flags out).
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait_check:
+ * @subprocess: a #GSubprocess
+ * @cancellable: a #GCancellable
+ * @error: a #GError
*
- * As with g_socket_receive(), data may be discarded if @socket is
- * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
- * provide enough buffer space to read a complete message. You can pass
- * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
- * removing it from the receive queue, but there is no portable way to find
- * out the length of the message other than by reading it into a
- * sufficiently-large buffer.
+ * Combines g_subprocess_wait() with g_spawn_check_exit_status().
*
- * If the socket is in blocking mode the call will block until there
- * is some data to receive, the connection is closed, or there is an
- * error. If there is no data available and the socket is in
- * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
- * returned. To be notified when data is available, wait for the
- * %G_IO_IN condition.
+ * 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
*
- * On error -1 is returned and @error is set accordingly.
+ * 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
*
- * the peer, or -1 on error
+ * Collects the result of a previous call to
+ * g_subprocess_wait_check_async().
*
- * Returns: Number of bytes read, or 0 if the connection was closed by
- * Since: 2.22
+ * Returns: %TRUE if successful, or %FALSE with @error set
+ * Since: 2.40
*/
/**
- * g_socket_receive_with_blocking:
- * @socket: a #GSocket
- * @buffer: 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
- * @error: #GError for error reporting, or %NULL to ignore.
- *
- * This behaves exactly the same as g_socket_receive(), except that
- * the choice of blocking or non-blocking behavior is determined by
- * the @blocking argument rather than by @socket's properties.
+ * g_subprocess_wait_finish:
+ * @subprocess: a #GSubprocess
+ * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
+ * @error: a pointer to a %NULL #GError, or %NULL
*
- * the peer, or -1 on error
+ * Collects the result of a previous call to
+ * g_subprocess_wait_async().
*
- * Returns: Number of bytes read, or 0 if the connection was closed by
- * Since: 2.26
+ * Returns: %TRUE if successful, or %FALSE with @error set
+ * Since: 2.40
*/
/**
- * g_socket_send:
- * @socket: a #GSocket
- * @buffer: (array length=size): 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.
+ * g_task_attach_source:
+ * @task: a #GTask
+ * @source: the source to attach
+ * @callback: the callback to invoke when @source triggers
*
- * Tries to send @size bytes from @buffer on the socket. This is
- * mainly used by connection-oriented sockets; it is identical to
- * g_socket_send_to() with @address set to %NULL.
+ * 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`.
*
- * If the socket is in blocking mode the call will block until there is
- * space for 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. 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.)
+ * This takes a reference on @task until @source is destroyed.
*
- * On error -1 is returned and @error is set accordingly.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_cancellable:
+ * @task: a #GTask
*
- * on error
+ * Gets @task's #GCancellable
*
- * Returns: Number of bytes written (which may be less than @size), or -1
- * Since: 2.22
+ * Returns: (transfer none): @task's #GCancellable
+ * Since: 2.36
*/
/**
- * g_socket_send_message:
- * @socket: a #GSocket
- * @address: 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.
- * @num_messages: number of elements in @messages, or -1.
- * @flags: an int containing #GSocketMsgFlags flags
- * @cancellable: (allow-none): a %GCancellable or %NULL
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_task_get_check_cancellable:
+ * @task: the #GTask
*
- * Send data to @address on @socket. This is the most complicated and
- * fully-featured version of this call. For easier use, see
- * g_socket_send() and g_socket_send_to().
+ * Gets @task's check-cancellable flag. See
+ * g_task_set_check_cancellable() for more details.
*
- * If @address is %NULL then the message is sent to the default receiver
- * (set by g_socket_connect()).
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_completed:
+ * @task: a #GTask.
*
- * @vectors must point to an array of #GOutputVector structs and
- * @num_vectors must be the length of this array. (If @num_vectors is -1,
- * 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
- * data from multiple sources into a single buffer, and more
- * network-efficient than making multiple calls to g_socket_send().
+ * 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.
*
- * @messages, if non-%NULL, is taken to point to an array of @num_messages
- * #GSocketControlMessage instances. These correspond to the control
- * messages to be sent on the socket.
- * If @num_messages is -1 then @messages is treated as a %NULL-terminated
- * array.
+ * Returns: %TRUE if the task has completed, %FALSE otherwise.
+ * Since: 2.44
+ */
+
+
+/**
+ * g_task_get_context:
+ * @task: a #GTask
*
- * @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.
+ * 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).
*
- * If the socket is in blocking mode the call will block until there is
- * space for 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. 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.)
+ * This will always return a non-%NULL value, even if the task's
+ * context is the default #GMainContext.
*
- * On error -1 is returned and @error is set accordingly.
+ * Returns: (transfer none): @task's #GMainContext
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_priority:
+ * @task: a #GTask
*
- * on error
+ * Gets @task's priority
*
- * Returns: Number of bytes written (which may be less than @size), or -1
- * Since: 2.22
+ * Returns: @task's priority
+ * Since: 2.36
*/
/**
- * g_socket_send_to:
- * @socket: a #GSocket
- * @address: a #GSocketAddress, or %NULL
- * @buffer: (array length=size): 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.
+ * g_task_get_return_on_cancel:
+ * @task: the #GTask
*
- * Tries to send @size bytes from @buffer to @address. If @address is
- * %NULL then the message is sent to the default receiver (set by
- * g_socket_connect()).
+ * Gets @task's return-on-cancel flag. See
+ * g_task_set_return_on_cancel() for more details.
*
- * See g_socket_send() for additional information.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_source_object:
+ * @task: a #GTask
*
- * on error
+ * Gets the source object from @task. Like
+ * g_async_result_get_source_object(), but does not ref the object.
*
- * Returns: Number of bytes written (which may be less than @size), or -1
- * Since: 2.22
+ * Returns: (transfer none) (type GObject): @task's source object, or %NULL
+ * Since: 2.36
*/
/**
- * g_socket_send_with_blocking:
- * @socket: a #GSocket
- * @buffer: (array length=size): 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
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_task_get_source_tag:
+ * @task: a #GTask
*
- * This behaves exactly the same as g_socket_send(), except that
- * the choice of blocking or non-blocking behavior is determined by
- * the @blocking argument rather than by @socket's properties.
+ * Gets @task's source tag. See g_task_set_source_tag().
*
- * on error
+ * Returns: (transfer none): @task's source tag
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_get_task_data:
+ * @task: a #GTask
*
- * Returns: Number of bytes written (which may be less than @size), or -1
- * Since: 2.26
+ * Gets @task's `task_data`.
+ *
+ * Returns: (transfer none): @task's `task_data`.
+ * Since: 2.36
*/
/**
- * g_socket_service_is_active:
- * @service: a #GSocketService
+ * g_task_had_error:
+ * @task: a #GTask.
*
- * Check whether the service is active or not. An active
- * service will accept new clients that connect, while
- * a non-active service will let connecting clients queue
- * up until the service is started.
+ * Tests if @task resulted in an error.
*
- * Returns: %TRUE if the service is active, %FALSE otherwise
- * Since: 2.22
+ * Returns: %TRUE if the task resulted in an error, %FALSE otherwise.
+ * Since: 2.36
*/
/**
- * g_socket_service_new:
+ * 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
*
- * Creates a new #GSocketService with no sockets to listen for.
- * New listeners can be added with e.g. g_socket_listener_add_address()
- * or g_socket_listener_add_inet_port().
+ * 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: a new #GSocketService.
- * Since: 2.22
+ * Returns: %TRUE if @result and @source_object are valid, %FALSE
+ * if not
+ * Since: 2.36
*/
/**
- * g_socket_service_start:
- * @service: a #GSocketService
+ * 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.
*
- * Starts the service, i.e. start accepting connections
- * from the added sockets when the mainloop runs.
+ * 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].
*
- * This call is thread-safe, so it may be called from a thread
- * handling an incoming client request.
+ * 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().
*
- * Since: 2.22
+ * 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_socket_service_stop:
- * @service: a #GSocketService
+ * g_task_propagate_boolean:
+ * @task: a #GTask.
+ * @error: return location for a #GError
*
- * Stops the service, i.e. stops accepting connections
- * from the added sockets when the mainloop runs.
+ * Gets the result of @task as a #gboolean.
*
- * This call is thread-safe, so it may be called from a thread
- * handling an incoming client request.
+ * If the task resulted in an error, or was cancelled, then this will
+ * instead return %FALSE and set @error.
*
- * Since: 2.22
+ * 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_socket_set_blocking:
- * @socket: a #GSocket.
- * @blocking: Whether to use blocking I/O or not.
+ * g_task_propagate_int:
+ * @task: a #GTask.
+ * @error: return location for a #GError
*
- * Sets the blocking mode of the socket. In blocking mode
- * all operations block until they succeed or there is an error. In
- * non-blocking mode all functions return results immediately or
- * with a %G_IO_ERROR_WOULD_BLOCK error.
+ * Gets the result of @task as an integer (#gssize).
*
- * All sockets are created in blocking mode. However, note that the
- * platform level socket is always non-blocking, and blocking mode
- * is a GSocket level feature.
+ * If the task resulted in an error, or was cancelled, then this will
+ * instead return -1 and set @error.
*
- * Since: 2.22
+ * 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_socket_set_keepalive:
- * @socket: a #GSocket.
- * @keepalive: Value for the keepalive flag
+ * g_task_propagate_pointer:
+ * @task: a #GTask
+ * @error: return location for a #GError
*
- * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
- * this flag is set on a socket, the system will attempt to verify that the
- * remote socket endpoint is still present if a sufficiently long period of
- * time passes with no data being exchanged. If the system is unable to
- * verify the presence of the remote endpoint, it will automatically close
- * the connection.
+ * Gets the result of @task as a pointer, and transfers ownership
+ * of that value to the caller.
*
- * This option is only functional on certain kinds of sockets. (Notably,
- * %G_SOCKET_PROTOCOL_TCP sockets.)
+ * If the task resulted in an error, or was cancelled, then this will
+ * instead return %NULL and set @error.
*
- * The exact time between pings is system- and protocol-dependent, but will
- * normally be at least two hours. Most commonly, you would set this flag
- * on a server socket if you want to allow clients to remain idle for long
- * periods of time, but also want to ensure that connections are eventually
- * garbage-collected if clients crash or become unreachable.
+ * Since this method transfers ownership of the return value (or
+ * error) to the caller, you may only call it once.
*
- * Since: 2.22
+ * Returns: (transfer full): the task result, or %NULL on error
+ * Since: 2.36
*/
/**
- * g_socket_set_listen_backlog:
- * @socket: a #GSocket.
- * @backlog: the maximum number of pending connections.
+ * 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
*
- * Sets the maximum number of outstanding connections allowed
- * when listening on this socket. If more clients than this are
- * connecting to the socket and the application is not handling them
- * on time then the new connections will be refused.
+ * 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.
*
- * Note that this must be called before g_socket_listen() and has no
- * effect if called after that.
+ * See also g_task_report_new_error().
*
- * Since: 2.22
+ * Since: 2.36
*/
/**
- * g_socket_set_timeout:
- * @socket: a #GSocket.
- * @timeout: the timeout for @socket, in seconds, or 0 for none
- *
- * Sets the time in seconds after which I/O operations on @socket will
- * time out if they have not yet completed.
+ * 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.
*
- * On a blocking socket, this means that any blocking #GSocket
- * operation will time out after @timeout seconds of inactivity,
- * returning %G_IO_ERROR_TIMED_OUT.
+ * 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.
*
- * On a non-blocking socket, calls to g_socket_condition_wait() will
- * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
- * created with g_socket_create_source() will trigger after
- * @timeout seconds of inactivity, with the requested condition
- * set, at which point calling g_socket_receive(), g_socket_send(),
- * g_socket_check_connect_result(), etc, will fail with
- * %G_IO_ERROR_TIMED_OUT.
+ * See also g_task_report_error().
*
- * If @timeout is 0 (the default), operations will never time out
- * on their own.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_boolean:
+ * @task: a #GTask.
+ * @result: the #gboolean result of a task function.
*
- * Note that if an I/O operation is interrupted by a signal, this may
- * cause the timeout to be reset.
+ * 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.26
+ * Since: 2.36
*/
/**
- * g_socket_shutdown:
- * @socket: a #GSocket
- * @shutdown_read: whether to shut down the read side
- * @shutdown_write: whether to shut down the write side
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_task_return_error:
+ * @task: a #GTask.
+ * @error: (transfer full): the #GError result of a task function.
*
- * Shut down part of a full-duplex connection.
+ * 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).
*
- * If @shutdown_read is %TRUE then the receiving side of the connection
- * is shut down, and further reading is disallowed.
+ * 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.
*
- * If @shutdown_write is %TRUE then the sending side of the connection
- * is shut down, and further writing is disallowed.
+ * See also g_task_return_new_error().
*
- * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_error_if_cancelled:
+ * @task: a #GTask
*
- * One example where this is used is graceful disconnect for TCP connections
- * where you close the sending side, then wait for the other side to close
- * the connection, thus ensuring that the other side saw all sent data.
+ * Checks if @task's #GCancellable has been cancelled, and if so, sets
+ * @task's error accordingly and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
+ *
+ * Returns: %TRUE if @task has been cancelled, %FALSE if not
+ * Since: 2.36
+ */
+
+
+/**
+ * g_task_return_int:
+ * @task: a #GTask.
+ * @result: the integer (#gssize) result of a task function.
+ *
+ * Sets @task's result to @result and completes the task (see
+ * g_task_return_pointer() for more discussion of exactly what this
+ * means).
*
- * Returns: %TRUE on success, %FALSE on error
- * Since: 2.22
+ * Since: 2.36
*/
/**
- * g_socket_speaks_ipv4:
- * @socket: a #GSocket
- *
- * Checks if a socket is capable of speaking IPv4.
+ * 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.
*
- * IPv4 sockets are capable of speaking IPv4. On some operating systems
- * and under some combinations of circumstances IPv6 sockets are also
- * capable of speaking IPv4. See RFC 3493 section 3.7 for more
- * information.
+ * 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).
*
- * No other types of sockets are currently considered as being capable
- * of speaking IPv4.
+ * See also g_task_return_error().
*
- * Returns: %TRUE if this socket can be used with IPv4.
- * Since: 2.22
+ * Since: 2.36
*/
/**
- * g_srv_target_copy:
- * @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.
*
- * Copies @target
+ * 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: a copy of @target
- * 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_free:
- * @target: a #GSrvTarget
+ * g_task_run_in_thread:
+ * @task: a #GTask
+ * @task_func: a #GTaskThreadFunc
*
- * Frees @target
+ * Runs @task_func in another thread. When @task_func returns, @task's
+ * #GAsyncReadyCallback will be invoked in @task's #GMainContext.
*
- * 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_get_hostname:
- * @target: a #GSrvTarget
+ * g_task_run_in_thread_sync:
+ * @task: a #GTask
+ * @task_func: a #GTaskThreadFunc
*
- * 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.)
+ * 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: @target's hostname
- * 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_get_port:
- * @target: a #GSrvTarget
+ * g_task_set_check_cancellable:
+ * @task: the #GTask
+ * @check_cancellable: whether #GTask will check the state of
+ * its #GCancellable for you.
*
- * Gets @target's port
+ * 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.
*
- * Returns: @target's port
- * Since: 2.22
+ * If @check_cancellable is %FALSE, then the #GTask will not check the
+ * cancellable itself, and it is up to @task's owner to do this (eg,
+ * via g_task_return_error_if_cancelled()).
+ *
+ * If you are using g_task_set_return_on_cancel() as well, then
+ * you must leave check-cancellable set %TRUE.
+ *
+ * Since: 2.36
*/
/**
- * g_srv_target_get_priority:
- * @target: a #GSrvTarget
+ * g_task_set_priority:
+ * @task: the #GTask
+ * @priority: the [priority][io-priority] of the request
*
- * 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 priority. If you do not call this, it will default to
+ * %G_PRIORITY_DEFAULT.
*
- * Returns: @target's priority
- * Since: 2.22
+ * This will affect the priority of #GSources created with
+ * g_task_attach_source() and the scheduling of tasks run in threads,
+ * and can also be explicitly retrieved later via
+ * g_task_get_priority().
+ *
+ * Since: 2.36
*/
/**
- * g_srv_target_get_weight:
- * @target: a #GSrvTarget
+ * g_task_set_return_on_cancel:
+ * @task: the #GTask
+ * @return_on_cancel: whether the task returns automatically when
+ * it is cancelled.
*
- * Gets @target's weight. You should not need to look at this;
- * #GResolver already sorts the targets according to the algorithm in
- * RFC 2782.
+ * 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().
*
- * Returns: @target's weight
- * Since: 2.22
+ * If @return_on_cancel is %TRUE, then cancelling @task's
+ * #GCancellable will immediately cause it to return, as though the
+ * task's #GTaskThreadFunc had called
+ * g_task_return_error_if_cancelled() and then returned.
+ *
+ * This allows you to create a cancellable wrapper around an
+ * uninterruptable function. The #GTaskThreadFunc just needs to be
+ * careful that it does not modify any externally-visible state after
+ * it has been cancelled. To do that, the thread should call
+ * g_task_set_return_on_cancel() again to (atomically) set
+ * return-on-cancel %FALSE before making externally-visible changes;
+ * if the task gets cancelled before the return-on-cancel flag could
+ * be changed, g_task_set_return_on_cancel() will indicate this by
+ * returning %FALSE.
+ *
+ * You can disable and re-enable this flag multiple times if you wish.
+ * If the task's #GCancellable is cancelled while return-on-cancel is
+ * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE
+ * again will cause the task to be cancelled at that point.
+ *
+ * If the task's #GCancellable is already cancelled before you call
+ * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the
+ * #GTaskThreadFunc will still be run (for consistency), but the task
+ * will also be completed right away.
+ *
+ * Returns: %TRUE if @task's return-on-cancel flag was changed to
+ * match @return_on_cancel. %FALSE if @task has already been
+ * cancelled.
+ * Since: 2.36
*/
/**
- * g_srv_target_list_sort: (skip)
- * @targets: a #GList of #GSrvTarget
+ * g_task_set_source_tag:
+ * @task: the #GTask
+ * @source_tag: an opaque pointer indicating the source of this task
*
- * Sorts @targets in place according to the algorithm in RFC 2782.
+ * 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.
*
- * Returns: (transfer full): the head of the sorted list.
- * Since: 2.22
+ * 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
- *
- * Creates a new #GSrvTarget with the given parameters.
+ * g_task_set_task_data:
+ * @task: the #GTask
+ * @task_data: (allow-none): task-specific data
+ * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
*
- * You should not need to use this; normally #GSrvTarget<!-- -->s are
- * created by #GResolver.
+ * Sets @task's task data (freeing the existing task data, if any).
*
- * Returns: a new #GSrvTarget.
- * Since: 2.22
+ * 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.
*
/**
+ * g_test_dbus_add_service_dir:
+ * @self: a #GTestDBus
+ * @path: path to a directory containing .service files
+ *
+ * Add a path where dbus-daemon will look up .service files. This can't be
+ * called after g_test_dbus_up().
+ */
+
+
+/**
+ * g_test_dbus_down:
+ * @self: a #GTestDBus
+ *
+ * Stop the session bus started by g_test_dbus_up().
+ *
+ * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
+ * is destroyed. This is done to ensure that the next unit test won't get a
+ * leaked singleton from this test.
+ */
+
+
+/**
+ * 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
+ * been called yet, %NULL is returned. This can be used with
+ * g_dbus_connection_new_for_address().
+ *
+ * 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
+ */
+
+
+/**
+ * g_test_dbus_new:
+ * @flags: a #GTestDBusFlags
+ *
+ * Create a new #GTestDBus object.
+ *
+ * Returns: (transfer full): a new #GTestDBus.
+ */
+
+
+/**
+ * g_test_dbus_stop:
+ * @self: a #GTestDBus
+ *
+ * Stop the session bus started by g_test_dbus_up().
+ *
+ * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
+ * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
+ * tests wanting to verify behaviour after the session bus has been stopped
+ * can use this function but should still call g_test_dbus_down() when done.
+ */
+
+
+/**
+ * g_test_dbus_unset:
+ *
+ * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
+ * won't use user's session bus.
+ *
+ * This is useful for unit tests that want to verify behaviour when no session
+ * bus is running. It is not necessary to call this if unit test already calls
+ * g_test_dbus_up() before acquiring the session bus.
+ */
+
+
+/**
+ * g_test_dbus_up:
+ * @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 bus.
+ *
+ * If this function is called from setup callback of g_test_add(),
+ * g_test_dbus_down() must be called in its teardown callback.
+ *
+ * If this function is called from unit test's main(), then g_test_dbus_down()
+ * must be called after g_test_run().
+ */
+
+
+/**
* g_themed_icon_append_name:
* @icon: a #GThemedIcon
* @iconname: name of icon to append to list of icons from within @icon.
*
* 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>
*/
*
* Creates a new themed icon for @iconname.
*
- * Returns: (transfer full): a new #GThemedIcon.
+ * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
*/
/**
* 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.
*
- * Returns: (transfer full): a new #GThemedIcon
+ * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
*/
* 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",
- * "gnome-dev",
- * "gnome"
+ * "gnome-dev-cdrom-audio",
+ * "gnome-dev-cdrom",
+ * "gnome-dev",
+ * "gnome"
* };
*
* icon1 = g_themed_icon_new_from_names (names, 4);
* icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
* ]|
*
- * Returns: (transfer full): a new #GThemedIcon.
+ * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
*/
*
* 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.
*
- * implementation.
- *
* Returns: the #GType of @backend's #GTlsCertificate
+ * implementation.
* Since: 2.28
*/
*
* Gets the #GType of @backend's #GTlsClientConnection implementation.
*
- * implementation.
- *
* Returns: the #GType of @backend's #GTlsClientConnection
+ * implementation.
* Since: 2.28
*/
*
* Gets the default #GTlsDatabase used to verify TLS connections.
*
- * unreffed when done.
- *
* Returns: (transfer full): the default database, which should be
+ * unreffed when done.
* Since: 2.30
*/
* g_tls_backend_get_file_database_type:
* @backend: the #GTlsBackend
*
- * Gets the #GTyep of @backend's #GTlsFileDatabase implementation.
+ * Gets the #GType of @backend's #GTlsFileDatabase implementation.
*
* Returns: the #GType of backend's #GTlsFileDatabase implementation.
* Since: 2.30
*
* Gets the #GType of @backend's #GTlsServerConnection implementation.
*
- * 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,
* 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
* 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
* 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
* 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): 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.
*
- * %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.
*
- * notification.
- *
* Returns: %TRUE if @conn requires a proper TLS close
+ * notification.
* Since: 2.28
*/
/**
* g_tls_connection_handshake:
* @conn: a #GTlsConnection
- * @cancellable: a #GCancellable, or %NULL
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
* @error: a #GError, or %NULL
*
* Attempts a TLS handshake on @conn.
/**
* g_tls_connection_handshake_async:
* @conn: a #GTlsConnection
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
- * @cancellable: a #GCancellable, or %NULL
+ * @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.
*
- * 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
*/
*
* Lookup a certificate by its handle.
*
- * The handle should have been created by calling g_tls_database_create_handle()
- * on a #GTlsDatabase object of the same TLS backend. The handle is designed
- * to remain valid across instantiations of the database.
+ * The handle should have been created by calling
+ * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+ * the same TLS backend. The handle is designed to remain valid across
+ * instantiations of the database.
*
* If the handle is no longer valid, or does not point to a certificate in
* this database, then %NULL will be returned.
* This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
* the lookup operation asynchronously.
*
- * #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
*/
* @user_data: the data to pass to the callback function
*
* Asynchronously lookup a certificate by its handle in the database. See
- * g_tls_database_lookup_handle() for more information.
+ * g_tls_database_lookup_certificate_for_handle() for more information.
*
* Since: 2.30
*/
* @error: a #GError pointer, or %NULL
*
* Finish an asynchronous lookup of a certificate by its handle. See
- * g_tls_database_lookup_handle() for more information.
+ * g_tls_database_lookup_certificate_handle() for more information.
*
* If the handle is no longer valid, or does not point to a certificate in
* this database, then %NULL will be returned.
*
- * 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.
*
- * 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.
*
- * 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.
*
- * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
- *
- * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects.
+ * 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.
*
- * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
- *
- * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects.
+ * 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.
*
- * 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. *
- * 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): the new #GTlsFileDatabase, or %NULL on error
+ * Returns: (transfer full) (type GTlsFileDatabase): the new
+ * #GTlsFileDatabase, or %NULL on error
* Since: 2.30
*/
* is called by called by #GTlsConnection or #GTlsDatabase to ask the user
* for a password.
*
- * Derived subclasses usually implement a password prompt, although they may
- * also choose to provide a password from elsewhere. The @password value will
- * be filled in and then @callback will be called. Alternatively the user may
- * abort this password request, which will usually abort the TLS connection.
+ * Derived subclasses usually implement a password prompt, although they may
+ * also choose to provide a password from elsewhere. The @password value will
+ * be filled in and then @callback will be called. Alternatively the user may
+ * abort this password request, which will usually 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 ask password interaction.
+ * 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.
*
- * 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 %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. Certain implementations may
- * not support immediate cancellation.
+ * contains a %G_IO_ERROR_CANCELLED error code.
*
- * Returns: The status of the ask password interaction.
- * Since: 2.30
+ * Returns: The status of the request certificate interaction.
+ * Since: 2.40
*/
* @password: a #GTlsPassword object
* @length: (allow-none): location to place the length of the password.
*
- * Get the password value. If @length is not %NULL then it will be filled
- * in with the length of the password value.
+ * Get the password value. If @length is not %NULL then it will be
+ * filled in with the length of the password value. (Note that the
+ * password value is not nul-terminated, so you can only pass %NULL
+ * for @length in contexts where you know the password will have a
+ * certain fixed length.)
*
- * Returns: The password value owned by the password object.
+ * Returns: The password value (owned by the password object).
* Since: 2.30
*/
* Set the value for this password. The @value will be copied by the password
* object.
*
- * Specify the @length, for a non-null-terminated password. Pass -1 as
- * @length if using a null-terminated password, and @length will be calculated
- * automatically.
+ * Specify the @length, for a non-nul-terminated password. Pass -1 as
+ * @length if using a nul-terminated password, and @length will be
+ * calculated automatically. (Note that the terminating nul is not
+ * considered part of the password in this case.)
*
* Since: 2.30
*/
/**
- * 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
* The @value will be owned by the password object, and later freed using
* the @destroy function callback.
*
- * Specify the @length, for a non-null-terminated password. Pass -1 as
- * @length if using a null-terminated password, and @length will be calculated
- * automatically.
+ * Specify the @length, for a non-nul-terminated password. Pass -1 as
+ * @length if using a nul-terminated password, and @length will be
+ * calculated automatically. (Note that the terminating nul is not
+ * considered part of the password in this case.)
*
* Since: 2.30
*/
* Creates a new #GTlsServerConnection wrapping @base_io_stream (which
* must have pollable input and output streams).
*
- * Returns: (transfer full): the new #GTlsServerConnection, or %NULL on error
+ * Returns: (transfer full) (type GTlsServerConnection): the new
+ * #GTlsServerConnection, or %NULL on error
* Since: 2.28
*/
/**
- * g_try_new:
- * @struct_type: the type of the elements to allocate
- * @n_structs: the number of elements to allocate
- *
- * Attempts to allocate @n_structs elements of type @struct_type, and returns
- * %NULL on failure. Contrast with g_new(), which aborts the program on failure.
- * The returned pointer is cast to a pointer to the given type.
- * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
- *
- * Since: 2.8
- * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
- */
-
-
-/**
- * g_try_new0:
- * @struct_type: the type of the elements to allocate
- * @n_structs: the number of elements to allocate
- *
- * Attempts to allocate @n_structs elements of type @struct_type, initialized
- * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
- * the program on failure.
- * The returned pointer is cast to a pointer to the given type.
- * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
- *
- * Since: 2.8
- * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
- */
-
-
-/**
- * g_try_renew:
- * @struct_type: the type of the elements to allocate
- * @mem: the currently allocated memory
- * @n_structs: the number of elements to allocate
- *
- * Attempts to reallocate the memory pointed to by @mem, so that it now has
- * space for @n_structs elements of type @struct_type, and returns %NULL on
- * failure. Contrast with g_renew(), which aborts the program on failure.
- * It returns the new address of the memory, which may have been moved.
- * The function returns %NULL if an overflow occurs.
- *
- * Since: 2.8
- * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
- */
-
-
-/**
* g_unix_connection_receive_credentials:
* @connection: A #GUnixConnection.
* @cancellable: (allow-none): A #GCancellable or %NULL.
* Other ways to exchange credentials with a foreign peer includes the
* #GUnixCredentialsMessage type and g_socket_get_credentials() function.
*
- * 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
*/
/**
+ * g_unix_connection_receive_credentials_async:
+ * @connection: A #GUnixConnection.
+ * @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 receive credentials.
+ *
+ * For more details, see g_unix_connection_receive_credentials() which is
+ * the synchronous version of this call.
+ *
+ * When the operation is finished, @callback will be called. You can then call
+ * g_unix_connection_receive_credentials_finish() to get the result of the operation.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_unix_connection_receive_credentials_finish:
+ * @connection: A #GUnixConnection.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL
+ *
+ * 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().
+ * Since: 2.32
+ */
+
+
+/**
* g_unix_connection_receive_fd:
* @connection: a #GUnixConnection
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
/**
+ * g_unix_connection_send_credentials_async:
+ * @connection: A #GUnixConnection.
+ * @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 send credentials.
+ *
+ * For more details, see g_unix_connection_send_credentials() which is
+ * the synchronous version of this call.
+ *
+ * When the operation is finished, @callback will be called. You can then call
+ * g_unix_connection_send_credentials_finish() to get the result of the operation.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_unix_connection_send_credentials_finish:
+ * @connection: A #GUnixConnection.
+ * @result: a #GAsyncResult.
+ * @error: a #GError, or %NULL
+ *
+ * Finishes an asynchronous send credentials operation started with
+ * g_unix_connection_send_credentials_async().
+ *
+ * Returns: %TRUE if the operation was successful, otherwise %FALSE.
+ * Since: 2.32
+ */
+
+
+/**
* g_unix_connection_send_fd:
* @connection: a #GUnixConnection
* @fd: a file descriptor
* this index with g_unix_fd_list_get() then you will receive back a
* duplicated copy of the same file descriptor.
*
- * (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.
*
- * 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.
*
- * 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.
*
- * 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.
*
- * of the OS.
- *
* Returns: %TRUE if @mount_path is considered an implementation detail
+ * of the OS.
*/
*
* Compares two unix mounts.
*
- * or less than @mount2, respectively.
- *
* Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
+ * or less than @mount2, respectively.
*/
/**
* g_unix_mount_free:
- * @mount_entry: a #GUnixMount.
+ * @mount_entry: a #GUnixMountEntry.
*
* Frees a unix mount.
*/
* Guesses the name of a Unix mount.
* The result is a translated string.
*
- * 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.
*
- * 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.
*
- * 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().
*
- * 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().
*
- * 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.
*
/**
- * g_utf8_next_char:
- * @p: Pointer to the start of a valid UTF-8 character
- *
- * Skips to the next character in a UTF-8 string. The string must be
- * valid; this macro is as fast as possible, and has no error-checking.
- * You would use this macro to iterate over a string character by
- * character. The macro returns the start of the next UTF-8 character.
- * Before using this macro, use g_utf8_validate() to validate strings
- * that may contain invalid UTF-8.
- */
-
-
-/**
* g_vfs_get_default:
*
* Gets the default #GVfs for the system.
*
* Gets a #GFile for @path.
*
- * 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.
*
- * 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.
*
- * 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.
*
- * 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: 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_identifer() to obtain
- * the identifiers themselves.
- *
- * of strings containing kinds of identifiers. Use g_strfreev() to free.
+ * 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.
*/
* either be equal or a prefix of what this function returns. In
* other words, in code
*
- * <programlisting>
- * GMount *mount;
- * GFile *mount_root
- * GFile *volume_activation_root;
- *
- * 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>
+ * |[<!-- language="C" -->
+ * GMount *mount;
+ * GFile *mount_root
+ * GFile *volume_activation_root;
*
+ * 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
+ * ]|
* then the expression
- *
- * <programlisting>
- * (g_file_has_prefix (volume_activation_root, mount_root) ||
- * </programlisting>
- *
+ * |[<!-- language="C" -->
+ * (g_file_has_prefix (volume_activation_root, mount_root) ||
+ * g_file_equal (volume_activation_root, mount_root))
+ * ]|
* 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.
*
- * g_object_unref() to free.
- *
- * Returns: (transfer full): the activation root of @volume or %NULL. Use
+ * 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.
*
- * 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.
+ * 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.
*
- * 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.
- *
- * requested identfier, or %NULL if the #GVolume
- * doesn't have this kind of identifier
+ * 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
*/
/**
* g_volume_get_mount:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
*
* Gets the mount for the @volume.
*
- * 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.
*
- * 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.
*
- * 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
- * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
*/
*
* Gets the volume monitor used by gio.
*
- * 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())
*
- * 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())
*
- * 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.
- */
-
-
-/**
- * g_warn_if_fail:
- * @expr: the expression to check
- *
- * Logs a warning if the expression is not true.
- *
- * Since: 2.16
- */
-
-
-/**
- * g_warn_if_reached:
- *
- * Logs a critical warning.
- *
- * Since: 2.16
+ * Returns: %TRUE if the volume should be automatically mounted
*/
/**
* g_win32_input_stream_new:
* @handle: a Win32 file handle
- * @close_fd: %TRUE to close the handle when done
+ * @close_handle: %TRUE to close the handle when done
*
- * Creates a new #GWin32InputStream for the given @fd.
+ * Creates a new #GWin32InputStream for the given @handle.
*
* If @close_handle is %TRUE, the handle will be closed
* when the stream is closed.
/**
- * gchararray:
- *
- * A C representable type name for #G_TYPE_STRING.
- */
-
-
-/**
- * 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
- *
- * to handle @mime_type.
- *
- * Returns: a #GList containing the desktop ids which claim
- */
-
-
-/**
- * gunichar:
- *
- * A type which can hold any UTF-32 or UCS-4 character code,
- * also known as a Unicode code point.
- *
- * If you want to produce the UTF-8 representation of a #gunichar,
- * use g_ucs4_to_utf8(). See also g_utf8_to_ucs4() for the reverse
- * process.
- *
- * To print/scan values of this type as integer, use
- * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
- *
- * The notation to express a Unicode code point in running text is
- * as a hexadecimal number with four to six digits and uppercase
- * letters, prefixed by the string "U+". Leading zeros are omitted,
- * unless the code point would have fewer than four hexadecimal digits.
- * For example, "U+0041 LATIN CAPITAL LETTER A". To print a code point
- * in the U+-notation, use the format string "U+\%04"G_GINT32_FORMAT"X".
- * To scan, use the format string "U+\%06"G_GINT32_FORMAT"X".
- *
- * |[
- * gunichar c;
- * sscanf ("U+0041", "U+%06"G_GINT32_FORMAT"X", &c)
- * g_print ("Read U+%04"G_GINT32_FORMAT"X", c);
- * ]|
- */
-
-
-/**
- * gunichar2:
- *
- * A type which can hold any UTF-16 code
- * point<footnote id="utf16_surrogate_pairs">UTF-16 also has so called
- * <firstterm>surrogate pairs</firstterm> to encode characters beyond
- * the BMP as pairs of 16bit numbers. Surrogate pairs cannot be stored
- * in a single gunichar2 field, but all GLib functions accepting gunichar2
- * arrays will correctly interpret surrogate pairs.</footnote>.
- *
- * To print/scan values of this type to/from text you need to convert
- * to/from UTF-8, using g_utf16_to_utf8()/g_utf8_to_utf16().
+ * get_viewable_logical_drives:
*
- * To print/scan values of this type as integer, use
- * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
- */
-
-
-/**
- * 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