From 0d40f8413c59605114eb3325a6e07668ad5b0b9a Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 12 Feb 2018 15:30:38 +0100 Subject: Revert "Update the GLib annotations" This reverts commit 96c2e06aa661d37ad1cdf31825bbb921125357ae. --- gir/gio-2.0.c | 43516 ++++++++++++++++++++++++++++------------------------ gir/glib-2.0.c | 168 +- gir/gobject-2.0.c | 488 +- 3 files changed, 23757 insertions(+), 20415 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 068dbd9c..ecdb2cf2 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2366,9 +2366,13 @@ /** * GNetworkMonitor::network-changed: * @monitor: a #GNetworkMonitor - * @network_available: the current value of #GNetworkMonitor:network-available + * @available: the current value of #GNetworkMonitor:network-available * - * Emitted when the network configuration changes. + * 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.32 */ @@ -3563,20 +3567,18 @@ /** * GTlsClientConnection:use-ssl3: * - * If %TRUE, forces the connection to use a fallback version of TLS + * 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. + * handshake at all with a "modern" TLS handshake. * - * Despite the property name, the fallback version is usually not - * SSL 3.0, because SSL 3.0 is generally disabled by the #GTlsBackend. - * #GTlsClientConnection will use the next-highest available version - * as the fallback version. + * 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 - * Deprecated: 2.56: SSL 3.0 is insecure, and this property does not - * generally enable or disable it, despite its name. */ @@ -4203,6 +4205,462 @@ */ +/** + * GXdpDocuments: + * + * Abstract interface type for the D-Bus interface org.freedesktop.portal.Documents. + */ + + +/** + * GXdpDocuments::handle-add: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @arg_o_path_fd: Argument passed by remote caller. + * @arg_reuse_existing: Argument passed by remote caller. + * @arg_persistent: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the Add() 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 gxdp_documents_complete_add() 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. + */ + + +/** + * GXdpDocuments::handle-add-full: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @arg_o_path_fds: Argument passed by remote caller. + * @arg_flags: Argument passed by remote caller. + * @arg_app_id: Argument passed by remote caller. + * @arg_permissions: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the AddFull() 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 gxdp_documents_complete_add_full() 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. + */ + + +/** + * GXdpDocuments::handle-add-named: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @arg_o_path_parent_fd: Argument passed by remote caller. + * @arg_filename: Argument passed by remote caller. + * @arg_reuse_existing: Argument passed by remote caller. + * @arg_persistent: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the AddNamed() 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 gxdp_documents_complete_add_named() 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. + */ + + +/** + * GXdpDocuments::handle-delete: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the Delete() 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 gxdp_documents_complete_delete() 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. + */ + + +/** + * GXdpDocuments::handle-get-mount-point: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the GetMountPoint() 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 gxdp_documents_complete_get_mount_point() 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. + */ + + +/** + * GXdpDocuments::handle-grant-permissions: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * @arg_app_id: Argument passed by remote caller. + * @arg_permissions: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the GrantPermissions() 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 gxdp_documents_complete_grant_permissions() 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. + */ + + +/** + * GXdpDocuments::handle-info: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the Info() 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 gxdp_documents_complete_info() 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. + */ + + +/** + * GXdpDocuments::handle-list: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_app_id: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the List() 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 gxdp_documents_complete_list() 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. + */ + + +/** + * GXdpDocuments::handle-lookup: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_filename: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the Lookup() 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 gxdp_documents_complete_lookup() 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. + */ + + +/** + * GXdpDocuments::handle-revoke-permissions: + * @object: A #GXdpDocuments. + * @invocation: A #GDBusMethodInvocation. + * @arg_doc_id: Argument passed by remote caller. + * @arg_app_id: Argument passed by remote caller. + * @arg_permissions: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the RevokePermissions() 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 gxdp_documents_complete_revoke_permissions() 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. + */ + + +/** + * GXdpDocuments:version: + * + * Represents the D-Bus property "version". + * + * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side. + */ + + +/** + * GXdpDocumentsIface: + * @parent_iface: The parent interface. + * @handle_add: Handler for the #GXdpDocuments::handle-add signal. + * @handle_add_full: Handler for the #GXdpDocuments::handle-add-full signal. + * @handle_add_named: Handler for the #GXdpDocuments::handle-add-named signal. + * @handle_delete: Handler for the #GXdpDocuments::handle-delete signal. + * @handle_get_mount_point: Handler for the #GXdpDocuments::handle-get-mount-point signal. + * @handle_grant_permissions: Handler for the #GXdpDocuments::handle-grant-permissions signal. + * @handle_info: Handler for the #GXdpDocuments::handle-info signal. + * @handle_list: Handler for the #GXdpDocuments::handle-list signal. + * @handle_lookup: Handler for the #GXdpDocuments::handle-lookup signal. + * @handle_revoke_permissions: Handler for the #GXdpDocuments::handle-revoke-permissions signal. + * @get_version: Getter for the #GXdpDocuments:version property. + * + * Virtual table for the D-Bus interface org.freedesktop.portal.Documents. + */ + + +/** + * GXdpDocumentsProxy: + * + * The #GXdpDocumentsProxy structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpDocumentsProxyClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpDocumentsProxy. + */ + + +/** + * GXdpDocumentsSkeleton: + * + * The #GXdpDocumentsSkeleton structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpDocumentsSkeletonClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpDocumentsSkeleton. + */ + + +/** + * GXdpNetworkMonitor: + * + * Abstract interface type for the D-Bus interface org.freedesktop.portal.NetworkMonitor. + */ + + +/** + * GXdpNetworkMonitor::changed: + * @object: A #GXdpNetworkMonitor. + * @arg_available: Argument. + * + * On the client-side, this signal is emitted whenever the D-Bus signal "changed" 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. + */ + + +/** + * GXdpNetworkMonitor:available: + * + * Represents the D-Bus property "available". + * + * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side. + */ + + +/** + * GXdpNetworkMonitor:connectivity: + * + * Represents the D-Bus property "connectivity". + * + * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side. + */ + + +/** + * GXdpNetworkMonitor:metered: + * + * Represents the D-Bus property "metered". + * + * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side. + */ + + +/** + * GXdpNetworkMonitorIface: + * @parent_iface: The parent interface. + * @get_available: Getter for the #GXdpNetworkMonitor:available property. + * @get_connectivity: Getter for the #GXdpNetworkMonitor:connectivity property. + * @get_metered: Getter for the #GXdpNetworkMonitor:metered property. + * @changed: Handler for the #GXdpNetworkMonitor::changed signal. + * + * Virtual table for the D-Bus interface org.freedesktop.portal.NetworkMonitor. + */ + + +/** + * GXdpNetworkMonitorProxy: + * + * The #GXdpNetworkMonitorProxy structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpNetworkMonitorProxyClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpNetworkMonitorProxy. + */ + + +/** + * GXdpNetworkMonitorSkeleton: + * + * The #GXdpNetworkMonitorSkeleton structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpNetworkMonitorSkeletonClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpNetworkMonitorSkeleton. + */ + + +/** + * GXdpOpenURI: + * + * Abstract interface type for the D-Bus interface org.freedesktop.portal.OpenURI. + */ + + +/** + * GXdpOpenURI::handle-open-file: + * @object: A #GXdpOpenURI. + * @invocation: A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @arg_parent_window: Argument passed by remote caller. + * @arg_fd: Argument passed by remote caller. + * @arg_options: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the OpenFile() 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 gxdp_open_uri_complete_open_file() 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. + */ + + +/** + * GXdpOpenURI::handle-open-uri: + * @object: A #GXdpOpenURI. + * @invocation: A #GDBusMethodInvocation. + * @arg_parent_window: Argument passed by remote caller. + * @arg_uri: Argument passed by remote caller. + * @arg_options: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the OpenURI() 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 gxdp_open_uri_complete_open_uri() 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. + */ + + +/** + * GXdpOpenURI:version: + * + * Represents the D-Bus property "version". + * + * Since the D-Bus property for this #GObject property is readable but not writable, it is meaningful to read from it on both the client- and service-side. It is only meaningful, however, to write to it on the service-side. + */ + + +/** + * GXdpOpenURIIface: + * @parent_iface: The parent interface. + * @handle_open_file: Handler for the #GXdpOpenURI::handle-open-file signal. + * @handle_open_uri: Handler for the #GXdpOpenURI::handle-open-uri signal. + * @get_version: Getter for the #GXdpOpenURI:version property. + * + * Virtual table for the D-Bus interface org.freedesktop.portal.OpenURI. + */ + + +/** + * GXdpOpenURIProxy: + * + * The #GXdpOpenURIProxy structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpOpenURIProxyClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpOpenURIProxy. + */ + + +/** + * GXdpOpenURISkeleton: + * + * The #GXdpOpenURISkeleton structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpOpenURISkeletonClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpOpenURISkeleton. + */ + + +/** + * GXdpProxyResolver: + * + * Abstract interface type for the D-Bus interface org.freedesktop.portal.ProxyResolver. + */ + + +/** + * GXdpProxyResolver::handle-lookup: + * @object: A #GXdpProxyResolver. + * @invocation: A #GDBusMethodInvocation. + * @arg_uri: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the Lookup() 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 gxdp_proxy_resolver_complete_lookup() 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. + */ + + +/** + * GXdpProxyResolverIface: + * @parent_iface: The parent interface. + * @handle_lookup: Handler for the #GXdpProxyResolver::handle-lookup signal. + * + * Virtual table for the D-Bus interface org.freedesktop.portal.ProxyResolver. + */ + + +/** + * GXdpProxyResolverProxy: + * + * The #GXdpProxyResolverProxy structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpProxyResolverProxyClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpProxyResolverProxy. + */ + + +/** + * GXdpProxyResolverSkeleton: + * + * The #GXdpProxyResolverSkeleton structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * GXdpProxyResolverSkeletonClass: + * @parent_class: The parent class. + * + * Class structure for #GXdpProxyResolverSkeleton. + */ + + /** * GZlibCompressor: * @@ -4274,6 +4732,51 @@ */ +/** + * SECTION:GXdpDocuments + * @title: GXdpDocuments + * @short_description: Generated C code for the org.freedesktop.portal.Documents D-Bus interface + * + * This section contains code for working with the org.freedesktop.portal.Documents D-Bus interface in C. + */ + + +/** + * SECTION:GXdpNetworkMonitor + * @title: GXdpNetworkMonitor + * @short_description: Generated C code for the org.freedesktop.portal.NetworkMonitor D-Bus interface + * + * This section contains code for working with the org.freedesktop.portal.NetworkMonitor D-Bus interface in C. + */ + + +/** + * SECTION:GXdpOpenURI + * @title: GXdpOpenURI + * @short_description: Generated C code for the org.freedesktop.portal.OpenURI D-Bus interface + * + * This section contains code for working with the org.freedesktop.portal.OpenURI D-Bus interface in C. + */ + + +/** + * SECTION:GXdpProxyResolver + * @title: GXdpProxyResolver + * @short_description: Generated C code for the org.freedesktop.portal.ProxyResolver D-Bus interface + * + * This section contains code for working with the org.freedesktop.portal.ProxyResolver D-Bus interface in C. + */ + + +/** + * SECTION:_GFreedesktopDBus + * @title: _GFreedesktopDBus + * @short_description: Generated C code for the org.freedesktop.DBus D-Bus interface + * + * This section contains code for working with the org.freedesktop.DBus D-Bus interface in C. + */ + + /** * SECTION:extensionpoints * @short_description: Extension Points @@ -5316,9 +5819,6 @@ * 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). - * - * TCP D-Bus connections are supported, but accessing them via a proxy is - * currently not supported. */ @@ -5774,7 +6274,7 @@ * both well-known and unique names. * * By default, #GDBusProxy will cache all properties (and listen to - * changes) of the remote object, and proxy all signals that get + * 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 @@ -9657,6 +10157,341 @@ */ +/** + * _GFreedesktopDBus: + * + * Abstract interface type for the D-Bus interface org.freedesktop.DBus. + */ + + +/** + * _GFreedesktopDBus::handle-add-match: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_rule: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the AddMatch() 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_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. + */ + + +/** + * _GFreedesktopDBus::handle-get-connection-selinux-security-context: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_name: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the GetConnectionSELinuxSecurityContext() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _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 GetConnectionUnixProcessID() 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_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: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _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 GetConnectionUnixUser() 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_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 if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-get-id: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the GetId() 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_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 if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-get-name-owner: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_name: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the GetNameOwner() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-hello: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the Hello() 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_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. + */ + + +/** + * _GFreedesktopDBus::handle-list-activatable-names: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the ListActivatableNames() 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_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. + */ + + +/** + * _GFreedesktopDBus::handle-list-names: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the ListNames() 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_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. + */ + + +/** + * _GFreedesktopDBus::handle-list-queued-owners: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_name: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the ListQueuedOwners() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-name-has-owner: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_name: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the NameHasOwner() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-release-name: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_name: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the ReleaseName() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-reload-config: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * + * Signal emitted when a remote caller is invoking the ReloadConfig() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-remove-match: + * @object: A #_GFreedesktopDBus. + * @invocation: A #GDBusMethodInvocation. + * @arg_rule: Argument passed by remote caller. + * + * Signal emitted when a remote caller is invoking the RemoveMatch() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::handle-request-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 RequestName() 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_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. + */ + + +/** + * _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 StartServiceByName() 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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _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 UpdateActivationEnvironment() 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_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. + * + * Returns: %TRUE if the invocation was handled, %FALSE to let other signal handlers run. + */ + + +/** + * _GFreedesktopDBus::name-acquired: + * @object: A #_GFreedesktopDBus. + * @arg_name: Argument. + * + * On the client-side, this signal is emitted whenever the D-Bus signal "NameAcquired" 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. + */ + + +/** + * _GFreedesktopDBus::name-lost: + * @object: A #_GFreedesktopDBus. + * @arg_name: Argument. + * + * On the client-side, this signal is emitted whenever the D-Bus signal "NameLost" 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. + */ + + +/** + * _GFreedesktopDBus::name-owner-changed: + * @object: A #_GFreedesktopDBus. + * @arg_name: Argument. + * @arg_old_owner: Argument. + * @arg_new_owner: Argument. + * + * On the client-side, this signal is emitted whenever the D-Bus signal "NameOwnerChanged" 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. + */ + + +/** + * _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. + * + * Virtual table for the D-Bus interface org.freedesktop.DBus. + */ + + +/** + * _GFreedesktopDBusProxy: + * + * The #_GFreedesktopDBusProxy structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * _GFreedesktopDBusProxyClass: + * @parent_class: The parent class. + * + * Class structure for #_GFreedesktopDBusProxy. + */ + + +/** + * _GFreedesktopDBusSkeleton: + * + * The #_GFreedesktopDBusSkeleton structure contains only private data and should only be accessed using the provided API. + */ + + +/** + * _GFreedesktopDBusSkeletonClass: + * @parent_class: The parent class. + * + * Class structure for #_GFreedesktopDBusSkeleton. + */ + + /** * _g_dbus_initialize: * @@ -9867,6558 +10702,8620 @@ /** - * _g_io_module_extract_name: - * @filename: filename of a GIOModule + * _g_freedesktop_dbus_call_add_match: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_rule: Argument to pass with the method invocation. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * Extract the plugin name from its filename. It removes optional "lib" or - * "libgio" prefix, and removes everything after the first dot. For example: - * "libgiognutls.so" -> "gnutls". + * Asynchronously invokes the AddMatch() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Returns: (transfer full): the module's name + * See _g_freedesktop_dbus_call_add_match_sync() for the synchronous, blocking version of this method. */ /** - * _g_io_module_get_default: - * @extension_point: the name of an extension point - * @envvar: (nullable): the name of an environment variable to - * override the default implementation. - * @verify_func: (nullable): a function to call to verify that - * a given implementation is usable in the current environment. + * _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. * - * Retrieves the default object implementing @extension_point. + * Finishes an operation started with _g_freedesktop_dbus_call_add_match(). * - * 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. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_add_match_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_rule: Argument to pass with the method invocation. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * 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. + * Synchronously invokes the AddMatch() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * The result is cached after it is generated the first time, and - * the function is thread-safe. + * See _g_freedesktop_dbus_call_add_match() for the asynchronous version of this method. * - * Returns: (transfer none): an object implementing - * @extension_point, or %NULL if there are no usable - * implementations. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * _g_io_module_get_default_type: - * @extension_point: the name of an extension point - * @envvar: (nullable): the name of an environment variable to - * override the default implementation. - * @is_supported_offset: a vtable offset, or zero - * - * Retrieves the default class implementing @extension_point. + * _g_freedesktop_dbus_call_get_connection_selinux_security_context: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 @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. + * Asynchronously invokes the GetConnectionSELinuxSecurityContext() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * 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. + * See _g_freedesktop_dbus_call_get_connection_selinux_security_context_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _g_freedesktop_dbus_call_get_connection_selinux_security_context_finish: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_security_context: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_selinux_security_context(). + * @error: Return location for error or %NULL. * - * The result is cached after it is generated the first time, and - * the function is thread-safe. + * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_selinux_security_context(). * - * Returns: (transfer none): an object implementing - * @extension_point, or %NULL if there are no usable - * implementations. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * _g_poll_file_monitor_new: - * @file: a #GFile. + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Polls @file for changes. + * Synchronously invokes the GetConnectionSELinuxSecurityContext() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: a new #GFileMonitor for the given #GFile. + * 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_action_activate: - * @action: a #GAction - * @parameter: (nullable): the parameter to the activation + * _g_freedesktop_dbus_call_get_connection_unix_process_id: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * Activates the action. + * Asynchronously invokes the GetConnectionUnixProcessID() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * @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. + * See _g_freedesktop_dbus_call_get_connection_unix_process_id_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _g_freedesktop_dbus_call_get_connection_unix_process_id_finish: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_pid: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_get_connection_unix_process_id(). + * @error: Return location for error or %NULL. * - * If the @parameter GVariant is floating, it is consumed. + * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_process_id(). * - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_change_state: - * @action: a #GAction - * @value: the new state + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Request for the state of @action to be changed to @value. + * Synchronously invokes the GetConnectionUnixProcessID() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * The action must be stateful and @value must be of the correct type. - * See g_action_get_state_type(). + * See _g_freedesktop_dbus_call_get_connection_unix_process_id() for the asynchronous version of this method. * - * 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(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_get_connection_unix_user: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 the @value GVariant is floating, it is consumed. + * Asynchronously invokes the GetConnectionUnixUser() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Since: 2.30 + * See _g_freedesktop_dbus_call_get_connection_unix_user_sync() for the synchronous, blocking version of this method. */ /** - * g_action_get_enabled: - * @action: a #GAction - * - * Checks if @action is currently enabled. + * _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. * - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. + * Finishes an operation started with _g_freedesktop_dbus_call_get_connection_unix_user(). * - * Returns: whether the action is enabled - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_get_name: - * @action: a #GAction + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Queries the name of @action. + * Synchronously invokes the GetConnectionUnixUser() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: the name of the action - * Since: 2.28 + * 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_action_get_parameter_type: - * @action: a #GAction + * _g_freedesktop_dbus_call_get_id: + * @proxy: A #_GFreedesktopDBusProxy. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * Queries the type of the parameter that must be given when activating - * @action. + * Asynchronously invokes the GetId() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * When activating the action using g_action_activate(), the #GVariant - * given to that function must be of the type returned by this function. + * See _g_freedesktop_dbus_call_get_id_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _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. * - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. + * Finishes an operation started with _g_freedesktop_dbus_call_get_id(). * - * Returns: (nullable): the parameter type - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_get_state: - * @action: a #GAction - * - * Queries the current state of @action. + * _g_freedesktop_dbus_call_get_id_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_unique_id: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * 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(). + * Synchronously invokes the GetId() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * See _g_freedesktop_dbus_call_get_id() for the asynchronous version of this method. * - * Returns: (transfer full): the current state of the action - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_get_state_hint: - * @action: a #GAction + * _g_freedesktop_dbus_call_get_name_owner: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * Requests a hint about the valid range of values for the state of - * @action. + * Asynchronously invokes the GetNameOwner() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * 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. + * See _g_freedesktop_dbus_call_get_name_owner_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _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. * - * 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. + * Finishes an operation started with _g_freedesktop_dbus_call_get_name_owner(). * - * 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: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * Synchronously invokes the GetNameOwner() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: (nullable) (transfer full): the state range hint - * Since: 2.28 + * 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_action_get_state_type: - * @action: a #GAction + * _g_freedesktop_dbus_call_hello: + * @proxy: A #_GFreedesktopDBusProxy. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * Queries the type of the state of @action. + * Asynchronously invokes the Hello() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * 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. + * See _g_freedesktop_dbus_call_hello_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _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. * - * 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(). + * Finishes an operation started with _g_freedesktop_dbus_call_hello(). * - * Returns: (nullable): the state type, if the action is stateful - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_group_action_added: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group + * _g_freedesktop_dbus_call_hello_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Emits the #GActionGroup::action-added signal on @action_group. + * Synchronously invokes the Hello() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * This function should only be called by #GActionGroup implementations. + * See _g_freedesktop_dbus_call_hello() for the asynchronous version of this method. * - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * 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_freedesktop_dbus_call_list_activatable_names: + * @proxy: A #_GFreedesktopDBusProxy. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * This function should only be called by #GActionGroup implementations. + * Asynchronously invokes the ListActivatableNames() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Since: 2.28 + * See _g_freedesktop_dbus_call_list_activatable_names_sync() for the synchronous, blocking version of this method. */ /** - * 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_freedesktop_dbus_call_list_activatable_names_finish: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_activatable_names: (out) (array zero-terminated=1): 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. * - * This function should only be called by #GActionGroup implementations. + * Finishes an operation started with _g_freedesktop_dbus_call_list_activatable_names(). * - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * 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 + * _g_freedesktop_dbus_call_list_activatable_names_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_activatable_names: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Emits the #GActionGroup::action-state-changed signal on @action_group. + * Synchronously invokes the ListActivatableNames() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * This function should only be called by #GActionGroup implementations. + * See _g_freedesktop_dbus_call_list_activatable_names() for the asynchronous version of this method. * - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_group_activate_action: - * @action_group: a #GActionGroup - * @action_name: the name of the action to activate - * @parameter: (nullable): parameters to the activation - * - * Activate the named action within @action_group. + * _g_freedesktop_dbus_call_list_names: + * @proxy: A #_GFreedesktopDBusProxy. + * @cancellable: (nullable): 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 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(). + * Asynchronously invokes the ListNames() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Since: 2.28 + * See _g_freedesktop_dbus_call_list_names_sync() for the synchronous, blocking version of this method. */ /** - * 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 + * _g_freedesktop_dbus_call_list_names_finish: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_names: (out) (array zero-terminated=1): 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. * - * Request for the state of the named action within @action_group to be - * changed to @value. + * Finishes an operation started with _g_freedesktop_dbus_call_list_names(). * - * The action must be stateful and @value must be of the correct type. - * See g_action_group_get_action_state_type(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_list_names_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_names: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * 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(). + * Synchronously invokes the ListNames() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * If the @value GVariant is floating, it is consumed. + * See _g_freedesktop_dbus_call_list_names() for the asynchronous version of this method. * - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * 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_freedesktop_dbus_call_list_queued_owners: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 action must be enabled in order to be activated or in order to - * have its state changed from outside callers. + * Asynchronously invokes the ListQueuedOwners() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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: whether or not the action is currently enabled - * Since: 2.28 + * See _g_freedesktop_dbus_call_list_queued_owners_sync() for the synchronous, blocking version of this method. */ /** - * g_action_group_get_action_parameter_type: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query + * _g_freedesktop_dbus_call_list_queued_owners_finish: + * @proxy: A #_GFreedesktopDBusProxy. + * @out_queued_owners: (out) (array zero-terminated=1): 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. * - * Queries the type of the parameter that must be given when activating - * the named action within @action_group. + * Finishes an operation started with _g_freedesktop_dbus_call_list_queued_owners(). * - * 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. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_list_queued_owners_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @out_queued_owners: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. + * Synchronously invokes the ListQueuedOwners() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * 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. + * See _g_freedesktop_dbus_call_list_queued_owners() for the asynchronous version of this method. * - * Returns: (nullable): the parameter type - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * 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_freedesktop_dbus_call_name_has_owner: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * Asynchronously invokes the NameHasOwner() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Returns: (nullable): the current state of the action - * Since: 2.28 + * See _g_freedesktop_dbus_call_name_has_owner_sync() for the synchronous, blocking version of this method. */ /** - * g_action_group_get_action_state_hint: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query + * _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. * - * Requests a hint about the valid range of values for the state of the - * named action within @action_group. + * Finishes an operation started with _g_freedesktop_dbus_call_name_has_owner(). * - * 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 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_group_get_action_state_type: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Queries the type of the state of the named action within - * @action_group. + * Synchronously invokes the NameHasOwner() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * 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. + * See _g_freedesktop_dbus_call_name_has_owner() for the asynchronous version of this method. * - * 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(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_release_name: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_name: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 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. + * Asynchronously invokes the ReleaseName() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Returns: (nullable): the state type, if the action is stateful - * Since: 2.28 + * See _g_freedesktop_dbus_call_release_name_sync() for the synchronous, blocking version of this method. */ /** - * g_action_group_has_action: - * @action_group: a #GActionGroup - * @action_name: the name of the action to check for + * _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. * - * Checks if the named action exists within @action_group. + * Finishes an operation started with _g_freedesktop_dbus_call_release_name(). * - * Returns: whether the named action exists - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_group_list_actions: - * @action_group: a #GActionGroup + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Lists the actions contained within @action_group. + * Synchronously invokes the ReleaseName() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * The caller is responsible for freeing the list with g_strfreev() when - * it is no longer required. + * See _g_freedesktop_dbus_call_release_name() for the asynchronous version of this method. * - * Returns: (transfer full): a %NULL-terminated array of the names of the - * actions in the group - * Since: 2.28 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * 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) (optional): the parameter type, or %NULL if none needed - * @state_type: (out) (optional): the state type, or %NULL if stateless - * @state_hint: (out) (optional): the state hint, or %NULL if none - * @state: (out) (optional): the current state, or %NULL if stateless + * _g_freedesktop_dbus_call_reload_config: + * @proxy: A #_GFreedesktopDBusProxy. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * Queries all aspects of the named action within an @action_group. + * Asynchronously invokes the ReloadConfig() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * 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. + * See _g_freedesktop_dbus_call_reload_config_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _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. * - * This provides two main benefits. + * Finishes an operation started with _g_freedesktop_dbus_call_reload_config(). * - * 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. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_reload_config_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * 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. + * Synchronously invokes the ReloadConfig() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * 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. + * See _g_freedesktop_dbus_call_reload_config() for the asynchronous version of this method. * - * Returns: %TRUE if the action exists, else %FALSE - * Since: 2.32 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_map_add_action: - * @action_map: a #GActionMap - * @action: a #GAction - * - * 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. + * _g_freedesktop_dbus_call_remove_match: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_rule: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 action map takes its own reference on @action. + * Asynchronously invokes the RemoveMatch() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Since: 2.32 + * See _g_freedesktop_dbus_call_remove_match_sync() for the synchronous, blocking version of this method. */ /** - * 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 - * - * A convenience function for creating multiple #GSimpleAction instances - * and adding them to a #GActionMap. + * _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. * - * Each action is constructed as per one #GActionEntry. + * Finishes an operation started with _g_freedesktop_dbus_call_remove_match(). * - * |[ - * static void - * activate_quit (GSimpleAction *simple, - * GVariant *parameter, - * gpointer user_data) - * { - * exit (0); - * } + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_remove_match_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_rule: Argument to pass with the method invocation. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * static void - * activate_print_string (GSimpleAction *simple, - * GVariant *parameter, - * gpointer user_data) - * { - * g_print ("%s\n", g_variant_get_string (parameter, NULL)); - * } + * Synchronously invokes the RemoveMatch() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * static GActionGroup * - * create_action_group (void) - * { - * const GActionEntry entries[] = { - * { "quit", activate_quit }, - * { "print-string", activate_print_string, "s" } - * }; - * GSimpleActionGroup *group; + * See _g_freedesktop_dbus_call_remove_match() for the asynchronous version of this method. * - * group = g_simple_action_group_new (); - * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _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: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL. + * @user_data: User data to pass to @callback. * - * return G_ACTION_GROUP (group); - * } - * ]| + * Asynchronously invokes the RequestName() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Since: 2.32 + * See _g_freedesktop_dbus_call_request_name_sync() for the synchronous, blocking version of this method. */ /** - * 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_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. * - * If no such action exists, returns %NULL. + * Finishes an operation started with _g_freedesktop_dbus_call_request_name(). * - * Returns: (transfer none): a #GAction, or %NULL - * Since: 2.32 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_map_remove_action: - * @action_map: a #GActionMap - * @action_name: the name of the action + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Removes the named action from the action map. + * Synchronously invokes the RequestName() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * If no action of this name is in the map then nothing happens. + * See _g_freedesktop_dbus_call_request_name() for the asynchronous version of this method. * - * Since: 2.32 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_name_is_valid: - * @action_name: an potential action name + * _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: (nullable): 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 if @action_name is valid. + * Asynchronously invokes the StartServiceByName() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * @action_name is valid if it consists only of alphanumeric characters, - * plus '-' and '.'. The empty string is not a valid action name. + * See _g_freedesktop_dbus_call_start_service_by_name_sync() for the synchronous, blocking version of this method. + */ + + +/** + * _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. * - * It is an error to call this function with a non-utf8 @action_name. - * @action_name must not be %NULL. + * Finishes an operation started with _g_freedesktop_dbus_call_start_service_by_name(). * - * Returns: %TRUE if @action_name is valid - * Since: 2.38 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_action_parse_detailed_name: - * @detailed_name: a detailed action name - * @action_name: (out): the action name - * @target_value: (out): the target value, or %NULL for no target - * @error: a pointer to a %NULL #GError, or %NULL - * - * Parses a detailed action name into its separate name and target - * components. + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Detailed action names can have three formats. + * Synchronously invokes the StartServiceByName() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * 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". + * See _g_freedesktop_dbus_call_start_service_by_name() for the asynchronous version of this method. * - * 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". + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_update_activation_environment: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_environment: Argument to pass with the method invocation. + * @cancellable: (nullable): 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 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 '.'. + * Asynchronously invokes the UpdateActivationEnvironment() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Returns: %TRUE if successful, else %FALSE with @error set - * Since: 2.38 + * See _g_freedesktop_dbus_call_update_activation_environment_sync() for the synchronous, blocking version of this method. */ /** - * g_action_print_detailed_name: - * @action_name: a valid action name - * @target_value: (nullable): a #GVariant target value, or %NULL + * _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. * - * Formats a detailed action name from @action_name and @target_value. + * Finishes an operation started with _g_freedesktop_dbus_call_update_activation_environment(). * - * It is an error to call this function with an invalid action name. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * _g_freedesktop_dbus_call_update_activation_environment_sync: + * @proxy: A #_GFreedesktopDBusProxy. + * @arg_environment: Argument to pass with the method invocation. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * This function is the opposite of g_action_parse_detailed_name(). - * It will produce a string that can be parsed back to the @action_name - * and @target_value by that function. + * Synchronously invokes the UpdateActivationEnvironment() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * See that function for the types of strings that will be printed by - * this function. + * See _g_freedesktop_dbus_call_update_activation_environment() for the asynchronous version of this method. * - * Returns: a detailed format string - * Since: 2.38 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_app_info_add_supports_type: - * @appinfo: a #GAppInfo. - * @content_type: a string. - * @error: a #GError. + * _g_freedesktop_dbus_complete_add_match: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Adds a content type to the application information to indicate the - * application is capable of opening files with the given content type. + * Helper function used in service implementations to finish handling invocations of the AddMatch() 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. * - * Returns: %TRUE on success, %FALSE on error. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_can_delete: - * @appinfo: a #GAppInfo + * _g_freedesktop_dbus_complete_get_connection_selinux_security_context: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @security_context: Parameter to return. * - * Obtains the information whether the #GAppInfo can be deleted. - * See g_app_info_delete(). + * Helper function used in service implementations to finish handling invocations of the GetConnectionSELinuxSecurityContext() 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. * - * Returns: %TRUE if @appinfo can be deleted - * Since: 2.20 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_can_remove_supports_type: - * @appinfo: a #GAppInfo. + * _g_freedesktop_dbus_complete_get_connection_unix_process_id: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @pid: Parameter to return. * - * Checks if a supported content type can be removed from an application. + * Helper function used in service implementations to finish handling invocations of the GetConnectionUnixProcessID() 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. * - * Returns: %TRUE if it is possible to remove supported - * content types from a given @appinfo, %FALSE if not. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_create_from_commandline: - * @commandline: (type filename): the commandline to use - * @application_name: (nullable): 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. - * - * Creates a new #GAppInfo from the given information. + * _g_freedesktop_dbus_complete_get_connection_unix_user: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @uid: Parameter to return. * - * 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. + * Helper function used in service implementations to finish handling invocations of the GetConnectionUnixUser() 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. * - * Returns: (transfer full): new #GAppInfo for given command. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_delete: (virtual do_delete) - * @appinfo: a #GAppInfo - * - * Tries to delete a #GAppInfo. + * _g_freedesktop_dbus_complete_get_id: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @unique_id: Parameter to return. * - * 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(). + * Helper function used in service implementations to finish handling invocations of the GetId() 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. * - * Returns: %TRUE if @appinfo has been deleted - * Since: 2.20 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_dup: - * @appinfo: a #GAppInfo. + * _g_freedesktop_dbus_complete_get_name_owner: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @unique_name: Parameter to return. * - * Creates a duplicate of a #GAppInfo. + * Helper function used in service implementations to finish handling invocations of the GetNameOwner() 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. * - * Returns: (transfer full): a duplicate of @appinfo. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_equal: - * @appinfo1: the first #GAppInfo. - * @appinfo2: the second #GAppInfo. - * - * Checks if two #GAppInfos are equal. + * _g_freedesktop_dbus_complete_hello: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @assigned_name: Parameter to return. * - * Note that the check may not compare each individual - * field, and only does an identity check. In case detecting changes in the - * contents is needed, program code must additionally compare relevant fields. + * Helper function used in service implementations to finish handling invocations of the Hello() 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. * - * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_all: - * - * Gets a list of all of the applications currently registered - * on this system. + * _g_freedesktop_dbus_complete_list_activatable_names: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @activatable_names: Parameter to return. * - * 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. + * Helper function used in service implementations to finish handling invocations of the ListActivatableNames() 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. * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_all_for_type: - * @content_type: the content type to find a #GAppInfo for + * _g_freedesktop_dbus_complete_list_names: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @names: Parameter to return. * - * 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(). + * Helper function used in service implementations to finish handling invocations of the ListNames() 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. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * for given @content_type or %NULL on error. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_commandline: - * @appinfo: a #GAppInfo + * _g_freedesktop_dbus_complete_list_queued_owners: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @queued_owners: Parameter to return. * - * Gets the commandline with which the application will be - * started. + * Helper function used in service implementations to finish handling invocations of the ListQueuedOwners() 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. * - * Returns: (type filename): a string containing the @appinfo's commandline, - * or %NULL if this information is not available - * Since: 2.20 + * This method will free @invocation, you cannot use it afterwards. */ /** - * 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 + * _g_freedesktop_dbus_complete_name_has_owner: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @has_owner: Parameter to return. * - * Gets the default #GAppInfo for a given content type. + * Helper function used in service implementations to finish handling invocations of the NameHasOwner() 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. * - * Returns: (transfer full): #GAppInfo for given @content_type or - * %NULL on error. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_default_for_uri_scheme: - * @uri_scheme: a string containing a URI scheme. + * _g_freedesktop_dbus_complete_release_name: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @value: Parameter to return. * - * 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". + * Helper function used in service implementations to finish handling invocations of the ReleaseName() 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. * - * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_description: - * @appinfo: a #GAppInfo. + * _g_freedesktop_dbus_complete_reload_config: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Gets a human-readable description of an installed application. + * Helper function used in service implementations to finish handling invocations of the ReloadConfig() 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. * - * Returns: a string containing a description of the - * application @appinfo, or %NULL if none. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_display_name: - * @appinfo: a #GAppInfo. + * _g_freedesktop_dbus_complete_remove_match: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Gets the display name of the application. The display name is often more - * descriptive to the user than the name itself. + * Helper function used in service implementations to finish handling invocations of the RemoveMatch() 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. * - * Returns: the display name of the application for @appinfo, or the name if - * no display name is available. - * Since: 2.24 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_executable: - * @appinfo: a #GAppInfo + * _g_freedesktop_dbus_complete_request_name: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @value: Parameter to return. * - * Gets the executable's name for the installed application. + * Helper function used in service implementations to finish handling invocations of the RequestName() 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. * - * Returns: (type filename): a string containing the @appinfo's application - * binaries name + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_fallback_for_type: - * @content_type: the content type to find a #GAppInfo for + * _g_freedesktop_dbus_complete_start_service_by_name: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @value: Parameter to return. * - * 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. + * Helper function used in service implementations to finish handling invocations of the StartServiceByName() 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. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * for given @content_type or %NULL on error. - * Since: 2.28 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_icon: - * @appinfo: a #GAppInfo. + * _g_freedesktop_dbus_complete_update_activation_environment: + * @object: A #_GFreedesktopDBus. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Gets the icon for the application. + * Helper function used in service implementations to finish handling invocations of the UpdateActivationEnvironment() 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. * - * Returns: (transfer none): the default #GIcon for @appinfo or %NULL - * if there is no default icon. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_app_info_get_id: - * @appinfo: a #GAppInfo. - * - * 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. + * _g_freedesktop_dbus_emit_name_acquired: + * @object: A #_GFreedesktopDBus. + * @arg_name: Argument to pass with the signal. * - * Note that the returned ID may be %NULL, depending on how - * the @appinfo has been constructed. - * - * Returns: a string containing the application's ID. + * Emits the "NameAcquired" D-Bus signal. */ /** - * g_app_info_get_name: - * @appinfo: a #GAppInfo. - * - * Gets the installed name of the application. + * _g_freedesktop_dbus_emit_name_lost: + * @object: A #_GFreedesktopDBus. + * @arg_name: Argument to pass with the signal. * - * Returns: the name of the application for @appinfo. + * Emits the "NameLost" D-Bus signal. */ /** - * 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_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. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * for given @content_type or %NULL on error. - * Since: 2.28 + * Emits the "NameOwnerChanged" D-Bus signal. */ /** - * g_app_info_get_supported_types: - * @appinfo: a #GAppInfo that can handle files + * _g_freedesktop_dbus_interface_info: * - * 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. + * Gets a machine-readable description of the org.freedesktop.DBus D-Bus interface. * - * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): - * a list of content types. - * Since: 2.34 + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. */ /** - * g_app_info_launch: - * @appinfo: a #GAppInfo - * @files: (nullable) (element-type GFile): a #GList of #GFile objects - * @context: (nullable): a #GAppLaunchContext or %NULL - * @error: a #GError - * - * Launches the application. Passes @files to the launched application - * as arguments, using the optional @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. + * _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. * - * 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. + * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class. + * The properties are overridden in the order they are defined. * - * 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. + * Returns: The last property id. + */ + + +/** + * _g_freedesktop_dbus_proxy_new: + * @connection: A #GDBusConnection. + * @flags: Flags from the #GDBusProxyFlags enumeration. + * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + * @object_path: An object path. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: User data to pass to @callback. * - * 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(). + * Asynchronously creates a proxy for the D-Bus interface org.freedesktop.DBus. See g_dbus_proxy_new() for more details. * - * 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 @context. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * See _g_freedesktop_dbus_proxy_new_sync() for the synchronous, blocking version of this constructor. */ /** - * g_app_info_launch_default_for_uri: - * @uri: the uri to show - * @context: (nullable): an optional #GAppLaunchContext - * @error: (nullable): return location for an error, or %NULL + * _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 * - * 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. + * Finishes an operation started with _g_freedesktop_dbus_proxy_new(). * - * Returns: %TRUE on success, %FALSE on error. + * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_app_info_launch_default_for_uri_async: - * @uri: the uri to show - * @context: (nullable): an optional #GAppLaunchContext - * @cancellable: (nullable): a #GCancellable - * @callback: (nullable): a #GASyncReadyCallback to call when the request is done - * @user_data: (nullable): data to pass to @callback + * _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: (nullable): A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: User data to pass to @callback. * - * Async version of g_app_info_launch_default_for_uri(). + * Like _g_freedesktop_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * This version is useful if you are interested in receiving - * error information in the case where the application is - * sandboxed and the portal may present an application chooser - * dialog to the user. + * When the operation is finished, @callback will be invoked in the thread-default main loop 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. * - * Since: 2.50 + * See _g_freedesktop_dbus_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor. */ /** - * g_app_info_launch_default_for_uri_finish: - * @result: a #GAsyncResult - * @error: (nullable): return location for an error, or %NULL + * _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 * - * Finishes an asynchronous launch-default-for-uri operation. + * Finishes an operation started with _g_freedesktop_dbus_proxy_new_for_bus(). * - * Returns: %TRUE if the launch was successful, %FALSE if @error is set - * Since: 2.50 + * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_app_info_launch_uris: - * @appinfo: a #GAppInfo - * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch. - * @context: (nullable): a #GAppLaunchContext or %NULL - * @error: a #GError + * _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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL * - * Launches the application. This passes the @uris to the launched application - * as arguments, using the optional @context to get information - * about the details of the launcher (like what screen it is on). - * On error, @error will be set accordingly. + * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * To launch the application without arguments pass a %NULL @uris list. + * The calling thread is blocked until a reply is received. * - * 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. + * See _g_freedesktop_dbus_proxy_new_for_bus() for the asynchronous version of this constructor. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_app_info_monitor_get: + * _g_freedesktop_dbus_proxy_new_sync: + * @connection: A #GDBusConnection. + * @flags: Flags from the #GDBusProxyFlags enumeration. + * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + * @object_path: An object path. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL * - * Gets the #GAppInfoMonitor for the current thread-default main - * context. + * Synchronously creates a proxy for the D-Bus interface org.freedesktop.DBus. See g_dbus_proxy_new_sync() for more details. * - * 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. + * The calling thread is blocked until a reply is received. * - * You must only call g_object_unref() on the return value from under - * the same main context as you created it. + * See _g_freedesktop_dbus_proxy_new() for the asynchronous version of this constructor. * - * Returns: (transfer full): a reference to a #GAppInfoMonitor - * Since: 2.40 + * Returns: (transfer full) (type _GFreedesktopDBusProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_app_info_remove_supports_type: - * @appinfo: a #GAppInfo. - * @content_type: a string. - * @error: a #GError. + * _g_freedesktop_dbus_skeleton_new: * - * Removes a supported type from an application, if possible. + * Creates a skeleton object for the D-Bus interface org.freedesktop.DBus. * - * Returns: %TRUE on success, %FALSE on error. + * Returns: (transfer full) (type _GFreedesktopDBusSkeleton): The skeleton object. */ /** - * g_app_info_reset_type_associations: - * @content_type: a content type + * _g_io_module_extract_name: + * @filename: filename of a GIOModule * - * 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(). + * Extract the plugin name from its filename. It removes optional "lib" or + * "libgio" prefix, and removes everything after the first dot. For example: + * "libgiognutls.so" -> "gnutls". * - * Since: 2.20 + * Returns: (transfer full): the module's name */ /** - * g_app_info_set_as_default_for_extension: - * @appinfo: a #GAppInfo. - * @extension: (type filename): a string containing the file extension - * (without the dot). - * @error: a #GError. + * _g_io_module_get_default: + * @extension_point: the name of an extension point + * @envvar: (nullable): the name of an environment variable to + * override the default implementation. + * @verify_func: (nullable): a function to call to verify that + * a given implementation is usable in the current environment. * - * Sets the application as the default handler for the given file extension. + * Retrieves the default object implementing @extension_point. * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_set_as_default_for_type: - * @appinfo: a #GAppInfo. - * @content_type: the content type. - * @error: a #GError. + * 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. * - * Sets the application as the default handler for a given type. + * 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. * - * Returns: %TRUE on success, %FALSE on error. + * The result is cached after it is generated the first time, and + * the function is thread-safe. + * + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. */ /** - * g_app_info_set_as_last_used_for_type: - * @appinfo: a #GAppInfo. - * @content_type: the content type. - * @error: a #GError. + * _g_io_module_get_default_type: + * @extension_point: the name of an extension point + * @envvar: (nullable): the name of an environment variable to + * override the default implementation. + * @is_supported_offset: a vtable offset, or zero * - * 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. + * Retrieves the default class implementing @extension_point. * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_should_show: - * @appinfo: a #GAppInfo. + * 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. * - * Checks if the application info should be shown in menus that - * list available applications. + * 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. * - * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. + * The result is cached after it is generated the first time, and + * the function is thread-safe. + * + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. */ /** - * g_app_info_supports_files: - * @appinfo: a #GAppInfo. + * _g_poll_file_monitor_new: + * @file: a #GFile. * - * Checks if the application accepts files as arguments. + * Polls @file for changes. * - * Returns: %TRUE if the @appinfo supports files. + * Returns: a new #GFileMonitor for the given #GFile. */ /** - * g_app_info_supports_uris: - * @appinfo: a #GAppInfo. + * g_action_activate: + * @action: a #GAction + * @parameter: (nullable): the parameter to the activation * - * Checks if the application supports reading files and directories from URIs. + * Activates the action. * - * Returns: %TRUE if the @appinfo supports URIs. - */ - - -/** - * g_app_launch_context_get_display: - * @context: a #GAppLaunchContext - * @info: a #GAppInfo - * @files: (element-type GFile): a #GList of #GFile objects + * @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. * - * 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. + * If the @parameter GVariant is floating, it is consumed. * - * Returns: a display string for the display. + * Since: 2.28 */ /** - * g_app_launch_context_get_environment: - * @context: a #GAppLaunchContext + * g_action_change_state: + * @action: a #GAction + * @value: the new state * - * 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`. + * Request for the state of @action to be changed to @value. * - * Returns: (array zero-terminated=1) (element-type filename) (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 + * The action must be stateful and @value must be of the correct type. + * See g_action_get_state_type(). * - * Initiates startup notification for the application and returns the - * `DESKTOP_STARTUP_ID` for the launched operation, if supported. + * 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(). * - * Startup notification IDs are defined in the - * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"). + * If the @value GVariant is floating, it is consumed. * - * Returns: a startup notification ID for the application, or %NULL if - * not supported. + * Since: 2.30 */ /** - * 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_action_get_enabled: + * @action: a #GAction * - * 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(). - */ - - -/** - * g_app_launch_context_new: + * Checks if @action is currently enabled. * - * Creates a new application launch context. This is not normally used, - * instead you instantiate a subclass of this, such as #GdkAppLaunchContext. + * An action must be enabled in order to be activated or in order to + * have its state changed from outside callers. * - * Returns: a #GAppLaunchContext. + * Returns: whether the action is enabled + * Since: 2.28 */ /** - * g_app_launch_context_setenv: - * @context: a #GAppLaunchContext - * @variable: (type filename): the environment variable to set - * @value: (type filename): the value for to set the variable to. + * g_action_get_name: + * @action: a #GAction * - * Arranges for @variable to be set to @value in the child's - * environment when @context is used to launch an application. + * Queries the name of @action. * - * Since: 2.32 + * Returns: the name of the action + * Since: 2.28 */ /** - * g_app_launch_context_unsetenv: - * @context: a #GAppLaunchContext - * @variable: (type filename): the environment variable to remove + * g_action_get_parameter_type: + * @action: a #GAction * - * Arranges for @variable to be unset in the child's environment - * when @context is used to launch an application. + * Queries the type of the parameter that must be given when activating + * @action. * - * Since: 2.32 + * When activating the action using g_action_activate(), 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. + * + * Returns: (nullable): the parameter type + * Since: 2.28 */ /** - * g_application_activate: - * @application: a #GApplication + * g_action_get_state: + * @action: a #GAction * - * Activates the application. + * Queries the current state of @action. * - * In essence, this results in the #GApplication::activate signal being - * emitted in the primary instance. + * 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(). * - * The application must be registered before calling this function. + * The return value (if non-%NULL) should be freed with + * g_variant_unref() when it is no longer required. * + * Returns: (transfer full): the current state of the action * Since: 2.28 */ /** - * 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 + * g_action_get_state_hint: + * @action: a #GAction * - * Add an option to be handled by @application. + * Requests a hint about the valid range of values for the state of + * @action. * - * 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. + * 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. * - * 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. + * 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. * - * See #GOptionEntry for more documentation of the arguments. + * 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. * - * Since: 2.42 + * 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 */ /** - * g_application_add_main_option_entries: - * @application: a #GApplication - * @entries: (array zero-terminated=1) (element-type GOptionEntry): a - * %NULL-terminated list of #GOptionEntrys - * - * Adds main option entries to be handled by @application. - * - * This function is comparable to g_option_context_add_main_entries(). - * - * After the commandline arguments are parsed, the - * #GApplication::handle-local-options signal will be emitted. At this - * point, the application can inspect the values pointed to by @arg_data - * in the given #GOptionEntrys. - * - * Unlike #GOptionContext, #GApplication supports giving a %NULL - * @arg_data for a non-callback #GOptionEntry. This results in the - * argument in question being packed into a #GVariantDict which is also - * passed to #GApplication::handle-local-options, where it can be - * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is - * set, then the resulting dictionary is sent to the primary instance, - * where g_application_command_line_get_options_dict() will return it. - * This "packing" is done according to the type of the argument -- - * booleans for normal flags, strings for strings, bytestrings for - * filenames, etc. The packing only occurs if the flag is given (ie: we - * do not pack a "false" #GVariant in the case that a flag is missing). - * - * In general, it is recommended that all commandline arguments are - * parsed locally. The options dictionary should then be used to - * transmit the result of the parsing to the primary instance, where - * g_variant_dict_lookup() can be used. For local options, it is - * possible to either use @arg_data in the usual way, or to consult (and - * potentially remove) the option from the options dictionary. + * g_action_get_state_type: + * @action: a #GAction * - * 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. + * Queries the type of the state of @action. * - * 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). + * 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. * - * It is important to use the proper GVariant format when retrieving - * the options with g_variant_dict_lookup(): - * - for %G_OPTION_ARG_NONE, use b - * - for %G_OPTION_ARG_STRING, use &s - * - for %G_OPTION_ARG_INT, use i - * - for %G_OPTION_ARG_INT64, use x - * - for %G_OPTION_ARG_DOUBLE, use d - * - for %G_OPTION_ARG_FILENAME, use ^ay - * - for %G_OPTION_ARG_STRING_ARRAY, use &as - * - for %G_OPTION_ARG_FILENAME_ARRAY, use ^aay + * 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(). * - * Since: 2.40 + * Returns: (nullable): the state type, if the action is stateful + * Since: 2.28 */ /** - * g_application_add_option_group: - * @application: the #GApplication - * @group: (transfer full): a #GOptionGroup - * - * Adds a #GOptionGroup to the commandline handling of @application. - * - * This function is comparable to g_option_context_add_group(). - * - * Unlike g_application_add_main_option_entries(), this function does - * not deal with %NULL @arg_data and never transmits options to the - * primary instance. - * - * The reason for that is because, by the time the options arrive at the - * primary instance, it is typically too late to do anything with them. - * Taking the GTK option group as an example: GTK will already have been - * initialised by the time the #GApplication::command-line handler runs. - * In the case that this is not the first-running instance of the - * application, the existing instance may already have been running for - * a very long time. + * g_action_group_action_added: + * @action_group: a #GActionGroup + * @action_name: the name of an action in the group * - * 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. + * Emits the #GActionGroup::action-added signal on @action_group. * - * 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. + * This function should only be called by #GActionGroup implementations. * - * Since: 2.40 + * Since: 2.28 */ /** - * g_application_bind_busy_property: - * @application: a #GApplication - * @object: (type GObject.Object): a #GObject - * @property: the name of a boolean property of @object + * 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 * - * Marks @application as busy (see g_application_mark_busy()) while - * @property on @object is %TRUE. + * Emits the #GActionGroup::action-enabled-changed signal on @action_group. * - * The binding holds a reference to @application while it is active, but - * not to @object. Instead, the binding is destroyed when @object is - * finalized. + * This function should only be called by #GActionGroup implementations. * - * Since: 2.44 + * Since: 2.28 */ /** - * g_application_command_line_create_file_for_arg: - * @cmdline: a #GApplicationCommandLine - * @arg: (type filename): an argument from @cmdline + * g_action_group_action_removed: + * @action_group: a #GActionGroup + * @action_name: the name of an action in the group * - * Creates a #GFile corresponding to a filename that was given as part - * of the invocation of @cmdline. + * Emits the #GActionGroup::action-removed signal on @action_group. * - * 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. + * This function should only be called by #GActionGroup implementations. * - * Returns: (transfer full): a new #GFile - * Since: 2.36 + * Since: 2.28 */ /** - * g_application_command_line_get_arguments: - * @cmdline: a #GApplicationCommandLine - * @argc: (out) (optional): the length of the arguments array, or %NULL - * - * Gets the list of arguments that was passed on the command line. - * - * The strings in the array may contain non-UTF-8 data on UNIX (such as - * filenames or arguments given in the system locale) but are always in - * UTF-8 on Windows. + * 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 * - * If you wish to use the return value with #GOptionContext, you must - * use g_option_context_parse_strv(). + * Emits the #GActionGroup::action-state-changed signal on @action_group. * - * The return value is %NULL-terminated and should be freed using - * g_strfreev(). + * This function should only be called by #GActionGroup implementations. * - * Returns: (array length=argc) (element-type filename) (transfer full): - * the string array containing the arguments (the argv) * Since: 2.28 */ /** - * 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_action_group_activate_action: + * @action_group: a #GActionGroup + * @action_name: the name of the action to activate + * @parameter: (nullable): parameters to the activation * - * It is possible that the remote application did not send a working - * directory, so this may be %NULL. + * Activate the named action within @action_group. * - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. + * 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(). * - * Returns: (nullable) (type filename): the current directory, or %NULL * Since: 2.28 */ /** - * g_application_command_line_get_environ: - * @cmdline: a #GApplicationCommandLine + * 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 * - * 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. + * Request for the state of the named action within @action_group to be + * changed to @value. * - * 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 action must be stateful and @value must be of the correct type. + * See g_action_group_get_action_state_type(). * - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. + * 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(). * - * See g_application_command_line_getenv() if you are only interested - * in the value of a single environment variable. + * If the @value GVariant is floating, it is consumed. * - * Returns: (array zero-terminated=1) (element-type filename) (transfer none): - * the environment strings, or %NULL if they were not sent * Since: 2.28 */ /** - * g_application_command_line_get_exit_status: - * @cmdline: a #GApplicationCommandLine - * - * Gets the exit status of @cmdline. See - * g_application_command_line_set_exit_status() for more information. + * g_action_group_get_action_enabled: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Returns: the exit status - * Since: 2.28 - */ - - -/** - * g_application_command_line_get_is_remote: - * @cmdline: a #GApplicationCommandLine + * Checks if the named action within @action_group is currently enabled. * - * Determines if @cmdline represents a remote invocation. + * An action must be enabled in order to be activated or in order to + * have its state changed from outside callers. * - * Returns: %TRUE if the invocation was remote + * Returns: whether or not the action is currently enabled * Since: 2.28 */ /** - * g_application_command_line_get_options_dict: - * @cmdline: a #GApplicationCommandLine + * g_action_group_get_action_parameter_type: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Gets the options there were passed to g_application_command_line(). + * Queries the type of the parameter that must be given when activating + * the named action within @action_group. * - * 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. + * 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. * - * If no options were sent then an empty dictionary is returned so that - * you don't need to check for %NULL. + * In the case that this function returns %NULL, you must not give any + * #GVariant, but %NULL instead. * - * Returns: (transfer none): a #GVariantDict with the options - * Since: 2.40 + * 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 */ /** - * g_application_command_line_get_platform_data: - * @cmdline: #GApplicationCommandLine + * g_action_group_get_action_state: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Gets the platform data associated with the invocation of @cmdline. + * Queries the current state of the named action within @action_group. * - * 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. + * 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(). * - * For local invocation, it will be %NULL. + * The return value (if non-%NULL) should be freed with + * g_variant_unref() when it is no longer required. * - * Returns: (nullable): the platform data, or %NULL + * Returns: (nullable): the current state of the action * Since: 2.28 */ /** - * g_application_command_line_get_stdin: - * @cmdline: a #GApplicationCommandLine + * g_action_group_get_action_state_hint: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Gets the stdin of the invoking process. + * Requests a hint about the valid range of values for the state of the + * named action within @action_group. * - * 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. + * 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. * - * You must only call this function once per commandline invocation. + * 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. * - * Returns: (transfer full): a #GInputStream for stdin - * Since: 2.34 + * 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 */ /** - * g_application_command_line_getenv: - * @cmdline: a #GApplicationCommandLine - * @name: (type filename): the environment variable to get + * g_action_group_get_action_state_type: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * 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. + * Queries the type of the state of the named action within + * @action_group. * - * 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). + * 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. * - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. + * 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(). * - * Returns: the value of the variable, or %NULL if unset or unsent + * 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. + * + * Returns: (nullable): the state type, if the action is stateful * Since: 2.28 */ /** - * 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_action_group_has_action: + * @action_group: a #GActionGroup + * @action_name: the name of the action to check for * - * 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. + * Checks if the named action exists within @action_group. * + * Returns: whether the named action exists * Since: 2.28 */ /** - * g_application_command_line_printerr: - * @cmdline: a #GApplicationCommandLine - * @format: a printf-style format string - * @...: arguments, as per @format + * g_action_group_list_actions: + * @action_group: a #GActionGroup * - * Formats a message and prints it using the stderr print handler in the - * invoking process. + * Lists the actions contained within @action_group. * - * 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. + * 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 group * Since: 2.28 */ /** - * g_application_command_line_set_exit_status: - * @cmdline: a #GApplicationCommandLine - * @exit_status: the exit status + * 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) (optional): the parameter type, or %NULL if none needed + * @state_type: (out) (optional): the state type, or %NULL if stateless + * @state_hint: (out) (optional): the state hint, or %NULL if none + * @state: (out) (optional): the current state, or %NULL if stateless * - * Sets the exit status that will be used when the invoking process - * exits. + * Queries all aspects of the named action within an @action_group. * - * 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. + * 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. * - * 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. + * This provides two main benefits. * - * 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 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.28 - */ - - -/** - * g_application_get_application_id: - * @application: a #GApplication + * 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 the unique identifier for @application. + * 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: the identifier for @application, owned by @application - * Since: 2.28 + * Returns: %TRUE if the action exists, else %FALSE + * Since: 2.32 */ /** - * g_application_get_dbus_connection: - * @application: a #GApplication - * - * Gets the #GDBusConnection being used by the application, or %NULL. + * g_action_map_add_action: + * @action_map: a #GActionMap + * @action: a #GAction * - * 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. + * Adds an action to the @action_map. * - * 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. + * If the action map already contains an action with the same name + * as @action then the old action is dropped from the action map. * - * This function must not be called before the application has been - * registered. See g_application_get_is_registered(). + * The action map takes its own reference on @action. * - * Returns: (transfer none): a #GDBusConnection, or %NULL - * Since: 2.34 + * Since: 2.32 */ /** - * g_application_get_dbus_object_path: - * @application: a #GApplication - * - * Gets the D-Bus object path being used by the application, or %NULL. + * 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 * - * 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. + * A convenience function for creating multiple #GSimpleAction instances + * and adding them to a #GActionMap. * - * 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. + * Each action is constructed as per one #GActionEntry. * - * This function must not be called before the application has been - * registered. See g_application_get_is_registered(). + * |[ + * static void + * activate_quit (GSimpleAction *simple, + * GVariant *parameter, + * gpointer user_data) + * { + * exit (0); + * } * - * Returns: the object path, or %NULL - * Since: 2.34 - */ - - -/** - * g_application_get_default: + * static void + * activate_print_string (GSimpleAction *simple, + * GVariant *parameter, + * gpointer user_data) + * { + * g_print ("%s\n", g_variant_get_string (parameter, NULL)); + * } * - * Returns the default #GApplication instance for this process. + * static GActionGroup * + * create_action_group (void) + * { + * const GActionEntry entries[] = { + * { "quit", activate_quit }, + * { "print-string", activate_print_string, "s" } + * }; + * GSimpleActionGroup *group; * - * 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(). + * group = g_simple_action_group_new (); + * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); * - * If there is no default application then %NULL is returned. + * return G_ACTION_GROUP (group); + * } + * ]| * - * Returns: (transfer none): the default application for this process, or %NULL * Since: 2.32 */ /** - * g_application_get_flags: - * @application: a #GApplication + * g_action_map_lookup_action: + * @action_map: a #GActionMap + * @action_name: the name of an action * - * Gets the flags for @application. + * Looks up the action with the name @action_name in @action_map. * - * See #GApplicationFlags. + * If no such action exists, returns %NULL. * - * Returns: the flags for @application - * Since: 2.28 + * Returns: (transfer none): a #GAction, or %NULL + * Since: 2.32 */ /** - * g_application_get_inactivity_timeout: - * @application: a #GApplication + * g_action_map_remove_action: + * @action_map: a #GActionMap + * @action_name: the name of the action * - * Gets the current inactivity timeout for the application. + * Removes the named action from the action map. * - * This is the amount of time (in milliseconds) after the last call to - * g_application_release() before the application stops running. + * If no action of this name is in the map then nothing happens. * - * Returns: the timeout, in milliseconds - * Since: 2.28 + * Since: 2.32 */ /** - * g_application_get_is_busy: - * @application: a #GApplication + * g_action_name_is_valid: + * @action_name: an potential action name * - * Gets the application's current busy state, as set through - * g_application_mark_busy() or g_application_bind_busy_property(). + * Checks if @action_name is valid. * - * Returns: %TRUE if @application is currenty marked as busy - * Since: 2.44 + * @action_name is valid if it consists only of alphanumeric characters, + * plus '-' and '.'. The empty string is not a valid action name. + * + * It is an error to call this function with a non-utf8 @action_name. + * @action_name must not be %NULL. + * + * Returns: %TRUE if @action_name is valid + * Since: 2.38 */ /** - * g_application_get_is_registered: - * @application: a #GApplication + * 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 * - * Checks if @application is registered. + * Parses a detailed action name into its separate name and target + * components. * - * An application is registered if g_application_register() has been - * successfully called. + * Detailed action names can have three formats. * - * Returns: %TRUE if @application is registered - * Since: 2.28 + * The first format is used to represent an action name with no target + * value and consists of just an action name containing no whitespace + * nor the characters ':', '(' or ')'. For example: "app.action". + * + * The second format is used to represent an action with a target value + * that is a non-empty string consisting only of alphanumerics, plus '-' + * and '.'. In that case, the action name and target value are + * separated by a double colon ("::"). For example: + * "app.action::target". + * + * The third format is used to represent an action with any type of + * target value, including strings. The target value follows the action + * name, surrounded in parens. For example: "app.action(42)". The + * target value is parsed using g_variant_parse(). If a tuple-typed + * value is desired, it must be specified in the same way, resulting in + * two sets of parens, for example: "app.action((1,2,3))". A string + * target can be specified this way as well: "app.action('target')". + * For strings, this third format must be used if * target value is + * empty or contains characters other than alphanumerics, '-' and '.'. + * + * Returns: %TRUE if successful, else %FALSE with @error set + * Since: 2.38 */ /** - * g_application_get_is_remote: - * @application: a #GApplication + * g_action_print_detailed_name: + * @action_name: a valid action name + * @target_value: (nullable): a #GVariant target value, or %NULL * - * Checks if @application is remote. + * Formats a detailed action name from @action_name and @target_value. * - * 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. + * It is an error to call this function with an invalid action name. * - * The value of this property cannot be accessed before - * g_application_register() has been called. See - * g_application_get_is_registered(). + * This function is the opposite of g_action_parse_detailed_name(). + * It will produce a string that can be parsed back to the @action_name + * and @target_value by that function. * - * Returns: %TRUE if @application is remote - * Since: 2.28 + * See that function for the types of strings that will be printed by + * this function. + * + * Returns: a detailed format string + * Since: 2.38 */ /** - * g_application_get_resource_base_path: - * @application: a #GApplication - * - * Gets the resource base path of @application. + * g_app_info_add_supports_type: + * @appinfo: a #GAppInfo. + * @content_type: a string. + * @error: a #GError. * - * See g_application_set_resource_base_path() for more information. + * Adds a content type to the application information to indicate the + * application is capable of opening files with the given content type. * - * Returns: (nullable): the base resource path, if one is set - * Since: 2.42 + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_application_hold: - * @application: a #GApplication - * - * Increases the use count of @application. + * g_app_info_can_delete: + * @appinfo: a #GAppInfo * - * 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. + * Obtains the information whether the #GAppInfo can be deleted. + * See g_app_info_delete(). * - * To cancel the hold, call g_application_release(). + * Returns: %TRUE if @appinfo can be deleted + * Since: 2.20 */ /** - * 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(). - * - * For convenience, the restrictions on application identifiers are - * reproduced here: - * - * - Application identifiers must contain only the ASCII characters - * "[A-Z][a-z][0-9]_-." and must not begin with a digit. + * g_app_info_can_remove_supports_type: + * @appinfo: a #GAppInfo. * - * - Application identifiers must contain at least one '.' (period) - * character (and thus at least two elements). + * Checks if a supported content type can be removed from an application. * - * - Application identifiers must not begin or end with a '.' (period) - * character. + * Returns: %TRUE if it is possible to remove supported + * content types from a given @appinfo, %FALSE if not. + */ + + +/** + * g_app_info_create_from_commandline: + * @commandline: (type filename): the commandline to use + * @application_name: (nullable): 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. * - * - Application identifiers must not contain consecutive '.' (period) - * characters. + * Creates a new #GAppInfo from the given information. * - * - Application identifiers must not exceed 255 characters. + * 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: %TRUE if @application_id is valid + * Returns: (transfer full): new #GAppInfo for given command. */ /** - * g_application_mark_busy: - * @application: a #GApplication - * - * Increases the busy count of @application. - * - * Use this function to indicate that the application is busy, for instance - * while a long running operation is pending. + * g_app_info_delete: (virtual do_delete) + * @appinfo: a #GAppInfo * - * 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). + * Tries to delete a #GAppInfo. * - * To cancel the busy indication, use g_application_unmark_busy(). + * 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(). * - * Since: 2.38 + * Returns: %TRUE if @appinfo has been deleted + * Since: 2.20 */ /** - * g_application_new: - * @application_id: (nullable): the application id - * @flags: the application flags + * g_app_info_dup: + * @appinfo: a #GAppInfo. * - * Creates a new #GApplication instance. + * Creates a duplicate of a #GAppInfo. * - * 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 + * Returns: (transfer full): a duplicate of @appinfo. */ /** - * 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 - * - * 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. + * g_app_info_equal: + * @appinfo1: the first #GAppInfo. + * @appinfo2: the second #GAppInfo. * - * @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 "". + * Checks if two #GAppInfos are equal. * - * The application must be registered before calling this function - * and it must have the %G_APPLICATION_HANDLES_OPEN flag set. + * Note that the check may not compare each individual + * field, and only does an identity check. In case detecting changes in the + * contents is needed, program code must additionally compare relevant fields. * - * Since: 2.28 + * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. */ /** - * g_application_quit: - * @application: a #GApplication - * - * Immediately quits the application. - * - * Upon return to the mainloop, g_application_run() will return, - * calling only the 'shutdown' function before doing so. + * g_app_info_get_all: * - * The hold count is ignored. - * Take care if your code has called g_application_hold() on the application and - * is therefore still expecting it to exist. - * (Note that you may have called g_application_hold() indirectly, for example - * through gtk_application_add_window().) + * Gets a list of all of the applications currently registered + * on this system. * - * The result of calling g_application_run() again after it returns is - * unspecified. + * 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. * - * Since: 2.32 + * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos. */ /** - * g_application_register: - * @application: a #GApplication - * @cancellable: (nullable): 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. - * - * 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. + * g_app_info_get_all_for_type: + * @content_type: the content type to find a #GAppInfo for * - * 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. + * 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: %TRUE if registration succeeded - * Since: 2.28 + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. */ /** - * g_application_release: - * @application: a #GApplication - * - * Decrease the use count of @application. + * g_app_info_get_commandline: + * @appinfo: a #GAppInfo * - * When the use count reaches zero, the application will stop running. + * Gets the commandline with which the application will be + * started. * - * Never call this function except to cancel the effect of a previous - * call to g_application_hold(). + * Returns: (type filename): a string containing the @appinfo's commandline, + * or %NULL if this information is not available + * Since: 2.20 */ /** - * g_application_run: - * @application: a #GApplication - * @argc: the argc from main() (or 0 if @argv is %NULL) - * @argv: (array length=argc) (element-type filename) (nullable): - * the argv from main(), or %NULL - * - * Runs the application. - * - * 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. - * - * 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. - * - * If, after the above is done, the use count of the application is zero - * then the exit status is returned immediately. If the use count is - * non-zero then the default main context is iterated until the use count - * falls to zero, at which point 0 is returned. - * - * If the %G_APPLICATION_IS_SERVICE flag is set, then the 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]. - * - * Much like g_main_loop_run(), this function will acquire the main context - * for the duration that the application is running. + * 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 * - * 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. + * Gets the default #GAppInfo for a given content type. * - * Returns: the exit status - * Since: 2.28 + * Returns: (transfer full): #GAppInfo for given @content_type or + * %NULL on error. */ /** - * g_application_send_notification: - * @application: a #GApplication - * @id: (nullable): id of the notification, or %NULL - * @notification: the #GNotification to send - * - * Sends a notification on behalf of @application to the desktop shell. - * There is no guarantee that the notification is displayed immediately, - * or even at all. - * - * Notifications may persist after the application exits. It will be - * D-Bus-activated when the notification or one of its actions is - * activated. - * - * Modifying @notification after this call has no effect. However, the - * object can be reused for a later call to this function. - * - * @id may be any string that uniquely identifies the event for the - * application. It does not need to be in any special format. For - * example, "new-message" might be appropriate for a notification about - * new messages. - * - * If a previous notification was sent with the same @id, it will be - * replaced with @notification and shown again as if it was a new - * notification. This works even for notifications sent from a previous - * execution of the application, as long as @id is the same string. - * - * @id may be %NULL, but it is impossible to replace or withdraw - * notifications without an id. + * g_app_info_get_default_for_uri_scheme: + * @uri_scheme: a string containing a URI scheme. * - * If @notification is no longer relevant, it can be withdrawn with - * g_application_withdraw_notification(). + * 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". * - * Since: 2.40 + * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. */ /** - * g_application_set_action_group: - * @application: a #GApplication - * @action_group: (nullable): a #GActionGroup, or %NULL + * g_app_info_get_description: + * @appinfo: a #GAppInfo. * - * This used to be how actions were associated with a #GApplication. - * Now there is #GActionMap for that. + * Gets a human-readable description of an installed application. * - * 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. + * Returns: a string containing a description of the + * application @appinfo, or %NULL if none. */ /** - * g_application_set_application_id: - * @application: a #GApplication - * @application_id: (nullable): the identifier for @application - * - * Sets the unique identifier for @application. - * - * The application id can only be modified if @application has not yet - * been registered. + * g_app_info_get_display_name: + * @appinfo: a #GAppInfo. * - * If non-%NULL, the application id must be valid. See - * g_application_id_is_valid(). + * Gets the display name of the application. The display name is often more + * descriptive to the user than the name itself. * - * Since: 2.28 + * Returns: the display name of the application for @appinfo, or the name if + * no display name is available. + * Since: 2.24 */ /** - * g_application_set_default: - * @application: (nullable): the application to set as default, or %NULL - * - * Sets or unsets the default application for the process, as returned - * by g_application_get_default(). + * g_app_info_get_executable: + * @appinfo: a #GAppInfo * - * This function does not take its own reference on @application. If - * @application is destroyed then the default application will revert - * back to %NULL. + * Gets the executable's name for the installed application. * - * Since: 2.32 + * Returns: (type filename): a string containing the @appinfo's application + * binaries name */ /** - * g_application_set_flags: - * @application: a #GApplication - * @flags: the flags for @application - * - * Sets the flags for @application. - * - * The flags can only be modified if @application has not yet been - * registered. + * g_app_info_get_fallback_for_type: + * @content_type: the content type to find a #GAppInfo for * - * See #GApplicationFlags. + * 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. * + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ /** - * g_application_set_inactivity_timeout: - * @application: a #GApplication - * @inactivity_timeout: the timeout, in milliseconds - * - * Sets the current inactivity timeout for the application. - * - * This is the amount of time (in milliseconds) after the last call to - * g_application_release() before the application stops running. + * g_app_info_get_icon: + * @appinfo: a #GAppInfo. * - * 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 the icon for the application. * - * Since: 2.28 + * Returns: (transfer none): the default #GIcon for @appinfo or %NULL + * if there is no default icon. */ /** - * g_application_set_option_context_description: - * @application: the #GApplication - * @description: (nullable): a string to be shown in `--help` output - * after the list of options, or %NULL + * g_app_info_get_id: + * @appinfo: a #GAppInfo. * - * Adds a description to the @application option context. + * 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. * - * See g_option_context_set_description() for more information. + * Note that the returned ID may be %NULL, depending on how + * the @appinfo has been constructed. * - * Since: 2.56 + * Returns: a string containing the application's ID. */ /** - * g_application_set_option_context_parameter_string: - * @application: the #GApplication - * @parameter_string: (nullable): a string which is displayed - * in the first line of `--help` output, after the usage summary `programname [OPTION...]`. + * g_app_info_get_name: + * @appinfo: a #GAppInfo. * - * Sets the parameter string to be used by the commandline handling of @application. + * Gets the installed name of the application. * - * This function registers the argument to be passed to g_option_context_new() - * when the internal #GOptionContext of @application is created. + * Returns: the name of the application for @appinfo. + */ + + +/** + * g_app_info_get_recommended_for_type: + * @content_type: the content type to find a #GAppInfo for * - * See g_option_context_new() for more information about @parameter_string. + * 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. * - * Since: 2.56 + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. + * Since: 2.28 */ /** - * g_application_set_option_context_summary: - * @application: the #GApplication - * @summary: (nullable): a string to be shown in `--help` output - * before the list of options, or %NULL - * - * Adds a summary to the @application option context. + * g_app_info_get_supported_types: + * @appinfo: a #GAppInfo that can handle files * - * See g_option_context_set_summary() for more information. + * 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. * - * Since: 2.56 + * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): + * a list of content types. + * Since: 2.34 */ /** - * g_application_set_resource_base_path: - * @application: a #GApplication - * @resource_path: (nullable): the resource path to use - * - * Sets (or unsets) the base resource path of @application. + * g_app_info_launch: + * @appinfo: a #GAppInfo + * @files: (nullable) (element-type GFile): a #GList of #GFile objects + * @context: (nullable): a #GAppLaunchContext or %NULL + * @error: a #GError * - * 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. + * Launches the application. Passes @files to the launched application + * as arguments, using the optional @context to get information + * about the details of the launcher (like what screen it is on). + * On error, @error will be set accordingly. * - * 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. + * To launch the application without arguments pass a %NULL @files list. * - * 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". + * 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. * - * See #GResource for more information about adding resources to your - * application. + * 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. * - * You can disable automatic resource loading functionality by setting - * the path to %NULL. + * 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(). * - * 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. When writing - * a sub-class of #GApplication you should either set the - * #GApplication:resource-base-path property at construction time, or call - * this function during the instance initialization. Alternatively, you - * can call this function in the #GApplicationClass.startup virtual function, - * before chaining up to the parent implementation. + * 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 @context. * - * Since: 2.42 + * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** - * g_application_unbind_busy_property: - * @application: a #GApplication - * @object: (type GObject.Object): a #GObject - * @property: the name of a boolean property of @object + * g_app_info_launch_default_for_uri: + * @uri: the uri to show + * @context: (nullable): an optional #GAppLaunchContext + * @error: (nullable): return location for an error, or %NULL * - * Destroys a binding between @property and the busy state of - * @application that was previously created with - * g_application_bind_busy_property(). + * 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. * - * Since: 2.44 + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_application_unmark_busy: - * @application: a #GApplication - * - * Decreases the busy count of @application. + * g_app_info_launch_default_for_uri_async: + * @uri: the uri to show + * @context: (nullable): an optional #GAppLaunchContext + * @cancellable: (nullable): a #GCancellable + * @callback: (nullable): a #GASyncReadyCallback to call when the request is done + * @user_data: (nullable): data to pass to @callback * - * When the busy count reaches zero, the new state will be propagated - * to other processes. + * Async version of g_app_info_launch_default_for_uri(). * - * This function must only be called to cancel the effect of a previous - * call to g_application_mark_busy(). + * This version is useful if you are interested in receiving + * error information in the case where the application is + * sandboxed and the portal may present an application chooser + * dialog to the user. * - * Since: 2.38 + * Since: 2.50 */ /** - * g_application_withdraw_notification: - * @application: a #GApplication - * @id: id of a previously sent notification - * - * Withdraws a notification that was sent with - * g_application_send_notification(). - * - * This call does nothing if a notification with @id doesn't exist or - * the notification was never sent. - * - * This function works even for notifications sent in previous - * executions of this application, as long @id is the same as it was for - * the sent notification. + * g_app_info_launch_default_for_uri_finish: + * @result: a #GAsyncResult + * @error: (nullable): return location for an error, or %NULL * - * 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. + * Finishes an asynchronous launch-default-for-uri operation. * - * Since: 2.40 + * Returns: %TRUE if the launch was successful, %FALSE if @error is set + * Since: 2.50 */ /** - * 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 - * - * 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. - * - * This method is intended for language bindings. If writing in C, - * g_async_initable_new_async() should typically be used instead. - * - * 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. - * - * 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_app_info_launch_uris: + * @appinfo: a #GAppInfo + * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch. + * @context: (nullable): a #GAppLaunchContext or %NULL + * @error: a #GError * - * 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. + * Launches the application. This passes the @uris to the launched application + * as arguments, using the optional @context to get information + * about the details of the launcher (like what screen it is on). + * On error, @error will be set accordingly. * - * Callers should not assume that a class which implements #GAsyncInitable can - * be initialized multiple times; for more information, see g_initable_init(). - * If a class explicitly supports being initialized multiple times, - * implementation requires yielding all subsequent calls to init_async() on the - * results of the first call. + * To launch the application without arguments pass a %NULL @uris list. * - * 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. + * 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. * - * Since: 2.22 + * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** - * 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_app_info_monitor_get: * - * Returns: %TRUE if successful. If an error has occurred, this function - * will return %FALSE and set @error appropriately if present. - * Since: 2.22 - */ - - -/** - * g_async_initable_new_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the [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: (nullable): 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. + * Gets the #GAppInfoMonitor for the current thread-default main + * context. * - * Helper function for constructing #GAsyncInitable object. This is - * similar to g_object_new() but also initializes the object asynchronously. + * 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. * - * 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. + * You must only call g_object_unref() on the return value from under + * the same main context as you created it. * - * Since: 2.22 + * Returns: (transfer full): a reference to a #GAppInfoMonitor + * Since: 2.40 */ /** - * 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_app_info_remove_supports_type: + * @appinfo: a #GAppInfo. + * @content_type: a string. + * @error: a #GError. * - * Finishes the async construction for the various g_async_initable_new - * calls, returning the created object or %NULL on error. + * Removes a supported type from an application, if possible. * - * Returns: (type GObject.Object) (transfer full): a newly created #GObject, - * or %NULL on error. Free with g_object_unref(). - * Since: 2.22 + * Returns: %TRUE on success, %FALSE on error. */ /** - * 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 - * - * Helper function for constructing #GAsyncInitable object. This is - * similar to g_object_new_valist() but also initializes the object - * asynchronously. + * g_app_info_reset_type_associations: + * @content_type: a content type * - * 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. + * 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(). * - * Since: 2.22 + * Since: 2.20 */ /** - * 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 - * - * Helper function for constructing #GAsyncInitable object. This is - * similar to g_object_newv() but also initializes the object asynchronously. + * g_app_info_set_as_default_for_extension: + * @appinfo: a #GAppInfo. + * @extension: (type filename): a string containing the file extension + * (without the dot). + * @error: a #GError. * - * 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. + * Sets the application as the default handler for the given file extension. * - * Since: 2.22 - * Deprecated: 2.54: Use g_object_new_with_properties() and - * g_async_initable_init_async() instead. See #GParameter for more information. + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_async_result_get_source_object: - * @res: a #GAsyncResult + * g_app_info_set_as_default_for_type: + * @appinfo: a #GAppInfo. + * @content_type: the content type. + * @error: a #GError. * - * Gets the source object from a #GAsyncResult. + * Sets the application as the default handler for a given type. * - * Returns: (transfer full) (nullable): a new reference to the source - * object for the @res, or %NULL if there is none. + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_async_result_get_user_data: - * @res: a #GAsyncResult. + * g_app_info_set_as_last_used_for_type: + * @appinfo: a #GAppInfo. + * @content_type: the content type. + * @error: a #GError. * - * Gets the user data from a #GAsyncResult. + * 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: (transfer full): the user data for @res. + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_async_result_is_tagged: - * @res: a #GAsyncResult - * @source_tag: an application-defined tag + * g_app_info_should_show: + * @appinfo: a #GAppInfo. * - * Checks if @res has the given @source_tag (generally a function - * pointer indicating the function @res was created by). + * Checks if the application info should be shown in menus that + * list available applications. * - * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if - * not. - * Since: 2.34 + * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. */ /** - * g_async_result_legacy_propagate_error: - * @res: a #GAsyncResult - * @error: (out): a location to propagate the error to. - * - * If @res is a #GSimpleAsyncResult, this is equivalent to - * g_simple_async_result_propagate_error(). Otherwise it returns - * %FALSE. + * g_app_info_supports_files: + * @appinfo: a #GAppInfo. * - * 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. + * Checks if the application accepts files as arguments. * - * Returns: %TRUE if @error is has been filled in with an error from - * @res, %FALSE if not. - * Since: 2.34 + * Returns: %TRUE if the @appinfo supports files. */ /** - * g_buffered_input_stream_fill: - * @stream: a #GBufferedInputStream - * @count: the number of bytes that will be read from the stream - * @cancellable: (nullable): 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. - * 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 @count is -1 then the attempted read size is equal to the number of - * bytes that are required to fill the buffer. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * 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. + * g_app_info_supports_uris: + * @appinfo: a #GAppInfo. * - * For the asynchronous, non-blocking, version of this function, see - * g_buffered_input_stream_fill_async(). + * Checks if the application supports reading files and directories from URIs. * - * Returns: the number of bytes read into @stream's buffer, up to @count, - * or -1 on error. + * Returns: %TRUE if the @appinfo supports URIs. */ /** - * 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: (nullable): optional #GCancellable object - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): a #gpointer + * g_app_launch_context_get_display: + * @context: a #GAppLaunchContext + * @info: a #GAppInfo + * @files: (element-type GFile): a #GList of #GFile objects * - * 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(). + * 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. * - * If @count is -1 then the attempted read size is equal to the number - * of bytes that are required to fill the buffer. + * Returns: a display string for the display. */ /** - * g_buffered_input_stream_fill_finish: - * @stream: a #GBufferedInputStream - * @result: a #GAsyncResult - * @error: a #GError + * g_app_launch_context_get_environment: + * @context: a #GAppLaunchContext * - * Finishes an asynchronous read. + * 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`. * - * Returns: a #gssize of the read stream, or `-1` on an error. + * Returns: (array zero-terminated=1) (element-type filename) (transfer full): + * the child's environment + * Since: 2.32 */ /** - * g_buffered_input_stream_get_available: - * @stream: #GBufferedInputStream + * g_app_launch_context_get_startup_notify_id: + * @context: a #GAppLaunchContext + * @info: a #GAppInfo + * @files: (element-type GFile): a #GList of of #GFile objects * - * Gets the size of the available data within the stream. + * Initiates startup notification for the application and returns the + * `DESKTOP_STARTUP_ID` for the launched operation, if supported. * - * Returns: size of the available stream. + * Startup notification IDs are defined in the + * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"). + * + * Returns: a startup notification ID for the application, or %NULL if + * not supported. */ /** - * g_buffered_input_stream_get_buffer_size: - * @stream: a #GBufferedInputStream - * - * Gets the size of the input buffer. + * 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(). * - * Returns: the current buffer size. + * 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(). */ /** - * g_buffered_input_stream_new: - * @base_stream: a #GInputStream + * g_app_launch_context_new: * - * Creates a new #GInputStream from the given @base_stream, with - * a buffer set to the default size (4 kilobytes). + * Creates a new application launch context. This is not normally used, + * instead you instantiate a subclass of this, such as #GdkAppLaunchContext. * - * Returns: a #GInputStream for the given @base_stream. + * Returns: a #GAppLaunchContext. */ /** - * g_buffered_input_stream_new_sized: - * @base_stream: a #GInputStream - * @size: a #gsize + * g_app_launch_context_setenv: + * @context: a #GAppLaunchContext + * @variable: (type filename): the environment variable to set + * @value: (type filename): the value for to set the variable to. * - * Creates a new #GBufferedInputStream from the given @base_stream, - * with a buffer set to @size. + * Arranges for @variable to be set to @value in the child's + * environment when @context is used to launch an application. * - * Returns: a #GInputStream. + * Since: 2.32 */ /** - * 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 + * g_app_launch_context_unsetenv: + * @context: a #GAppLaunchContext + * @variable: (type filename): the environment variable to remove * - * Peeks in the buffer, copying data of size @count into @buffer, - * offset @offset bytes. + * Arranges for @variable to be unset in the child's environment + * when @context is used to launch an application. * - * Returns: a #gsize of the number of bytes peeked, or -1 on error. + * Since: 2.32 */ /** - * g_buffered_input_stream_peek_buffer: - * @stream: a #GBufferedInputStream - * @count: (out): a #gsize to get the number of bytes available in the buffer + * g_application_activate: + * @application: a #GApplication * - * 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. + * Activates the application. * - * Returns: (array length=count) (element-type guint8) (transfer none): - * read-only buffer + * 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 */ /** - * g_buffered_input_stream_read_byte: - * @stream: a #GBufferedInputStream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occurring, or %NULL to ignore + * 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 * - * Tries to read a single byte from the stream or the buffer. Will block - * during this read. + * Add an option to be handled by @application. * - * 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. + * 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. * - * 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 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. * - * On error -1 is returned and @error is set accordingly. + * See #GOptionEntry for more documentation of the arguments. * - * Returns: the byte read from the @stream, or -1 on end of stream or error. + * Since: 2.42 */ /** - * g_buffered_input_stream_set_buffer_size: - * @stream: a #GBufferedInputStream - * @size: a #gsize + * g_application_add_main_option_entries: + * @application: a #GApplication + * @entries: (array zero-terminated=1) (element-type GOptionEntry): a + * %NULL-terminated list of #GOptionEntrys * - * 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. + * Adds main option entries to be handled by @application. * - * Checks if the buffer automatically grows as data is added. + * This function is comparable to g_option_context_add_main_entries(). * - * Returns: %TRUE if the @stream's buffer automatically grows, - * %FALSE otherwise. - */ - - -/** - * g_buffered_output_stream_get_buffer_size: - * @stream: a #GBufferedOutputStream. + * 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. * - * Gets the size of the buffer in the @stream. + * 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). * - * Returns: the current size of the buffer. - */ - - -/** - * g_buffered_output_stream_new: - * @base_stream: a #GOutputStream. + * 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. * - * Creates a new buffered output stream for a base stream. + * 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. * - * Returns: a #GOutputStream for the given @base_stream. - */ - - -/** - * g_buffered_output_stream_new_sized: - * @base_stream: a #GOutputStream. - * @size: a #gsize. + * 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). * - * Creates a new buffered output stream with a given buffer size. + * It is important to use the proper GVariant format when retrieving + * the options with g_variant_dict_lookup(): + * - for %G_OPTION_ARG_NONE, use b + * - for %G_OPTION_ARG_STRING, use &s + * - for %G_OPTION_ARG_INT, use i + * - for %G_OPTION_ARG_INT64, use x + * - for %G_OPTION_ARG_DOUBLE, use d + * - for %G_OPTION_ARG_FILENAME, use ^ay + * - for %G_OPTION_ARG_STRING_ARRAY, use &as + * - for %G_OPTION_ARG_FILENAME_ARRAY, use ^aay * - * Returns: a #GOutputStream with an internal buffer set to @size. + * Since: 2.40 */ /** - * g_buffered_output_stream_set_auto_grow: - * @stream: a #GBufferedOutputStream. - * @auto_grow: a #gboolean. + * g_application_add_option_group: + * @application: the #GApplication + * @group: (transfer full): a #GOptionGroup * - * 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. + * Adds a #GOptionGroup to the commandline handling of @application. * - * Sets the size of the internal buffer to @size. - */ + * This function is comparable to g_option_context_add_group(). + * + * Unlike g_application_add_main_option_entries(), this function does + * not deal with %NULL @arg_data and never transmits options to the + * primary instance. + * + * The reason for that is because, by the time the options arrive at the + * primary instance, it is typically too late to do anything with them. + * Taking the GTK option group as an example: GTK will already have been + * initialised by the time the #GApplication::command-line handler runs. + * In the case that this is not the first-running instance of the + * application, the existing instance may already have been running for + * a very long time. + * + * This means that the options from #GOptionGroup are only really usable + * in the case that the instance of the application being run is the + * first instance. Passing options like `--display=` or `--gdk-debug=` + * on future runs will have no effect on the existing primary instance. + * + * Calling this function will cause the options in the supplied option + * group to be parsed, but it does not cause you to be "opted in" to the + * new functionality whereby unrecognised options are rejected even if + * %G_APPLICATION_HANDLES_COMMAND_LINE was given. + * + * Since: 2.40 + */ /** - * g_bus_get: - * @bus_type: a #GBusType - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to @callback - * - * Asynchronously connects to the message bus specified by @bus_type. + * g_application_bind_busy_property: + * @application: a #GApplication + * @object: (type GObject.Object): a #GObject + * @property: the name of a boolean property of @object * - * When the operation is finished, @callback will be invoked. You can - * then call g_bus_get_finish() to get the result of the operation. + * Marks @application as busy (see g_application_mark_busy()) while + * @property on @object is %TRUE. * - * This is a asynchronous failable function. See g_bus_get_sync() for - * the synchronous version. + * 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.26 + * Since: 2.44 */ /** - * 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_application_command_line_create_file_for_arg: + * @cmdline: a #GApplicationCommandLine + * @arg: (type filename): an argument from @cmdline * - * 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(). + * Creates a #GFile corresponding to a filename that was given as part + * of the invocation of @cmdline. * - * Note that the returned #GDBusConnection object will (usually) have - * the #GDBusConnection:exit-on-close property set to %TRUE. + * 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 #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 + * Returns: (transfer full): a new #GFile + * Since: 2.36 */ /** - * g_bus_get_sync: - * @bus_type: a #GBusType - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL + * g_application_command_line_get_arguments: + * @cmdline: a #GApplicationCommandLine + * @argc: (out) (optional): the length of the arguments array, 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. + * Gets the list of arguments that was passed on the command line. * - * This is a synchronous failable function. See g_bus_get() and - * g_bus_get_finish() for the asynchronous version. + * 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. * - * 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(). + * If you wish to use the return value with #GOptionContext, you must + * use g_option_context_parse_strv(). * - * Note that the returned #GDBusConnection object will (usually) have - * the #GDBusConnection:exit-on-close property set to %TRUE. + * The return value is %NULL-terminated and should be freed using + * g_strfreev(). * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 + * Returns: (array length=argc) (element-type filename) (transfer full): + * the string array containing the arguments (the argv) + * Since: 2.28 */ /** - * 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: (nullable): handler to invoke when connected to the bus of type @bus_type or %NULL - * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL - * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL - * @user_data: user data to pass to handlers - * @user_data_free_func: (nullable): function for freeing @user_data or %NULL - * - * Starts acquiring @name on the bus specified by @bus_type and calls - * @name_acquired_handler and @name_lost_handler when the name is - * acquired respectively lost. Callbacks will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this function from. - * - * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler - * callbacks will be invoked after calling this function - there are three - * possible cases: - * - * - @name_lost_handler with a %NULL connection (if a connection to the bus - * can't be made). + * g_application_command_line_get_cwd: + * @cmdline: a #GApplicationCommandLine * - * - @bus_acquired_handler then @name_lost_handler (if the name can't be - * obtained) + * Gets the working directory of the command line invocation. + * The string may contain non-utf8 data. * - * - @bus_acquired_handler then @name_acquired_handler (if the name was - * obtained). + * It is possible that the remote application did not send a working + * directory, so this may be %NULL. * - * When you are done owning the name, just call g_bus_unown_name() - * with the owner id this function returns. + * The return value should not be modified or freed and is valid for as + * long as @cmdline exists. * - * 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. + * Returns: (nullable) (type filename): the current directory, or %NULL + * Since: 2.28 + */ + + +/** + * g_application_command_line_get_environ: + * @cmdline: a #GApplicationCommandLine * - * 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. + * 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. * - * 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. + * 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). * - * 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. + * The return value should not be modified or freed and is valid for as + * long as @cmdline exists. * - * 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. + * See g_application_command_line_getenv() if you are only interested + * in the value of a single environment variable. * - * Returns: an identifier (never 0) that an be used with - * g_bus_unown_name() to stop owning the name. - * Since: 2.26 + * Returns: (array zero-terminated=1) (element-type filename) (transfer none): + * the environment strings, or %NULL if they were not sent + * Since: 2.28 */ /** - * 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: (nullable): handler to invoke when @name is acquired or %NULL - * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL - * @user_data: user data to pass to handlers - * @user_data_free_func: (nullable): function for freeing @user_data or %NULL + * g_application_command_line_get_exit_status: + * @cmdline: a #GApplicationCommandLine * - * Like g_bus_own_name() but takes a #GDBusConnection instead of a - * #GBusType. + * Gets the exit status of @cmdline. See + * g_application_command_line_set_exit_status() for more information. * - * Returns: an identifier (never 0) that an be used with - * g_bus_unown_name() to stop owning the name - * Since: 2.26 + * Returns: the exit status + * Since: 2.28 */ /** - * 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: (nullable): #GClosure to invoke when @name is - * acquired or %NULL - * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost - * or %NULL + * g_application_command_line_get_is_remote: + * @cmdline: a #GApplicationCommandLine * - * Version of g_bus_own_name_on_connection() using closures instead of - * callbacks for easier binding in other languages. + * Determines if @cmdline represents a remote invocation. * - * Returns: an identifier (never 0) that an be used with - * g_bus_unown_name() to stop owning the name. - * Since: 2.26 + * Returns: %TRUE if the invocation was remote + * Since: 2.28 */ /** - * 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: (nullable): #GClosure to invoke when connected to - * the bus of type @bus_type or %NULL - * @name_acquired_closure: (nullable): #GClosure to invoke when @name is - * acquired or %NULL - * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost or - * %NULL + * g_application_command_line_get_options_dict: + * @cmdline: a #GApplicationCommandLine * - * Version of g_bus_own_name() using closures instead of callbacks for - * easier binding in other languages. + * Gets the options there were passed to g_application_command_line(). * - * Returns: an identifier (never 0) that an be used with - * g_bus_unown_name() to stop owning the name. - * Since: 2.26 + * If you did not override local_command_line() then these are the same + * options that were parsed according to the #GOptionEntrys added to the + * application with g_application_add_main_option_entries() and possibly + * modified from your GApplication::handle-local-options handler. + * + * If no options were sent then an empty dictionary is returned so that + * you don't need to check for %NULL. + * + * Returns: (transfer none): a #GVariantDict with the options + * Since: 2.40 */ /** - * g_bus_unown_name: - * @owner_id: an identifier obtained from g_bus_own_name() + * g_application_command_line_get_platform_data: + * @cmdline: #GApplicationCommandLine * - * Stops owning a name. + * Gets the platform data associated with the invocation of @cmdline. * - * Since: 2.26 + * 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 */ /** - * g_bus_unwatch_name: - * @watcher_id: An identifier obtained from g_bus_watch_name() + * g_application_command_line_get_stdin: + * @cmdline: a #GApplicationCommandLine * - * Stops watching a name. + * Gets the stdin of the invoking process. * - * Since: 2.26 + * The #GInputStream can be used to read data passed to the standard + * input of the invoking process. + * This doesn't work on all platforms. Presently, it is only available + * on UNIX when using a DBus daemon capable of passing file descriptors. + * If stdin is not available then %NULL will be returned. In the + * future, support may be expanded to other platforms. + * + * You must only call this function once per commandline invocation. + * + * Returns: (transfer full): a #GInputStream for stdin + * Since: 2.34 */ /** - * g_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: (nullable): Handler to invoke when @name is known to exist or %NULL. - * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL. - * - * 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. - * - * 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. + * g_application_command_line_getenv: + * @cmdline: a #GApplicationCommandLine + * @name: (type filename): the environment variable to get * - * 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. + * 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. * - * 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. + * 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). * - * 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. + * The return value should not be modified or freed and is valid for as + * long as @cmdline exists. * - * Returns: An identifier (never 0) that an be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 + * Returns: the value of the variable, or %NULL if unset or unsent + * Since: 2.28 */ /** - * 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: (nullable): Handler to invoke when @name is known to exist or %NULL. - * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL. + * g_application_command_line_print: + * @cmdline: a #GApplicationCommandLine + * @format: a printf-style format string + * @...: arguments, as per @format * - * Like g_bus_watch_name() but takes a #GDBusConnection instead of a - * #GBusType. + * Formats a message and prints it using the stdout print handler in the + * invoking process. * - * Returns: An identifier (never 0) that an be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 + * 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. + * + * Since: 2.28 */ /** - * 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: (nullable): #GClosure to invoke when @name is known - * to exist or %NULL. - * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known - * to not exist or %NULL. + * g_application_command_line_printerr: + * @cmdline: a #GApplicationCommandLine + * @format: a printf-style format string + * @...: arguments, as per @format * - * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for - * easier binding in other languages. + * Formats a message and prints it using the stderr print handler in the + * invoking process. * - * Returns: An identifier (never 0) that an be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 + * 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 */ /** - * 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: (nullable): #GClosure to invoke when @name is known - * to exist or %NULL. - * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known - * to not exist or %NULL. + * g_application_command_line_set_exit_status: + * @cmdline: a #GApplicationCommandLine + * @exit_status: the exit status * - * Version of g_bus_watch_name() using closures instead of callbacks for - * easier binding in other languages. + * Sets the exit status that will be used when the invoking process + * exits. * - * Returns: An identifier (never 0) that an be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 + * 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. + * + * 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. + * + * 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. + * + * Since: 2.28 */ /** - * g_bytes_icon_get_bytes: - * @icon: a #GIcon. + * g_application_get_application_id: + * @application: a #GApplication * - * Gets the #GBytes associated with the given @icon. + * Gets the unique identifier for @application. * - * Returns: (transfer none): a #GBytes, or %NULL. - * Since: 2.38 + * Returns: the identifier for @application, owned by @application + * Since: 2.28 */ /** - * g_bytes_icon_new: - * @bytes: a #GBytes. + * g_application_get_dbus_connection: + * @application: a #GApplication * - * Creates a new icon for a bytes. + * Gets the #GDBusConnection being used by the application, or %NULL. * - * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given - * @bytes, or %NULL on error. - * Since: 2.38 + * 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. + * + * 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. + * + * This function must not be called before the application has been + * registered. See g_application_get_is_registered(). + * + * Returns: (transfer none): a #GDBusConnection, or %NULL + * Since: 2.34 */ /** - * g_cancellable_cancel: - * @cancellable: (nullable): a #GCancellable object. + * g_application_get_dbus_object_path: + * @application: a #GApplication * - * 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 D-Bus object path being used by the application, or %NULL. * - * 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 #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. * - * If @cancellable is %NULL, this function returns immediately for convenience. + * 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 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. + * This function must not be called before the application has been + * registered. See g_application_get_is_registered(). + * + * Returns: the object path, or %NULL + * Since: 2.34 */ /** - * g_cancellable_connect: - * @cancellable: A #GCancellable. - * @callback: The #GCallback to connect. - * @data: Data to pass to @callback. - * @data_destroy_func: (nullable): Free function for @data or %NULL. + * g_application_get_default: * - * 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. + * Returns the default #GApplication instance for this process. * - * @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. + * 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(). * - * @data_destroy_func will be called when the handler is - * disconnected, or immediately if the cancellable is already - * cancelled. - * - * See #GCancellable::cancelled for details on how to use this. - * - * 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(). + * If there is no default application then %NULL is returned. * - * Returns: The id of the signal handler or 0 if @cancellable has already - * been cancelled. - * Since: 2.22 + * Returns: (transfer none): the default application for this process, or %NULL + * Since: 2.32 */ /** - * g_cancellable_disconnect: - * @cancellable: (nullable): 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_application_get_flags: + * @application: a #GApplication * - * 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. + * Gets the flags for @application. * - * If @cancellable is %NULL or @handler_id is `0` this function does - * nothing. + * See #GApplicationFlags. * - * Since: 2.22 + * Returns: the flags for @application + * Since: 2.28 */ /** - * g_cancellable_get_current: + * g_application_get_inactivity_timeout: + * @application: a #GApplication * - * Gets the top cancellable from the stack. + * Gets the current inactivity timeout for the application. * - * Returns: (nullable) (transfer none): a #GCancellable from the top - * of the stack, or %NULL if the stack is empty. + * This is the amount of time (in milliseconds) after the last call to + * g_application_release() before the application stops running. + * + * Returns: the timeout, in milliseconds + * Since: 2.28 */ /** - * g_cancellable_get_fd: - * @cancellable: a #GCancellable. - * - * 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. + * g_application_get_is_busy: + * @application: a #GApplication * - * See also g_cancellable_make_pollfd(). + * Gets the application's current busy state, as set through + * g_application_mark_busy() or g_application_bind_busy_property(). * - * Returns: A valid file descriptor. %-1 if the file descriptor - * is not supported, or on errors. + * Returns: %TRUE if @application is currenty marked as busy + * Since: 2.44 */ /** - * g_cancellable_is_cancelled: - * @cancellable: (nullable): a #GCancellable or %NULL + * g_application_get_is_registered: + * @application: a #GApplication * - * Checks if a cancellable job has been cancelled. + * Checks if @application is registered. * - * Returns: %TRUE if @cancellable is cancelled, - * FALSE if called with %NULL or if item is not cancelled. + * An application is registered if g_application_register() has been + * successfully called. + * + * Returns: %TRUE if @application is registered + * Since: 2.28 */ /** - * g_cancellable_make_pollfd: - * @cancellable: (nullable): 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. + * g_application_get_is_remote: + * @application: a #GApplication * - * 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(). + * Checks if @application is remote. * - * 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. + * 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. * - * 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 value of this property cannot be accessed before + * g_application_register() has been called. See + * g_application_get_is_registered(). * - * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on - * failure to prepare the cancellable. - * Since: 2.22 + * Returns: %TRUE if @application is remote + * Since: 2.28 */ /** - * g_cancellable_new: - * - * Creates a new #GCancellable object. + * g_application_get_resource_base_path: + * @application: a #GApplication * - * Applications that want to start one or more operations - * that should be cancellable should create a #GCancellable - * and pass it to the operations. + * Gets the resource base path of @application. * - * One #GCancellable can be used in multiple consecutive - * operations or in multiple concurrent operations. + * See g_application_set_resource_base_path() for more information. * - * Returns: a #GCancellable. + * Returns: (nullable): the base resource path, if one is set + * Since: 2.42 */ /** - * g_cancellable_pop_current: - * @cancellable: a #GCancellable object + * g_application_hold: + * @application: a #GApplication * - * Pops @cancellable off the cancellable stack (verifying that @cancellable - * is on the top of the stack). + * Increases the use count of @application. + * + * 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. + * + * To cancel the hold, call g_application_release(). */ /** - * g_cancellable_push_current: - * @cancellable: a #GCancellable object + * g_application_id_is_valid: + * @application_id: a potential application identifier * - * Pushes @cancellable onto the cancellable stack. The current - * cancellable can then be received using g_cancellable_get_current(). + * Checks if @application_id is a valid application identifier. * - * This is useful when implementing cancellable operations in - * code that does not allow you to pass down the cancellable object. + * A valid ID is required for calls to g_application_new() and + * g_application_set_application_id(). * - * This is typically called automatically by e.g. #GFile operations, - * so you rarely have to call this yourself. - */ - - -/** - * g_cancellable_release_fd: - * @cancellable: a #GCancellable + * For convenience, the restrictions on application identifiers are + * reproduced here: * - * Releases a resources previously allocated by g_cancellable_get_fd() - * or g_cancellable_make_pollfd(). + * - Application identifiers must contain only the ASCII characters + * "[A-Z][a-z][0-9]_-." and must not begin with a digit. * - * 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. + * - Application identifiers must contain at least one '.' (period) + * character (and thus at least two elements). * - * Since: 2.22 + * - Application identifiers must not begin or end with a '.' (period) + * character. + * + * - Application identifiers must not contain consecutive '.' (period) + * characters. + * + * - Application identifiers must not exceed 255 characters. + * + * Returns: %TRUE if @application_id is valid */ /** - * g_cancellable_reset: - * @cancellable: a #GCancellable object. + * g_application_mark_busy: + * @application: a #GApplication * - * Resets @cancellable to its uncancelled state. + * Increases the busy count of @application. * - * If cancellable is currently in use by any cancellable operation - * then the behavior of this function is undefined. + * Use this function to indicate that the application is busy, for instance + * while a long running operation is pending. * - * 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. + * The busy state will be exposed to other processes, so a session shell will + * use that information to indicate the state to the user (e.g. with a + * spinner). + * + * To cancel the busy indication, use g_application_unmark_busy(). + * + * Since: 2.38 */ /** - * g_cancellable_set_error_if_cancelled: - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: #GError to append error state to + * g_application_new: + * @application_id: (nullable): the application id + * @flags: the application flags * - * If the @cancellable is cancelled, sets the error to notify - * that the operation was cancelled. + * Creates a new #GApplication instance. * - * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not + * 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 */ /** - * g_cancellable_source_new: (skip) - * @cancellable: (nullable): a #GCancellable, or %NULL + * 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 * - * 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. + * Opens the given files. * - * For convenience, you can call this with a %NULL #GCancellable, - * in which case the source will never trigger. + * In essence, this results in the #GApplication::open signal being emitted + * in the primary instance. * - * The new #GSource will hold a reference to the #GCancellable. + * @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. * - * Returns: (transfer full): the new #GSource. * Since: 2.28 */ /** - * g_charset_converter_get_num_fallbacks: - * @converter: a #GCharsetConverter + * g_application_quit: + * @application: a #GApplication * - * Gets the number of fallbacks that @converter has applied so far. + * Immediately quits the application. * - * Returns: the number of fallbacks that @converter has applied - * Since: 2.24 + * Upon return to the mainloop, g_application_run() will return, + * calling only the 'shutdown' function before doing so. + * + * The hold count is ignored. + * Take care if your code has called g_application_hold() on the application and + * is therefore still expecting it to exist. + * (Note that you may have called g_application_hold() indirectly, for example + * through gtk_application_add_window().) + * + * The result of calling g_application_run() again after it returns is + * unspecified. + * + * Since: 2.32 */ /** - * g_charset_converter_get_use_fallback: - * @converter: a #GCharsetConverter + * g_application_register: + * @application: a #GApplication + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a pointer to a NULL #GError, or %NULL * - * Gets the #GCharsetConverter:use-fallback property. + * Attempts registration of the application. * - * Returns: %TRUE if fallbacks are used by @converter - * Since: 2.24 + * 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 */ /** - * g_charset_converter_new: - * @to_charset: destination charset - * @from_charset: source charset - * @error: #GError for error reporting, or %NULL to ignore. + * g_application_release: + * @application: a #GApplication * - * Creates a new #GCharsetConverter. + * Decrease the use count of @application. * - * Returns: a new #GCharsetConverter or %NULL on error. - * Since: 2.24 + * 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(). */ /** - * g_charset_converter_set_use_fallback: - * @converter: a #GCharsetConverter - * @use_fallback: %TRUE to use fallbacks + * g_application_run: + * @application: a #GApplication + * @argc: the argc from main() (or 0 if @argv is %NULL) + * @argv: (array length=argc) (element-type filename) (nullable): + * the argv from main(), or %NULL * - * Sets the #GCharsetConverter:use-fallback property. + * Runs the application. * - * Since: 2.24 + * 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. + * + * 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. + * + * If, after the above is done, the use count of the application is zero + * then the exit status is returned immediately. If the use count is + * non-zero then the default main context is iterated until the use count + * falls to zero, at which point 0 is returned. + * + * If the %G_APPLICATION_IS_SERVICE flag is set, then the 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]. + * + * Much like g_main_loop_run(), this function will acquire the main context + * for the duration that the application is running. + * + * Since 2.40, applications that are not explicitly flagged as services + * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or + * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the + * default handler for local_command_line) if "--gapplication-service" + * was given in the command line. If this flag is present then normal + * commandline processing is interrupted and the + * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" + * solution whereby running an application directly from the commandline + * will invoke it in the normal way (which can be useful for debugging) + * while still allowing applications to be D-Bus activated in service + * mode. The D-Bus service file should invoke the executable with + * "--gapplication-service" as the sole commandline argument. This + * approach is suitable for use by most graphical applications but + * should not be used from applications like editors that need precise + * control over when processes invoked via the commandline will exit and + * what their exit status will be. + * + * Returns: the exit status + * Since: 2.28 */ /** - * g_content_type_can_be_executable: - * @type: a content type string + * g_application_send_notification: + * @application: a #GApplication + * @id: (nullable): id of the notification, or %NULL + * @notification: the #GNotification to send * - * 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). + * 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. * - * Returns: %TRUE if the file type corresponds to a type that - * can be executable, %FALSE otherwise. + * Notifications may persist after the application exits. It will be + * D-Bus-activated when the notification or one of its actions is + * activated. + * + * Modifying @notification after this call has no effect. However, the + * object can be reused for a later call to this function. + * + * @id may be any string that uniquely identifies the event for the + * application. It does not need to be in any special format. For + * example, "new-message" might be appropriate for a notification about + * new messages. + * + * If a previous notification was sent with the same @id, it will be + * replaced with @notification and shown again as if it was a new + * notification. This works even for notifications sent from a previous + * execution of the application, as long as @id is the same string. + * + * @id may be %NULL, but it is impossible to replace or withdraw + * notifications without an id. + * + * If @notification is no longer relevant, it can be withdrawn with + * g_application_withdraw_notification(). + * + * Since: 2.40 */ /** - * g_content_type_equals: - * @type1: a content type string - * @type2: a content type string + * g_application_set_action_group: + * @application: a #GApplication + * @action_group: (nullable): a #GActionGroup, or %NULL * - * Compares two content types for equality. + * This used to be how actions were associated with a #GApplication. + * Now there is #GActionMap for that. * - * Returns: %TRUE if the two strings are identical or equivalent, - * %FALSE otherwise. + * 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. */ /** - * g_content_type_from_mime_type: - * @mime_type: a mime type string + * g_application_set_application_id: + * @application: a #GApplication + * @application_id: (nullable): the identifier for @application * - * Tries to find a content type based on the mime type name. + * Sets the unique identifier for @application. * - * Returns: (nullable): Newly allocated string with content type or - * %NULL. Free with g_free() - * Since: 2.18 + * The application id can only be modified if @application has not yet + * been registered. + * + * If non-%NULL, the application id must be valid. See + * g_application_id_is_valid(). + * + * Since: 2.28 */ /** - * g_content_type_get_description: - * @type: a content type string + * g_application_set_default: + * @application: (nullable): the application to set as default, or %NULL * - * Gets the human readable description of the content type. + * Sets or unsets the default application for the process, as returned + * by g_application_get_default(). * - * Returns: a short description of the content type @type. Free the - * returned string with g_free() + * 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_content_type_get_generic_icon_name: - * @type: a content type string + * g_application_set_flags: + * @application: a #GApplication + * @flags: the flags for @application * - * Gets the generic icon name for a content type. + * Sets the flags for @application. * - * See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on the generic icon name. + * The flags can only be modified if @application has not yet been + * registered. * - * Returns: (nullable): the registered generic icon name for the given @type, - * or %NULL if unknown. Free with g_free() - * Since: 2.34 + * See #GApplicationFlags. + * + * Since: 2.28 */ /** - * g_content_type_get_icon: - * @type: a content type string + * g_application_set_inactivity_timeout: + * @application: a #GApplication + * @inactivity_timeout: the timeout, in milliseconds * - * Gets the icon for a content type. + * Sets the current inactivity timeout for the application. * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned - * object with g_object_unref() + * This is the amount of time (in milliseconds) after the last call to + * g_application_release() before the application stops running. + * + * 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. + * + * Since: 2.28 */ /** - * g_content_type_get_mime_type: - * @type: a content type string + * g_application_set_option_context_description: + * @application: the #GApplication + * @description: (nullable): a string to be shown in `--help` output + * after the list of options, or %NULL * - * Gets the mime type for the content type, if one is registered. + * Adds a description to the @application option context. * - * Returns: (nullable): the registered mime type for the given @type, - * or %NULL if unknown. + * See g_option_context_set_description() for more information. + * + * Since: 2.56 */ /** - * g_content_type_get_symbolic_icon: - * @type: a content type string + * g_application_set_option_context_parameter_string: + * @application: the #GApplication + * @parameter_string: (nullable): a string which is displayed + * in the first line of `--help` output, after the usage summary `programname [OPTION...]`. * - * Gets the symbolic icon for a content type. + * Sets the parameter string to be used by the commandline handling of @application. * - * Returns: (transfer full): symbolic #GIcon corresponding to the content type. - * Free the returned object with g_object_unref() - * Since: 2.34 + * This function registers the argument to be passed to g_option_context_new() + * when the internal #GOptionContext of @application is created. + * + * See g_option_context_new() for more information about @parameter_string. + * + * Since: 2.56 */ /** - * g_content_type_guess: - * @filename: (nullable): a string, or %NULL - * @data: (nullable) (array length=data_size): a stream of data, or %NULL - * @data_size: the size of @data - * @result_uncertain: (out) (optional): return location for the certainty - * of the result, or %NULL + * g_application_set_option_context_summary: + * @application: the #GApplication + * @summary: (nullable): a string to be shown in `--help` output + * before the list of options, 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. + * Adds a summary to the @application option context. * - * Returns: a string indicating a guessed content type for the - * given data. Free with g_free() + * See g_option_context_set_summary() for more information. + * + * Since: 2.56 */ /** - * g_content_type_guess_for_tree: - * @root: the root of the tree to guess a type for + * g_application_set_resource_base_path: + * @application: a #GApplication + * @resource_path: (nullable): the resource path to use * - * 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. + * Sets (or unsets) the base resource path of @application. * - * 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. + * 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. * - * This function is useful in the implementation of - * g_mount_guess_content_type(). + * 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. * - * 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_content_type_is_a: - * @type: a content type string - * @supertype: a content type string + * 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". * - * Determines if @type is a subset of @supertype. + * See #GResource for more information about adding resources to your + * application. * - * Returns: %TRUE if @type is a kind of @supertype, - * %FALSE otherwise. - */ - - -/** - * g_content_type_is_mime_type: - * @type: a content type string - * @mime_type: a mime type string + * You can disable automatic resource loading functionality by setting + * the path to %NULL. * - * Determines if @type is a subset of @mime_type. - * Convenience wrapper around g_content_type_is_a(). + * 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. When writing + * a sub-class of #GApplication you should either set the + * #GApplication:resource-base-path property at construction time, or call + * this function during the instance initialization. Alternatively, you + * can call this function in the #GApplicationClass.startup virtual function, + * before chaining up to the parent implementation. * - * Returns: %TRUE if @type is a kind of @mime_type, - * %FALSE otherwise. - * Since: 2.52 + * Since: 2.42 */ /** - * g_content_type_is_unknown: - * @type: a content type string + * g_application_unbind_busy_property: + * @application: a #GApplication + * @object: (type GObject.Object): a #GObject + * @property: the name of a boolean property of @object * - * Checks if the content type is the generic "unknown" type. - * On UNIX this is the "application/octet-stream" mimetype, - * while on win32 it is "*" and on OSX it is a dynamic type - * or octet-stream. + * Destroys a binding between @property and the busy state of + * @application that was previously created with + * g_application_bind_busy_property(). * - * Returns: %TRUE if the type is the unknown type. + * Since: 2.44 */ /** - * g_content_types_get_registered: + * g_application_unmark_busy: + * @application: a #GApplication * - * 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). + * Decreases the busy count of @application. * - * Returns: (element-type utf8) (transfer full): list of the registered - * content types + * When the busy count reaches zero, the new state will be propagated + * to other processes. + * + * This function must only be called to cancel the effect of a previous + * call to g_application_mark_busy(). + * + * Since: 2.38 */ /** - * g_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: (element-type guint8) (array length=outbuf_size): 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 - * - * 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. + * g_application_withdraw_notification: + * @application: a #GApplication + * @id: id of a previously sent notification * - * 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. + * Withdraws a notification that was sent with + * g_application_send_notification(). * - * 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. + * This call does nothing if a notification with @id doesn't exist or + * the notification was never sent. * - * 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). + * 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. * - * 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. + * 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. * - * On error %G_CONVERTER_ERROR is returned and @error is set accordingly. - * Some errors need special handling: + * 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 * - * %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. + * 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. * - * %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. + * This method is intended for language bindings. If writing in C, + * g_async_initable_new_async() should typically be used instead. * - * 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). + * 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. * - * 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. + * 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 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. + * 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. * - * 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. + * Callers should not assume that a class which implements #GAsyncInitable can + * be initialized multiple times; for more information, see g_initable_init(). + * If a class explicitly supports being initialized multiple times, + * implementation requires yielding all subsequent calls to init_async() on the + * results of the first call. * - * 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). + * 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. * - * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error. - * Since: 2.24 + * Since: 2.22 */ /** - * g_converter_input_stream_get_converter: - * @converter_stream: a #GConverterInputStream + * g_async_initable_init_finish: + * @initable: a #GAsyncInitable. + * @res: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets the #GConverter that is used by @converter_stream. + * Finishes asynchronous initialization and returns the result. + * See g_async_initable_init_async(). * - * Returns: (transfer none): the converter of the converter input stream - * Since: 2.24 + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. + * Since: 2.22 */ /** - * g_converter_input_stream_new: - * @base_stream: a #GInputStream - * @converter: a #GConverter - * - * Creates a new converter input stream for the @base_stream. + * 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: (nullable): 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. * - * Returns: a new #GInputStream. - */ - - -/** - * g_converter_output_stream_get_converter: - * @converter_stream: a #GConverterOutputStream + * Helper function for constructing #GAsyncInitable object. This is + * similar to g_object_new() but also initializes the object asynchronously. * - * Gets the #GConverter that is used by @converter_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. * - * Returns: (transfer none): the converter of the converter output stream - * Since: 2.24 + * Since: 2.22 */ /** - * g_converter_output_stream_new: - * @base_stream: a #GOutputStream - * @converter: a #GConverter + * 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 * - * Creates a new converter output stream for the @base_stream. + * Finishes the async construction for the various g_async_initable_new + * calls, returning the created object or %NULL on error. * - * Returns: a new #GOutputStream. + * Returns: (type GObject.Object) (transfer full): a newly created #GObject, + * or %NULL on error. Free with g_object_unref(). + * Since: 2.22 */ /** - * g_converter_reset: - * @converter: a #GConverter. + * 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 * - * 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. + * Helper function for constructing #GAsyncInitable object. This is + * similar to g_object_new_valist() but also initializes the object + * asynchronously. * - * Since: 2.24 + * 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 */ /** - * g_credentials_get_native: (skip) - * @credentials: A #GCredentials. - * @native_type: The type of native credentials to get. + * 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 * - * Gets a pointer to native credentials of type @native_type from - * @credentials. + * Helper function for constructing #GAsyncInitable object. This is + * similar to g_object_newv() but also initializes the object asynchronously. * - * 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. + * 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. * - * 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 + * Since: 2.22 + * Deprecated: 2.54: Use g_object_new_with_properties() and + * g_async_initable_init_async() instead. See #GParameter for more information. */ /** - * g_credentials_get_unix_pid: - * @credentials: A #GCredentials - * @error: Return location for error or %NULL. - * - * Tries to get the UNIX process identifier from @credentials. This - * method is only available on UNIX platforms. + * g_async_result_get_source_object: + * @res: a #GAsyncResult * - * 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. + * Gets the source object from a #GAsyncResult. * - * Returns: The UNIX process ID, or -1 if @error is set. - * Since: 2.36 + * Returns: (transfer full) (nullable): a new reference to the source + * object for the @res, or %NULL if there is none. */ /** - * 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_async_result_get_user_data: + * @res: a #GAsyncResult. * - * 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 the user data from a #GAsyncResult. * - * Returns: The UNIX user identifier or -1 if @error is set. - * Since: 2.26 + * Returns: (transfer full): the user data for @res. */ /** - * 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. + * g_async_result_is_tagged: + * @res: a #GAsyncResult + * @source_tag: an application-defined tag * - * This operation can fail if #GCredentials is not supported on the - * the OS. + * Checks if @res has the given @source_tag (generally a function + * pointer indicating the function @res was created by). * - * Returns: %TRUE if @credentials and @other_credentials has the same - * user, %FALSE otherwise or if @error is set. - * Since: 2.26 + * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if + * not. + * Since: 2.34 */ /** - * g_credentials_new: + * g_async_result_legacy_propagate_error: + * @res: a #GAsyncResult + * @error: (out): a location to propagate the error to. * - * Creates a new #GCredentials object with credentials matching the - * the current process. + * If @res is a #GSimpleAsyncResult, this is equivalent to + * g_simple_async_result_propagate_error(). Otherwise it returns + * %FALSE. * - * Returns: A #GCredentials. Free with g_object_unref(). - * Since: 2.26 + * This can be used for legacy error handling in async *_finish() + * wrapper functions that traditionally handled #GSimpleAsyncResult + * error returns themselves rather than calling into the virtual method. + * This should not be used in new code; #GAsyncResult errors that are + * set by virtual methods should also be extracted by virtual methods, + * to enable subclasses to chain up correctly. + * + * Returns: %TRUE if @error is has been filled in with an error from + * @res, %FALSE if not. + * Since: 2.34 */ /** - * g_credentials_set_native: - * @credentials: A #GCredentials. - * @native_type: The type of native credentials to set. - * @native: (not nullable): A pointer to native credentials. + * g_buffered_input_stream_fill: + * @stream: a #GBufferedInputStream + * @count: the number of bytes that will be read from the stream + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @error: location to store the error occurring, or %NULL to ignore * - * Copies the native credentials of type @native_type from @native - * into @credentials. + * Tries to read @count bytes from the stream into the buffer. + * Will block during this read. * - * 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. + * 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. * - * Since: 2.26 + * 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 @count is -1 then the attempted read size is equal to the number of + * bytes that are required to fill the buffer. + * + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an + * 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(). + * + * Returns: the number of bytes read into @stream's buffer, up to @count, + * or -1 on error. */ /** - * 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_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: (nullable): optional #GCancellable object + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): a #gpointer * - * 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. + * 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(). * - * Returns: %TRUE if @uid was set, %FALSE if error is set. - * Since: 2.26 + * If @count is -1 then the attempted read size is equal to the number + * of bytes that are required to fill the buffer. */ /** - * g_credentials_to_string: - * @credentials: A #GCredentials object. + * g_buffered_input_stream_fill_finish: + * @stream: a #GBufferedInputStream + * @result: a #GAsyncResult + * @error: a #GError * - * 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. + * Finishes an asynchronous read. * - * Returns: A string that should be freed with g_free(). - * Since: 2.26 + * Returns: a #gssize of the read stream, or `-1` on an error. */ /** - * g_data_input_stream_get_byte_order: - * @stream: a given #GDataInputStream. + * g_buffered_input_stream_get_available: + * @stream: #GBufferedInputStream * - * Gets the byte order for the data input stream. + * Gets the size of the available data within the stream. * - * Returns: the @stream's current #GDataStreamByteOrder. + * Returns: size of the available stream. */ /** - * g_data_input_stream_get_newline_type: - * @stream: a given #GDataInputStream. + * g_buffered_input_stream_get_buffer_size: + * @stream: a #GBufferedInputStream * - * Gets the current newline type for the @stream. + * Gets the size of the input buffer. * - * Returns: #GDataStreamNewlineType for the given @stream. + * Returns: the current buffer size. */ /** - * g_data_input_stream_new: - * @base_stream: a #GInputStream. + * g_buffered_input_stream_new: + * @base_stream: a #GInputStream * - * Creates a new data input stream for the @base_stream. + * Creates a new #GInputStream from the given @base_stream, with + * a buffer set to the default size (4 kilobytes). * - * Returns: a new #GDataInputStream. + * Returns: a #GInputStream for the given @base_stream. */ /** - * g_data_input_stream_read_byte: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_buffered_input_stream_new_sized: + * @base_stream: a #GInputStream + * @size: a #gsize * - * Reads an unsigned 8-bit/1-byte value from @stream. + * Creates a new #GBufferedInputStream from the given @base_stream, + * with a buffer set to @size. * - * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 - * if an error occurred. + * Returns: a #GInputStream. */ /** - * g_data_input_stream_read_int16: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a 16-bit/2-byte value from @stream. + * 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 * - * 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(). + * Peeks in the buffer, copying data of size @count into @buffer, + * offset @offset bytes. * - * Returns: a signed 16-bit/2-byte value read from @stream or %0 if - * an error occurred. + * Returns: a #gsize of the number of bytes peeked, or -1 on error. */ /** - * g_data_input_stream_read_int32: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): 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(). + * g_buffered_input_stream_peek_buffer: + * @stream: a #GBufferedInputStream + * @count: (out): a #gsize to get the number of bytes available in 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. + * 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: a signed 32-bit/4-byte value read from the @stream or %0 if - * an error occurred. + * Returns: (array length=count) (element-type guint8) (transfer none): + * read-only buffer */ /** - * g_data_input_stream_read_int64: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_buffered_input_stream_read_byte: + * @stream: a #GBufferedInputStream + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @error: location to store the error occurring, or %NULL to ignore * - * Reads a 64-bit/8-byte value from @stream. + * Tries to read a single byte from the stream or the buffer. Will block + * during this read. * - * 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(). + * 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 @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. * - * Returns: a signed 64-bit/8-byte value read from @stream or %0 if - * an error occurred. + * 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. */ /** - * g_data_input_stream_read_line: - * @stream: a given #GDataInputStream. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * 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. - * - * 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_buffered_input_stream_set_buffer_size: + * @stream: a #GBufferedInputStream + * @size: a #gsize * - * 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. + * 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_data_input_stream_read_line_async: - * @stream: a given #GDataInputStream. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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_buffered_output_stream_get_auto_grow: + * @stream: a #GBufferedOutputStream. * - * 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. + * Checks if the buffer automatically grows as data is added. * - * Since: 2.20 + * Returns: %TRUE if the @stream's buffer automatically grows, + * %FALSE otherwise. */ /** - * g_data_input_stream_read_line_finish: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. + * g_buffered_output_stream_get_buffer_size: + * @stream: a #GBufferedOutputStream. * - * 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. + * Gets the size of the buffer in the @stream. * - * 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 + * Returns: the current size of the buffer. */ /** - * g_data_input_stream_read_line_finish_utf8: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. + * g_buffered_output_stream_new: + * @base_stream: a #GOutputStream. * - * Finish an asynchronous call started by - * g_data_input_stream_read_line_async(). + * Creates a new buffered output stream for a base stream. * - * 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 + * Returns: a #GOutputStream for the given @base_stream. */ /** - * g_data_input_stream_read_line_utf8: - * @stream: a given #GDataInputStream. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a UTF-8 encoded line from the data input stream. + * g_buffered_output_stream_new_sized: + * @base_stream: a #GOutputStream. + * @size: a #gsize. * - * 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 buffered output stream with a given buffer size. * - * 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 + * Returns: a #GOutputStream with an internal buffer set to @size. */ /** - * g_data_input_stream_read_uint16: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): 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_buffered_output_stream_set_auto_grow: + * @stream: a #GBufferedOutputStream. + * @auto_grow: a #gboolean. * - * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if - * an error occurred. + * 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_data_input_stream_read_uint32: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): 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_buffered_output_stream_set_buffer_size: + * @stream: a #GBufferedOutputStream. + * @size: a #gsize. * - * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if - * an error occurred. + * Sets the size of the internal buffer to @size. */ /** - * g_data_input_stream_read_uint64: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_bus_get: + * @bus_type: a #GBusType + * @cancellable: (nullable): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * - * Reads an unsigned 64-bit/8-byte value from @stream. + * Asynchronously connects to the message bus specified by @bus_type. * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order(). + * When the operation is finished, @callback will be invoked. You can + * then call g_bus_get_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. + * This is a asynchronous failable function. See g_bus_get_sync() for + * the synchronous version. * - * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if - * an error occurred. + * Since: 2.26 */ /** - * g_data_input_stream_read_until: - * @stream: a given #GDataInputStream. - * @stop_chars: characters to terminate the read. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_bus_get_finish: + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_bus_get() + * @error: return location for error or %NULL * - * Reads a string from the data input stream, up to the first - * occurrence of any of the stop characters. + * Finishes an operation started with g_bus_get(). * - * Note that, in contrast to g_data_input_stream_read_until_async(), - * this function consumes the stop character that it finds. + * 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(). * - * 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. + * Note that the returned #GDBusConnection object will (usually) have + * the #GDBusConnection:exit-on-close property set to %TRUE. * - * 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. - * Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more - * consistent behaviour regarding the stop character. + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). + * Since: 2.26 */ /** - * 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: (nullable): 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_bus_get_sync: + * @bus_type: a #GBusType + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: return location for error or %NULL * - * The asynchronous version of g_data_input_stream_read_until(). - * It is an error to have two outstanding calls to this function. + * 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. * - * 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. + * This is a synchronous failable function. See g_bus_get() and + * g_bus_get_finish() for the asynchronous version. * - * 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. + * 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(). * - * 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. + * Note that the returned #GDBusConnection object will (usually) have + * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Since: 2.20 - * Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which - * has more consistent behaviour regarding the stop character. + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). + * Since: 2.26 */ /** - * g_data_input_stream_read_until_finish: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. + * 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: (nullable): handler to invoke when connected to the bus of type @bus_type or %NULL + * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL + * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL + * @user_data: user data to pass to handlers + * @user_data_free_func: (nullable): function for freeing @user_data or %NULL * - * Finish an asynchronous call started by - * g_data_input_stream_read_until_async(). + * 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. * - * 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. - * Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which - * has more consistent behaviour regarding the stop character. - */ - - -/** - * 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) (optional): a #gsize to get the length of the data read in - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: #GError for error reporting + * 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: * - * Reads a string from the data input stream, up to the first - * occurrence of any of the stop characters. + * - @name_lost_handler with a %NULL connection (if a connection to the bus + * can't be made). * - * 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. + * - @bus_acquired_handler then @name_lost_handler (if the name can't be + * obtained) * - * Note that @stop_chars may contain '\0' if @stop_chars_len is - * specified. + * - @bus_acquired_handler then @name_acquired_handler (if the name was + * obtained). * - * 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 + * 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 */ /** - * 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: (nullable): 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 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. + * 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: (nullable): handler to invoke when @name is acquired or %NULL + * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL + * @user_data: user data to pass to handlers + * @user_data_free_func: (nullable): function for freeing @user_data or %NULL * - * 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. + * 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 */ /** - * g_data_input_stream_read_upto_finish: - * @stream: a #GDataInputStream - * @result: the #GAsyncResult that was provided to the callback - * @length: (out) (optional): 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_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: (nullable): #GClosure to invoke when @name is + * acquired or %NULL + * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost + * or %NULL * - * 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. + * Version of g_bus_own_name_on_connection() using closures instead of + * callbacks for easier binding in other languages. * - * 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 + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. + * Since: 2.26 */ /** - * g_data_input_stream_set_byte_order: - * @stream: a given #GDataInputStream. - * @order: a #GDataStreamByteOrder to set. + * 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: (nullable): #GClosure to invoke when connected to + * the bus of type @bus_type or %NULL + * @name_acquired_closure: (nullable): #GClosure to invoke when @name is + * acquired or %NULL + * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost or + * %NULL * - * This function sets the byte order for the given @stream. All subsequent - * reads from the @stream will be read in the given @order. + * Version of g_bus_own_name() using closures instead of callbacks for + * easier binding in other languages. + * + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. + * Since: 2.26 */ /** - * g_data_input_stream_set_newline_type: - * @stream: a #GDataInputStream. - * @type: the type of new line return as #GDataStreamNewlineType. + * g_bus_unown_name: + * @owner_id: an identifier obtained from g_bus_own_name() * - * Sets the newline type for the @stream. + * Stops owning a name. * - * 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_bus_unwatch_name: + * @watcher_id: An identifier obtained from g_bus_watch_name() * - * Gets the byte order for the stream. + * Stops watching a name. * - * Returns: the #GDataStreamByteOrder for the @stream. + * Since: 2.26 */ /** - * g_data_output_stream_new: - * @base_stream: a #GOutputStream. + * 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: (nullable): Handler to invoke when @name is known to exist or %NULL. + * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL. + * @user_data: User data to pass to handlers. + * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL. * - * Creates a new data output stream for @base_stream. + * 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. * - * Returns: #GDataOutputStream. + * 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. + * + * 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 */ /** - * g_data_output_stream_put_byte: - * @stream: a #GDataOutputStream. - * @data: a #guchar. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * 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: (nullable): Handler to invoke when @name is known to exist or %NULL. + * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL. + * @user_data: User data to pass to handlers. + * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL. * - * Puts a byte into the output stream. + * Like g_bus_watch_name() but takes a #GDBusConnection instead of a + * #GBusType. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. + * Since: 2.26 */ /** - * g_data_output_stream_put_int16: - * @stream: a #GDataOutputStream. - * @data: a #gint16. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * 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: (nullable): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known + * to not exist or %NULL. * - * Puts a signed 16-bit integer into the output stream. + * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for + * easier binding in other languages. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. + * Since: 2.26 */ /** - * g_data_output_stream_put_int32: - * @stream: a #GDataOutputStream. - * @data: a #gint32. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * 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: (nullable): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known + * to not exist or %NULL. * - * Puts a signed 32-bit integer into the output stream. + * Version of g_bus_watch_name() using closures instead of callbacks for + * easier binding in other languages. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. + * Since: 2.26 */ /** - * g_data_output_stream_put_int64: - * @stream: a #GDataOutputStream. - * @data: a #gint64. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_bytes_icon_get_bytes: + * @icon: a #GIcon. * - * Puts a signed 64-bit integer into the stream. + * Gets the #GBytes associated with the given @icon. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: (transfer none): a #GBytes, or %NULL. + * Since: 2.38 */ /** - * g_data_output_stream_put_string: - * @stream: a #GDataOutputStream. - * @str: a string. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_bytes_icon_new: + * @bytes: a #GBytes. * - * Puts a string into the output stream. + * Creates a new icon for a bytes. * - * Returns: %TRUE if @string was successfully added to the @stream. + * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given + * @bytes, or %NULL on error. + * Since: 2.38 */ /** - * g_data_output_stream_put_uint16: - * @stream: a #GDataOutputStream. - * @data: a #guint16. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_cancellable_cancel: + * @cancellable: (nullable): a #GCancellable object. * - * Puts an unsigned 16-bit integer into the output stream. + * 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.) * - * Returns: %TRUE if @data was successfully added to the @stream. + * 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. */ /** - * g_data_output_stream_put_uint32: - * @stream: a #GDataOutputStream. - * @data: a #guint32. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_cancellable_connect: + * @cancellable: A #GCancellable. + * @callback: The #GCallback to connect. + * @data: Data to pass to @callback. + * @data_destroy_func: (nullable): Free function for @data or %NULL. * - * Puts an unsigned 32-bit integer into the stream. + * 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. * - * Returns: %TRUE if @data was successfully added to the @stream. + * @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. + * + * @data_destroy_func will be called when the handler is + * disconnected, or immediately if the cancellable is already + * cancelled. + * + * See #GCancellable::cancelled for details on how to use this. + * + * Since GLib 2.40, the lock protecting @cancellable is not held when + * @callback is invoked. This lifts a restriction in place for + * earlier GLib versions which now makes it easier to write cleanup + * code that unconditionally invokes e.g. g_cancellable_cancel(). + * + * Returns: The id of the signal handler or 0 if @cancellable has already + * been cancelled. + * Since: 2.22 */ /** - * g_data_output_stream_put_uint64: - * @stream: a #GDataOutputStream. - * @data: a #guint64. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_cancellable_disconnect: + * @cancellable: (nullable): A #GCancellable or %NULL. + * @handler_id: Handler id of the handler to be disconnected, or `0`. * - * Puts an unsigned 64-bit integer into the stream. + * 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. * - * Returns: %TRUE if @data was successfully added to the @stream. + * 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. + * + * If @cancellable is %NULL or @handler_id is `0` this function does + * nothing. + * + * Since: 2.22 */ /** - * g_data_output_stream_set_byte_order: - * @stream: a #GDataOutputStream. - * @order: a %GDataStreamByteOrder. + * g_cancellable_get_current: * - * Sets the byte order of the data output stream to @order. + * Gets the top cancellable from the stack. + * + * Returns: (nullable) (transfer none): a #GCancellable from the top + * of the stack, or %NULL if the stack is empty. */ /** - * g_datagram_based_condition_check: - * @datagram_based: a #GDatagramBased - * @condition: a #GIOCondition mask to check - * - * Checks on the readiness of @datagram_based to perform operations. The - * operations specified in @condition are checked for and masked against the - * currently-satisfied conditions on @datagram_based. The result is returned. - * - * %G_IO_IN will be set in the return value if data is available to read with - * g_datagram_based_receive_messages(), or if the connection is closed remotely - * (EOS); and if the datagram_based has not been closed locally using some - * implementation-specific method (such as g_socket_close() or - * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). - * - * If the connection is shut down or closed (by calling g_socket_close() or - * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for - * example), all calls to this function will return %G_IO_ERROR_CLOSED. - * - * %G_IO_OUT will be set if it is expected that at least one byte can be sent - * using g_datagram_based_send_messages() without blocking. It will not be set - * if the datagram_based has been closed locally. - * - * %G_IO_HUP will be set if the connection has been closed locally. + * g_cancellable_get_fd: + * @cancellable: a #GCancellable. * - * %G_IO_ERR will be set if there was an asynchronous error in transmitting data - * previously enqueued using g_datagram_based_send_messages(). + * 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. * - * Note that on Windows, it is possible for an operation to return - * %G_IO_ERROR_WOULD_BLOCK even immediately after - * g_datagram_based_condition_check() has claimed that the #GDatagramBased is - * ready for writing. Rather than calling g_datagram_based_condition_check() and - * then writing to the #GDatagramBased if it succeeds, it is generally better to - * simply try writing right away, and try again later if the initial attempt - * returns %G_IO_ERROR_WOULD_BLOCK. + * 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(). * - * 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. Apart from - * these flags, the output is guaranteed to be masked by @condition. + * After a successful return from this function, you should use + * g_cancellable_release_fd() to free up resources allocated for + * the returned file descriptor. * - * This call never blocks. + * See also g_cancellable_make_pollfd(). * - * Returns: the #GIOCondition mask of the current state - * Since: 2.48 + * Returns: A valid file descriptor. %-1 if the file descriptor + * is not supported, or on errors. */ /** - * g_datagram_based_condition_wait: - * @datagram_based: a #GDatagramBased - * @condition: a #GIOCondition mask to wait for - * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 - * to block indefinitely - * @cancellable: (nullable): a #GCancellable - * @error: return location for a #GError - * - * Waits for up to @timeout microseconds for condition to become true on - * @datagram_based. If the condition is met, %TRUE is returned. + * g_cancellable_is_cancelled: + * @cancellable: (nullable): a #GCancellable or %NULL * - * If @cancellable is cancelled before the condition is met, or if @timeout is - * reached before the condition is met, then %FALSE is returned and @error is - * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). + * Checks if a cancellable job has been cancelled. * - * Returns: %TRUE if the condition was met, %FALSE otherwise - * Since: 2.48 + * Returns: %TRUE if @cancellable is cancelled, + * FALSE if called with %NULL or if item is not cancelled. */ /** - * g_datagram_based_create_source: - * @datagram_based: a #GDatagramBased - * @condition: a #GIOCondition mask to monitor - * @cancellable: (nullable): a #GCancellable + * g_cancellable_make_pollfd: + * @cancellable: (nullable): a #GCancellable or %NULL + * @pollfd: a pointer to a #GPollFD * - * Creates a #GSource that can be attached to a #GMainContext to monitor for - * the availability of the specified @condition on the #GDatagramBased. The - * #GSource keeps a reference to the @datagram_based. + * 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 callback on the source is of the #GDatagramBasedSourceFunc type. + * 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(). * - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these - * conditions will always be reported in the callback if they are true. + * 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. * - * If non-%NULL, @cancellable 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(). + * 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(). * - * Returns: (transfer full): a newly allocated #GSource - * Since: 2.48 + * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on + * failure to prepare the cancellable. + * Since: 2.22 */ /** - * g_datagram_based_receive_messages: - * @datagram_based: a #GDatagramBased - * @messages: (array length=num_messages): an array of #GInputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags for the overall operation - * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 - * to block indefinitely - * @cancellable: (nullable): a %GCancellable - * @error: return location for a #GError - * - * Receive one or more data messages from @datagram_based in one go. - * - * @messages must point to an array of #GInputMessage structs and - * @num_messages must be the length of this array. Each #GInputMessage - * contains a pointer to an array of #GInputVector structs describing the - * buffers that the data received in each message will be written to. - * - * @flags modify how all messages are received. 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. These - * flags affect the overall receive operation. Flags affecting individual - * messages are returned in #GInputMessage.flags. - * - * The other members of #GInputMessage are treated as described in its - * documentation. + * g_cancellable_new: * - * If @timeout is negative the call will block until @num_messages have been - * received, the connection is closed remotely (EOS), @cancellable is cancelled, - * or an error occurs. + * Creates a new #GCancellable object. * - * If @timeout is 0 the call will return up to @num_messages without blocking, - * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system - * to be received. + * Applications that want to start one or more operations + * that should be cancellable should create a #GCancellable + * and pass it to the operations. * - * If @timeout is positive the call will block on the same conditions as if - * @timeout were negative. If the timeout is reached - * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, - * otherwise it will return the number of messages received before timing out. - * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with - * recvmmsg().) + * One #GCancellable can be used in multiple consecutive + * operations or in multiple concurrent operations. * - * To be notified when messages are available, wait for the %G_IO_IN condition. - * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from - * g_datagram_based_receive_messages() even if you were previously notified of a - * %G_IO_IN condition. + * Returns: a #GCancellable. + */ + + +/** + * g_cancellable_pop_current: + * @cancellable: a #GCancellable object * - * If the remote peer closes the connection, any messages queued in the - * underlying receive buffer will be returned, and subsequent calls to - * g_datagram_based_receive_messages() will return 0 (with no error set). + * Pops @cancellable off the cancellable stack (verifying that @cancellable + * is on the top of the stack). + */ + + +/** + * g_cancellable_push_current: + * @cancellable: a #GCancellable object * - * If the connection is shut down or closed (by calling g_socket_close() or - * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for - * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * Pushes @cancellable onto the cancellable stack. The current + * cancellable can then be received using g_cancellable_get_current(). * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be received; otherwise the number of - * messages successfully received before the error will be returned. If - * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any - * other error. + * This is useful when implementing cancellable operations in + * code that does not allow you to pass down the cancellable object. * - * Returns: number of messages received, or -1 on error. Note that the number - * of messages received may be smaller than @num_messages if @timeout is - * zero or positive, if the peer closed the connection, or if @num_messages - * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - * to receive the remaining messages. - * Since: 2.48 + * This is typically called automatically by e.g. #GFile operations, + * so you rarely have to call this yourself. */ /** - * g_datagram_based_send_messages: - * @datagram_based: a #GDatagramBased - * @messages: (array length=num_messages): an array of #GOutputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags - * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 - * to block indefinitely - * @cancellable: (nullable): a %GCancellable - * @error: return location for a #GError - * - * Send one or more data messages from @datagram_based in one go. - * - * @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. - * - * @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. - * - * The other members of #GOutputMessage are treated as described in its - * documentation. - * - * If @timeout is negative the call will block until @num_messages have been - * sent, @cancellable is cancelled, or an error occurs. - * - * If @timeout is 0 the call will send up to @num_messages without blocking, - * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. - * - * If @timeout is positive the call will block on the same conditions as if - * @timeout were negative. If the timeout is reached before any messages are - * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number - * of messages sent before timing out. - * - * To be notified when messages can be sent, wait for the %G_IO_OUT condition. - * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from - * g_datagram_based_send_messages() 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.) + * g_cancellable_release_fd: + * @cancellable: a #GCancellable * - * If the connection is shut down or closed (by calling g_socket_close() or - * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for - * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * Releases a resources previously allocated by g_cancellable_get_fd() + * or g_cancellable_make_pollfd(). * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be sent; otherwise the number of messages - * successfully sent before the error will be returned. If @cancellable is - * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. + * 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. * - * Returns: number of messages sent, or -1 on error. Note that the number of - * messages sent may be smaller than @num_messages if @timeout is zero - * or positive, 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.48 + * Since: 2.22 */ /** - * g_dbus_action_group_get: - * @connection: A #GDBusConnection - * @bus_name: (nullable): the bus name which exports the action - * group or %NULL if @connection is not a message bus connection - * @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. + * g_cancellable_reset: + * @cancellable: a #GCancellable object. * - * 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. + * Resets @cancellable to its uncancelled state. * - * 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 cancellable is currently in use by any cancellable operation + * then the behavior of this function is undefined. * - * Returns: (transfer full): a #GDBusActionGroup - * Since: 2.32 + * 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_dbus_address_escape_value: - * @string: an unescaped string to be included in a D-Bus address - * as the value in a key-value pair - * - * Escape @string so it can appear in a D-Bus address as the value - * part of a key-value pair. + * g_cancellable_set_error_if_cancelled: + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: #GError to append error state to * - * 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`. + * If the @cancellable is cancelled, sets the error to notify + * that the operation was cancelled. * - * Returns: (transfer full): a copy of @string with all - * non-optionally-escaped bytes escaped - * Since: 2.36 + * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not */ /** - * g_dbus_address_get_for_bus_sync: - * @bus_type: a #GBusType - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL + * g_cancellable_source_new: (skip) + * @cancellable: (nullable): a #GCancellable, or %NULL * - * Synchronously looks up the D-Bus address for the well-known message - * bus instance specified by @bus_type. This may involve using various - * platform specific mechanisms. + * 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. * - * The returned address will be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * For convenience, you can call this with a %NULL #GCancellable, + * in which case the source will never trigger. * - * Returns: a valid D-Bus address string for @bus_type or %NULL if - * @error is set - * Since: 2.26 + * The new #GSource will hold a reference to the #GCancellable. + * + * Returns: (transfer full): the new #GSource. + * Since: 2.28 */ /** - * g_dbus_address_get_stream: - * @address: A valid D-Bus address. - * @cancellable: (nullable): 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. @address must be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * 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. + * g_charset_converter_get_num_fallbacks: + * @converter: a #GCharsetConverter * - * This is an asynchronous failable function. See - * g_dbus_address_get_stream_sync() for the synchronous version. + * Gets the number of fallbacks that @converter has applied so far. * - * Since: 2.26 + * Returns: the number of fallbacks that @converter has applied + * Since: 2.24 */ /** - * g_dbus_address_get_stream_finish: - * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). - * @out_guid: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any. - * @error: Return location for error or %NULL. + * g_charset_converter_get_use_fallback: + * @converter: a #GCharsetConverter * - * Finishes an operation started with g_dbus_address_get_stream(). + * Gets the #GCharsetConverter:use-fallback property. * - * Returns: (transfer full): A #GIOStream or %NULL if @error is set. - * Since: 2.26 + * Returns: %TRUE if fallbacks are used by @converter + * Since: 2.24 */ /** - * g_dbus_address_get_stream_sync: - * @address: A valid D-Bus address. - * @out_guid: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * 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. @address must be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * g_charset_converter_new: + * @to_charset: destination charset + * @from_charset: source charset + * @error: #GError for error reporting, or %NULL to ignore. * - * This is a synchronous failable function. See - * g_dbus_address_get_stream() for the asynchronous version. + * Creates a new #GCharsetConverter. * - * Returns: (transfer full): A #GIOStream or %NULL if @error is set. - * Since: 2.26 + * Returns: a new #GCharsetConverter or %NULL on error. + * Since: 2.24 */ /** - * g_dbus_annotation_info_lookup: - * @annotations: (array zero-terminated=1) (nullable): 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_charset_converter_set_use_fallback: + * @converter: a #GCharsetConverter + * @use_fallback: %TRUE to use fallbacks * - * The cost of this function is O(n) in number of annotations. + * Sets the #GCharsetConverter:use-fallback property. * - * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. - * Since: 2.26 + * Since: 2.24 */ /** - * g_dbus_annotation_info_ref: - * @info: A #GDBusNodeInfo + * g_content_type_can_be_executable: + * @type: a content type string * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Checks if a content type can be executable. Note that for instance + * things like text files can be executables (i.e. scripts and batch files). * - * Returns: The same @info. - * Since: 2.26 + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. */ /** - * g_dbus_annotation_info_unref: - * @info: A #GDBusAnnotationInfo. + * g_content_type_equals: + * @type1: a content type string + * @type2: a content type string * - * 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. + * Compares two content types for equality. * - * Since: 2.26 + * Returns: %TRUE if the two strings are identical or equivalent, + * %FALSE otherwise. */ /** - * g_dbus_arg_info_ref: - * @info: A #GDBusArgInfo + * g_content_type_from_mime_type: + * @mime_type: a mime type string * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Tries to find a content type based on the mime type name. * - * Returns: The same @info. - * Since: 2.26 + * Returns: (nullable): Newly allocated string with content type or + * %NULL. Free with g_free() + * Since: 2.18 */ /** - * g_dbus_arg_info_unref: - * @info: A #GDBusArgInfo. + * g_content_type_get_description: + * @type: a content type string * - * 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 human readable description of the content type. * - * Since: 2.26 + * Returns: a short description of the content type @type. Free the + * returned string with g_free() */ /** - * g_dbus_auth_observer_allow_mechanism: - * @observer: A #GDBusAuthObserver. - * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. + * g_content_type_get_generic_icon_name: + * @type: a content type string * - * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. + * Gets the generic icon name for a content type. * - * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. + * See the + * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) + * specification for more on the generic icon name. + * + * Returns: (nullable): the registered generic icon name for the given @type, + * or %NULL if unknown. Free with g_free() * Since: 2.34 */ /** - * g_dbus_auth_observer_authorize_authenticated_peer: - * @observer: A #GDBusAuthObserver. - * @stream: A #GIOStream for the #GDBusConnection. - * @credentials: (nullable): Credentials received from the peer or %NULL. + * g_content_type_get_icon: + * @type: a content type string * - * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. + * Gets the icon for a content type. * - * Returns: %TRUE if the peer is authorized, %FALSE if not. - * Since: 2.26 + * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned + * object with g_object_unref() */ /** - * g_dbus_auth_observer_new: + * g_content_type_get_mime_type: + * @type: a content type string * - * Creates a new #GDBusAuthObserver object. + * Gets the mime type for the content type, if one is registered. * - * Returns: A #GDBusAuthObserver. Free with g_object_unref(). - * Since: 2.26 + * Returns: (nullable): the registered mime type for the given @type, + * or %NULL if unknown. */ /** - * 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 - * - * 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. - * - * 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. - * - * 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. + * g_content_type_get_symbolic_icon: + * @type: a content type string * - * If @user_data_free_func is non-%NULL, it will be called (in the - * thread-default main context of the thread you are calling this - * method from) at some point after @user_data is no longer - * needed. (It is not guaranteed to be called synchronously when the - * filter is removed, and may be called after @connection has been - * destroyed.) + * Gets the symbolic icon for a content type. * - * Returns: a filter identifier that can be used with - * g_dbus_connection_remove_filter() - * Since: 2.26 + * Returns: (transfer full): symbolic #GIcon corresponding to the content type. + * Free the returned object with g_object_unref() + * Since: 2.34 */ /** - * g_dbus_connection_call: - * @connection: a #GDBusConnection - * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the method - * or %NULL if not passing parameters - * @reply_type: (nullable): the expected type of the reply (which will be a - * tuple), 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: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the request - * is satisfied or %NULL if you don't care about the result of the - * method invocation - * @user_data: the data to pass to @callback - * - * Asynchronously invokes the @method_name method on the - * @interface_name D-Bus interface on the remote object at - * @object_path owned by @bus_name. + * g_content_type_guess: + * @filename: (nullable): a string, or %NULL + * @data: (nullable) (array length=data_size): a stream of data, or %NULL + * @data_size: the size of @data + * @result_uncertain: (out) (optional): return location for the certainty + * of the result, or %NULL * - * 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. + * 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. * - * 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. Unless it’s - * %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more - * values. + * Returns: a string indicating a guessed content type for the + * given data. Free with g_free() + */ + + +/** + * g_content_type_guess_for_tree: + * @root: the root of the tree to guess a type for * - * 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); - * ]| + * 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 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. + * 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 @callback is %NULL then the D-Bus method call message will be sent with - * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. + * This function is useful in the implementation of + * g_mount_guess_content_type(). * - * Since: 2.26 + * 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_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_content_type_is_a: + * @type: a content type string + * @supertype: a content type string * - * Finishes an operation started with g_dbus_connection_call(). + * Determines if @type is a subset of @supertype. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.26 + * Returns: %TRUE if @type is a kind of @supertype, + * %FALSE otherwise. */ /** - * g_dbus_connection_call_sync: - * @connection: a #GDBusConnection - * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the method - * or %NULL if not passing parameters - * @reply_type: (nullable): 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: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL + * g_content_type_is_mime_type: + * @type: a content type string + * @mime_type: a mime type string * - * Synchronously invokes the @method_name method on the - * @interface_name D-Bus interface on the remote object at - * @object_path owned by @bus_name. + * Determines if @type is a subset of @mime_type. + * Convenience wrapper around g_content_type_is_a(). * - * 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. + * Returns: %TRUE if @type is a kind of @mime_type, + * %FALSE otherwise. + * Since: 2.52 + */ + + +/** + * g_content_type_is_unknown: + * @type: a content type string * - * 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. + * Checks if the content type is the generic "unknown" type. + * On UNIX this is the "application/octet-stream" mimetype, + * while on win32 it is "*" and on OSX it is a dynamic type + * or octet-stream. * - * 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); - * ]| + * Returns: %TRUE if the type is the unknown type. + */ + + +/** + * g_content_types_get_registered: * - * The calling thread is blocked until a reply is received. See - * g_dbus_connection_call() for the asynchronous version of - * this method. + * 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: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.26 + * Returns: (element-type utf8) (transfer full): list of the registered + * content types */ /** - * g_dbus_connection_call_with_unix_fd_list: - * @connection: a #GDBusConnection - * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the method - * or %NULL if not passing parameters - * @reply_type: (nullable): 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: (nullable): a #GUnixFDList or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): 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_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: (element-type guint8) (array length=outbuf_size): 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 * - * Like g_dbus_connection_call() but also takes a #GUnixFDList object. + * 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. * - * This method is only available on UNIX. + * 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. * - * Since: 2.30 + * 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. + * + * 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_dbus_connection_call_with_unix_fd_list_finish: - * @connection: a #GDBusConnection - * @out_fd_list: (out) (optional): 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_converter_input_stream_get_converter: + * @converter_stream: a #GConverterInputStream * - * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). + * Gets the #GConverter that is used by @converter_stream. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.30 + * Returns: (transfer none): the converter of the converter input stream + * Since: 2.24 */ /** - * g_dbus_connection_call_with_unix_fd_list_sync: - * @connection: a #GDBusConnection - * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for - * the method or %NULL if not passing parameters - * @reply_type: (nullable): 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: (nullable): a #GUnixFDList or %NULL - * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL - * @cancellable: (nullable): 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_converter_input_stream_new: + * @base_stream: a #GInputStream + * @converter: a #GConverter * - * This method is only available on UNIX. + * Creates a new converter input stream for the @base_stream. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.30 + * Returns: a new #GInputStream. */ /** - * g_dbus_connection_close: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is - * satisfied or %NULL if you don't care about the result - * @user_data: The data to pass to @callback - * - * Closes @connection. Note that this never causes the process to - * exit (this might only happen if the other end of a shared message - * bus connection disconnects, see #GDBusConnection:exit-on-close). - * - * 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. - * - * If @connection is already closed, this method fails with - * %G_IO_ERROR_CLOSED. - * - * 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. + * g_converter_output_stream_get_converter: + * @converter_stream: a #GConverterOutputStream * - * 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. + * Gets the #GConverter that is used by @converter_stream. * - * Since: 2.26 + * Returns: (transfer none): the converter of the converter output stream + * Since: 2.24 */ /** - * 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_converter_output_stream_new: + * @base_stream: a #GOutputStream + * @converter: a #GConverter * - * Finishes an operation started with g_dbus_connection_close(). + * Creates a new converter output stream for the @base_stream. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set - * Since: 2.26 + * Returns: a new #GOutputStream. */ /** - * g_dbus_connection_close_sync: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL + * g_converter_reset: + * @converter: a #GConverter. * - * 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. + * 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. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set - * Since: 2.26 + * Since: 2.24 */ /** - * g_dbus_connection_emit_signal: - * @connection: a #GDBusConnection - * @destination_bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the signal - * or %NULL if not passing parameters - * @error: Return location for error or %NULL - * - * Emits a signal. + * g_credentials_get_native: (skip) + * @credentials: A #GCredentials. + * @native_type: The type of native credentials to get. * - * If the parameters GVariant is floating, it is consumed. + * Gets a pointer to native credentials of type @native_type from + * @credentials. * - * This can only fail if @parameters is not compatible with the D-Bus protocol. + * 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 unless @error is set + * 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_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). + * g_credentials_get_unix_pid: + * @credentials: A #GCredentials + * @error: Return location for error or %NULL. * - * You can unexport the action group using - * g_dbus_connection_unexport_action_group() with the return value of - * this function. + * Tries to get the UNIX process identifier from @credentials. This + * method is only available on UNIX platforms. * - * 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. + * This operation can fail if #GCredentials is not supported on the + * OS or if the native credentials type does not contain information + * about the UNIX process ID. * - * Returns: the ID of the export (never zero), or 0 in case of failure - * Since: 2.32 + * Returns: The UNIX process ID, or -1 if @error is set. + * Since: 2.36 */ /** - * 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. + * g_credentials_get_unix_user: + * @credentials: A #GCredentials + * @error: Return location for error or %NULL. * - * 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). + * Tries to get the UNIX user identifier from @credentials. This + * method is only available on UNIX platforms. * - * You can unexport the menu model using - * g_dbus_connection_unexport_menu_model() with the return value of - * this function. + * 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. * - * Returns: the ID of the export (never zero), or 0 in case of failure - * Since: 2.32 + * Returns: The UNIX user identifier or -1 if @error is set. + * Since: 2.26 */ /** - * g_dbus_connection_flush: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): 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_credentials_is_same_user: + * @credentials: A #GCredentials. + * @other_credentials: A #GCredentials. + * @error: Return location for error or %NULL. * - * 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. + * Checks if @credentials and @other_credentials is the same user. * - * 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. + * This operation can fail if #GCredentials is not supported on the + * the OS. * + * Returns: %TRUE if @credentials and @other_credentials has the same + * user, %FALSE otherwise or if @error is set. * Since: 2.26 */ /** - * g_dbus_connection_flush_finish: - * @connection: a #GDBusConnection - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed - * to g_dbus_connection_flush() - * @error: return location for error or %NULL + * g_credentials_new: * - * Finishes an operation started with g_dbus_connection_flush(). + * Creates a new #GCredentials object with credentials matching the + * the current process. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set + * Returns: A #GCredentials. Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_connection_flush_sync: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL + * g_credentials_set_native: + * @credentials: A #GCredentials. + * @native_type: The type of native credentials to set. + * @native: (not nullable): A pointer to native credentials. * - * 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. + * Copies the native credentials of type @native_type from @native + * into @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. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** - * g_dbus_connection_get_capabilities: - * @connection: a #GDBusConnection + * g_credentials_set_unix_user: + * @credentials: A #GCredentials. + * @uid: The UNIX user identifier to set. + * @error: Return location for error or %NULL. * - * Gets the capabilities negotiated with the remote peer + * Tries to set the UNIX user identifier on @credentials. This method + * is only available on UNIX platforms. * - * Returns: zero or more flags from the #GDBusCapabilityFlags 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. 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_dbus_connection_get_exit_on_close: - * @connection: a #GDBusConnection + * g_credentials_to_string: + * @credentials: A #GCredentials object. * - * Gets whether the process is terminated when @connection is - * closed by the remote peer. See - * #GDBusConnection:exit-on-close for more details. + * 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: whether the process is terminated when @connection is - * closed by the remote peer + * Returns: A string that should be freed with g_free(). * Since: 2.26 */ /** - * g_dbus_connection_get_guid: - * @connection: a #GDBusConnection + * g_data_input_stream_get_byte_order: + * @stream: a given #GDataInputStream. * - * The GUID of the peer performing the role of server when - * authenticating. See #GDBusConnection:guid for more details. + * Gets the byte order for the data input stream. * - * Returns: The GUID. Do not free this string, it is owned by - * @connection. - * Since: 2.26 + * Returns: the @stream's current #GDataStreamByteOrder. */ /** - * g_dbus_connection_get_last_serial: - * @connection: a #GDBusConnection + * g_data_input_stream_get_newline_type: + * @stream: a given #GDataInputStream. * - * 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(). + * Gets the current newline type for the @stream. * - * Returns: the last used serial or zero when no message has been sent - * within the current thread - * Since: 2.34 + * Returns: #GDataStreamNewlineType for the given @stream. */ /** - * 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_data_input_stream_new: + * @base_stream: a #GInputStream. * - * 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. + * Creates a new data input stream for the @base_stream. * - * Returns: (transfer none) (nullable): a #GCredentials or %NULL if not - * available. Do not free this object, it is owned by @connection. - * Since: 2.26 + * Returns: a new #GDataInputStream. */ /** - * g_dbus_connection_get_stream: - * @connection: a #GDBusConnection - * - * Gets the underlying stream used for IO. + * g_data_input_stream_read_byte: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * 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. + * Reads an unsigned 8-bit/1-byte value from @stream. * - * Returns: (transfer none): the stream used for IO - * Since: 2.26 + * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 + * if an error occurred. */ /** - * g_dbus_connection_get_unique_name: - * @connection: a #GDBusConnection + * g_data_input_stream_read_int16: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * 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. + * Reads a 16-bit/2-byte value from @stream. * - * 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 + * 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_dbus_connection_is_closed: - * @connection: a #GDBusConnection + * g_data_input_stream_read_int32: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Gets whether @connection is closed. + * Reads a signed 32-bit/4-byte value from @stream. * - * Returns: %TRUE if the connection is closed, %FALSE otherwise - * Since: 2.26 + * 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: a signed 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ /** - * g_dbus_connection_new: - * @stream: a #GIOStream - * @guid: (nullable): the GUID to use if a authenticating as a server or %NULL - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to @callback + * g_data_input_stream_read_int64: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages + * Reads a 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() 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: a signed 64-bit/8-byte value read from @stream or %0 if + * an error occurred. + */ + + +/** + * g_data_input_stream_read_line: + * @stream: a given #GDataInputStream. + * @length: (out) (optional): a #gsize to get the length of the data read in. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. + * + * 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. + * + * 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: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8): + * a NUL terminated byte array with the line that was read in + * (without the newlines). Set @length to a #gsize to get the length + * of the read line. On an error, it will return %NULL and @error + * will be set. If there's no content to read, it will still return + * %NULL, but @error won't be set. + */ + + +/** + * g_data_input_stream_read_line_async: + * @stream: a given #GDataInputStream. + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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. + * + * 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. + * + * Since: 2.20 + */ + + +/** + * g_data_input_stream_read_line_finish: + * @stream: a given #GDataInputStream. + * @result: the #GAsyncResult that was provided to the callback. + * @length: (out) (optional): 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. + * + * 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_data_input_stream_read_line_finish_utf8: + * @stream: a given #GDataInputStream. + * @result: the #GAsyncResult that was provided to the callback. + * @length: (out) (optional): 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(). + * + * 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_data_input_stream_read_line_utf8: + * @stream: a given #GDataInputStream. + * @length: (out) (optional): a #gsize to get the length of the data read in. + * @cancellable: (nullable): 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. + * + * 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_data_input_stream_read_uint16: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): 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(). + * + * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if + * an error occurred. + */ + + +/** + * g_data_input_stream_read_uint32: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): 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. + * + * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. + */ + + +/** + * g_data_input_stream_read_uint64: + * @stream: a given #GDataInputStream. + * @cancellable: (nullable): 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(). + * + * 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_data_input_stream_read_until: + * @stream: a given #GDataInputStream. + * @stop_chars: characters to terminate the read. + * @length: (out) (optional): a #gsize to get the length of the data read in. + * @cancellable: (nullable): 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. + * + * 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_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: (nullable): 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. + * + * Since: 2.20 + */ + + +/** + * g_data_input_stream_read_until_finish: + * @stream: a given #GDataInputStream. + * @result: the #GAsyncResult that was provided to the callback. + * @length: (out) (optional): 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(). + * + * 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_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) (optional): a #gsize to get the length of the data read in + * @cancellable: (nullable): 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 not consume the stop character. You have to use + * g_data_input_stream_read_byte() to get it before calling + * g_data_input_stream_read_upto() again. + * + * Note that @stop_chars may contain '\0' if @stop_chars_len is + * specified. + * + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error + * 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 [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 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_data_input_stream_read_upto_finish: + * @stream: a #GDataInputStream + * @result: the #GAsyncResult that was provided to the callback + * @length: (out) (optional): 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(). + * + * Note that this function does not consume the stop character. You + * have to use g_data_input_stream_read_byte() to get it before calling + * g_data_input_stream_read_upto_async() again. + * + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. + * Since: 2.24 + */ + + +/** + * g_data_input_stream_set_byte_order: + * @stream: a given #GDataInputStream. + * @order: a #GDataStreamByteOrder 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. + */ + + +/** + * g_data_input_stream_set_newline_type: + * @stream: a #GDataInputStream. + * @type: the type of new line return as #GDataStreamNewlineType. + * + * Sets the newline type for the @stream. + * + * 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_data_output_stream_get_byte_order: + * @stream: a #GDataOutputStream. + * + * Gets the byte order for the stream. + * + * Returns: the #GDataStreamByteOrder for the @stream. + */ + + +/** + * g_data_output_stream_new: + * @base_stream: a #GOutputStream. + * + * Creates a new data output stream for @base_stream. + * + * Returns: #GDataOutputStream. + */ + + +/** + * g_data_output_stream_put_byte: + * @stream: a #GDataOutputStream. + * @data: a #guchar. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts a byte into the output stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_int16: + * @stream: a #GDataOutputStream. + * @data: a #gint16. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts a signed 16-bit integer into the output stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_int32: + * @stream: a #GDataOutputStream. + * @data: a #gint32. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts a signed 32-bit integer into the output stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_int64: + * @stream: a #GDataOutputStream. + * @data: a #gint64. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts a signed 64-bit integer into the stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_string: + * @stream: a #GDataOutputStream. + * @str: a string. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts a string into the output stream. + * + * Returns: %TRUE if @string was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_uint16: + * @stream: a #GDataOutputStream. + * @data: a #guint16. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts an unsigned 16-bit integer into the output stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_uint32: + * @stream: a #GDataOutputStream. + * @data: a #guint32. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts an unsigned 32-bit integer into the stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_put_uint64: + * @stream: a #GDataOutputStream. + * @data: a #guint64. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. + * + * Puts an unsigned 64-bit integer into the stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. + */ + + +/** + * g_data_output_stream_set_byte_order: + * @stream: a #GDataOutputStream. + * @order: a %GDataStreamByteOrder. + * + * Sets the byte order of the data output stream to @order. + */ + + +/** + * g_datagram_based_condition_check: + * @datagram_based: a #GDatagramBased + * @condition: a #GIOCondition mask to check + * + * Checks on the readiness of @datagram_based to perform operations. The + * operations specified in @condition are checked for and masked against the + * currently-satisfied conditions on @datagram_based. The result is returned. + * + * %G_IO_IN will be set in the return value if data is available to read with + * g_datagram_based_receive_messages(), or if the connection is closed remotely + * (EOS); and if the datagram_based has not been closed locally using some + * implementation-specific method (such as g_socket_close() or + * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). + * + * If the connection is shut down or closed (by calling g_socket_close() or + * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for + * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * + * %G_IO_OUT will be set if it is expected that at least one byte can be sent + * using g_datagram_based_send_messages() without blocking. It will not be set + * if the datagram_based has been closed locally. + * + * %G_IO_HUP will be set if the connection has been closed locally. + * + * %G_IO_ERR will be set if there was an asynchronous error in transmitting data + * previously enqueued using g_datagram_based_send_messages(). + * + * Note that on Windows, it is possible for an operation to return + * %G_IO_ERROR_WOULD_BLOCK even immediately after + * g_datagram_based_condition_check() has claimed that the #GDatagramBased is + * ready for writing. Rather than calling g_datagram_based_condition_check() and + * then writing to the #GDatagramBased if it succeeds, it is generally better to + * simply try writing 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. Apart from + * these flags, the output is guaranteed to be masked by @condition. + * + * This call never blocks. + * + * Returns: the #GIOCondition mask of the current state + * Since: 2.48 + */ + + +/** + * g_datagram_based_condition_wait: + * @datagram_based: a #GDatagramBased + * @condition: a #GIOCondition mask to wait for + * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 + * to block indefinitely + * @cancellable: (nullable): a #GCancellable + * @error: return location for a #GError + * + * Waits for up to @timeout microseconds for condition to become true on + * @datagram_based. If the condition is met, %TRUE is returned. + * + * If @cancellable is cancelled before the condition is met, or if @timeout is + * reached before the condition is met, then %FALSE is returned and @error is + * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). + * + * Returns: %TRUE if the condition was met, %FALSE otherwise + * Since: 2.48 + */ + + +/** + * g_datagram_based_create_source: + * @datagram_based: a #GDatagramBased + * @condition: a #GIOCondition mask to monitor + * @cancellable: (nullable): a #GCancellable + * + * Creates a #GSource that can be attached to a #GMainContext to monitor for + * the availability of the specified @condition on the #GDatagramBased. The + * #GSource keeps a reference to the @datagram_based. + * + * The callback on the source is of the #GDatagramBasedSourceFunc type. + * + * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these + * conditions will always be reported in the callback if they are true. + * + * If non-%NULL, @cancellable 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(). + * + * Returns: (transfer full): a newly allocated #GSource + * Since: 2.48 + */ + + +/** + * g_datagram_based_receive_messages: + * @datagram_based: a #GDatagramBased + * @messages: (array length=num_messages): an array of #GInputMessage structs + * @num_messages: the number of elements in @messages + * @flags: an int containing #GSocketMsgFlags flags for the overall operation + * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 + * to block indefinitely + * @cancellable: (nullable): a %GCancellable + * @error: return location for a #GError + * + * Receive one or more data messages from @datagram_based in one go. + * + * @messages must point to an array of #GInputMessage structs and + * @num_messages must be the length of this array. Each #GInputMessage + * contains a pointer to an array of #GInputVector structs describing the + * buffers that the data received in each message will be written to. + * + * @flags modify how all messages are received. 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. These + * flags affect the overall receive operation. Flags affecting individual + * messages are returned in #GInputMessage.flags. + * + * The other members of #GInputMessage are treated as described in its + * documentation. + * + * If @timeout is negative the call will block until @num_messages have been + * received, the connection is closed remotely (EOS), @cancellable is cancelled, + * or an error occurs. + * + * If @timeout is 0 the call will return up to @num_messages without blocking, + * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system + * to be received. + * + * If @timeout is positive the call will block on the same conditions as if + * @timeout were negative. If the timeout is reached + * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, + * otherwise it will return the number of messages received before timing out. + * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with + * recvmmsg().) + * + * To be notified when messages are available, wait for the %G_IO_IN condition. + * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from + * g_datagram_based_receive_messages() even if you were previously notified of a + * %G_IO_IN condition. + * + * If the remote peer closes the connection, any messages queued in the + * underlying receive buffer will be returned, and subsequent calls to + * g_datagram_based_receive_messages() will return 0 (with no error set). + * + * If the connection is shut down or closed (by calling g_socket_close() or + * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for + * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * + * On error -1 is returned and @error is set accordingly. An error will only + * be returned if zero messages could be received; otherwise the number of + * messages successfully received before the error will be returned. If + * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any + * other error. + * + * Returns: number of messages received, or -1 on error. Note that the number + * of messages received may be smaller than @num_messages if @timeout is + * zero or positive, if the peer closed the connection, or if @num_messages + * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try + * to receive the remaining messages. + * Since: 2.48 + */ + + +/** + * g_datagram_based_send_messages: + * @datagram_based: a #GDatagramBased + * @messages: (array length=num_messages): an array of #GOutputMessage structs + * @num_messages: the number of elements in @messages + * @flags: an int containing #GSocketMsgFlags flags + * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 + * to block indefinitely + * @cancellable: (nullable): a %GCancellable + * @error: return location for a #GError + * + * Send one or more data messages from @datagram_based in one go. + * + * @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. + * + * @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. + * + * The other members of #GOutputMessage are treated as described in its + * documentation. + * + * If @timeout is negative the call will block until @num_messages have been + * sent, @cancellable is cancelled, or an error occurs. + * + * If @timeout is 0 the call will send up to @num_messages without blocking, + * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. + * + * If @timeout is positive the call will block on the same conditions as if + * @timeout were negative. If the timeout is reached before any messages are + * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number + * of messages sent before timing out. + * + * To be notified when messages can be sent, wait for the %G_IO_OUT condition. + * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from + * g_datagram_based_send_messages() 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.) + * + * If the connection is shut down or closed (by calling g_socket_close() or + * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for + * example), all calls to this function will return %G_IO_ERROR_CLOSED. + * + * On error -1 is returned and @error is set accordingly. An error will only + * be returned if zero messages could be sent; otherwise the number of messages + * successfully sent before the error will be returned. If @cancellable is + * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. + * + * Returns: number of messages sent, or -1 on error. Note that the number of + * messages sent may be smaller than @num_messages if @timeout is zero + * or positive, 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.48 + */ + + +/** + * g_dbus_action_group_get: + * @connection: A #GDBusConnection + * @bus_name: (nullable): the bus name which exports the action + * group or %NULL if @connection is not a message bus connection + * @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. + * + * 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_dbus_address_escape_value: + * @string: an unescaped string to be included in a D-Bus address + * as the value in a key-value pair + * + * Escape @string so it can appear in a D-Bus address as the value + * part of a key-value pair. + * + * For instance, if @string is `/run/bus-for-:0`, + * this function would return `/run/bus-for-%3A0`, + * which could be used in a D-Bus address like + * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`. + * + * Returns: (transfer full): a copy of @string with all + * non-optionally-escaped bytes escaped + * Since: 2.36 + */ + + +/** + * g_dbus_address_get_for_bus_sync: + * @bus_type: a #GBusType + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: return location for error or %NULL + * + * Synchronously looks up the D-Bus address for the well-known message + * bus instance specified by @bus_type. This may involve using various + * platform specific mechanisms. + * + * The returned address will be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * + * Returns: a valid D-Bus address string for @bus_type or %NULL if + * @error is set + * Since: 2.26 + */ + + +/** + * g_dbus_address_get_stream: + * @address: A valid D-Bus address. + * @cancellable: (nullable): 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. @address must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * + * 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. + * + * This is an asynchronous failable function. See + * g_dbus_address_get_stream_sync() for the synchronous version. + * + * 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: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any. + * @error: Return location for error or %NULL. + * + * Finishes an operation started with g_dbus_address_get_stream(). + * + * 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: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. + * + * 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. @address must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * + * This is a synchronous failable function. See + * g_dbus_address_get_stream() for the asynchronous version. + * + * Returns: (transfer full): A #GIOStream or %NULL if @error is set. + * Since: 2.26 + */ + + +/** + * g_dbus_annotation_info_lookup: + * @annotations: (array zero-terminated=1) (nullable): A %NULL-terminated array of annotations or %NULL. + * @name: The name of the annotation to look up. + * + * Looks up the value of an annotation. + * + * The cost of this function is O(n) in number of annotations. + * + * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. + * Since: 2.26 + */ + + +/** + * g_dbus_annotation_info_ref: + * @info: A #GDBusNodeInfo + * + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. + * + * Returns: The same @info. + * Since: 2.26 + */ + + +/** + * g_dbus_annotation_info_unref: + * @info: A #GDBusAnnotationInfo. + * + * 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.26 + */ + + +/** + * g_dbus_arg_info_ref: + * @info: A #GDBusArgInfo + * + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. + * + * Returns: The same @info. + * Since: 2.26 + */ + + +/** + * g_dbus_arg_info_unref: + * @info: A #GDBusArgInfo. + * + * 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.26 + */ + + +/** + * g_dbus_auth_observer_allow_mechanism: + * @observer: A #GDBusAuthObserver. + * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. + * + * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. + * + * 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: (nullable): Credentials received from the peer or %NULL. + * + * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. + * + * Returns: %TRUE if the peer is authorized, %FALSE if not. + * Since: 2.26 + */ + + +/** + * g_dbus_auth_observer_new: + * + * Creates a new #GDBusAuthObserver object. + * + * 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 + * + * 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. + * + * 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. + * + * 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 @user_data_free_func is non-%NULL, it will be called (in the + * thread-default main context of the thread you are calling this + * method from) at some point after @user_data is no longer + * needed. (It is not guaranteed to be called synchronously when the + * filter is removed, and may be called after @connection has been + * destroyed.) + * + * Returns: a filter identifier that can be used with + * g_dbus_connection_remove_filter() + * Since: 2.26 + */ + + +/** + * g_dbus_connection_call: + * @connection: a #GDBusConnection + * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (nullable): 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: (nullable): a #GCancellable or %NULL + * @callback: (nullable): a #GAsyncReadyCallback to call when the request + * is satisfied or %NULL if you don't care about the result of the + * method invocation + * @user_data: the data to pass to @callback + * + * Asynchronously invokes the @method_name method on the + * @interface_name D-Bus interface on the remote object at + * @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. + * + * 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); + * ]| + * + * 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_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 + * + * Finishes an operation started with g_dbus_connection_call(). + * + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). + * Since: 2.26 + */ + + +/** + * g_dbus_connection_call_sync: + * @connection: a #GDBusConnection + * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (nullable): 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: (nullable): 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. + * + * 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); + * ]| + * + * 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_dbus_connection_call_with_unix_fd_list: + * @connection: a #GDBusConnection + * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (nullable): 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: (nullable): a #GUnixFDList or %NULL + * @cancellable: (nullable): a #GCancellable or %NULL + * @callback: (nullable): 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. + * + * This method is only available on UNIX. + * + * Since: 2.30 + */ + + +/** + * g_dbus_connection_call_with_unix_fd_list_finish: + * @connection: a #GDBusConnection + * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + * g_dbus_connection_call_with_unix_fd_list() + * @error: return location for error or %NULL + * + * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). + * + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). + * Since: 2.30 + */ + + +/** + * g_dbus_connection_call_with_unix_fd_list_sync: + * @connection: a #GDBusConnection + * @bus_name: (nullable): 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: (nullable): a #GVariant tuple with parameters for + * the method or %NULL if not passing parameters + * @reply_type: (nullable): 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: (nullable): a #GUnixFDList or %NULL + * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: return location for error or %NULL + * + * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. + * + * This method is only available on UNIX. + * + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). + * Since: 2.30 + */ + + +/** + * g_dbus_connection_close: + * @connection: a #GDBusConnection + * @cancellable: (nullable): a #GCancellable or %NULL + * @callback: (nullable): a #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback + * + * Closes @connection. Note that this never causes the process to + * exit (this might only happen if the other end of a shared message + * bus connection disconnects, see #GDBusConnection:exit-on-close). + * + * 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. + * + * If @connection is already closed, this method fails with + * %G_IO_ERROR_CLOSED. + * + * 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_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 + * + * Finishes an operation started with g_dbus_connection_close(). + * + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set + * Since: 2.26 + */ + + +/** + * g_dbus_connection_close_sync: + * @connection: a #GDBusConnection + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: return location for error or %NULL + * + * Synchronously closees @connection. The calling thread is blocked + * until this is done. See g_dbus_connection_close() for the + * asynchronous version of this method and more details about what it + * does. + * + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set + * Since: 2.26 + */ + + +/** + * g_dbus_connection_emit_signal: + * @connection: a #GDBusConnection + * @destination_bus_name: (nullable): 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: (nullable): 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. + * + * This can only fail if @parameters is not compatible with the D-Bus protocol. + * + * Returns: %TRUE unless @error is set + * Since: 2.26 + */ + + +/** + * 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. + * + * 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. + * + * Returns: the ID of the export (never zero), or 0 in case of failure + * Since: 2.32 + */ + + +/** + * 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 menu model 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 menu model using + * g_dbus_connection_unexport_menu_model() with the return value of + * this function. + * + * Returns: the ID of the export (never zero), or 0 in case of failure + * Since: 2.32 + */ + + +/** + * g_dbus_connection_flush: + * @connection: a #GDBusConnection + * @cancellable: (nullable): a #GCancellable or %NULL + * @callback: (nullable): 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 guaranteed that the message has + * been sent to the networking buffers in the OS kernel. + * + * This is an asynchronous method. When the operation is finished, + * @callback will be invoked in the + * [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. + * + * Since: 2.26 + */ + + +/** + * g_dbus_connection_flush_finish: + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_flush() + * @error: return location for error or %NULL + * + * Finishes an operation started with g_dbus_connection_flush(). + * + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set + * Since: 2.26 + */ + + +/** + * g_dbus_connection_flush_sync: + * @connection: a #GDBusConnection + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: return location for error or %NULL + * + * Synchronously flushes @connection. The calling thread is blocked + * until this is done. See g_dbus_connection_flush() for the + * asynchronous version of this method and more details about what it + * does. + * + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set + * Since: 2.26 + */ + + +/** + * g_dbus_connection_get_capabilities: + * @connection: a #GDBusConnection + * + * Gets the capabilities negotiated with the remote peer + * + * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration + * Since: 2.26 + */ + + +/** + * g_dbus_connection_get_exit_on_close: + * @connection: a #GDBusConnection + * + * Gets whether the process is terminated when @connection is + * closed by the remote peer. See + * #GDBusConnection:exit-on-close for more details. + * + * Returns: whether the process is terminated when @connection is + * closed by the remote peer + * Since: 2.26 + */ + + +/** + * 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. + * + * 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 + * + * 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(). + * + * Returns: the last used serial or zero when no message has been sent + * within the current thread + * Since: 2.34 + */ + + +/** + * g_dbus_connection_get_peer_credentials: + * @connection: a #GDBusConnection + * + * 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. + * + * 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. + * + * Returns: (transfer none) (nullable): a #GCredentials or %NULL if not + * available. Do not free this object, it is owned by @connection. + * Since: 2.26 + */ + + +/** + * g_dbus_connection_get_stream: + * @connection: a #GDBusConnection + * + * Gets the underlying stream used for IO. + * + * 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. + * + * Returns: (transfer none): the stream used for IO + * Since: 2.26 + */ + + +/** + * g_dbus_connection_get_unique_name: + * @connection: a #GDBusConnection + * + * Gets the unique name of @connection as assigned by the message + * bus. This can also be used to figure out if @connection is a + * message bus connection. + * + * Returns: the unique name or %NULL if @connection is not a message + * bus connection. Do not free this string, it is owned by + * @connection. + * Since: 2.26 + */ + + +/** + * g_dbus_connection_is_closed: + * @connection: a #GDBusConnection + * + * Gets whether @connection is closed. + * + * Returns: %TRUE if the connection is closed, %FALSE otherwise + * Since: 2.26 + */ + + +/** + * g_dbus_connection_new: + * @stream: a #GIOStream + * @guid: (nullable): the GUID to use if a authenticating as a server or %NULL + * @flags: flags describing how to make the connection + * @observer: (nullable): a #GDBusAuthObserver or %NULL + * @cancellable: (nullable): 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. + * + * This is a asynchronous failable constructor. See + * g_dbus_connection_new_sync() for the synchronous + * version. + * + * Since: 2.26 + */ + + +/** + * g_dbus_connection_new_finish: + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback + * passed to g_dbus_connection_new(). + * @error: return location for error or %NULL + * + * Finishes an operation started with g_dbus_connection_new(). + * + * Returns: a #GDBusConnection or %NULL if @error is set. Free + * with g_object_unref(). + * Since: 2.26 + */ + + +/** + * g_dbus_connection_new_for_address: + * @address: a D-Bus address + * @flags: flags describing how to make the connection + * @observer: (nullable): a #GDBusAuthObserver or %NULL + * @cancellable: (nullable): 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](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * + * 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. + * + * This is a asynchronous failable constructor. See + * g_dbus_connection_new_for_address_sync() for the synchronous + * version. + * + * Since: 2.26 + */ + + +/** + * 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 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: (nullable): a #GDBusAuthObserver or %NULL + * @cancellable: (nullable): a #GCancellable or %NULL + * @error: return location for error or %NULL + * + * Synchronously connects and sets up a D-Bus client connection for + * exchanging D-Bus messages with an endpoint specified by @address + * which must be in the + * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * + * 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_dbus_connection_new_sync: + * @stream: a #GIOStream + * @guid: (nullable): the GUID to use if a authenticating as a server or %NULL + * @flags: flags describing how to make the connection + * @observer: (nullable): a #GDBusAuthObserver or %NULL + * @cancellable: (nullable): 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. + * 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. + * + * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 + */ + + +/** + * g_dbus_connection_register_object: + * @connection: a #GDBusConnection + * @object_path: the object path to register at + * @interface_info: introspection data for the interface + * @vtable: (nullable): a #GDBusInterfaceVTable to call into or %NULL + * @user_data: (nullable): 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 + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. + * + * Note that all #GVariant values passed to functions in @vtable will match + * the signature given in @interface_info - if a remote caller passes + * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` + * is returned to the remote caller. + * + * Additionally, if the remote caller attempts to invoke methods or + * access properties not mentioned in @interface_info the + * `org.freedesktop.DBus.Error.UnknownMethod` resp. + * `org.freedesktop.DBus.Error.InvalidArgs` errors + * are returned to the caller. + * + * It is considered a programming error if the + * #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 can implement org.freedesktop.DBus.Properties + * yourself, e.g. to handle getting and setting of properties asynchronously. + * + * Note that the reference count on @interface_info will be + * incremented by 1 (unless allocated statically, e.g. if the + * reference count is -1, see g_dbus_interface_info_ref()) for as long + * as the object is exported. Also note that @vtable will be copied. + * + * See 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_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object) + * @connection: A #GDBusConnection. + * @object_path: The object path to register at. + * @interface_info: Introspection data for the interface. + * @method_call_closure: (nullable): #GClosure for handling incoming method calls. + * @get_property_closure: (nullable): #GClosure for getting a property. + * @set_property_closure: (nullable): #GClosure for setting a property. + * @error: Return location for error or %NULL. + * + * Version of g_dbus_connection_register_object() using closures instead of a + * #GDBusInterfaceVTable for easier binding in other languages. + * + * Returns: 0 if @error is set, otherwise a registration id (never 0) + * that can be used with g_dbus_connection_unregister_object() . + * Since: 2.46 + */ + + +/** + * 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 dynamic 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 + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. + * + * If an existing subtree is already registered at @object_path or + * then @error is set to #G_IO_ERROR_EXISTS. + * + * 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. + * + * Note that @vtable will be copied so you cannot change it after + * registration. + * + * See this [server][gdbus-subtree-server] for an example of how to use + * this method. + * + * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) + * that can be used with g_dbus_connection_unregister_subtree() . + * Since: 2.26 + */ + + +/** + * g_dbus_connection_remove_filter: + * @connection: a #GDBusConnection + * @filter_id: an identifier obtained from g_dbus_connection_add_filter() + * + * Removes a filter. + * + * Note that since filters run in a different thread, there is a race + * condition where it is possible that the filter will be running even + * after calling g_dbus_connection_remove_filter(), so you cannot just + * free data that the filter might be using. Instead, you should pass + * a #GDestroyNotify to g_dbus_connection_add_filter(), which will be + * called when it is guaranteed that the data is no longer needed. + * + * Since: 2.26 + */ + + +/** + * g_dbus_connection_send_message: + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent + * @out_serial: (out) (optional): 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 this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. + * + * Note that @message must be unlocked, unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * + * Returns: %TRUE if the message was well-formed and queued for + * transmission, %FALSE if @error is set + * Since: 2.26 + */ + + +/** + * g_dbus_connection_send_message_with_reply: + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @out_serial: (out) (optional): return location for serial number assigned + * to @message when sending it or %NULL + * @cancellable: (nullable): a #GCancellable or %NULL + * @callback: (nullable): 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. + * + * 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_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 + * + * 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. + * + * 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_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) (optional): return location for serial number + * assigned to @message when sending it or %NULL + * @cancellable: (nullable): 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. + * + * 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_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. + * + * 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. + * + * Since: 2.26 + */ + + +/** + * g_dbus_connection_signal_subscribe: + * @connection: a #GDBusConnection + * @sender: (nullable): sender name to match on (unique or well-known name) + * or %NULL to listen from all senders + * @interface_name: (nullable): D-Bus interface name to match on or %NULL to + * match on all interfaces + * @member: (nullable): D-Bus signal name to match on or %NULL to match on + * all signals + * @object_path: (nullable): object path to match on or %NULL to match on + * all object paths + * @arg0: (nullable): contents of first string argument to match on or %NULL + * to match on all kinds of arguments + * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the + * signal + * @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: (nullable): 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 + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. + * + * If @connection is not a message bus connection, @sender must be + * %NULL. + * + * 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. + * + * 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. + * + * If @user_data_free_func is non-%NULL, it will be called (in the + * thread-default main context of the thread you are calling this + * method from) at some point after @user_data is no longer + * needed. (It is not guaranteed to be called synchronously when the + * signal is unsubscribed from, and may be called after @connection + * has been destroyed.) + * + * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() + * Since: 2.26 + */ + + +/** + * g_dbus_connection_signal_unsubscribe: + * @connection: a #GDBusConnection + * @subscription_id: a subscription id obtained from + * g_dbus_connection_signal_subscribe() + * + * Unsubscribes from signals. + * + * Since: 2.26 + */ + + +/** + * g_dbus_connection_start_message_processing: + * @connection: a #GDBusConnection + * + * 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. + * + * Since: 2.26 + */ + + +/** + * 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(). + * + * 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_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(). + * + * 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_dbus_connection_unregister_object: + * @connection: a #GDBusConnection + * @registration_id: a registration id obtained from + * g_dbus_connection_register_object() + * + * Unregisters an object. + * + * Returns: %TRUE if the object was unregistered, %FALSE otherwise + * Since: 2.26 + */ + + +/** + * g_dbus_connection_unregister_subtree: + * @connection: a #GDBusConnection + * @registration_id: a subtree registration id obtained from + * g_dbus_connection_register_subtree() + * + * Unregisters a subtree. + * + * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise + * 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 + * `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 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_dbus_error_get_remote_error: + * @error: a #GError + * + * Gets the D-Bus error name used for @error, if any. + * + * This function is guaranteed to return a D-Bus error name for all + * #GErrors returned from functions handling remote method calls + * (e.g. g_dbus_connection_call_finish()) unless + * g_dbus_error_strip_remote_error() has been used on @error. + * + * Returns: an allocated string or %NULL if the D-Bus error name + * could not be found. Free with g_free(). + * Since: 2.26 + */ + + +/** + * g_dbus_error_is_remote_error: + * @error: A #GError. + * + * Checks if @error represents an error received via D-Bus from a remote peer. If so, + * use g_dbus_error_get_remote_error() to get the name of the error. + * + * Returns: %TRUE if @error represents an error from a remote peer, + * %FALSE otherwise. + * Since: 2.26 + */ + + +/** + * 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). + * + * This function is typically only used in object mappings to prepare + * #GError instances for applications. Regular applications should not use + * it. + * + * 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. + * + * This is typically done in the routine that returns the #GQuark for + * an error domain. + * + * Returns: %TRUE if the association was created, %FALSE if it already + * exists. + * Since: 2.26 + */ + + +/** + * g_dbus_error_register_error_domain: + * @error_domain_quark_name: The error domain name. + * @quark_volatile: A pointer where to store the #GQuark. + * @entries: (array length=num_entries): A pointer to @num_entries #GDBusErrorEntry struct items. + * @num_entries: Number of items to register. + * + * Helper function for associating a #GError error domain with D-Bus error names. * - * 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. + * 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: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL. + * @...: Arguments for @format. * - * If @observer is not %NULL it may be used to control the - * authentication process. + * 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). * - * 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. + * 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: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL. + * @var_args: Arguments for @format. * - * This is a asynchronous failable constructor. See - * g_dbus_connection_new_sync() for the synchronous - * version. + * Like g_dbus_error_set_dbus_error() but intended for language bindings. + * + * Since: 2.26 + */ + + +/** + * g_dbus_error_strip_remote_error: + * @error: A #GError. + * + * 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. + * + * This is typically used when presenting errors to the end user. + * + * Returns: %TRUE if information was stripped, %FALSE otherwise. + * 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. + * + * 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_dbus_generate_guid: + * + * 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_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: + * + * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay' + * - #G_TYPE_STRV: 'as', 'ao' or 'aay' + * - #G_TYPE_BOOLEAN: 'b' + * - #G_TYPE_UCHAR: 'y' + * - #G_TYPE_INT: 'i', 'n' + * - #G_TYPE_UINT: 'u', 'q' + * - #G_TYPE_INT64 'x' + * - #G_TYPE_UINT64: 't' + * - #G_TYPE_DOUBLE: 'd' + * - #G_TYPE_VARIANT: Any #GVariantType + * + * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type + * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType + * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not + * in the table above. + * + * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is + * %NULL, the empty #GVariant instance (never %NULL) for @type is + * returned (e.g. 0 for scalar types, the empty string for string types, + * '/' for object path types, the empty array for any array type and so on). + * + * See the g_dbus_gvariant_to_gvalue() function for how to convert a + * #GVariant to a #GValue. + * + * Returns: A #GVariant (never floating) of #GVariantType @type holding + * the data from @gvalue or %NULL in case of failure. Free with + * g_variant_unref(). + * Since: 2.30 + */ + + +/** + * g_dbus_gvariant_to_gvalue: + * @value: A #GVariant. + * @out_gvalue: (out): 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. So, a #GVariant + * containing any basic or string array type will be converted to a #GValue + * containing a basic value or string array. Any other #GVariant (handle, + * variant, tuple, dict entry) will be converted to a #GValue containing that + * #GVariant. + * + * The conversion never fails - a valid #GValue is always returned in + * @out_gvalue. + * + * Since: 2.30 + */ + + +/** + * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object) + * @interface_: An exported D-Bus interface. + * + * Gets the #GDBusObject that @interface_ belongs to, if any. + * + * Returns: (transfer full): A #GDBusObject or %NULL. The returned + * reference should be freed with g_object_unref(). + * Since: 2.32 + */ + + +/** + * g_dbus_interface_get_info: + * @interface_: An exported D-Bus interface. + * + * Gets D-Bus introspection information for the D-Bus interface + * implemented by @interface_. + * + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_get_object: (skip) + * @interface_: An exported D-Bus interface + * + * Gets the #GDBusObject that @interface_ belongs to, if any. + * + * It is not safe to use the returned object if @interface_ or + * the returned object is being used from other threads. See + * g_dbus_interface_dup_object() for a thread-safe alternative. + * + * Returns: (transfer none): A #GDBusObject or %NULL. The returned + * reference belongs to @interface_ and should not be freed. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_info_cache_build: + * @info: A #GDBusInterfaceInfo. + * + * 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(). + * + * If this has already been called with @info, the existing cache is + * used and its use count is increased. + * + * Note that @info cannot be modified until + * g_dbus_interface_info_cache_release() is called. + * + * Since: 2.30 + */ + + +/** + * g_dbus_interface_info_cache_release: + * @info: A GDBusInterfaceInfo + * + * 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. + * + * Since: 2.30 + */ + + +/** + * g_dbus_interface_info_generate_xml: + * @info: A #GDBusNodeInfo + * @indent: Indentation level. + * @string_builder: A #GString to to append XML data to. + * + * Appends an XML representation of @info (and its children) to @string_builder. + * + * This function is typically used for generating introspection XML + * documents at run-time for handling the + * `org.freedesktop.DBus.Introspectable.Introspect` + * method. + * + * Since: 2.26 + */ + + +/** + * g_dbus_interface_info_lookup_method: + * @info: A #GDBusInterfaceInfo. + * @name: A D-Bus method name (typically in CamelCase) + * + * Looks up information about a method. + * + * The cost of this function is O(n) in number of methods unless + * g_dbus_interface_info_cache_build() has been used on @info. + * + * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. + * 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. + * + * The cost of this function is O(n) in number of properties unless + * g_dbus_interface_info_cache_build() has been used on @info. + * + * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. + * Since: 2.26 + */ + + +/** + * g_dbus_interface_info_lookup_signal: + * @info: A #GDBusInterfaceInfo. + * @name: A D-Bus signal name (typically in CamelCase) + * + * Looks up information about a signal. + * + * 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: The same @info. + * Since: 2.26 + */ + + +/** + * g_dbus_interface_info_unref: + * @info: A #GDBusInterfaceInfo. + * + * 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.26 + */ + + +/** + * g_dbus_interface_set_object: + * @interface_: An exported D-Bus interface. + * @object: (nullable): A #GDBusObject or %NULL. + * + * Sets the #GDBusObject for @interface_ to @object. + * + * Note that @interface_ will hold a weak reference to @object. + * + * Since: 2.30 + */ + + +/** + * 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. + * + * Use g_dbus_interface_skeleton_unexport() to unexport the object. + * + * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with + * @error set. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_flush: + * @interface_: A #GDBusInterfaceSkeleton. + * + * 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::PropertiesChanged` + * signal later (e.g. in an idle handler). This technique is useful + * for collapsing multiple property changes into one. + * + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_get_connection: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Gets the first connection that @interface_ is exported on, if any. + * + * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is + * not exported anywhere. Do not free, the object belongs to @interface_. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_get_connections: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Gets a list of the connections that @interface_ is exported on. + * + * Returns: (element-type GDBusConnection) (transfer full): A list of + * all the connections that @interface_ is exported on. The returned + * list should be freed with g_list_free() after each element has + * been freed with g_object_unref(). + * Since: 2.32 + */ + + +/** + * g_dbus_interface_skeleton_get_flags: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior + * of @interface_ + * + * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_get_info: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Gets D-Bus introspection information for the D-Bus interface + * implemented by @interface_. + * + * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_get_object_path: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Gets the object path that @interface_ is exported on, if any. + * + * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported + * anywhere. Do not free, the string belongs to @interface_. + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_get_properties: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Gets all D-Bus properties for @interface_. + * + * Returns: (transfer full): A #GVariant of type + * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + * Free with g_variant_unref(). + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_get_vtable: (skip) + * @interface_: A #GDBusInterfaceSkeleton. + * + * 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: A #GDBusInterfaceVTable (never %NULL). + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_has_connection: + * @interface_: A #GDBusInterfaceSkeleton. + * @connection: A #GDBusConnection. + * + * Checks if @interface_ is exported on @connection. + * + * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise. + * Since: 2.32 + */ + + +/** + * g_dbus_interface_skeleton_set_flags: + * @interface_: A #GDBusInterfaceSkeleton. + * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration. + * + * Sets flags describing what the behavior of @skeleton should be. + * + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_unexport: + * @interface_: A #GDBusInterfaceSkeleton. + * + * Stops exporting @interface_ on all connections it is exported on. + * + * To unexport @interface_ from only a single connection, use + * g_dbus_interface_skeleton_unexport_from_connection() + * + * Since: 2.30 + */ + + +/** + * g_dbus_interface_skeleton_unexport_from_connection: + * @interface_: A #GDBusInterfaceSkeleton. + * @connection: A #GDBusConnection. + * + * Stops exporting @interface_ on @connection. + * + * To stop exporting on all connections the interface is exported on, + * use g_dbus_interface_skeleton_unexport(). + * + * Since: 2.32 + */ + + +/** + * g_dbus_is_address: + * @string: A string. + * + * Checks if @string is a + * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * + * This doesn't check if @string is actually supported by #GDBusServer + * or #GDBusConnection - use g_dbus_is_supported_address() to do more + * checks. * + * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_connection_new_finish: - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback - * passed to g_dbus_connection_new(). - * @error: return location for error or %NULL + * g_dbus_is_guid: + * @string: The string to check. * - * Finishes an operation started with g_dbus_connection_new(). + * Checks if @string is a D-Bus GUID. * - * Returns: a #GDBusConnection or %NULL if @error is set. Free - * with g_object_unref(). + * See the D-Bus specification regarding what strings are valid D-Bus + * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * + * Returns: %TRUE if @string is a guid, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_connection_new_for_address: - * @address: a D-Bus address - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): 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](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * 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. + * g_dbus_is_interface_name: + * @string: The string to check. * - * 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. + * Checks if @string is a valid D-Bus interface name. * - * If @observer is not %NULL it may be used to control the - * authentication process. + * Returns: %TRUE if valid, %FALSE otherwise. + * Since: 2.26 + */ + + +/** + * g_dbus_is_member_name: + * @string: The string to check. * - * This is a asynchronous failable constructor. See - * g_dbus_connection_new_for_address_sync() for the synchronous - * version. + * Checks if @string is a valid D-Bus member (e.g. signal or method) name. * + * Returns: %TRUE if valid, %FALSE otherwise. * Since: 2.26 */ /** - * 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_is_name: + * @string: The string to check. * - * Finishes an operation started with g_dbus_connection_new_for_address(). + * Checks if @string is a valid D-Bus bus name (either unique or well-known). * - * Returns: a #GDBusConnection or %NULL if @error is set. Free with - * g_object_unref(). + * Returns: %TRUE if valid, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_connection_new_for_address_sync: - * @address: a D-Bus address - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL + * g_dbus_is_supported_address: + * @string: A string. + * @error: Return location for error or %NULL. * - * Synchronously connects and sets up a D-Bus client connection for - * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the + * Like g_dbus_is_address() but also checks if the library supports the + * transports in @string and that key/value pairs for each transport + * are valid. See the specification of the * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * - * 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(). + * 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_dbus_connection_new_sync: - * @stream: a #GIOStream - * @guid: (nullable): the GUID to use if a authenticating as a server or %NULL - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): 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_is_unique_name: + * @string: The string to check. * - * This is a synchronous failable constructor. See - * g_dbus_connection_new() for the asynchronous version. + * Checks if @string is a valid D-Bus unique bus name. * - * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: %TRUE if valid, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_connection_register_object: + * g_dbus_menu_model_get: * @connection: a #GDBusConnection - * @object_path: the object path to register at - * @interface_info: introspection data for the interface - * @vtable: (nullable): a #GDBusInterfaceVTable to call into or %NULL - * @user_data: (nullable): 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 - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. - * - * Note that all #GVariant values passed to functions in @vtable will match - * the signature given in @interface_info - if a remote caller passes - * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` - * is returned to the remote caller. - * - * Additionally, if the remote caller attempts to invoke methods or - * access properties not mentioned in @interface_info the - * `org.freedesktop.DBus.Error.UnknownMethod` resp. - * `org.freedesktop.DBus.Error.InvalidArgs` errors - * are returned to the caller. - * - * It is considered a programming error if the - * #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 can implement org.freedesktop.DBus.Properties - * yourself, e.g. to handle getting and setting of properties asynchronously. + * @bus_name: (nullable): the bus name which exports the menu model + * or %NULL if @connection is not a message bus connection + * @object_path: the object path at which the menu model is exported * - * 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. + * Obtains a #GDBusMenuModel for the menu model which is exported + * at the given @bus_name and @object_path. * - * See this [server][gdbus-server] for an example of how to use this method. + * 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: 0 if @error is set, otherwise a registration id (never 0) - * that can be used with g_dbus_connection_unregister_object() - * Since: 2.26 + * Returns: (transfer full): a #GDBusMenuModel object. Free with + * g_object_unref(). + * Since: 2.32 */ /** - * g_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object) - * @connection: A #GDBusConnection. - * @object_path: The object path to register at. - * @interface_info: Introspection data for the interface. - * @method_call_closure: (nullable): #GClosure for handling incoming method calls. - * @get_property_closure: (nullable): #GClosure for getting a property. - * @set_property_closure: (nullable): #GClosure for setting a property. + * 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. * - * Version of g_dbus_connection_register_object() using closures instead of a - * #GDBusInterfaceVTable for easier binding in other languages. + * Utility function to calculate how many bytes are needed to + * completely deserialize the D-Bus message stored at @blob. * - * Returns: 0 if @error is set, otherwise a registration id (never 0) - * that can be used with g_dbus_connection_unregister_object() . - * Since: 2.46 + * 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_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 dynamic 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 - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. - * - * If an existing subtree is already registered at @object_path or - * then @error is set to #G_IO_ERROR_EXISTS. - * - * 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. + * g_dbus_message_copy: + * @message: A #GDBusMessage. + * @error: Return location for error or %NULL. * - * Note that @vtable will be copied so you cannot change it after - * registration. + * Copies @message. The copy is a deep copy and the returned + * #GDBusMessage is completely identical except that it is guaranteed + * to not be locked. * - * See this [server][gdbus-subtree-server] for an example of how to use - * this method. + * This operation can fail if e.g. @message contains file descriptors + * and the per-process or system-wide open files limit is reached. * - * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) - * that can be used with g_dbus_connection_unregister_subtree() . + * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_connection_remove_filter: - * @connection: a #GDBusConnection - * @filter_id: an identifier obtained from g_dbus_connection_add_filter() - * - * Removes a filter. + * g_dbus_message_get_arg0: + * @message: A #GDBusMessage. * - * Note that since filters run in a different thread, there is a race - * condition where it is possible that the filter will be running even - * after calling g_dbus_connection_remove_filter(), so you cannot just - * free data that the filter might be using. Instead, you should pass - * a #GDestroyNotify to g_dbus_connection_add_filter(), which will be - * called when it is guaranteed that the data is no longer needed. + * Convenience to get the first item in the body of @message. * + * Returns: The string item or %NULL if the first item in the body of + * @message is not a string. * Since: 2.26 */ /** - * g_dbus_connection_send_message: - * @connection: a #GDBusConnection - * @message: a #GDBusMessage - * @flags: flags affecting how the message is sent - * @out_serial: (out) (optional): 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 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. + * g_dbus_message_get_body: + * @message: A #GDBusMessage. * - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * Gets the body of a message. * - * Returns: %TRUE if the message was well-formed and queued for - * transmission, %FALSE if @error is set + * Returns: (transfer none): A #GVariant or %NULL if the body is + * empty. Do not free, it is owned by @message. * Since: 2.26 */ /** - * g_dbus_connection_send_message_with_reply: - * @connection: a #GDBusConnection - * @message: a #GDBusMessage - * @flags: flags affecting how the message is sent - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @out_serial: (out) (optional): return location for serial number assigned - * to @message when sending it or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): 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. - * - * 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_message_get_byte_order: + * @message: A #GDBusMessage. * - * 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. + * Gets the byte order of @message. * - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * Returns: The byte order. + */ + + +/** + * g_dbus_message_get_destination: + * @message: A #GDBusMessage. * - * 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. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. * + * Returns: The value. * Since: 2.26 */ /** - * g_dbus_connection_send_message_with_reply_finish: - * @connection: a #GDBusConnection - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to - * g_dbus_connection_send_message_with_reply() - * @error: teturn 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. + * g_dbus_message_get_error_name: + * @message: A #GDBusMessage. * - * 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. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. * - * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set + * Returns: The value. * Since: 2.26 */ /** - * g_dbus_connection_send_message_with_reply_sync: - * @connection: a #GDBusConnection - * @message: a #GDBusMessage - * @flags: flags affecting how the message is sent. - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @out_serial: (out) (optional): return location for serial number - * assigned to @message when sending it or %NULL - * @cancellable: (nullable): 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. - * - * 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. + * g_dbus_message_get_flags: + * @message: A #GDBusMessage. * - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * Gets the flags for @message. * - * Returns: (transfer full): a locked #GDBusMessage that is the reply - * to @message or %NULL if @error is set + * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). * Since: 2.26 */ /** - * g_dbus_connection_set_exit_on_close: - * @connection: a #GDBusConnection - * @exit_on_close: whether the process should be terminated - * when @connection is closed by the remote peer - * - * 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_message_get_header: + * @message: A #GDBusMessage. + * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) * - * 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. + * Gets a header field on @message. * + * Returns: A #GVariant with the value if the header was found, %NULL + * otherwise. Do not free, it is owned by @message. * Since: 2.26 */ /** - * g_dbus_connection_signal_subscribe: - * @connection: a #GDBusConnection - * @sender: (nullable): sender name to match on (unique or well-known name) - * or %NULL to listen from all senders - * @interface_name: (nullable): D-Bus interface name to match on or %NULL to - * match on all interfaces - * @member: (nullable): D-Bus signal name to match on or %NULL to match on - * all signals - * @object_path: (nullable): object path to match on or %NULL to match on - * all object paths - * @arg0: (nullable): contents of first string argument to match on or %NULL - * to match on all kinds of arguments - * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the - * signal - * @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: (nullable): function to free @user_data with when - * subscription is removed or %NULL + * g_dbus_message_get_header_fields: + * @message: A #GDBusMessage. * - * 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. + * Gets an array of all header fields on @message that are set. * - * If @connection is not a message bus connection, @sender must be - * %NULL. + * 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_dbus_message_get_interface: + * @message: A #GDBusMessage. * - * 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. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. * - * 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 value. + * Since: 2.26 + */ + + +/** + * g_dbus_message_get_locked: + * @message: A #GDBusMessage. * - * If @user_data_free_func is non-%NULL, it will be called (in the - * thread-default main context of the thread you are calling this - * method from) at some point after @user_data is no longer - * needed. (It is not guaranteed to be called synchronously when the - * signal is unsubscribed from, and may be called after @connection - * has been destroyed.) + * 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: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() + * Returns: %TRUE if @message is locked, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_connection_signal_unsubscribe: - * @connection: a #GDBusConnection - * @subscription_id: a subscription id obtained from - * g_dbus_connection_signal_subscribe() + * g_dbus_message_get_member: + * @message: A #GDBusMessage. * - * Unsubscribes from signals. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. * + * Returns: The value. * Since: 2.26 */ /** - * g_dbus_connection_start_message_processing: - * @connection: a #GDBusConnection + * g_dbus_message_get_message_type: + * @message: A #GDBusMessage. * - * 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. + * Gets the type of @message. * + * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). * Since: 2.26 */ /** - * 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_message_get_num_unix_fds: + * @message: A #GDBusMessage. * - * 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. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. * - * Since: 2.32 + * Returns: The value. + * Since: 2.26 */ /** - * 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_message_get_path: + * @message: A #GDBusMessage. * - * 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. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. * - * Since: 2.32 + * Returns: The value. + * 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_message_get_reply_serial: + * @message: A #GDBusMessage. * - * Unregisters an object. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. * - * Returns: %TRUE if the object was unregistered, %FALSE otherwise + * Returns: The value. * 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_message_get_sender: + * @message: A #GDBusMessage. * - * Unregisters a subtree. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. * - * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise + * Returns: The value. * Since: 2.26 */ /** - * g_dbus_error_encode_gerror: - * @error: A #GError. + * g_dbus_message_get_serial: + * @message: A #GDBusMessage. * - * 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. + * Gets the serial for @message. * - * 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(). + * Returns: A #guint32. + * Since: 2.26 + */ + + +/** + * g_dbus_message_get_signature: + * @message: A #GDBusMessage. * - * This function is typically only used in object mappings to put a - * #GError on the wire. Regular applications should not use it. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. * - * Returns: A D-Bus error name (never %NULL). Free with g_free(). + * Returns: The value. * Since: 2.26 */ /** - * g_dbus_error_get_remote_error: - * @error: a #GError + * g_dbus_message_get_unix_fd_list: + * @message: A #GDBusMessage. * - * Gets the D-Bus error name used for @error, if any. + * Gets the UNIX file descriptors associated with @message, if any. * - * 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. + * This method is only available on UNIX. * - * Returns: an allocated string or %NULL if the D-Bus error name - * could not be found. Free with g_free(). + * 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_error_is_remote_error: - * @error: A #GError. + * g_dbus_message_lock: + * @message: A #GDBusMessage. * - * 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. + * If @message is locked, does nothing. Otherwise locks the message. * - * Returns: %TRUE if @error represents an error from a remote peer, - * %FALSE otherwise. * Since: 2.26 */ /** - * 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. + * g_dbus_message_new: * - * 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. + * Creates a new empty #GDBusMessage. * - * 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(). + * 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. * - * 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(). + * 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(). * - * 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). + * Returns: A new #GDBusMessage or %NULL if @error is set. Free with + * g_object_unref(). + * Since: 2.26 + */ + + +/** + * g_dbus_message_new_method_call: + * @name: (nullable): A valid D-Bus name or %NULL. + * @path: A valid object path. + * @interface_: (nullable): A valid D-Bus interface name or %NULL. + * @method: A valid method name. * - * This function is typically only used in object mappings to prepare - * #GError instances for applications. Regular applications should not use - * it. + * Creates a new #GDBusMessage for a method call. * - * Returns: An allocated #GError. Free with g_error_free(). + * Returns: A #GDBusMessage. Free with g_object_unref(). * 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. + * 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. * - * Creates an association to map between @dbus_error_name and - * #GErrors specified by @error_domain and @error_code. + * Creates a new #GDBusMessage that is an error reply to @method_call_message. * - * This is typically done in the routine that returns the #GQuark for - * an error domain. + * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 + */ + + +/** + * 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. * - * Returns: %TRUE if the association was created, %FALSE if it already - * exists. + * Creates a new #GDBusMessage that is an error reply to @method_call_message. + * + * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_error_register_error_domain: - * @error_domain_quark_name: The error domain name. - * @quark_volatile: A pointer where to store the #GQuark. - * @entries: (array length=num_entries): A pointer to @num_entries #GDBusErrorEntry struct items. - * @num_entries: Number of items to register. + * 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. * - * Helper function for associating a #GError error domain with D-Bus error names. + * Like g_dbus_message_new_method_error() but intended for language bindings. * + * Returns: (transfer full): A #GDBusMessage. Free with g_object_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: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL. - * @...: Arguments for @format. + * g_dbus_message_new_method_reply: + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * - * 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). + * Creates a new #GDBusMessage that is a reply to @method_call_message. * + * Returns: (transfer full): #GDBusMessage. Free with g_object_unref(). * 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: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL. - * @var_args: Arguments for @format. + * g_dbus_message_new_signal: + * @path: A valid object path. + * @interface_: A valid D-Bus interface name. + * @signal: A valid signal name. * - * Like g_dbus_error_set_dbus_error() but intended for language bindings. + * Creates a new #GDBusMessage for a signal emission. * + * Returns: A #GDBusMessage. Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_error_strip_remote_error: - * @error: A #GError. + * g_dbus_message_print: (type method-return) + * @message: A #GDBusMessage. + * @indent: Indentation level. * - * 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. + * Produces a human-readable multi-line description of @message. * - * This is typically used when presenting errors to the end user. + * 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: %TRUE if information was stripped, %FALSE otherwise. + * Returns: A string that should be freed with g_free(). * 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_message_set_body: + * @message: A #GDBusMessage. + * @body: Either %NULL or a #GVariant that is a tuple. * - * Destroys an association previously set up with g_dbus_error_register_error(). + * 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). + * + * If @body is floating, @message assumes ownership of @body. * - * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found. * Since: 2.26 */ /** - * g_dbus_generate_guid: + * g_dbus_message_set_byte_order: + * @message: A #GDBusMessage. + * @byte_order: The byte order. * - * Generate a D-Bus GUID that can be used with - * e.g. g_dbus_connection_new(). + * Sets the byte order of @message. + */ + + +/** + * g_dbus_message_set_destination: + * @message: A #GDBusMessage. + * @value: The value to set. * - * See the D-Bus specification regarding what strings are valid D-Bus - * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. * - * Returns: A valid D-Bus GUID. Free with g_free(). * Since: 2.26 */ /** - * g_dbus_gvalue_to_gvariant: - * @gvalue: A #GValue to convert to a #GVariant - * @type: A #GVariantType + * g_dbus_message_set_error_name: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Converts a #GValue to a #GVariant of the type indicated by the @type - * parameter. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. * - * The conversion is using the following rules: + * Since: 2.26 + */ + + +/** + * g_dbus_message_set_flags: + * @message: A #GDBusMessage. + * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags + * enumeration bitwise ORed together). * - * - #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 + * Sets the flags to set on @message. * - * 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. + * Since: 2.26 + */ + + +/** + * g_dbus_message_set_header: + * @message: A #GDBusMessage. + * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) + * @value: (nullable): A #GVariant to set the header field or %NULL to clear the header field. * - * 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). + * Sets a header field on @message. * - * See the g_dbus_gvariant_to_gvalue() function for how to convert a - * #GVariant to a #GValue. + * If @value is floating, @message assumes ownership of @value. * - * 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 + * Since: 2.26 */ /** - * g_dbus_gvariant_to_gvalue: - * @value: A #GVariant. - * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue. + * g_dbus_message_set_interface: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Converts a #GVariant to a #GValue. If @value is floating, it is consumed. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. * - * The rules specified in the g_dbus_gvalue_to_gvariant() function are - * used - this function is essentially its reverse form. So, a #GVariant - * containing any basic or string array type will be converted to a #GValue - * containing a basic value or string array. Any other #GVariant (handle, - * variant, tuple, dict entry) will be converted to a #GValue containing that - * #GVariant. + * Since: 2.26 + */ + + +/** + * g_dbus_message_set_member: + * @message: A #GDBusMessage. + * @value: The value to set. * - * The conversion never fails - a valid #GValue is always returned in - * @out_gvalue. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. * - * Since: 2.30 + * Since: 2.26 */ /** - * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object) - * @interface_: An exported D-Bus interface. + * g_dbus_message_set_message_type: + * @message: A #GDBusMessage. + * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). * - * Gets the #GDBusObject that @interface_ belongs to, if any. + * Sets @message to be of @type. * - * Returns: (transfer full): A #GDBusObject or %NULL. The returned - * reference should be freed with g_object_unref(). - * Since: 2.32 + * Since: 2.26 */ /** - * g_dbus_interface_get_info: - * @interface_: An exported D-Bus interface. + * g_dbus_message_set_num_unix_fds: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Gets D-Bus introspection information for the D-Bus interface - * implemented by @interface_. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. * - * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. - * Since: 2.30 + * Since: 2.26 */ /** - * g_dbus_interface_get_object: (skip) - * @interface_: An exported D-Bus interface - * - * Gets the #GDBusObject that @interface_ belongs to, if any. + * g_dbus_message_set_path: + * @message: A #GDBusMessage. + * @value: The value to set. * - * 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. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. * - * Returns: (transfer none): A #GDBusObject or %NULL. The returned - * reference belongs to @interface_ and should not be freed. - * Since: 2.30 + * Since: 2.26 */ /** - * g_dbus_interface_info_cache_build: - * @info: A #GDBusInterfaceInfo. + * g_dbus_message_set_reply_serial: + * @message: A #GDBusMessage. + * @value: The value to set. * - * 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(). + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. * - * If this has already been called with @info, the existing cache is - * used and its use count is increased. + * Since: 2.26 + */ + + +/** + * g_dbus_message_set_sender: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Note that @info cannot be modified until - * g_dbus_interface_info_cache_release() is called. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. * - * Since: 2.30 + * Since: 2.26 */ /** - * g_dbus_interface_info_cache_release: - * @info: A GDBusInterfaceInfo + * g_dbus_message_set_serial: + * @message: A #GDBusMessage. + * @serial: A #guint32. * - * 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. + * Sets the serial for @message. * - * Since: 2.30 + * Since: 2.26 */ /** - * g_dbus_interface_info_generate_xml: - * @info: A #GDBusNodeInfo - * @indent: Indentation level. - * @string_builder: A #GString to to append XML data to. - * - * Appends an XML representation of @info (and its children) to @string_builder. + * g_dbus_message_set_signature: + * @message: A #GDBusMessage. + * @value: The value to set. * - * This function is typically used for generating introspection XML - * documents at run-time for handling the - * `org.freedesktop.DBus.Introspectable.Introspect` - * method. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. * * Since: 2.26 */ /** - * g_dbus_interface_info_lookup_method: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus method name (typically in CamelCase) + * g_dbus_message_set_unix_fd_list: + * @message: A #GDBusMessage. + * @fd_list: (nullable): A #GUnixFDList or %NULL. * - * Looks up information about a method. + * 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). * - * The cost of this function is O(n) in number of methods unless - * g_dbus_interface_info_cache_build() has been used on @info. + * This method is only available on UNIX. * - * 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_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. * - * The cost of this function is O(n) in number of properties unless - * g_dbus_interface_info_cache_build() has been used on @info. + * Serializes @message to a blob. The byte order returned by + * g_dbus_message_get_byte_order() will be used. * - * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. + * 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_dbus_interface_info_lookup_signal: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus signal name (typically in CamelCase) + * g_dbus_message_to_gerror: + * @message: A #GDBusMessage. + * @error: The #GError to set. * - * Looks up information about a signal. + * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does + * nothing and returns %FALSE. * - * The cost of this function is O(n) in number of signals unless - * g_dbus_interface_info_cache_build() has been used on @info. + * 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: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. + * Returns: %TRUE if @error was set, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_interface_info_ref: - * @info: A #GDBusInterfaceInfo + * g_dbus_method_info_ref: + * @info: A #GDBusMethodInfo * * If @info is statically allocated does nothing. Otherwise increases * the reference count. @@ -16429,8 +19326,8 @@ /** - * g_dbus_interface_info_unref: - * @info: A #GDBusInterfaceInfo. + * 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, @@ -16441,6614 +19338,7162 @@ /** - * g_dbus_interface_set_object: - * @interface_: An exported D-Bus interface. - * @object: (nullable): A #GDBusObject or %NULL. - * - * Sets the #GDBusObject for @interface_ to @object. + * g_dbus_method_invocation_get_connection: + * @invocation: A #GDBusMethodInvocation. * - * Note that @interface_ will hold a weak reference to @object. + * Gets the #GDBusConnection the method was invoked on. * - * Since: 2.30 + * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation. + * 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. + * g_dbus_method_invocation_get_interface_name: + * @invocation: A #GDBusMethodInvocation. * - * 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. + * Gets the name of the D-Bus interface the method was invoked on. * - * Use g_dbus_interface_skeleton_unexport() to unexport the object. + * 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: %TRUE if the interface was exported on @connection, otherwise %FALSE with - * @error set. - * Since: 2.30 + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_flush: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_message: + * @invocation: A #GDBusMethodInvocation. * - * If @interface_ has outstanding changes, request for these changes to be - * emitted immediately. + * 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. * - * For example, an exported D-Bus interface may queue up property - * changes and emit the - * `org.freedesktop.DBus.Properties.PropertiesChanged` - * signal later (e.g. in an idle handler). This technique is useful - * for collapsing multiple property changes into one. + * 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.30 + * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_get_connection: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_method_info: + * @invocation: A #GDBusMethodInvocation. * - * Gets the first connection that @interface_ is exported on, if any. + * Gets information about the method call, if any. * - * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is - * not exported anywhere. Do not free, the object belongs to @interface_. - * Since: 2.30 + * If this method invocation is a property Get, Set or GetAll call that + * has been redirected to the method call handler then %NULL will be + * returned. See g_dbus_method_invocation_get_property_info() and + * #GDBusInterfaceVTable for more information. + * + * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_get_connections: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_method_name: + * @invocation: A #GDBusMethodInvocation. * - * Gets a list of the connections that @interface_ is exported on. + * Gets the name of the method that was invoked. * - * 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 + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_get_flags: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_object_path: + * @invocation: A #GDBusMethodInvocation. * - * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior - * of @interface_ + * Gets the object path the method was invoked on. * - * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. - * Since: 2.30 + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_get_info: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_parameters: + * @invocation: A #GDBusMethodInvocation. * - * Gets D-Bus introspection information for the D-Bus interface - * implemented by @interface_. + * 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 #GDBusInterfaceInfo (never %NULL). Do not free. - * Since: 2.30 + * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_get_object_path: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_property_info: + * @invocation: A #GDBusMethodInvocation * - * Gets the object path that @interface_ is exported on, if any. + * Gets information about the property that this method call is for, if + * any. * - * 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 + * 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_interface_skeleton_get_properties: - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_sender: + * @invocation: A #GDBusMethodInvocation. * - * Gets all D-Bus properties for @interface_. + * Gets the bus name that invoked the method. * - * Returns: (transfer full): A #GVariant of type - * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. - * Free with g_variant_unref(). - * Since: 2.30 + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_get_vtable: (skip) - * @interface_: A #GDBusInterfaceSkeleton. + * g_dbus_method_invocation_get_user_data: (skip) + * @invocation: A #GDBusMethodInvocation. * - * 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. + * Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). * - * Returns: A #GDBusInterfaceVTable (never %NULL). - * Since: 2.30 + * Returns: A #gpointer. + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_has_connection: - * @interface_: A #GDBusInterfaceSkeleton. - * @connection: A #GDBusConnection. + * 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. * - * Checks if @interface_ is exported on @connection. + * Finishes handling a D-Bus method call by returning an error. * - * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise. - * Since: 2.32 + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. + * + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_set_flags: - * @interface_: A #GDBusInterfaceSkeleton. - * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration. + * 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. * - * Sets flags describing what the behavior of @skeleton should be. + * Finishes handling a D-Bus method call by returning an error. * - * Since: 2.30 + * 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 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(). + * + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. + * + * Since 2.48, if the method call requested for a reply not to be sent + * then this call will free @invocation but otherwise do nothing (as per + * the recommendations of the D-Bus specification). + * + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_unexport: - * @interface_: A #GDBusInterfaceSkeleton. + * 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. * - * Stops exporting @interface_ on all connections it is exported on. + * Like g_dbus_method_invocation_return_error() but without printf()-style formatting. * - * To unexport @interface_ from only a single connection, use - * g_dbus_interface_skeleton_unexport_from_connection() + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. * - * Since: 2.30 + * Since: 2.26 */ /** - * g_dbus_interface_skeleton_unexport_from_connection: - * @interface_: A #GDBusInterfaceSkeleton. - * @connection: A #GDBusConnection. + * 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. * - * Stops exporting @interface_ on @connection. + * Like g_dbus_method_invocation_return_error() but intended for + * language bindings. * - * To stop exporting on all connections the interface is exported on, - * use g_dbus_interface_skeleton_unexport(). + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. * - * Since: 2.32 + * Since: 2.26 */ /** - * g_dbus_is_address: - * @string: A string. + * g_dbus_method_invocation_return_gerror: + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @error: A #GError. * - * Checks if @string is a - * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * Like g_dbus_method_invocation_return_error() but takes a #GError + * instead of the error domain, error code and message. * - * This doesn't check if @string is actually supported by #GDBusServer - * or #GDBusConnection - use g_dbus_is_supported_address() to do more - * checks. + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. * - * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_is_guid: - * @string: The string to check. + * g_dbus_method_invocation_return_value: + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. * - * Checks if @string is a D-Bus GUID. + * Finishes handling a D-Bus method call by returning @parameters. + * If the @parameters GVariant is floating, it is consumed. * - * See the D-Bus specification regarding what strings are valid D-Bus - * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * It is an error if @parameters is not of the right format: it must be a tuple + * containing the out-parameters of the D-Bus method. Even if the method has a + * single out-parameter, it must be contained in a tuple. If the method has no + * out-parameters, @parameters may be %NULL or an empty tuple. + * + * |[ + * GDBusMethodInvocation *invocation = some_invocation; + * g_autofree gchar *result_string = NULL; + * g_autoptr (GError) error = NULL; + * + * result_string = calculate_result (&error); + * + * if (error != NULL) + * g_dbus_method_invocation_return_gerror (invocation, error); + * else + * g_dbus_method_invocation_return_value (invocation, + * g_variant_new ("(s)", result_string)); + * + * /* Do not free @invocation here; returning a value does that */ + * ]| + * + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. + * + * Since 2.48, if the method call requested for a reply not to be sent + * then this call will sink @parameters and free @invocation, but + * otherwise do nothing (as per the recommendations of the D-Bus + * specification). * - * Returns: %TRUE if @string is a guid, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_is_interface_name: - * @string: The string to check. + * g_dbus_method_invocation_return_value_with_unix_fd_list: + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. + * @fd_list: (nullable): A #GUnixFDList or %NULL. * - * Checks if @string is a valid D-Bus interface name. + * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 + * This method is only available on UNIX. + * + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. + * + * Since: 2.30 */ /** - * g_dbus_is_member_name: - * @string: The string to check. + * g_dbus_method_invocation_take_error: (skip) + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @error: (transfer full): A #GError. * - * Checks if @string is a valid D-Bus member (e.g. signal or method) name. + * Like g_dbus_method_invocation_return_gerror() but takes ownership + * of @error so the caller does not need to free it. * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 + * This method will take ownership of @invocation. See + * #GDBusInterfaceVTable for more information about the ownership of + * @invocation. + * + * Since: 2.30 */ /** - * g_dbus_is_name: - * @string: The string to check. + * g_dbus_node_info_generate_xml: + * @info: A #GDBusNodeInfo. + * @indent: Indentation level. + * @string_builder: A #GString to to append XML data to. * - * Checks if @string is a valid D-Bus bus name (either unique or well-known). + * Appends an XML representation of @info (and its children) to @string_builder. + * + * This function is typically used for generating introspection XML documents at run-time for + * handling the `org.freedesktop.DBus.Introspectable.Introspect` method. * - * Returns: %TRUE if valid, %FALSE otherwise. * Since: 2.26 */ /** - * g_dbus_is_supported_address: - * @string: A string. - * @error: Return location for error or %NULL. + * g_dbus_node_info_lookup_interface: + * @info: A #GDBusNodeInfo. + * @name: A D-Bus interface name. * - * Like g_dbus_is_address() but also checks if the library supports the - * transports in @string and that key/value pairs for each transport - * are valid. See the specification of the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + * Looks up information about an interface. * - * Returns: %TRUE if @string is a valid D-Bus address that is - * supported by this library, %FALSE if @error is set. + * The cost of this function is O(n) in number of interfaces. + * + * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. * Since: 2.26 */ /** - * g_dbus_is_unique_name: - * @string: The string to check. + * g_dbus_node_info_new_for_xml: + * @xml_data: Valid D-Bus introspection XML. + * @error: Return location for error. * - * Checks if @string is a valid D-Bus unique bus name. + * Parses @xml_data and returns a #GDBusNodeInfo representing the data. * - * Returns: %TRUE if valid, %FALSE otherwise. + * The introspection XML must contain exactly one top-level + * 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_menu_model_get: - * @connection: a #GDBusConnection - * @bus_name: (nullable): the bus name which exports the menu model - * or %NULL if @connection is not a message bus connection - * @object_path: the object path at which the menu model is exported - * - * Obtains a #GDBusMenuModel for the menu model which is exported - * at the given @bus_name and @object_path. + * g_dbus_node_info_ref: + * @info: A #GDBusNodeInfo * - * 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. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * Returns: (transfer full): a #GDBusMenuModel object. Free with - * g_object_unref(). - * Since: 2.32 + * Returns: The same @info. + * Since: 2.26 */ /** - * 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. + * g_dbus_node_info_unref: + * @info: A #GDBusNodeInfo. * - * Utility function to calculate how many bytes are needed to - * completely deserialize the D-Bus message stored at @blob. + * 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: 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_dbus_message_copy: - * @message: A #GDBusMessage. - * @error: Return location for error or %NULL. + * g_dbus_object_get_interface: + * @object: A #GDBusObject. + * @interface_name: A D-Bus interface name. * - * Copies @message. The copy is a deep copy and the returned - * #GDBusMessage is completely identical except that it is guaranteed - * to not be locked. + * Gets the D-Bus interface with name @interface_name associated with + * @object, if any. * - * This operation can fail if e.g. @message contains file descriptors - * and the per-process or system-wide open files limit is reached. + * Returns: (transfer full): %NULL if not found, otherwise a + * #GDBusInterface that must be freed with g_object_unref(). + * Since: 2.30 + */ + + +/** + * g_dbus_object_get_interfaces: + * @object: A #GDBusObject. * - * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 + * Gets the D-Bus interfaces associated with @object. + * + * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. + * The returned list must be freed by g_list_free() after each element has been freed + * with g_object_unref(). + * Since: 2.30 */ /** - * g_dbus_message_get_arg0: - * @message: A #GDBusMessage. + * g_dbus_object_get_object_path: + * @object: A #GDBusObject. * - * Convenience to get the first item in the body of @message. + * Gets the object path for @object. * - * Returns: The string item or %NULL if the first item in the body of - * @message is not a string. - * Since: 2.26 + * Returns: A string owned by @object. Do not free. + * Since: 2.30 */ /** - * g_dbus_message_get_body: - * @message: A #GDBusMessage. + * g_dbus_object_manager_client_get_connection: + * @manager: A #GDBusObjectManagerClient * - * Gets the body of a message. + * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer none): A #GVariant or %NULL if the body is - * empty. Do not free, it is owned by @message. - * Since: 2.26 + * Returns: (transfer none): A #GDBusConnection object. Do not free, + * the object belongs to @manager. + * Since: 2.30 */ /** - * g_dbus_message_get_byte_order: - * @message: A #GDBusMessage. + * g_dbus_object_manager_client_get_flags: + * @manager: A #GDBusObjectManagerClient + * + * Gets the flags that @manager was constructed with. + * + * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags + * enumeration. + * Since: 2.30 + */ + + +/** + * g_dbus_object_manager_client_get_name: + * @manager: A #GDBusObjectManagerClient * - * Gets the byte order of @message. + * Gets the name that @manager is for, or %NULL if not a message bus + * connection. * - * Returns: The byte order. + * Returns: A unique or well-known name. Do not free, the string + * belongs to @manager. + * Since: 2.30 */ /** - * g_dbus_message_get_destination: - * @message: A #GDBusMessage. + * g_dbus_object_manager_client_get_name_owner: + * @manager: A #GDBusObjectManagerClient. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. + * 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: The value. - * Since: 2.26 + * Returns: (nullable): The name owner or %NULL if no name owner + * exists. Free with g_free(). + * Since: 2.30 */ /** - * g_dbus_message_get_error_name: - * @message: A #GDBusMessage. + * 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: The data to pass to @callback. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. + * Asynchronously creates a new #GDBusObjectManagerClient object. * - * Returns: The value. - * Since: 2.26 + * 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. + * + * Since: 2.30 */ /** - * g_dbus_message_get_flags: - * @message: A #GDBusMessage. + * 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. * - * Gets the flags for @message. + * Finishes an operation started with g_dbus_object_manager_client_new(). * - * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). - * 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_message_get_header: - * @message: A #GDBusMessage. - * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) + * 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: The data to pass to @callback. * - * Gets a header field on @message. + * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a + * #GDBusConnection. * - * Returns: A #GVariant with the value if the header was found, %NULL - * otherwise. Do not free, it is owned by @message. - * Since: 2.26 + * 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. + * + * Since: 2.30 */ /** - * g_dbus_message_get_header_fields: - * @message: A #GDBusMessage. + * 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. * - * Gets an array of all header fields on @message that are set. + * Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). * - * 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 + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). + * Since: 2.30 */ /** - * g_dbus_message_get_interface: - * @message: A #GDBusMessage. + * 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL + * @error: Return location for error or %NULL. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. + * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead + * of a #GDBusConnection. * - * Returns: The value. - * 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_bus() + * 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_message_get_locked: - * @message: A #GDBusMessage. + * g_dbus_object_manager_client_new_sync: + * @connection: A #GDBusConnection. + * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. + * @name: (nullable): 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL + * @error: Return location for error or %NULL. * - * 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. + * Creates a new #GDBusObjectManagerClient object. * - * Returns: %TRUE if @message is locked, %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_message_get_member: - * @message: A #GDBusMessage. + * g_dbus_object_manager_get_interface: + * @manager: A #GDBusObjectManager. + * @object_path: Object path to lookup. + * @interface_name: D-Bus interface name to lookup. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. + * Gets the interface proxy for @interface_name at @object_path, if + * any. * - * Returns: The value. - * Since: 2.26 + * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free + * with g_object_unref(). + * Since: 2.30 */ /** - * g_dbus_message_get_message_type: - * @message: A #GDBusMessage. + * g_dbus_object_manager_get_object: + * @manager: A #GDBusObjectManager. + * @object_path: Object path to lookup. * - * Gets the type of @message. + * Gets the #GDBusObjectProxy at @object_path, if any. * - * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). - * Since: 2.26 + * Returns: (transfer full): A #GDBusObject or %NULL. Free with + * g_object_unref(). + * Since: 2.30 */ /** - * g_dbus_message_get_num_unix_fds: - * @message: A #GDBusMessage. + * g_dbus_object_manager_get_object_path: + * @manager: A #GDBusObjectManager. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. + * Gets the object path that @manager is for. * - * Returns: The value. - * Since: 2.26 + * Returns: A string owned by @manager. Do not free. + * Since: 2.30 */ /** - * g_dbus_message_get_path: - * @message: A #GDBusMessage. + * g_dbus_object_manager_get_objects: + * @manager: A #GDBusObjectManager. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. + * Gets all #GDBusObject objects known to @manager. * - * Returns: The value. - * 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_message_get_reply_serial: - * @message: A #GDBusMessage. + * g_dbus_object_manager_server_export: + * @manager: A #GDBusObjectManagerServer. + * @object: A #GDBusObjectSkeleton. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. + * Exports @object on @manager. * - * Returns: The value. - * Since: 2.26 + * If there is already a #GDBusObject exported at the object path, + * then the old object is removed. + * + * The object path for @object must be in the hierarchy rooted by the + * object path for @manager. + * + * Note that @manager will take a reference on @object for as long as + * it is exported. + * + * Since: 2.30 */ /** - * g_dbus_message_get_sender: - * @message: A #GDBusMessage. + * g_dbus_object_manager_server_export_uniquely: + * @manager: A #GDBusObjectManagerServer. + * @object: An object. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. + * 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: The value. - * Since: 2.26 + * Since: 2.30 */ /** - * g_dbus_message_get_serial: - * @message: A #GDBusMessage. + * g_dbus_object_manager_server_get_connection: + * @manager: A #GDBusObjectManagerServer * - * Gets the serial for @message. + * Gets the #GDBusConnection used by @manager. * - * Returns: A #guint32. - * 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_message_get_signature: - * @message: A #GDBusMessage. + * g_dbus_object_manager_server_is_exported: + * @manager: A #GDBusObjectManagerServer. + * @object: An object. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + * Returns whether @object is currently exported on @manager. * - * Returns: The value. - * Since: 2.26 + * Returns: %TRUE if @object is exported + * Since: 2.34 */ /** - * g_dbus_message_get_unix_fd_list: - * @message: A #GDBusMessage. + * g_dbus_object_manager_server_new: + * @object_path: The object path to export the manager object at. * - * Gets the UNIX file descriptors associated with @message, if any. + * Creates a new #GDBusObjectManagerServer object. * - * This method is only available on UNIX. + * 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 + * [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) + * signals being emitted. * - * 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 + * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref(). + * Since: 2.30 */ /** - * g_dbus_message_lock: - * @message: A #GDBusMessage. - * - * If @message is locked, does nothing. Otherwise locks the message. + * g_dbus_object_manager_server_set_connection: + * @manager: A #GDBusObjectManagerServer. + * @connection: (nullable): A #GDBusConnection or %NULL. * - * Since: 2.26 + * Exports all objects managed by @manager on @connection. If + * @connection is %NULL, stops exporting objects. */ /** - * g_dbus_message_new: + * g_dbus_object_manager_server_unexport: + * @manager: A #GDBusObjectManagerServer. + * @object_path: An object path. * - * Creates a new empty #GDBusMessage. + * If @manager has an object at @path, removes the object. Otherwise + * does nothing. * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Note that @object_path must be in the hierarchy rooted by the + * object path for @manager. + * + * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise. + * Since: 2.30 */ /** - * 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. + * g_dbus_object_proxy_get_connection: + * @proxy: a #GDBusObjectProxy * - * 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(). + * Gets the connection that @proxy is for. * - * Returns: A new #GDBusMessage or %NULL if @error is set. Free with - * g_object_unref(). - * Since: 2.26 + * Returns: (transfer none): A #GDBusConnection. Do not free, the + * object is owned by @proxy. + * Since: 2.30 */ /** - * g_dbus_message_new_method_call: - * @name: (nullable): A valid D-Bus name or %NULL. - * @path: A valid object path. - * @interface_: (nullable): A valid D-Bus interface name or %NULL. - * @method: A valid method name. + * g_dbus_object_proxy_new: + * @connection: a #GDBusConnection + * @object_path: the object path * - * Creates a new #GDBusMessage for a method call. + * Creates a new #GDBusObjectProxy for the given connection and + * object path. * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Returns: a new #GDBusObjectProxy + * Since: 2.30 */ /** - * 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_dbus_object_skeleton_add_interface: + * @object: A #GDBusObjectSkeleton. + * @interface_: A #GDBusInterfaceSkeleton. * - * Creates a new #GDBusMessage that is an error reply to @method_call_message. + * Adds @interface_ to @object. * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * If @object already contains a #GDBusInterfaceSkeleton with the same + * interface name, it is removed before @interface_ is added. + * + * Note that @object takes its own reference on @interface_ and holds + * it until removed. + * + * Since: 2.30 */ /** - * 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_dbus_object_skeleton_flush: + * @object: A #GDBusObjectSkeleton. * - * Creates a new #GDBusMessage that is an error reply to @method_call_message. + * This method simply calls g_dbus_interface_skeleton_flush() on all + * interfaces belonging to @object. See that method for when flushing + * is useful. * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Since: 2.30 */ /** - * 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_dbus_object_skeleton_new: + * @object_path: An object path. * - * Like g_dbus_message_new_method_error() but intended for language bindings. + * Creates a new #GDBusObjectSkeleton. * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Returns: A #GDBusObjectSkeleton. Free with g_object_unref(). + * Since: 2.30 */ /** - * 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_dbus_object_skeleton_remove_interface: + * @object: A #GDBusObjectSkeleton. + * @interface_: A #GDBusInterfaceSkeleton. * - * Creates a new #GDBusMessage that is a reply to @method_call_message. + * Removes @interface_ from @object. * - * Returns: (transfer full): #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Since: 2.30 */ /** - * g_dbus_message_new_signal: - * @path: A valid object path. - * @interface_: A valid D-Bus interface name. - * @signal: A valid signal name. + * g_dbus_object_skeleton_remove_interface_by_name: + * @object: A #GDBusObjectSkeleton. + * @interface_name: A D-Bus interface name. * - * Creates a new #GDBusMessage for a signal emission. + * Removes the #GDBusInterface with @interface_name from @object. * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * If no D-Bus interface of the given interface exists, this function + * does nothing. + * + * Since: 2.30 */ /** - * g_dbus_message_print: (type method-return) - * @message: A #GDBusMessage. - * @indent: Indentation level. - * - * Produces a human-readable multi-line description of @message. + * g_dbus_object_skeleton_set_object_path: + * @object: A #GDBusObjectSkeleton. + * @object_path: A valid D-Bus object path. * - * 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 - * ]| + * Sets the object path for @object. * - * Returns: A string that should be freed with g_free(). - * Since: 2.26 + * Since: 2.30 */ /** - * 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_dbus_property_info_ref: + * @info: A #GDBusPropertyInfo * - * If @body is floating, @message assumes ownership of @body. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * + * Returns: The same @info. * Since: 2.26 */ /** - * g_dbus_message_set_byte_order: - * @message: A #GDBusMessage. - * @byte_order: The byte order. + * g_dbus_property_info_unref: + * @info: A #GDBusPropertyInfo. * - * Sets the byte order of @message. + * 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.26 */ /** - * g_dbus_message_set_destination: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_dbus_proxy_call: + * @proxy: A #GDBusProxy. + * @method_name: Name of method to invoke. + * @parameters: (nullable): 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: (nullable): A #GCancellable or %NULL. + * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. + * @user_data: The data to pass to @callback. + * + * Asynchronously invokes the @method_name method on @proxy. + * + * If @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.: + * |[ + * 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); + * ]| * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. + * 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. * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_error_name: - * @message: A #GDBusMessage. - * @value: The value to set. + * 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. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. + * 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_dbus_message_set_flags: - * @message: A #GDBusMessage. - * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags - * enumeration bitwise ORed together). + * 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. * - * Sets the flags to set on @message. + * Finishes an operation started with g_dbus_proxy_call(). * + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ /** - * g_dbus_message_set_header: - * @message: A #GDBusMessage. - * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) - * @value: (nullable): A #GVariant to set the header field or %NULL to clear the header field. + * g_dbus_proxy_call_sync: + * @proxy: A #GDBusProxy. + * @method_name: Name of method to invoke. + * @parameters: (nullable): 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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Sets a header field on @message. + * Synchronously invokes the @method_name method on @proxy. * - * If @value is floating, @message assumes ownership of @value. + * 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. * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_interface: - * @message: A #GDBusMessage. - * @value: The value to set. + * 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. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. + * 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); + * ]| * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_member: - * @message: A #GDBusMessage. - * @value: The value to set. + * The calling thread is blocked until a reply is received. See + * g_dbus_proxy_call() for the asynchronous version of this + * method. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. + * 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: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ /** - * g_dbus_message_set_message_type: - * @message: A #GDBusMessage. - * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). + * g_dbus_proxy_call_with_unix_fd_list: + * @proxy: A #GDBusProxy. + * @method_name: Name of method to invoke. + * @parameters: (nullable): 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: (nullable): A #GUnixFDList or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @callback: (nullable): 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 @message to be of @type. + * Like g_dbus_proxy_call() but also takes a #GUnixFDList object. * - * Since: 2.26 + * This method is only available on UNIX. + * + * Since: 2.30 */ /** - * g_dbus_message_set_num_unix_fds: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_dbus_proxy_call_with_unix_fd_list_finish: + * @proxy: A #GDBusProxy. + * @out_fd_list: (out) (optional): 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. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. + * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). * - * 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_message_set_path: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_dbus_proxy_call_with_unix_fd_list_sync: + * @proxy: A #GDBusProxy. + * @method_name: Name of method to invoke. + * @parameters: (nullable): 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: (nullable): A #GUnixFDList or %NULL. + * @out_fd_list: (out) (optional): Return location for a #GUnixFDList or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. + * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. * - * Since: 2.26 + * This method is only available on UNIX. + * + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). + * Since: 2.30 */ /** - * g_dbus_message_set_reply_serial: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_dbus_proxy_get_cached_property: + * @proxy: A #GDBusProxy. + * @property_name: Property name. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. + * 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_message_set_sender: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_dbus_proxy_get_cached_property_names: + * @proxy: A #GDBusProxy. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. + * 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_message_set_serial: - * @message: A #GDBusMessage. - * @serial: A #guint32. + * g_dbus_proxy_get_connection: + * @proxy: A #GDBusProxy. * - * Sets the serial for @message. + * Gets the connection @proxy is for. * + * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free. * Since: 2.26 */ /** - * g_dbus_message_set_signature: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_dbus_proxy_get_default_timeout: + * @proxy: A #GDBusProxy. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + * 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. * + * See the #GDBusProxy:g-default-timeout property for more details. + * + * Returns: Timeout to use for @proxy. * Since: 2.26 */ /** - * g_dbus_message_set_unix_fd_list: - * @message: A #GDBusMessage. - * @fd_list: (nullable): 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_dbus_proxy_get_flags: + * @proxy: A #GDBusProxy. * - * This method is only available on UNIX. + * Gets the flags that @proxy was constructed with. * + * Returns: Flags from the #GDBusProxyFlags enumeration. * Since: 2.26 */ /** - * 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. + * g_dbus_proxy_get_interface_info: + * @proxy: A #GDBusProxy * - * Serializes @message to a blob. The byte order returned by - * g_dbus_message_get_byte_order() will be used. + * Returns the #GDBusInterfaceInfo, if any, specifying the interface + * that @proxy conforms to. See the #GDBusProxy:g-interface-info + * property for more details. * - * Returns: (array length=out_size) (transfer full): A pointer to a - * valid binary D-Bus message of @out_size bytes generated by @message - * or %NULL if @error is set. Free with g_free(). + * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned + * object, it is owned by @proxy. * Since: 2.26 */ /** - * g_dbus_message_to_gerror: - * @message: A #GDBusMessage. - * @error: The #GError to set. - * - * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does - * nothing and returns %FALSE. + * g_dbus_proxy_get_interface_name: + * @proxy: A #GDBusProxy. * - * 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. + * Gets the D-Bus interface name @proxy is for. * - * Returns: %TRUE if @error was set, %FALSE otherwise. + * Returns: A string owned by @proxy. Do not free. * Since: 2.26 */ /** - * g_dbus_method_info_ref: - * @info: A #GDBusMethodInfo + * g_dbus_proxy_get_name: + * @proxy: A #GDBusProxy. * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Gets the name that @proxy was constructed for. * - * Returns: The same @info. + * Returns: A string owned by @proxy. Do not free. * Since: 2.26 */ /** - * g_dbus_method_info_unref: - * @info: A #GDBusMethodInfo. + * g_dbus_proxy_get_name_owner: + * @proxy: A #GDBusProxy. * - * 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. + * 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: The name owner or %NULL if no name owner exists. Free with g_free(). * Since: 2.26 */ /** - * g_dbus_method_invocation_get_connection: - * @invocation: A #GDBusMethodInvocation. + * g_dbus_proxy_get_object_path: + * @proxy: A #GDBusProxy. * - * Gets the #GDBusConnection the method was invoked on. + * Gets the object path @proxy is for. * - * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation. + * Returns: A string owned by @proxy. Do not free. * Since: 2.26 */ /** - * g_dbus_method_invocation_get_interface_name: - * @invocation: A #GDBusMethodInvocation. + * g_dbus_proxy_new: + * @connection: A #GDBusConnection. + * @flags: Flags used when constructing the proxy. + * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @name: (nullable): 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: (nullable): A #GCancellable or %NULL. + * @callback: Callback function to invoke when the proxy is ready. + * @user_data: User data to pass to @callback. * - * Gets the name of the D-Bus interface the method was invoked on. + * 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 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. + * 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. * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_message: - * @invocation: A #GDBusMethodInvocation. + * 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. * - * 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. + * 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 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. + * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. + * + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * - * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. * Since: 2.26 */ /** - * g_dbus_method_invocation_get_method_info: - * @invocation: A #GDBusMethodInvocation. - * - * Gets information about the method call, if any. + * 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. * - * 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. + * Finishes creating a #GDBusProxy. * - * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. + * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_method_invocation_get_method_name: - * @invocation: A #GDBusMethodInvocation. + * g_dbus_proxy_new_for_bus: + * @bus_type: A #GBusType. + * @flags: Flags used when constructing the proxy. + * @info: (nullable): 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: (nullable): A #GCancellable or %NULL. + * @callback: Callback function to invoke when the proxy is ready. + * @user_data: User data to pass to @callback. * - * Gets the name of the method that was invoked. + * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. + * + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * - * Returns: A string. Do not free, it is owned by @invocation. * Since: 2.26 */ /** - * g_dbus_method_invocation_get_object_path: - * @invocation: A #GDBusMethodInvocation. + * 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. * - * Gets the object path the method was invoked on. + * Finishes creating a #GDBusProxy. * - * Returns: A string. Do not free, it is owned by @invocation. + * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_method_invocation_get_parameters: - * @invocation: A #GDBusMethodInvocation. + * g_dbus_proxy_new_for_bus_sync: + * @bus_type: A #GBusType. + * @flags: Flags used when constructing the proxy. + * @info: (nullable): 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: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * 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. + * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation. + * #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_method_invocation_get_property_info: - * @invocation: A #GDBusMethodInvocation - * - * Gets information about the property that this method call is for, if - * any. + * g_dbus_proxy_new_sync: + * @connection: A #GDBusConnection. + * @flags: Flags used when constructing the proxy. + * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @name: (nullable): 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: (nullable): A #GCancellable or %NULL. + * @error: (nullable): Return location for error or %NULL. * - * 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. + * 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. * - * See #GDBusInterfaceVTable for more information. + * 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 the call was GetAll, %NULL will be returned. + * 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. * - * Returns: (transfer none): a #GDBusPropertyInfo or %NULL - * Since: 2.38 - */ - - -/** - * g_dbus_method_invocation_get_sender: - * @invocation: A #GDBusMethodInvocation. + * This is a synchronous failable constructor. See g_dbus_proxy_new() + * and g_dbus_proxy_new_finish() for the asynchronous version. * - * Gets the bus name that invoked the method. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * - * Returns: A string. Do not free, it is owned by @invocation. + * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 */ /** - * g_dbus_method_invocation_get_user_data: (skip) - * @invocation: A #GDBusMethodInvocation. + * g_dbus_proxy_set_cached_property: + * @proxy: A #GDBusProxy + * @property_name: Property name. + * @value: (nullable): Value for the property or %NULL to remove it from the cache. * - * Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). + * If @value is not %NULL, sets the cached value for the property with + * name @property_name to the value in @value. * - * Returns: A #gpointer. - * Since: 2.26 - */ - - -/** - * 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. + * If @value is %NULL, then the cached value is removed from the + * property cache. * - * Finishes handling a D-Bus method call by returning an error. + * 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. * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * 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 + * `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_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. - * - * Finishes handling a D-Bus method call by returning an error. - * - * 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 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_proxy_set_default_timeout: + * @proxy: A #GDBusProxy. + * @timeout_msec: Timeout in milliseconds. * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * 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. * - * Since 2.48, if the method call requested for a reply not to be sent - * then this call will free @invocation but otherwise do nothing (as per - * the recommendations of the D-Bus specification). + * See the #GDBusProxy:g-default-timeout property for more details. * * Since: 2.26 */ /** - * 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_dbus_proxy_set_interface_info: + * @proxy: A #GDBusProxy + * @info: (nullable): Minimum interface this proxy conforms to or %NULL to unset. * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * Ensure that interactions with @proxy conform to the given + * interface. See the #GDBusProxy:g-interface-info property for more + * details. * * 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. - * - * Like g_dbus_method_invocation_return_error() but intended for - * language bindings. + * g_dbus_server_get_client_address: + * @server: A #GDBusServer. * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * Gets a + * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) + * string that can be used by clients to connect to @server. * + * Returns: A D-Bus address string. Do not free, the string is owned + * by @server. * Since: 2.26 */ /** - * g_dbus_method_invocation_return_gerror: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @error: A #GError. + * g_dbus_server_get_flags: + * @server: A #GDBusServer. * - * Like g_dbus_method_invocation_return_error() but takes a #GError - * instead of the error domain, error code and message. + * Gets the flags for @server. * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * Returns: A set of flags from the #GDBusServerFlags enumeration. + * Since: 2.26 + */ + + +/** + * g_dbus_server_get_guid: + * @server: A #GDBusServer. + * + * Gets the GUID for @server. * + * Returns: A D-Bus GUID. Do not free this string, it is owned by @server. * Since: 2.26 */ /** - * g_dbus_method_invocation_return_value: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. + * g_dbus_server_is_active: + * @server: A #GDBusServer. * - * Finishes handling a D-Bus method call by returning @parameters. - * If the @parameters GVariant is floating, it is consumed. + * Gets whether @server is active. * - * It is an error if @parameters is not of the right format: it must be a tuple - * containing the out-parameters of the D-Bus method. Even if the method has a - * single out-parameter, it must be contained in a tuple. If the method has no - * out-parameters, @parameters may be %NULL or an empty tuple. + * Returns: %TRUE if server is active, %FALSE otherwise. + * Since: 2.26 + */ + + +/** + * g_dbus_server_new_sync: + * @address: A D-Bus address. + * @flags: Flags from the #GDBusServerFlags enumeration. + * @guid: A D-Bus GUID. + * @observer: (nullable): A #GDBusAuthObserver or %NULL. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for server or %NULL. * - * |[ - * GDBusMethodInvocation *invocation = some_invocation; - * g_autofree gchar *result_string = NULL; - * g_autoptr (GError) error = NULL; + * Creates a new D-Bus server that listens on the first address in + * @address that works. * - * result_string = calculate_result (&error); + * Once constructed, you can use g_dbus_server_get_client_address() to + * get a D-Bus address string that clients can use to connect. * - * if (error != NULL) - * g_dbus_method_invocation_return_gerror (invocation, error); - * else - * g_dbus_method_invocation_return_value (invocation, - * g_variant_new ("(s)", result_string)); + * Connect to the #GDBusServer::new-connection signal to handle + * incoming connections. * - * // Do not free @invocation here; returning a value does that - * ]| + * The returned #GDBusServer isn't active - you have to start it with + * g_dbus_server_start(). * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * #GDBusServer is used in this [example][gdbus-peer-to-peer]. * - * Since 2.48, if the method call requested for a reply not to be sent - * then this call will sink @parameters and free @invocation, but - * otherwise do nothing (as per the recommendations of the D-Bus - * specification). + * 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_method_invocation_return_value_with_unix_fd_list: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. - * @fd_list: (nullable): A #GUnixFDList or %NULL. + * g_dbus_server_start: + * @server: A #GDBusServer. * - * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. + * Starts @server. * - * This method is only available on UNIX. + * Since: 2.26 + */ + + +/** + * g_dbus_server_stop: + * @server: A #GDBusServer. * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * Stops @server. * - * Since: 2.30 + * Since: 2.26 */ /** - * 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_dbus_signal_info_ref: + * @info: A #GDBusSignalInfo * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * Since: 2.30 + * Returns: The same @info. + * Since: 2.26 */ /** - * g_dbus_node_info_generate_xml: - * @info: A #GDBusNodeInfo. - * @indent: Indentation level. - * @string_builder: A #GString to to append XML data to. - * - * Appends an XML representation of @info (and its children) to @string_builder. + * g_dbus_signal_info_unref: + * @info: A #GDBusSignalInfo. * - * This function is typically used for generating introspection XML documents at run-time for - * handling the `org.freedesktop.DBus.Introspectable.Introspect` method. + * 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.26 */ /** - * g_dbus_node_info_lookup_interface: - * @info: A #GDBusNodeInfo. - * @name: A D-Bus interface name. + * 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() * - * Looks up information about an interface. + * Gets the user-visible display name of the "additional application + * action" specified by @action_name. * - * The cost of this function is O(n) in number of interfaces. + * This corresponds to the "Name" key within the keyfile group for the + * action. * - * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 + * Returns: (transfer full): the locale-specific action name + * Since: 2.38 */ /** - * g_dbus_node_info_new_for_xml: - * @xml_data: Valid D-Bus introspection XML. - * @error: Return location for error. + * g_desktop_app_info_get_boolean: + * @info: a #GDesktopAppInfo + * @key: the key to look up * - * Parses @xml_data and returns a #GDBusNodeInfo representing the data. + * Looks up a boolean value in the keyfile backing @info. * - * The introspection XML must contain exactly one top-level - * element. + * The @key is looked up in the "Desktop Entry" group. * - * 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: the boolean value, or %FALSE if the key + * is not found + * Since: 2.36 + */ + + +/** + * g_desktop_app_info_get_categories: + * @info: a #GDesktopAppInfo * - * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free - * with g_dbus_node_info_unref(). - * Since: 2.26 + * Gets the categories from the desktop file. + * + * Returns: The unparsed Categories key from the desktop file; + * i.e. no attempt is made to split it by ';' or validate it. */ /** - * g_dbus_node_info_ref: - * @info: A #GDBusNodeInfo + * g_desktop_app_info_get_filename: + * @info: a #GDesktopAppInfo * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * 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: The same @info. - * Since: 2.26 + * Returns: (type filename): The full path to the file for @info, + * or %NULL if not known. + * Since: 2.24 */ /** - * g_dbus_node_info_unref: - * @info: A #GDBusNodeInfo. + * g_desktop_app_info_get_generic_name: + * @info: a #GDesktopAppInfo * - * 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 generic name from the destkop file. * - * Since: 2.26 + * Returns: The value of the GenericName key */ /** - * g_dbus_object_get_interface: - * @object: A #GDBusObject. - * @interface_name: A D-Bus interface name. + * g_desktop_app_info_get_implementations: + * @interface: the name of the interface * - * Gets the D-Bus interface with name @interface_name associated with - * @object, if any. + * Gets all applications that implement @interface. * - * Returns: (transfer full): %NULL if not found, otherwise a - * #GDBusInterface that must be freed with g_object_unref(). - * Since: 2.30 + * 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_object_get_interfaces: - * @object: A #GDBusObject. + * g_desktop_app_info_get_is_hidden: + * @info: a #GDesktopAppInfo. * - * Gets the D-Bus interfaces associated with @object. + * A desktop file is hidden if the Hidden key in it is + * set to True. * - * 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 + * Returns: %TRUE if hidden, %FALSE otherwise. */ /** - * g_dbus_object_get_object_path: - * @object: A #GDBusObject. + * g_desktop_app_info_get_keywords: + * @info: a #GDesktopAppInfo * - * Gets the object path for @object. + * Gets the keywords from the desktop file. * - * Returns: A string owned by @object. Do not free. - * Since: 2.30 + * Returns: (transfer none): The value of the Keywords key + * Since: 2.32 */ /** - * g_dbus_object_manager_client_get_connection: - * @manager: A #GDBusObjectManagerClient + * g_desktop_app_info_get_locale_string: + * @info: a #GDesktopAppInfo + * @key: the key to look up * - * Gets the #GDBusConnection used by @manager. + * Looks up a localized string value in the keyfile backing @info + * translated to the current locale. * - * Returns: (transfer none): A #GDBusConnection object. Do not free, - * the object belongs to @manager. - * Since: 2.30 + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: (nullable): a newly allocated string, or %NULL if the key + * is not found + * Since: 2.56 */ /** - * g_dbus_object_manager_client_get_flags: - * @manager: A #GDBusObjectManagerClient + * g_desktop_app_info_get_nodisplay: + * @info: a #GDesktopAppInfo * - * Gets the flags that @manager was constructed with. + * 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: Zero of more flags from the #GDBusObjectManagerClientFlags - * enumeration. + * Returns: The value of the NoDisplay key * Since: 2.30 */ /** - * g_dbus_object_manager_client_get_name: - * @manager: A #GDBusObjectManagerClient + * g_desktop_app_info_get_show_in: + * @info: a #GDesktopAppInfo + * @desktop_env: (nullable): a string specifying a desktop name * - * Gets the name that @manager is for, or %NULL if not a message bus - * connection. + * 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. * - * Returns: A unique or well-known name. Do not free, the string - * belongs to @manager. + * @desktop_env should typically be given as %NULL, in which case the + * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want + * to override the default mechanism then you may specify @desktop_env, + * but this is not recommended. + * + * Note that g_app_info_should_show() for @info will include this check (with + * %NULL for @desktop_env) as well as additional checks. + * + * Returns: %TRUE if the @info should be shown in @desktop_env according to the + * `OnlyShowIn` and `NotShowIn` keys, %FALSE + * otherwise. * Since: 2.30 */ /** - * g_dbus_object_manager_client_get_name_owner: - * @manager: A #GDBusObjectManagerClient. + * g_desktop_app_info_get_startup_wm_class: + * @info: a #GDesktopAppInfo that supports startup notify * - * 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. + * Retrieves the StartupWMClass field from @info. This represents the + * WM_CLASS property of the main window of the application, if launched + * through @info. * - * Returns: (nullable): The name owner or %NULL if no name owner - * exists. Free with g_free(). - * Since: 2.30 + * Returns: (transfer none): the startup WM class, or %NULL if none is set + * in the desktop file. + * Since: 2.34 */ /** - * 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * g_desktop_app_info_get_string: + * @info: a #GDesktopAppInfo + * @key: the key to look up * - * Asynchronously creates a new #GDBusObjectManagerClient object. + * Looks up a string value in the keyfile backing @info. * - * 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. + * The @key is looked up in the "Desktop Entry" group. * - * Since: 2.30 + * Returns: a newly allocated string, or %NULL if the key + * is not found + * Since: 2.36 */ /** - * 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. + * g_desktop_app_info_has_key: + * @info: a #GDesktopAppInfo + * @key: the key to look up * - * Finishes an operation started with g_dbus_object_manager_client_new(). + * Returns whether @key exists in the "Desktop Entry" group + * of the keyfile backing @info. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 + * Returns: %TRUE if the @key exists + * Since: 2.36 */ /** - * 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * 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: (nullable): a #GAppLaunchContext * - * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a - * #GDBusConnection. + * Activates the named application action. * - * 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. + * You may only call this function on action names that were + * returned from g_desktop_app_info_list_actions(). * - * Since: 2.30 + * 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_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_desktop_app_info_launch_uris_as_manager: + * @appinfo: a #GDesktopAppInfo + * @uris: (element-type utf8): List of URIs + * @launch_context: (nullable): a #GAppLaunchContext + * @spawn_flags: #GSpawnFlags, used for each process + * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once + * for each process. + * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup + * @pid_callback: (scope call) (nullable): Callback for child processes + * @pid_callback_data: (closure pid_callback) (nullable): User data for @callback + * @error: return location for a #GError, or %NULL * - * Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). + * 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: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 + * 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_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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @error: Return location for error or %NULL. + * g_desktop_app_info_list_actions: + * @info: a #GDesktopAppInfo * - * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead - * of a #GDBusConnection. + * Returns the list of "additional application actions" supported on the + * desktop file, as per the desktop file specification. * - * 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. + * As per the specification, this is the list of actions that are + * explicitly listed in the "Actions" key of the [Desktop Entry] group. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 + * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL + * Since: 2.38 */ /** - * g_dbus_object_manager_client_new_sync: - * @connection: A #GDBusConnection. - * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: (nullable): 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: (nullable): 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: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @error: Return location for error or %NULL. + * g_desktop_app_info_lookup_get_default_for_uri_scheme: + * @lookup: a #GDesktopAppInfoLookup + * @uri_scheme: a string containing a URI scheme. * - * Creates a new #GDBusObjectManagerClient object. + * Gets the default application for launching applications + * using this URI scheme for a particular GDesktopAppInfoLookup + * implementation. * - * 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. + * 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) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 + * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. + * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio. */ /** - * g_dbus_object_manager_get_interface: - * @manager: A #GDBusObjectManager. - * @object_path: Object path to lookup. - * @interface_name: D-Bus interface name to lookup. + * g_desktop_app_info_new: + * @desktop_id: the desktop file id * - * Gets the interface proxy for @interface_name at @object_path, if - * any. + * Creates a new #GDesktopAppInfo based on a desktop file id. * - * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free - * with g_object_unref(). - * Since: 2.30 + * 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_object_manager_get_object: - * @manager: A #GDBusObjectManager. - * @object_path: Object path to lookup. + * g_desktop_app_info_new_from_filename: + * @filename: (type filename): the path of a desktop file, in the GLib + * filename encoding * - * Gets the #GDBusObjectProxy at @object_path, if any. + * Creates a new #GDesktopAppInfo. * - * Returns: (transfer full): A #GDBusObject or %NULL. Free with - * g_object_unref(). - * Since: 2.30 + * Returns: a new #GDesktopAppInfo or %NULL on error. */ /** - * g_dbus_object_manager_get_object_path: - * @manager: A #GDBusObjectManager. + * g_desktop_app_info_new_from_keyfile: + * @key_file: an opened #GKeyFile * - * Gets the object path that @manager is for. + * Creates a new #GDesktopAppInfo. * - * Returns: A string owned by @manager. Do not free. - * Since: 2.30 + * Returns: a new #GDesktopAppInfo or %NULL on error. + * Since: 2.18 */ /** - * g_dbus_object_manager_get_objects: - * @manager: A #GDBusObjectManager. + * g_desktop_app_info_search: + * @search_string: the search string to use * - * Gets all #GDBusObject objects known to @manager. + * Searches desktop files for ones that match @search_string. * - * 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 + * 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_object_manager_server_export: - * @manager: A #GDBusObjectManagerServer. - * @object: A #GDBusObjectSkeleton. - * - * Exports @object on @manager. - * - * If there is already a #GDBusObject exported at the object path, - * then the old object is removed. + * g_desktop_app_info_set_desktop_env: + * @desktop_env: a string specifying what desktop this is * - * The object path for @object must be in the hierarchy rooted by the - * object path for @manager. + * 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. * - * Note that @manager will take a reference on @object for as long as - * it is exported. + * Should be called only once; subsequent calls are ignored. * - * Since: 2.30 + * 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_object_manager_server_export_uniquely: - * @manager: A #GDBusObjectManagerServer. - * @object: An object. + * g_drive_can_eject: + * @drive: a #GDrive. * - * 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. + * Checks if a drive can be ejected. * - * Since: 2.30 + * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise. */ /** - * g_dbus_object_manager_server_get_connection: - * @manager: A #GDBusObjectManagerServer + * g_drive_can_poll_for_media: + * @drive: a #GDrive. * - * Gets the #GDBusConnection used by @manager. + * Checks if a drive can be polled for media changes. * - * 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 + * Returns: %TRUE if the @drive can be polled for media changes, + * %FALSE otherwise. */ /** - * g_dbus_object_manager_server_is_exported: - * @manager: A #GDBusObjectManagerServer. - * @object: An object. + * g_drive_can_start: + * @drive: a #GDrive. * - * Returns whether @object is currently exported on @manager. + * Checks if a drive can be started. * - * Returns: %TRUE if @object is exported - * Since: 2.34 + * Returns: %TRUE if the @drive can be started, %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_object_manager_server_new: - * @object_path: The object path to export the manager object at. - * - * Creates a new #GDBusObjectManagerServer object. + * g_drive_can_start_degraded: + * @drive: a #GDrive. * - * 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 - * [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) - * signals being emitted. + * Checks if a drive can be started degraded. * - * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref(). - * Since: 2.30 + * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_object_manager_server_set_connection: - * @manager: A #GDBusObjectManagerServer. - * @connection: (nullable): A #GDBusConnection or %NULL. + * g_drive_can_stop: + * @drive: a #GDrive. * - * Exports all objects managed by @manager on @connection. If - * @connection is %NULL, stops exporting objects. + * Checks if a drive can be stopped. + * + * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_object_manager_server_unexport: - * @manager: A #GDBusObjectManagerServer. - * @object_path: An object path. + * g_drive_eject: + * @drive: a #GDrive. + * @flags: flags affecting the unmount if required for eject + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * If @manager has an object at @path, removes the object. Otherwise - * does nothing. + * Asynchronously ejects a drive. * - * Note that @object_path must be in the hierarchy rooted by the - * object path for @manager. + * When the operation is finished, @callback will be called. + * You can then call g_drive_eject_finish() to obtain the + * result of the operation. * - * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise. - * Since: 2.30 + * Deprecated: 2.22: Use g_drive_eject_with_operation() instead. */ /** - * g_dbus_object_proxy_get_connection: - * @proxy: a #GDBusObjectProxy + * g_drive_eject_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Gets the connection that @proxy is for. + * Finishes ejecting a drive. * - * Returns: (transfer none): A #GDBusConnection. Do not free, the - * object is owned by @proxy. - * Since: 2.30 + * Returns: %TRUE if the drive has been ejected successfully, + * %FALSE otherwise. + * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. */ /** - * g_dbus_object_proxy_new: - * @connection: a #GDBusConnection - * @object_path: the object path + * g_drive_eject_with_operation: + * @drive: a #GDrive. + * @flags: flags affecting the unmount if required for eject + * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid + * user interaction. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Creates a new #GDBusObjectProxy for the given connection and - * object path. + * 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: a new #GDBusObjectProxy - * Since: 2.30 + * Since: 2.22 */ /** - * g_dbus_object_skeleton_add_interface: - * @object: A #GDBusObjectSkeleton. - * @interface_: A #GDBusInterfaceSkeleton. - * - * Adds @interface_ to @object. - * - * If @object already contains a #GDBusInterfaceSkeleton with the same - * interface name, it is removed before @interface_ is added. + * 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. * - * Note that @object takes its own reference on @interface_ and holds - * it until removed. + * Finishes ejecting a drive. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * Since: 2.30 + * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_object_skeleton_flush: - * @object: A #GDBusObjectSkeleton. + * g_drive_enumerate_identifiers: + * @drive: a #GDrive * - * This method simply calls g_dbus_interface_skeleton_flush() on all - * interfaces belonging to @object. See that method for when flushing - * is useful. + * Gets the kinds of identifiers that @drive has. + * Use g_drive_get_identifier() to obtain the identifiers + * themselves. * - * Since: 2.30 + * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated + * array of strings containing kinds of identifiers. Use g_strfreev() + * to free. */ /** - * g_dbus_object_skeleton_new: - * @object_path: An object path. + * g_drive_get_icon: + * @drive: a #GDrive. * - * Creates a new #GDBusObjectSkeleton. + * Gets the icon for @drive. * - * Returns: A #GDBusObjectSkeleton. Free with g_object_unref(). - * Since: 2.30 + * Returns: (transfer full): #GIcon for the @drive. + * Free the returned object with g_object_unref(). */ /** - * g_dbus_object_skeleton_remove_interface: - * @object: A #GDBusObjectSkeleton. - * @interface_: A #GDBusInterfaceSkeleton. + * g_drive_get_identifier: + * @drive: a #GDrive + * @kind: the kind of identifier to return * - * Removes @interface_ from @object. + * Gets the identifier of the given kind for @drive. * - * Since: 2.30 + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GDrive + * doesn't have this kind of identifier. */ /** - * g_dbus_object_skeleton_remove_interface_by_name: - * @object: A #GDBusObjectSkeleton. - * @interface_name: A D-Bus interface name. - * - * Removes the #GDBusInterface with @interface_name from @object. + * g_drive_get_name: + * @drive: a #GDrive. * - * If no D-Bus interface of the given interface exists, this function - * does nothing. + * Gets the name of @drive. * - * Since: 2.30 + * Returns: a string containing @drive's name. The returned + * string should be freed when no longer needed. */ /** - * g_dbus_object_skeleton_set_object_path: - * @object: A #GDBusObjectSkeleton. - * @object_path: A valid D-Bus object path. + * g_drive_get_sort_key: + * @drive: A #GDrive. * - * Sets the object path for @object. + * Gets the sort key for @drive, if any. * - * Since: 2.30 + * Returns: Sorting key for @drive or %NULL if no such key is available. + * Since: 2.32 */ /** - * g_dbus_property_info_ref: - * @info: A #GDBusPropertyInfo + * g_drive_get_start_stop_type: + * @drive: a #GDrive. * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Gets a hint about how a drive can be started/stopped. * - * Returns: The same @info. - * Since: 2.26 + * Returns: A value from the #GDriveStartStopType enumeration. + * Since: 2.22 */ /** - * g_dbus_property_info_unref: - * @info: A #GDBusPropertyInfo. + * g_drive_get_symbolic_icon: + * @drive: a #GDrive. * - * 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 icon for @drive. * - * Since: 2.26 + * Returns: (transfer full): symbolic #GIcon for the @drive. + * Free the returned object with g_object_unref(). + * Since: 2.34 */ /** - * g_dbus_proxy_call: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): 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: (nullable): A #GCancellable or %NULL. - * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't - * care about the result of the method invocation. - * @user_data: The data to pass to @callback. - * - * Asynchronously invokes the @method_name method on @proxy. - * - * If @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.: - * |[ - * 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. + * g_drive_get_volumes: + * @drive: a #GDrive. * - * 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. + * Get a list of mountable volumes for @drive. * - * 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. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). * - * Since: 2.26 + * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive. */ /** - * 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_drive_has_media: + * @drive: a #GDrive. * - * Finishes an operation started with g_dbus_proxy_call(). + * 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: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.26 + * Returns: %TRUE if @drive has media, %FALSE otherwise. */ /** - * g_dbus_proxy_call_sync: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): 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: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously 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 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. + * g_drive_has_volumes: + * @drive: a #GDrive. * - * 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); - * ]| + * Check if @drive has any mountable volumes. * - * The calling thread is blocked until a reply is received. See - * g_dbus_proxy_call() for the asynchronous version of this - * method. + * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise. + */ + + +/** + * g_drive_is_media_check_automatic: + * @drive: a #GDrive. * - * 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. + * Checks if @drive is capabable of automatically detecting media changes. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.26 + * Returns: %TRUE if the @drive is capabable of automatically detecting + * media changes, %FALSE otherwise. */ /** - * g_dbus_proxy_call_with_unix_fd_list: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): 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: (nullable): A #GUnixFDList or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't - * care about the result of the method invocation. - * @user_data: The data to pass to @callback. - * - * Like g_dbus_proxy_call() but also takes a #GUnixFDList object. + * g_drive_is_media_removable: + * @drive: a #GDrive. * - * This method is only available on UNIX. + * Checks if the @drive supports removable media. * - * Since: 2.30 + * Returns: %TRUE if @drive supports removable media, %FALSE otherwise. */ /** - * g_dbus_proxy_call_with_unix_fd_list_finish: - * @proxy: A #GDBusProxy. - * @out_fd_list: (out) (optional): 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_drive_is_removable: + * @drive: a #GDrive. * - * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). + * Checks if the #GDrive and/or its media is considered removable by the user. + * See g_drive_is_media_removable(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.30 + * Returns: %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. + * Since: 2.50 */ /** - * g_dbus_proxy_call_with_unix_fd_list_sync: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): 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: (nullable): A #GUnixFDList or %NULL. - * @out_fd_list: (out) (optional): Return location for a #GUnixFDList or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_drive_poll_for_media: + * @drive: a #GDrive. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. + * Asynchronously polls @drive to see if media has been inserted or removed. * - * This method is only available on UNIX. + * 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_drive_poll_for_media_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.30 + * Finishes an operation started with g_drive_poll_for_media() on a drive. + * + * Returns: %TRUE if the drive has been poll_for_mediaed successfully, + * %FALSE otherwise. */ /** - * g_dbus_proxy_get_cached_property: - * @proxy: A #GDBusProxy. - * @property_name: Property name. + * g_drive_start: + * @drive: a #GDrive. + * @flags: flags affecting the start operation. + * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid + * user interaction. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * Looks up the value for a property from the cache. This call does no - * blocking IO. + * Asynchronously starts a drive. * - * 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. + * When the operation is finished, @callback will be called. + * You can then call g_drive_start_finish() to obtain the + * result of the operation. * - * 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 + * Since: 2.22 */ /** - * g_dbus_proxy_get_cached_property_names: - * @proxy: A #GDBusProxy. + * g_drive_start_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Gets the names of all cached properties on @proxy. + * Finishes starting a drive. * - * 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 + * Returns: %TRUE if the drive has been started successfully, + * %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_proxy_get_connection: - * @proxy: A #GDBusProxy. + * g_drive_stop: + * @drive: a #GDrive. + * @flags: flags affecting the unmount if required for stopping. + * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid + * user interaction. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * Gets the connection @proxy is for. + * Asynchronously stops a drive. * - * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free. - * 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_proxy_get_default_timeout: - * @proxy: A #GDBusProxy. - * - * 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. + * g_drive_stop_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * See the #GDBusProxy:g-default-timeout property for more details. + * Finishes stopping a drive. * - * Returns: Timeout to use for @proxy. - * Since: 2.26 + * Returns: %TRUE if the drive has been stopped successfully, + * %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_proxy_get_flags: - * @proxy: A #GDBusProxy. + * g_dtls_client_connection_get_accepted_cas: + * @conn: the #GDtlsClientConnection * - * Gets the flags that @proxy was constructed with. + * Gets the list of distinguished names of the Certificate Authorities + * that the server will accept certificates from. This will be set + * during the TLS handshake if the server requests a certificate. + * Otherwise, it will be %NULL. * - * Returns: Flags from the #GDBusProxyFlags enumeration. - * Since: 2.26 + * 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(). + * Since: 2.48 */ /** - * g_dbus_proxy_get_interface_info: - * @proxy: A #GDBusProxy + * g_dtls_client_connection_get_server_identity: + * @conn: the #GDtlsClientConnection * - * Returns the #GDBusInterfaceInfo, if any, specifying the interface - * that @proxy conforms to. See the #GDBusProxy:g-interface-info - * property for more details. + * Gets @conn's expected server identity * - * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned - * object, it is owned by @proxy. - * Since: 2.26 + * Returns: (transfer none): a #GSocketConnectable describing the + * expected server identity, or %NULL if the expected identity is not + * known. + * Since: 2.48 */ /** - * g_dbus_proxy_get_interface_name: - * @proxy: A #GDBusProxy. + * g_dtls_client_connection_get_validation_flags: + * @conn: the #GDtlsClientConnection * - * Gets the D-Bus interface name @proxy is for. + * Gets @conn's validation flags * - * Returns: A string owned by @proxy. Do not free. - * Since: 2.26 + * Returns: the validation flags + * Since: 2.48 */ /** - * g_dbus_proxy_get_name: - * @proxy: A #GDBusProxy. + * g_dtls_client_connection_new: + * @base_socket: the #GDatagramBased to wrap + * @server_identity: (nullable): the expected identity of the server + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the name that @proxy was constructed for. + * Creates a new #GDtlsClientConnection wrapping @base_socket which is + * assumed to communicate with the server identified by @server_identity. * - * Returns: A string owned by @proxy. Do not free. - * Since: 2.26 + * Returns: (transfer full) (type GDtlsClientConnection): the new + * #GDtlsClientConnection, or %NULL on error + * Since: 2.48 */ /** - * g_dbus_proxy_get_name_owner: - * @proxy: A #GDBusProxy. + * g_dtls_client_connection_set_server_identity: + * @conn: the #GDtlsClientConnection + * @identity: a #GSocketConnectable describing the expected server identity * - * 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. + * Sets @conn's expected server identity, which is used both to tell + * servers on virtual hosts which certificate to present, and also + * to let @conn know what name to look for in the certificate when + * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. * - * Returns: The name owner or %NULL if no name owner exists. Free with g_free(). - * Since: 2.26 + * Since: 2.48 */ /** - * g_dbus_proxy_get_object_path: - * @proxy: A #GDBusProxy. + * g_dtls_client_connection_set_validation_flags: + * @conn: the #GDtlsClientConnection + * @flags: the #GTlsCertificateFlags to use * - * Gets the object path @proxy is for. + * Sets @conn's validation flags, to override the default set of + * checks performed when validating a server certificate. By default, + * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. * - * Returns: A string owned by @proxy. Do not free. - * Since: 2.26 + * Since: 2.48 */ /** - * g_dbus_proxy_new: - * @connection: A #GDBusConnection. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: (nullable): 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: (nullable): 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. + * g_dtls_connection_close: + * @conn: a #GDtlsConnection + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a #GError, or %NULL * - * 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. + * Close the DTLS connection. This is equivalent to calling + * g_dtls_connection_shutdown() to shut down both sides of the connection. * - * 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. + * Closing a #GDtlsConnection waits for all buffered but untransmitted data to + * be sent before it completes. It then sends a `close_notify` DTLS alert to the + * peer and may wait for a `close_notify` to be received from the peer. It does + * not close the underlying #GDtlsConnection:base-socket; that must be closed + * separately. * - * 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. + * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED. + * Closing a #GDtlsConnection multiple times will not return an error. * - * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. + * #GDtlsConnections 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. * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. + * If @cancellable is cancelled, the #GDtlsConnection may be left + * partially-closed and any pending untransmitted data may be lost. Call + * g_dtls_connection_close() again to complete closing the #GDtlsConnection. * - * Since: 2.26 + * Returns: %TRUE on success, %FALSE otherwise + * Since: 2.48 */ /** - * 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_dtls_connection_close_async: + * @conn: a #GDtlsConnection + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the close operation is complete + * @user_data: the data to pass to the callback function * - * Finishes creating a #GDBusProxy. + * Asynchronously close the DTLS connection. See g_dtls_connection_close() for + * more information. * - * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * Since: 2.48 */ /** - * g_dbus_proxy_new_for_bus: - * @bus_type: A #GBusType. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): 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: (nullable): 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_dtls_connection_close_finish: + * @conn: a #GDtlsConnection + * @result: a #GAsyncResult + * @error: a #GError pointer, or %NULL * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. + * Finish an asynchronous TLS close operation. See g_dtls_connection_close() + * for more information. * - * Since: 2.26 + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set + * Since: 2.48 */ /** - * 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_dtls_connection_emit_accept_certificate: + * @conn: a #GDtlsConnection + * @peer_cert: the peer's #GTlsCertificate + * @errors: the problems with @peer_cert * - * Finishes creating a #GDBusProxy. + * Used by #GDtlsConnection implementations to emit the + * #GDtlsConnection::accept-certificate signal. * - * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * Returns: %TRUE if one of the signal handlers has returned + * %TRUE to accept @peer_cert + * Since: 2.48 */ /** - * g_dbus_proxy_new_for_bus_sync: - * @bus_type: A #GBusType. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): 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: (nullable): 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_dtls_connection_get_certificate: + * @conn: a #GDtlsConnection * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. + * Gets @conn's certificate, as set by + * g_dtls_connection_set_certificate(). * - * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). - * Since: 2.26 + * Returns: (transfer none): @conn's certificate, or %NULL + * Since: 2.48 */ /** - * g_dbus_proxy_new_sync: - * @connection: A #GDBusConnection. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: (nullable): 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: (nullable): A #GCancellable or %NULL. - * @error: (nullable): 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 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. + * g_dtls_connection_get_database: + * @conn: a #GDtlsConnection * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. + * Gets the certificate database that @conn uses to verify + * peer certificates. See g_dtls_connection_set_database(). * - * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). - * Since: 2.26 + * Returns: (transfer none): the certificate database that @conn uses or %NULL + * Since: 2.48 */ /** - * g_dbus_proxy_set_cached_property: - * @proxy: A #GDBusProxy - * @property_name: Property name. - * @value: (nullable): 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 - * `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. + * g_dtls_connection_get_interaction: + * @conn: a connection * - * 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)`. + * Get the object that will be used to interact with the user. It will be used + * for things like prompting the user for passwords. If %NULL is returned, then + * no user interaction will occur for this connection. * - * Since: 2.26 + * Returns: (transfer none): The interaction object. + * Since: 2.48 */ /** - * 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_dtls_connection_get_peer_certificate: + * @conn: a #GDtlsConnection * - * See the #GDBusProxy:g-default-timeout property for more details. + * Gets @conn's peer's certificate after the handshake has completed. + * (It is not set during the emission of + * #GDtlsConnection::accept-certificate.) * - * Since: 2.26 + * Returns: (transfer none): @conn's peer's certificate, or %NULL + * Since: 2.48 */ /** - * g_dbus_proxy_set_interface_info: - * @proxy: A #GDBusProxy - * @info: (nullable): Minimum interface this proxy conforms to or %NULL to unset. + * g_dtls_connection_get_peer_certificate_errors: + * @conn: a #GDtlsConnection * - * Ensure that interactions with @proxy conform to the given - * interface. See the #GDBusProxy:g-interface-info property for more - * details. + * Gets the errors associated with validating @conn's peer's + * certificate, after the handshake has completed. (It is not set + * during the emission of #GDtlsConnection::accept-certificate.) * - * Since: 2.26 + * Returns: @conn's peer's certificate errors + * Since: 2.48 */ /** - * g_dbus_server_get_client_address: - * @server: A #GDBusServer. + * g_dtls_connection_get_rehandshake_mode: + * @conn: a #GDtlsConnection * - * Gets a - * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) - * string that can be used by clients to connect to @server. + * Gets @conn rehandshaking mode. See + * g_dtls_connection_set_rehandshake_mode() for details. * - * Returns: A D-Bus address string. Do not free, the string is owned - * by @server. - * Since: 2.26 + * Returns: @conn's rehandshaking mode + * Since: 2.48 */ /** - * g_dbus_server_get_flags: - * @server: A #GDBusServer. + * g_dtls_connection_get_require_close_notify: + * @conn: a #GDtlsConnection * - * Gets the flags for @server. + * Tests whether or not @conn expects a proper TLS close notification + * when the connection is closed. See + * g_dtls_connection_set_require_close_notify() for details. * - * Returns: A set of flags from the #GDBusServerFlags enumeration. - * Since: 2.26 + * Returns: %TRUE if @conn requires a proper TLS close notification. + * Since: 2.48 */ /** - * g_dbus_server_get_guid: - * @server: A #GDBusServer. + * g_dtls_connection_handshake: + * @conn: a #GDtlsConnection + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a #GError, or %NULL * - * Gets the GUID for @server. + * Attempts a TLS handshake on @conn. * - * Returns: A D-Bus GUID. Do not free this string, it is owned by @server. - * Since: 2.26 + * On the client side, it is never necessary to call this method; + * although the connection needs to perform a handshake after + * connecting (or after sending a "STARTTLS"-type command) and may + * need to rehandshake later if the server requests it, + * #GDtlsConnection will handle this for you automatically when you try + * to send or receive data on the connection. However, you can call + * g_dtls_connection_handshake() manually if you want to know for sure + * whether the initial handshake succeeded or failed (as opposed to + * just immediately trying to write to @conn, in which + * case if it fails, it may not be possible to tell if it failed + * before or after completing the handshake). + * + * Likewise, on the server side, although a handshake is necessary at + * the beginning of the communication, you do not need to call this + * function explicitly unless you want clearer error reporting. + * However, you may call g_dtls_connection_handshake() later on to + * renegotiate parameters (encryption methods, etc) with the client. + * + * #GDtlsConnection::accept_certificate may be emitted during the + * handshake. + * + * Returns: success or failure + * Since: 2.48 */ /** - * g_dbus_server_is_active: - * @server: A #GDBusServer. + * g_dtls_connection_handshake_async: + * @conn: a #GDtlsConnection + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the handshake is complete + * @user_data: the data to pass to the callback function * - * Gets whether @server is active. + * Asynchronously performs a TLS handshake on @conn. See + * g_dtls_connection_handshake() for more information. * - * Returns: %TRUE if server is active, %FALSE otherwise. - * Since: 2.26 + * Since: 2.48 */ /** - * g_dbus_server_new_sync: - * @address: A D-Bus address. - * @flags: Flags from the #GDBusServerFlags enumeration. - * @guid: A D-Bus GUID. - * @observer: (nullable): A #GDBusAuthObserver or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for server or %NULL. - * - * Creates a new D-Bus server that listens on the first address in - * @address that works. + * g_dtls_connection_handshake_finish: + * @conn: a #GDtlsConnection + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * Once constructed, you can use g_dbus_server_get_client_address() to - * get a D-Bus address string that clients can use to connect. + * Finish an asynchronous TLS handshake operation. See + * g_dtls_connection_handshake() for more information. * - * Connect to the #GDBusServer::new-connection signal to handle - * incoming connections. + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set. + * Since: 2.48 + */ + + +/** + * g_dtls_connection_set_certificate: + * @conn: a #GDtlsConnection + * @certificate: the certificate to use for @conn * - * The returned #GDBusServer isn't active - you have to start it with - * g_dbus_server_start(). + * This sets the certificate that @conn will present to its peer + * during the TLS handshake. For a #GDtlsServerConnection, it is + * mandatory to set this, and that will normally be done at construct + * time. * - * #GDBusServer is used in this [example][gdbus-peer-to-peer]. + * For a #GDtlsClientConnection, this is optional. If a handshake fails + * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server + * requires a certificate, and if you try connecting again, you should + * call this method first. You can call + * g_dtls_client_connection_get_accepted_cas() on the failed connection + * to get a list of Certificate Authorities that the server will + * accept certificates from. * - * This is a synchronous failable constructor. See - * g_dbus_server_new() for the asynchronous version. + * (It is also possible that a server will allow the connection with + * or without a certificate; in that case, if you don't provide a + * certificate, you can tell that the server requested one by the fact + * that g_dtls_client_connection_get_accepted_cas() will return + * non-%NULL.) * - * Returns: A #GDBusServer or %NULL if @error is set. Free with - * g_object_unref(). - * Since: 2.26 + * Since: 2.48 */ /** - * g_dbus_server_start: - * @server: A #GDBusServer. + * g_dtls_connection_set_database: + * @conn: a #GDtlsConnection + * @database: a #GTlsDatabase * - * Starts @server. + * Sets the certificate database that is used to verify peer certificates. + * This is set to the default database by default. See + * g_tls_backend_get_default_database(). If set to %NULL, then + * peer certificate validation will always set the + * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning + * #GDtlsConnection::accept-certificate will always be emitted on + * client-side connections, unless that bit is not set in + * #GDtlsClientConnection:validation-flags). * - * Since: 2.26 + * Since: 2.48 */ /** - * g_dbus_server_stop: - * @server: A #GDBusServer. + * g_dtls_connection_set_interaction: + * @conn: a connection + * @interaction: (nullable): an interaction object, or %NULL * - * Stops @server. + * Set the object that will be used to interact with the user. It will be used + * for things like prompting the user for passwords. * - * Since: 2.26 + * The @interaction argument will normally be a derived subclass of + * #GTlsInteraction. %NULL can also be provided if no user interaction + * should occur for this connection. + * + * Since: 2.48 */ /** - * g_dbus_signal_info_ref: - * @info: A #GDBusSignalInfo + * g_dtls_connection_set_rehandshake_mode: + * @conn: a #GDtlsConnection + * @mode: the rehandshaking mode * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Sets how @conn behaves with respect to rehandshaking requests. * - * Returns: The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_signal_info_unref: - * @info: A #GDBusSignalInfo. + * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to + * rehandshake after the initial handshake is complete. (For a client, + * this means it will refuse rehandshake requests from the server, and + * for a server, this means it will close the connection with an error + * if the client attempts to rehandshake.) * - * 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_TLS_REHANDSHAKE_SAFELY means that the connection will allow a + * rehandshake only if the other end of the connection supports the + * 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. * - * Since: 2.26 + * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow + * 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.48 */ /** - * 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() + * g_dtls_connection_set_require_close_notify: + * @conn: a #GDtlsConnection + * @require_close_notify: whether or not to require close notification * - * Gets the user-visible display name of the "additional application - * action" specified by @action_name. + * Sets whether or not @conn expects a proper TLS close notification + * before the connection is closed. If this is %TRUE (the default), + * then @conn will expect to receive a TLS close notification from its + * peer before the connection is closed, and will return a + * %G_TLS_ERROR_EOF error if the connection is closed without proper + * notification (since this may indicate a network error, or + * man-in-the-middle attack). * - * This corresponds to the "Name" key within the keyfile group for the - * action. + * In some protocols, the application will know whether or not the + * connection was closed cleanly based on application-level data + * (because the application-level data includes a length field, or is + * somehow self-delimiting); in this case, the close notify is + * redundant and may be omitted. You + * can use g_dtls_connection_set_require_close_notify() to tell @conn + * to allow an "unannounced" connection close, in which case the close + * will show up as a 0-length read, as in a non-TLS + * #GDatagramBased, and it is up to the application to check that + * the data has been fully received. * - * Returns: (transfer full): the locale-specific action name - * Since: 2.38 + * Note that this only affects the behavior when the peer closes the + * connection; when the application calls g_dtls_connection_close_async() on + * @conn itself, this will send a close notification regardless of the + * setting of this property. If you explicitly want to do an unclean + * close, you can close @conn's #GDtlsConnection:base-socket rather + * than closing @conn itself. + * + * Since: 2.48 */ /** - * g_desktop_app_info_get_boolean: - * @info: a #GDesktopAppInfo - * @key: the key to look up + * g_dtls_connection_shutdown: + * @conn: a #GDtlsConnection + * @shutdown_read: %TRUE to stop reception of incoming datagrams + * @shutdown_write: %TRUE to stop sending outgoing datagrams + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a #GError, or %NULL * - * Looks up a boolean value in the keyfile backing @info. + * Shut down part or all of a DTLS connection. * - * The @key is looked up in the "Desktop Entry" group. + * If @shutdown_read is %TRUE then the receiving side of the connection is shut + * down, and further reading is disallowed. Subsequent calls to + * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. * - * Returns: the boolean value, or %FALSE if the key - * is not found - * Since: 2.36 + * If @shutdown_write is %TRUE then the sending side of the connection is shut + * down, and further writing is disallowed. Subsequent calls to + * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. + * + * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this + * is equivalent to calling g_dtls_connection_close(). + * + * If @cancellable is cancelled, the #GDtlsConnection may be left + * partially-closed and any pending untransmitted data may be lost. Call + * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. + * + * Returns: %TRUE on success, %FALSE otherwise + * Since: 2.48 */ /** - * g_desktop_app_info_get_categories: - * @info: a #GDesktopAppInfo + * g_dtls_connection_shutdown_async: + * @conn: a #GDtlsConnection + * @shutdown_read: %TRUE to stop reception of incoming datagrams + * @shutdown_write: %TRUE to stop sending outgoing datagrams + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the shutdown operation is complete + * @user_data: the data to pass to the callback function * - * Gets the categories from the desktop file. + * Asynchronously shut down part or all of the DTLS connection. See + * g_dtls_connection_shutdown() for more information. * - * Returns: The unparsed Categories key from the desktop file; - * i.e. no attempt is made to split it by ';' or validate it. + * Since: 2.48 */ /** - * g_desktop_app_info_get_filename: - * @info: a #GDesktopAppInfo + * g_dtls_connection_shutdown_finish: + * @conn: a #GDtlsConnection + * @result: a #GAsyncResult + * @error: a #GError pointer, or %NULL * - * 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. + * Finish an asynchronous TLS shutdown operation. See + * g_dtls_connection_shutdown() for more information. * - * Returns: (type filename): The full path to the file for @info, - * or %NULL if not known. - * Since: 2.24 + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set + * Since: 2.48 */ /** - * g_desktop_app_info_get_generic_name: - * @info: a #GDesktopAppInfo + * g_dtls_server_connection_new: + * @base_socket: the #GDatagramBased to wrap + * @certificate: (nullable): the default server certificate, or %NULL + * @error: #GError for error reporting, or %NULL to ignore * - * Gets the generic name from the destkop file. + * Creates a new #GDtlsServerConnection wrapping @base_socket. * - * Returns: The value of the GenericName key + * Returns: (transfer full) (type GDtlsServerConnection): the new + * #GDtlsServerConnection, or %NULL on error + * Since: 2.48 */ /** - * g_desktop_app_info_get_implementations: - * @interface: the name of the interface - * - * Gets all applications that implement @interface. + * g_emblem_get_icon: + * @emblem: a #GEmblem from which the icon should be extracted. * - * An application implements an interface if that interface is listed in - * the Implements= line of the desktop file of the application. + * Gives back the icon from @emblem. * - * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo - * objects. - * Since: 2.42 + * Returns: (transfer none): a #GIcon. The returned object belongs to + * the emblem and should not be modified or freed. + * Since: 2.18 */ /** - * g_desktop_app_info_get_is_hidden: - * @info: a #GDesktopAppInfo. + * g_emblem_get_origin: + * @emblem: a #GEmblem * - * A desktop file is hidden if the Hidden key in it is - * set to True. + * Gets the origin of the emblem. * - * Returns: %TRUE if hidden, %FALSE otherwise. + * Returns: (transfer none): the origin of the emblem + * Since: 2.18 */ /** - * g_desktop_app_info_get_keywords: - * @info: a #GDesktopAppInfo + * g_emblem_new: + * @icon: a GIcon containing the icon. * - * Gets the keywords from the desktop file. + * Creates a new emblem for @icon. * - * Returns: (transfer none): The value of the Keywords key - * Since: 2.32 + * Returns: a new #GEmblem. + * Since: 2.18 */ /** - * g_desktop_app_info_get_locale_string: - * @info: a #GDesktopAppInfo - * @key: the key to look up - * - * Looks up a localized string value in the keyfile backing @info - * translated to the current locale. + * g_emblem_new_with_origin: + * @icon: a GIcon containing the icon. + * @origin: a GEmblemOrigin enum defining the emblem's origin * - * The @key is looked up in the "Desktop Entry" group. + * Creates a new emblem for @icon. * - * Returns: (nullable): a newly allocated string, or %NULL if the key - * is not found - * Since: 2.56 + * Returns: a new #GEmblem. + * Since: 2.18 */ /** - * g_desktop_app_info_get_nodisplay: - * @info: a #GDesktopAppInfo + * g_emblemed_icon_add_emblem: + * @emblemed: a #GEmblemedIcon + * @emblem: a #GEmblem * - * 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(). + * Adds @emblem to the #GList of #GEmblems. * - * Returns: The value of the NoDisplay key - * Since: 2.30 + * Since: 2.18 */ /** - * g_desktop_app_info_get_show_in: - * @info: a #GDesktopAppInfo - * @desktop_env: (nullable): a string specifying a desktop name - * - * Checks if the application info should be shown in menus that list available - * applications for a specific name of the desktop, based on the - * `OnlyShowIn` and `NotShowIn` keys. - * - * @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_emblemed_icon_clear_emblems: + * @emblemed: a #GEmblemedIcon * - * Note that g_app_info_should_show() for @info will include this check (with - * %NULL for @desktop_env) as well as additional checks. + * Removes all the emblems from @icon. * - * Returns: %TRUE if the @info should be shown in @desktop_env according to the - * `OnlyShowIn` and `NotShowIn` keys, %FALSE - * otherwise. - * Since: 2.30 + * Since: 2.28 */ /** - * g_desktop_app_info_get_startup_wm_class: - * @info: a #GDesktopAppInfo that supports startup notify + * g_emblemed_icon_get_emblems: + * @emblemed: a #GEmblemedIcon * - * Retrieves the StartupWMClass field from @info. This represents the - * WM_CLASS property of the main window of the application, if launched - * through @info. + * Gets the list of emblems for the @icon. * - * Returns: (transfer none): the startup WM class, or %NULL if none is set - * in the desktop file. - * Since: 2.34 + * Returns: (element-type Gio.Emblem) (transfer none): a #GList of + * #GEmblems that is owned by @emblemed + * Since: 2.18 */ /** - * g_desktop_app_info_get_string: - * @info: a #GDesktopAppInfo - * @key: the key to look up - * - * Looks up a string value in the keyfile backing @info. + * g_emblemed_icon_get_icon: + * @emblemed: a #GEmblemedIcon * - * The @key is looked up in the "Desktop Entry" group. + * Gets the main icon for @emblemed. * - * Returns: a newly allocated string, or %NULL if the key - * is not found - * Since: 2.36 + * Returns: (transfer none): a #GIcon that is owned by @emblemed + * Since: 2.18 */ /** - * g_desktop_app_info_has_key: - * @info: a #GDesktopAppInfo - * @key: the key to look up + * g_emblemed_icon_new: + * @icon: a #GIcon + * @emblem: (nullable): a #GEmblem, or %NULL * - * Returns whether @key exists in the "Desktop Entry" group - * of the keyfile backing @info. + * Creates a new emblemed icon for @icon with the emblem @emblem. * - * Returns: %TRUE if the @key exists - * Since: 2.36 + * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon + * Since: 2.18 */ /** - * 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: (nullable): a #GAppLaunchContext + * g_file_append_to: + * @file: input #GFile + * @flags: a set of #GFileCreateFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Activates the named application action. + * Gets an output stream for appending data to the file. + * If the file doesn't already exist it is created. * - * You may only call this function on action names that were - * returned from g_desktop_app_info_list_actions(). + * 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. * - * 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. + * 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. * - * As with g_app_info_launch() there is no way to detect failures that - * occur while using this function. + * 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. * - * Since: 2.38 + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_desktop_app_info_launch_uris_as_manager: - * @appinfo: a #GDesktopAppInfo - * @uris: (element-type utf8): List of URIs - * @launch_context: (nullable): a #GAppLaunchContext - * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once - * for each process. - * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup - * @pid_callback: (scope call) (nullable): Callback for child processes - * @pid_callback_data: (closure pid_callback) (nullable): 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(). + * 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: (nullable): 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 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. + * Asynchronously opens @file for appending. * - * 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. + * For more details, see g_file_append_to() which is + * the synchronous version of this call. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * 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_desktop_app_info_list_actions: - * @info: a #GDesktopAppInfo - * - * Returns the list of "additional application actions" supported on the - * desktop file, as per the desktop file specification. + * g_file_append_to_finish: + * @file: input #GFile + * @res: #GAsyncResult + * @error: a #GError, or %NULL * - * As per the specification, this is the list of actions that are - * explicitly listed in the "Actions" key of the [Desktop Entry] group. + * Finishes an asynchronous file append operation started with + * g_file_append_to_async(). * - * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL - * Since: 2.38 + * Returns: (transfer full): a valid #GFileOutputStream + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_desktop_app_info_lookup_get_default_for_uri_scheme: - * @lookup: a #GDesktopAppInfoLookup - * @uri_scheme: a string containing a URI scheme. + * 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. * - * Gets the default application for launching applications - * using this URI scheme for a particular GDesktopAppInfoLookup - * implementation. + * 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 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(). + * Makes a duplicate of a file attribute info list. * - * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. - * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio. + * Returns: a copy of the given @list. */ /** - * g_desktop_app_info_new: - * @desktop_id: the desktop file id - * - * Creates a new #GDesktopAppInfo based on a desktop file id. + * g_file_attribute_info_list_lookup: + * @list: a #GFileAttributeInfoList. + * @name: the name of the attribute to lookup. * - * 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`). + * Gets the file attribute with the name @name from @list. * - * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id + * Returns: a #GFileAttributeInfo for the @name, or %NULL if an + * attribute isn't found. */ /** - * g_desktop_app_info_new_from_filename: - * @filename: (type filename): the path of a desktop file, in the GLib - * filename encoding + * g_file_attribute_info_list_new: * - * Creates a new #GDesktopAppInfo. + * Creates a new file attribute info list. * - * Returns: a new #GDesktopAppInfo or %NULL on error. + * Returns: a #GFileAttributeInfoList. */ /** - * g_desktop_app_info_new_from_keyfile: - * @key_file: an opened #GKeyFile + * g_file_attribute_info_list_ref: + * @list: a #GFileAttributeInfoList to reference. * - * Creates a new #GDesktopAppInfo. + * References a file attribute info list. * - * Returns: a new #GDesktopAppInfo or %NULL on error. - * Since: 2.18 + * Returns: #GFileAttributeInfoList or %NULL on error. */ /** - * g_desktop_app_info_search: - * @search_string: the search string to use + * g_file_attribute_info_list_unref: + * @list: The #GFileAttributeInfoList to unreference. * - * Searches desktop files for ones that match @search_string. + * Removes a reference from the given @list. If the reference count + * falls to zero, the @list is deleted. + */ + + +/** + * g_file_attribute_matcher_enumerate_namespace: + * @matcher: a #GFileAttributeMatcher. + * @ns: a string containing a file attribute namespace. * - * 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. + * 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.) + * + * TODO: this is awkwardly worded. * - * 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(). + * Returns: %TRUE if the matcher matches all of the entries + * in the given @ns, %FALSE otherwise. */ /** - * 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 - * `OnlyShowIn` and `NotShowIn` - * desktop entry fields. + * g_file_attribute_matcher_enumerate_next: + * @matcher: a #GFileAttributeMatcher. * - * Should be called only once; subsequent calls are ignored. + * Gets the next matched attribute from a #GFileAttributeMatcher. * - * Deprecated: 2.42: do not use this API. Since 2.42 the value of the - * `XDG_CURRENT_DESKTOP` environment variable will be used. + * Returns: a string containing the next attribute or %NULL if + * no more attribute exist. */ /** - * g_drive_can_eject: - * @drive: a #GDrive. + * g_file_attribute_matcher_matches: + * @matcher: a #GFileAttributeMatcher. + * @attribute: a file attribute key. * - * Checks if a drive can be ejected. + * 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: %TRUE if the @drive can be ejected, %FALSE otherwise. + * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise. */ /** - * g_drive_can_poll_for_media: - * @drive: a #GDrive. + * g_file_attribute_matcher_matches_only: + * @matcher: a #GFileAttributeMatcher. + * @attribute: a file attribute key. * - * Checks if a drive can be polled for media changes. + * Checks if a attribute matcher only matches a given attribute. Always + * returns %FALSE if "*" was used when creating the matcher. * - * Returns: %TRUE if the @drive can be polled for media changes, - * %FALSE otherwise. + * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise. */ /** - * g_drive_can_start: - * @drive: a #GDrive. + * g_file_attribute_matcher_new: + * @attributes: an attribute string to match. * - * Checks if a drive can be started. + * 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. * - * Returns: %TRUE if the @drive can be started, %FALSE otherwise. - * Since: 2.22 + * 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. + * + * ## Examples of file attribute matcher strings and results + * + * - `"*"`: matches all attributes. + * - `"standard::is-hidden"`: matches only the key is-hidden in the + * standard namespace. + * - `"standard::type,unix::*"`: matches the type key in the standard + * namespace and all keys in the unix namespace. + * + * Returns: a #GFileAttributeMatcher */ /** - * g_drive_can_start_degraded: - * @drive: a #GDrive. + * g_file_attribute_matcher_ref: + * @matcher: a #GFileAttributeMatcher. * - * Checks if a drive can be started degraded. + * References a file attribute matcher. * - * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise. - * Since: 2.22 + * Returns: a #GFileAttributeMatcher. */ /** - * g_drive_can_stop: - * @drive: a #GDrive. + * g_file_attribute_matcher_subtract: + * @matcher: Matcher to subtract from + * @subtract: The matcher to subtract * - * Checks if a drive can be stopped. + * Subtracts all attributes of @subtract from @matcher and returns + * a matcher that supports those attributes. * - * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise. - * Since: 2.22 + * 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. + * + * Returns: A file attribute matcher matching all attributes of + * @matcher that are not matched by @subtract */ /** - * g_drive_eject: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for eject - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback - * - * Asynchronously ejects a drive. + * g_file_attribute_matcher_to_string: + * @matcher: (nullable): a #GFileAttributeMatcher. * - * When the operation is finished, @callback will be called. - * You can then call g_drive_eject_finish() to obtain the - * result of the operation. + * 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. * - * Deprecated: 2.22: Use g_drive_eject_with_operation() instead. + * Returns: a string describing the attributes the matcher matches + * against or %NULL if @matcher was %NULL. + * Since: 2.32 */ /** - * g_drive_eject_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes ejecting a drive. + * g_file_attribute_matcher_unref: + * @matcher: a #GFileAttributeMatcher. * - * Returns: %TRUE if the drive has been ejected successfully, - * %FALSE otherwise. - * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. + * Unreferences @matcher. If the reference count falls below 1, + * the @matcher is automatically freed. */ /** - * g_drive_eject_with_operation: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_file_attribute_value_dup: + * @other: a #GFileAttributeValue to duplicate. * - * 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. + * Duplicates a file attribute. * - * Since: 2.22 + * Returns: a duplicate of the @other. */ /** - * 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_attribute_value_set: + * @attr: a #GFileAttributeValue to set the value in. + * @new_value: a #GFileAttributeValue to get the value from. * - * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise. - * Since: 2.22 + * Sets an attribute's value from another attribute. */ /** - * g_drive_enumerate_identifiers: - * @drive: a #GDrive + * g_file_copy: + * @source: input #GFile + * @destination: destination #GFile + * @flags: set of #GFileCopyFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (nullable) (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 * - * Gets the kinds of identifiers that @drive has. - * Use g_drive_get_identifier() to obtain the identifiers - * themselves. + * Copies the file @source to the location specified by @destination. + * Can not handle recursive copies of directories. * - * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated - * array of strings containing kinds of identifiers. Use g_strfreev() - * to free. + * 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 the flag #G_FILE_COPY_ALL_METADATA is specified then all the metadata + * that is possible to copy is copied, not just the default subset (which, + * for instance, does not include the owner, see #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. + * + * 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. + * + * 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_drive_get_icon: - * @drive: a #GDrive. + * g_file_copy_async: + * @source: input #GFile + * @destination: destination #GFile + * @flags: set of #GFileCopyFlags + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (nullable) (scope notified): function to callback with progress + * information, or %NULL if progress information is not needed + * @progress_callback_data: (closure progress_callback) (nullable): user data to pass to @progress_callback + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure callback): the data to pass to callback function * - * Gets the icon for @drive. + * Copies the file @source to the location specified by @destination + * asynchronously. For details of the behaviour, see g_file_copy(). * - * Returns: (transfer full): #GIcon for the @drive. - * Free the returned object with g_object_unref(). + * 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. + * + * 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_drive_get_identifier: - * @drive: a #GDrive - * @kind: the kind of identifier to return + * g_file_copy_attributes: + * @source: a #GFile with attributes + * @destination: a #GFile to copy attributes to + * @flags: a set of #GFileCopyFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, %NULL to ignore * - * Gets the identifier of the given kind for @drive. + * Copies the file attributes from @source to @destination. * - * Returns: a newly allocated string containing the - * requested identfier, or %NULL if the #GDrive - * doesn't have this kind of identifier. + * 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: %TRUE if the attributes were copied successfully, + * %FALSE otherwise. */ /** - * g_drive_get_name: - * @drive: a #GDrive. + * g_file_copy_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Gets the name of @drive. + * Finishes copying the file started with g_file_copy_async(). * - * Returns: a string containing @drive's name. The returned - * string should be freed when no longer needed. + * Returns: a %TRUE on success, %FALSE on error. */ /** - * g_drive_get_sort_key: - * @drive: A #GDrive. + * g_file_create: + * @file: input #GFile + * @flags: a set of #GFileCreateFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Gets the sort key for @drive, if any. + * Creates a new file and returns an output stream for writing to it. + * The file must not already exist. * - * Returns: Sorting key for @drive or %NULL if no such key is available. - * Since: 2.32 + * 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 a file or directory with this name already exists the + * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't + * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME + * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will + * be returned. Other errors are possible too, and depend on what kind + * of filesystem the file is on. + * + * Returns: (transfer full): a #GFileOutputStream for the newly created + * file, or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_drive_get_start_stop_type: - * @drive: a #GDrive. + * g_file_create_async: + * @file: input #GFile + * @flags: a set of #GFileCreateFlags + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 a hint about how a drive can be started/stopped. + * Asynchronously creates a new file and returns an output stream + * for writing to it. The file must not already exist. * - * Returns: A value from the #GDriveStartStopType enumeration. - * Since: 2.22 + * For more details, see g_file_create() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_create_finish() to get the result + * of the operation. */ /** - * g_drive_get_symbolic_icon: - * @drive: a #GDrive. + * g_file_create_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Gets the icon for @drive. + * Finishes an asynchronous file create operation started with + * g_file_create_async(). * - * Returns: (transfer full): symbolic #GIcon for the @drive. - * Free the returned object with g_object_unref(). - * Since: 2.34 + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_drive_get_volumes: - * @drive: a #GDrive. + * g_file_create_readwrite: + * @file: a #GFile + * @flags: a set of #GFileCreateFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: return location for a #GError, or %NULL * - * Get a list of mountable volumes for @drive. + * Creates a new file and returns a stream for reading and + * writing to it. The file must not already exist. * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * 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: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive. + * 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_drive_has_media: - * @drive: a #GDrive. + * 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: (nullable): 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 @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. + * Asynchronously creates a new file and returns a stream + * for reading and writing to it. The file must not already exist. * - * Returns: %TRUE if @drive has media, %FALSE otherwise. + * For more details, see g_file_create_readwrite() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_create_readwrite_finish() to get + * the result of the operation. + * + * Since: 2.22 */ /** - * g_drive_has_volumes: - * @drive: a #GDrive. + * g_file_create_readwrite_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Check if @drive has any mountable volumes. + * Finishes an asynchronous file create operation started with + * g_file_create_readwrite_async(). * - * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise. + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_drive_is_media_check_automatic: - * @drive: a #GDrive. + * g_file_delete: (virtual delete_file) + * @file: input #GFile + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Checks if @drive is capabable of automatically detecting media changes. + * 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(). * - * Returns: %TRUE if the @drive is capabable of automatically detecting - * media changes, %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: %TRUE if the file was deleted. %FALSE otherwise. */ /** - * g_drive_is_media_removable: - * @drive: a #GDrive. + * g_file_delete_async: (virtual delete_file_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 * - * Checks if the @drive supports removable media. + * 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(). * - * Returns: %TRUE if @drive supports removable media, %FALSE otherwise. + * Since: 2.34 */ /** - * g_drive_is_removable: - * @drive: a #GDrive. + * g_file_delete_finish: (virtual delete_file_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * Checks if the #GDrive and/or its media is considered removable by the user. - * See g_drive_is_media_removable(). + * Finishes deleting a file started with g_file_delete_async(). * - * Returns: %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. - * Since: 2.50 + * Returns: %TRUE if the file was deleted. %FALSE otherwise. + * Since: 2.34 */ /** - * g_drive_poll_for_media: - * @drive: a #GDrive. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + * g_file_descriptor_based_get_fd: + * @fd_based: a #GFileDescriptorBased. * - * Asynchronously polls @drive to see if media has been inserted or removed. + * Gets the underlying file descriptor. * - * 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. + * Returns: The file descriptor + * Since: 2.24 */ /** - * g_drive_poll_for_media_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_file_dup: + * @file: input #GFile * - * Finishes an operation started with g_drive_poll_for_media() on a drive. + * 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. * - * Returns: %TRUE if the drive has been poll_for_mediaed successfully, - * %FALSE otherwise. + * This call does no blocking I/O. + * + * Returns: (transfer full): a new #GFile that is a duplicate + * of the given #GFile. */ - -/** - * g_drive_start: - * @drive: a #GDrive. - * @flags: flags affecting the start operation. - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + +/** + * g_file_eject_mountable: + * @file: input #GFile + * @flags: flags affecting the operation + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL + * @user_data: (closure): the data to pass to callback function * - * Asynchronously starts a drive. + * 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(). * - * When the operation is finished, @callback will be called. - * You can then call g_drive_start_finish() to obtain 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. * - * Since: 2.22 + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead. */ /** - * g_drive_start_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. + * g_file_eject_mountable_finish: + * @file: input #GFile + * @result: a #GAsyncResult * @error: a #GError, or %NULL * - * Finishes starting a drive. + * Finishes an asynchronous eject operation started by + * g_file_eject_mountable(). * - * Returns: %TRUE if the drive has been started successfully, + * Returns: %TRUE if the @file was ejected successfully. * %FALSE otherwise. - * Since: 2.22 + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() + * instead. */ /** - * g_drive_stop: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for stopping. - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + * g_file_eject_mountable_with_operation: + * @file: input #GFile + * @flags: flags affecting the operation + * @mount_operation: (nullable): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL + * @user_data: (closure): the data to pass to callback function * - * Asynchronously stops a drive. + * 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(). * - * When the operation is finished, @callback will be called. - * You can then call g_drive_stop_finish() to obtain 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. * * Since: 2.22 */ /** - * g_drive_stop_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. + * g_file_eject_mountable_with_operation_finish: + * @file: input #GFile + * @result: a #GAsyncResult * @error: a #GError, or %NULL * - * Finishes stopping a drive. + * Finishes an asynchronous eject operation started by + * g_file_eject_mountable_with_operation(). * - * Returns: %TRUE if the drive has been stopped successfully, + * Returns: %TRUE if the @file was ejected successfully. * %FALSE otherwise. * Since: 2.22 */ /** - * g_dtls_client_connection_get_accepted_cas: - * @conn: the #GDtlsClientConnection + * g_file_enumerate_children: + * @file: input #GFile + * @attributes: an attribute query string + * @flags: a set of #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: #GError for error reporting * - * Gets the list of distinguished names of the Certificate Authorities - * that the server will accept certificates from. This will be set - * during the TLS handshake if the server requests a certificate. - * Otherwise, it will be %NULL. + * 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. * - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. + * 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. * - * Returns: (element-type GByteArray) (transfer full): the list of - * CA DNs. You should unref each element with g_byte_array_unref() and then - * the free the list with g_list_free(). - * Since: 2.48 + * 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_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_dtls_client_connection_get_server_identity: - * @conn: the #GDtlsClientConnection + * 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: (nullable): 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 @conn's expected server identity + * 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. * - * Returns: (transfer none): a #GSocketConnectable describing the - * expected server identity, or %NULL if the expected identity is not - * known. - * Since: 2.48 + * For more details, see g_file_enumerate_children() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. You can + * then call g_file_enumerate_children_finish() to get the result of + * the operation. */ /** - * g_dtls_client_connection_get_validation_flags: - * @conn: the #GDtlsClientConnection + * g_file_enumerate_children_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError * - * Gets @conn's validation flags + * Finishes an async enumerate children operation. + * See g_file_enumerate_children_async(). * - * Returns: the validation flags - * Since: 2.48 + * Returns: (transfer full): a #GFileEnumerator or %NULL + * if an error occurred. + * Free the returned object with g_object_unref(). */ /** - * g_dtls_client_connection_new: - * @base_socket: the #GDatagramBased to wrap - * @server_identity: (nullable): the expected identity of the server - * @error: #GError for error reporting, or %NULL to ignore. + * g_file_enumerator_close: + * @enumerator: a #GFileEnumerator. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Creates a new #GDtlsClientConnection wrapping @base_socket which is - * assumed to communicate with the server identified by @server_identity. + * Releases all resources used by this enumerator, making the + * enumerator return %G_IO_ERROR_CLOSED on all calls. * - * Returns: (transfer full) (type GDtlsClientConnection): the new - * #GDtlsClientConnection, or %NULL on error - * Since: 2.48 + * 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. + * + * Returns: #TRUE on success or #FALSE on error. */ /** - * g_dtls_client_connection_set_server_identity: - * @conn: the #GDtlsClientConnection - * @identity: a #GSocketConnectable describing the expected server identity + * g_file_enumerator_close_async: + * @enumerator: a #GFileEnumerator. + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 @conn's expected server identity, which is used both to tell - * servers on virtual hosts which certificate to present, and also - * to let @conn know what name to look for in the certificate when - * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. + * Asynchronously closes the file enumerator. * - * Since: 2.48 + * 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_dtls_client_connection_set_validation_flags: - * @conn: the #GDtlsClientConnection - * @flags: the #GTlsCertificateFlags to use + * g_file_enumerator_close_finish: + * @enumerator: a #GFileEnumerator. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Sets @conn's validation flags, to override the default set of - * checks performed when validating a server certificate. By default, - * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. + * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). * - * Since: 2.48 + * 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: %TRUE if the close operation has finished successfully. */ /** - * g_dtls_connection_close: - * @conn: a #GDtlsConnection - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Close the DTLS connection. This is equivalent to calling - * g_dtls_connection_shutdown() to shut down both sides of the connection. - * - * Closing a #GDtlsConnection waits for all buffered but untransmitted data to - * be sent before it completes. It then sends a `close_notify` DTLS alert to the - * peer and may wait for a `close_notify` to be received from the peer. It does - * not close the underlying #GDtlsConnection:base-socket; that must be closed - * separately. - * - * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a #GDtlsConnection multiple times will not return an error. + * g_file_enumerator_get_child: + * @enumerator: a #GFileEnumerator + * @info: a #GFileInfo gotten from g_file_enumerator_next_file() + * or the async equivalents. * - * #GDtlsConnections 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. + * 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(). * - * If @cancellable is cancelled, the #GDtlsConnection may be left - * partially-closed and any pending untransmitted data may be lost. Call - * g_dtls_connection_close() again to complete closing the #GDtlsConnection. + * This is a convenience method that's equivalent to: + * |[ + * gchar *name = g_file_info_get_name (info); + * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), + * name); + * ]| * - * Returns: %TRUE on success, %FALSE otherwise - * Since: 2.48 + * Returns: (transfer full): a #GFile for the #GFileInfo passed it. + * Since: 2.36 */ /** - * g_dtls_connection_close_async: - * @conn: a #GDtlsConnection - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the close operation is complete - * @user_data: the data to pass to the callback function + * g_file_enumerator_get_container: + * @enumerator: a #GFileEnumerator * - * Asynchronously close the DTLS connection. See g_dtls_connection_close() for - * more information. + * Get the #GFile container which is being enumerated. * - * Since: 2.48 + * Returns: (transfer none): the #GFile which is being enumerated. + * Since: 2.18 */ /** - * g_dtls_connection_close_finish: - * @conn: a #GDtlsConnection - * @result: a #GAsyncResult - * @error: a #GError pointer, or %NULL + * g_file_enumerator_has_pending: + * @enumerator: a #GFileEnumerator. * - * Finish an asynchronous TLS close operation. See g_dtls_connection_close() - * for more information. + * Checks if the file enumerator has pending operations. * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set - * Since: 2.48 + * Returns: %TRUE if the @enumerator has pending operations. */ /** - * g_dtls_connection_emit_accept_certificate: - * @conn: a #GDtlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert + * g_file_enumerator_is_closed: + * @enumerator: a #GFileEnumerator. * - * Used by #GDtlsConnection implementations to emit the - * #GDtlsConnection::accept-certificate signal. + * Checks if the file enumerator has been closed. * - * Returns: %TRUE if one of the signal handlers has returned - * %TRUE to accept @peer_cert - * Since: 2.48 + * Returns: %TRUE if the @enumerator is closed. */ /** - * g_dtls_connection_get_certificate: - * @conn: a #GDtlsConnection + * g_file_enumerator_iterate: + * @direnum: an open #GFileEnumerator + * @out_info: (out) (transfer none) (optional): Output location for the next #GFileInfo, or %NULL + * @out_child: (out) (transfer none) (optional): Output location for the next #GFile, or %NULL + * @cancellable: a #GCancellable + * @error: a #GError * - * Gets @conn's certificate, as set by - * g_dtls_connection_set_certificate(). + * 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. * - * Returns: (transfer none): @conn's certificate, or %NULL - * Since: 2.48 + * In contrast, with this function, a %FALSE return from + * g_file_enumerator_iterate() *always* means + * "error". End of iteration is signaled by @out_info or @out_child being %NULL. + * + * Another crucial difference is that the references for @out_info and + * @out_child are owned by @direnum (they are cached as hidden + * properties). You must not unref them in your own code. This makes + * memory management significantly easier for C code in combination + * with loops. + * + * Finally, this function optionally allows retrieving a #GFile as + * well. + * + * You must specify at least one of @out_info or @out_child. + * + * The code pattern for correctly using g_file_enumerator_iterate() from C + * is: + * + * |[ + * direnum = g_file_enumerate_children (file, ...); + * while (TRUE) + * { + * GFileInfo *info; + * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error)) + * goto out; + * if (!info) + * break; + * ... do stuff with "info"; do not unref it! ... + * } + * + * out: + * g_object_unref (direnum); // Note: frees the last @info + * ]| + * + * Since: 2.44 */ /** - * g_dtls_connection_get_database: - * @conn: a #GDtlsConnection + * g_file_enumerator_next_file: + * @enumerator: a #GFileEnumerator. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Gets the certificate database that @conn uses to verify - * peer certificates. See g_dtls_connection_set_database(). + * 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: (transfer none): the certificate database that @conn uses or %NULL - * Since: 2.48 + * 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_dtls_connection_get_interaction: - * @conn: a connection + * 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: (nullable): 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 * - * Get the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. If %NULL is returned, then - * no user interaction will occur for this connection. + * 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. * - * Returns: (transfer none): The interaction object. - * Since: 2.48 + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * + * The callback can be called with less than @num_files files in case of error + * or at the end of the enumerator. In case of a partial error the callback will + * be called with any succeeding items and no error, and on the next request the + * error will be reported. If a request is cancelled the callback will be called + * with %G_IO_ERROR_CANCELLED. + * + * 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_dtls_connection_get_peer_certificate: - * @conn: a #GDtlsConnection + * 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. * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of - * #GDtlsConnection::accept-certificate.) + * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). * - * Returns: (transfer none): @conn's peer's certificate, or %NULL - * Since: 2.48 + * 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_dtls_connection_get_peer_certificate_errors: - * @conn: a #GDtlsConnection - * - * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GDtlsConnection::accept-certificate.) + * g_file_enumerator_set_pending: + * @enumerator: a #GFileEnumerator. + * @pending: a boolean value. * - * Returns: @conn's peer's certificate errors - * Since: 2.48 + * Sets the file enumerator as having pending operations. */ /** - * g_dtls_connection_get_rehandshake_mode: - * @conn: a #GDtlsConnection + * g_file_equal: + * @file1: the first #GFile + * @file2: the second #GFile * - * Gets @conn rehandshaking mode. See - * g_dtls_connection_set_rehandshake_mode() for details. + * Checks if the two given #GFiles refer to the same file. * - * Returns: @conn's rehandshaking mode - * Since: 2.48 + * 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_dtls_connection_get_require_close_notify: - * @conn: a #GDtlsConnection + * g_file_find_enclosing_mount: + * @file: input #GFile + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError * - * Tests whether or not @conn expects a proper TLS close notification - * when the connection is closed. See - * g_dtls_connection_set_require_close_notify() for details. + * Gets a #GMount for the #GFile. * - * Returns: %TRUE if @conn requires a proper TLS close notification. - * Since: 2.48 + * If the #GFileIface for @file does not have a mount (e.g. + * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND + * and %NULL will be returned. + * + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Returns: (transfer full): a #GMount where the @file is located + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_dtls_connection_handshake: - * @conn: a #GDtlsConnection - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Attempts a TLS handshake on @conn. - * - * On the client side, it is never necessary to call this method; - * although the connection needs to perform a handshake after - * connecting (or after sending a "STARTTLS"-type command) and may - * need to rehandshake later if the server requests it, - * #GDtlsConnection will handle this for you automatically when you try - * to send or receive data on the connection. However, you can call - * g_dtls_connection_handshake() manually if you want to know for sure - * whether the initial handshake succeeded or failed (as opposed to - * just immediately trying to write to @conn, in which - * case if it fails, it may not be possible to tell if it failed - * before or after completing the handshake). + * g_file_find_enclosing_mount_async: + * @file: a #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 * - * Likewise, on the server side, although a handshake is necessary at - * the beginning of the communication, you do not need to call this - * function explicitly unless you want clearer error reporting. - * However, you may call g_dtls_connection_handshake() later on to - * renegotiate parameters (encryption methods, etc) with the client. + * Asynchronously gets the mount for the file. * - * #GDtlsConnection::accept_certificate may be emitted during the - * handshake. + * For more details, see g_file_find_enclosing_mount() which is + * the synchronous version of this call. * - * Returns: success or failure - * Since: 2.48 + * 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_dtls_connection_handshake_async: - * @conn: a #GDtlsConnection - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the handshake is complete - * @user_data: the data to pass to the callback function + * g_file_find_enclosing_mount_finish: + * @file: a #GFile + * @res: a #GAsyncResult + * @error: a #GError * - * Asynchronously performs a TLS handshake on @conn. See - * g_dtls_connection_handshake() for more information. + * Finishes an asynchronous find mount request. + * See g_file_find_enclosing_mount_async(). * - * Since: 2.48 + * Returns: (transfer full): #GMount for given @file or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_dtls_connection_handshake_finish: - * @conn: a #GDtlsConnection - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL + * g_file_get_basename: + * @file: input #GFile * - * Finish an asynchronous TLS handshake operation. See - * g_dtls_connection_handshake() for more information. + * Gets the base name (the last component of the path) for a given #GFile. * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set. - * Since: 2.48 + * 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: (type filename) (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_dtls_connection_set_certificate: - * @conn: a #GDtlsConnection - * @certificate: the certificate to use for @conn + * g_file_get_child: + * @file: input #GFile + * @name: (type filename): string containing the child's basename * - * This sets the certificate that @conn will present to its peer - * during the TLS handshake. For a #GDtlsServerConnection, it is - * mandatory to set this, and that will normally be done at construct - * time. + * Gets a child of @file with basename equal to @name. * - * For a #GDtlsClientConnection, this is optional. If a handshake fails - * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server - * requires a certificate, and if you try connecting again, you should - * call this method first. You can call - * g_dtls_client_connection_get_accepted_cas() on the failed connection - * to get a list of Certificate Authorities that the server will - * accept certificates from. + * 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. * - * (It is also possible that a server will allow the connection with - * or without a certificate; in that case, if you don't provide a - * certificate, you can tell that the server requested one by the fact - * that g_dtls_client_connection_get_accepted_cas() will return - * non-%NULL.) + * This call does no blocking I/O. * - * Since: 2.48 + * Returns: (transfer full): a #GFile to a child specified by @name. + * Free the returned object with g_object_unref(). */ /** - * g_dtls_connection_set_database: - * @conn: a #GDtlsConnection - * @database: a #GTlsDatabase + * g_file_get_child_for_display_name: + * @file: input #GFile + * @display_name: string to a possible child + * @error: return location for an error * - * Sets the certificate database that is used to verify peer certificates. - * This is set to the default database by default. See - * g_tls_backend_get_default_database(). If set to %NULL, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GDtlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GDtlsClientConnection:validation-flags). + * 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. * - * Since: 2.48 + * This call does no blocking I/O. + * + * Returns: (transfer full): a #GFile to the specified child, or + * %NULL if the display name couldn't be converted. + * Free the returned object with g_object_unref(). */ /** - * g_dtls_connection_set_interaction: - * @conn: a connection - * @interaction: (nullable): an interaction object, or %NULL + * g_file_get_parent: + * @file: input #GFile * - * Set the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. + * Gets the parent directory for the @file. + * If the @file represents the root directory of the + * file system, then %NULL will be returned. * - * The @interaction argument will normally be a derived subclass of - * #GTlsInteraction. %NULL can also be provided if no user interaction - * should occur for this connection. + * This call does no blocking I/O. * - * Since: 2.48 + * 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_dtls_connection_set_rehandshake_mode: - * @conn: a #GDtlsConnection - * @mode: the rehandshaking mode + * g_file_get_parse_name: + * @file: input #GFile * - * Sets how @conn behaves with respect to rehandshaking requests. + * 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(). * - * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to - * rehandshake after the initial handshake is complete. (For a client, - * this means it will refuse rehandshake requests from the server, and - * for a server, this means it will close the connection with an error - * if the client attempts to rehandshake.) + * 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. * - * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a - * rehandshake only if the other end of the connection supports the - * 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. + * 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). * - * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow - * 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. + * This call does no blocking I/O. * - * Since: 2.48 + * Returns: a string containing the #GFile's parse name. + * The returned string should be freed with g_free() + * when no longer needed. */ /** - * g_dtls_connection_set_require_close_notify: - * @conn: a #GDtlsConnection - * @require_close_notify: whether or not to require close notification - * - * Sets whether or not @conn expects a proper TLS close notification - * before the connection is closed. If this is %TRUE (the default), - * then @conn will expect to receive a TLS close notification from its - * peer before the connection is closed, and will return a - * %G_TLS_ERROR_EOF error if the connection is closed without proper - * notification (since this may indicate a network error, or - * man-in-the-middle attack). + * g_file_get_path: + * @file: input #GFile * - * In some protocols, the application will know whether or not the - * connection was closed cleanly based on application-level data - * (because the application-level data includes a length field, or is - * somehow self-delimiting); in this case, the close notify is - * redundant and may be omitted. You - * can use g_dtls_connection_set_require_close_notify() to tell @conn - * to allow an "unannounced" connection close, in which case the close - * will show up as a 0-length read, as in a non-TLS - * #GDatagramBased, and it is up to the application to check that - * the data has been fully received. + * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is + * guaranteed to be an absolute, canonical path. It might contain symlinks. * - * Note that this only affects the behavior when the peer closes the - * connection; when the application calls g_dtls_connection_close_async() on - * @conn itself, this will send a close notification regardless of the - * setting of this property. If you explicitly want to do an unclean - * close, you can close @conn's #GDtlsConnection:base-socket rather - * than closing @conn itself. + * This call does no blocking I/O. * - * Since: 2.48 + * Returns: (type filename) (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_dtls_connection_shutdown: - * @conn: a #GDtlsConnection - * @shutdown_read: %TRUE to stop reception of incoming datagrams - * @shutdown_write: %TRUE to stop sending outgoing datagrams - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL + * g_file_get_relative_path: + * @parent: input #GFile + * @descendant: input #GFile * - * Shut down part or all of a DTLS connection. + * Gets the path for @descendant relative to @parent. * - * If @shutdown_read is %TRUE then the receiving side of the connection is shut - * down, and further reading is disallowed. Subsequent calls to - * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. + * This call does no blocking I/O. * - * If @shutdown_write is %TRUE then the sending side of the connection is shut - * down, and further writing is disallowed. Subsequent calls to - * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. + * Returns: (type filename) (nullable): string with the relative path from + * @descendant to @parent, or %NULL if @descendant doesn't have @parent as + * prefix. The returned string should be freed with g_free() when + * no longer needed. + */ + + +/** + * g_file_get_uri: + * @file: input #GFile * - * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this - * is equivalent to calling g_dtls_connection_close(). + * Gets the URI for the @file. * - * If @cancellable is cancelled, the #GDtlsConnection may be left - * partially-closed and any pending untransmitted data may be lost. Call - * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. + * This call does no blocking I/O. * - * Returns: %TRUE on success, %FALSE otherwise - * Since: 2.48 + * Returns: a string containing the #GFile's URI. + * The returned string should be freed with g_free() + * when no longer needed. */ /** - * g_dtls_connection_shutdown_async: - * @conn: a #GDtlsConnection - * @shutdown_read: %TRUE to stop reception of incoming datagrams - * @shutdown_write: %TRUE to stop sending outgoing datagrams - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the shutdown operation is complete - * @user_data: the data to pass to the callback function + * g_file_get_uri_scheme: + * @file: input #GFile * - * Asynchronously shut down part or all of the DTLS connection. See - * g_dtls_connection_shutdown() for more information. + * 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. * - * Since: 2.48 + * This call does no blocking I/O. + * + * Returns: a string containing the URI scheme for the given + * #GFile. The returned string should be freed with g_free() + * when no longer needed. */ /** - * g_dtls_connection_shutdown_finish: - * @conn: a #GDtlsConnection - * @result: a #GAsyncResult - * @error: a #GError pointer, or %NULL + * g_file_has_parent: + * @file: input #GFile + * @parent: (nullable): the parent to check for, or %NULL * - * Finish an asynchronous TLS shutdown operation. See - * g_dtls_connection_shutdown() for more information. + * Checks if @file has a parent, and optionally, if it is @parent. * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set - * Since: 2.48 + * 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 an immediate child of @parent. + * + * Returns: %TRUE if @file is an immediate child of @parent (or any parent in + * the case that @parent is %NULL). + * Since: 2.24 */ /** - * g_dtls_server_connection_new: - * @base_socket: the #GDatagramBased to wrap - * @certificate: (nullable): the default server certificate, or %NULL - * @error: #GError for error reporting, or %NULL to ignore + * g_file_has_prefix: (virtual prefix_matches) + * @file: input #GFile + * @prefix: input #GFile * - * Creates a new #GDtlsServerConnection wrapping @base_socket. + * Checks whether @file has the prefix specified by @prefix. * - * Returns: (transfer full) (type GDtlsServerConnection): the new - * #GDtlsServerConnection, or %NULL on error - * Since: 2.48 + * In other words, if the names of initial elements of @file's + * pathname match @prefix. Only full pathname elements are matched, + * so a path like /foo is not considered a prefix of /foobar, only + * of /foo/bar. + * + * A #GFile is not a prefix of itself. If you want to check for + * equality, use g_file_equal(). + * + * This call does no I/O, as it works purely on names. As such it can + * sometimes return %FALSE even if @file is inside a @prefix (from a + * filesystem point of view), because the prefix of @file is an alias + * of @prefix. + * + * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, + * %FALSE otherwise. */ /** - * g_emblem_get_icon: - * @emblem: a #GEmblem from which the icon should be extracted. + * g_file_has_uri_scheme: + * @file: input #GFile + * @uri_scheme: a string containing a URI scheme * - * Gives back the icon from @emblem. + * Checks to see if a #GFile has a given URI scheme. * - * Returns: (transfer none): a #GIcon. The returned object belongs to - * the emblem and should not be modified or freed. - * Since: 2.18 + * 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_emblem_get_origin: - * @emblem: a #GEmblem + * g_file_hash: (virtual hash) + * @file: (type GFile): #gconstpointer to a #GFile * - * Gets the origin of the emblem. + * Creates a hash value for a #GFile. * - * Returns: (transfer none): the origin of the emblem - * Since: 2.18 + * This call does no blocking I/O. + * + * 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_emblem_new: - * @icon: a GIcon containing the icon. + * g_file_icon_get_file: + * @icon: a #GIcon. * - * Creates a new emblem for @icon. + * Gets the #GFile associated with the given @icon. * - * Returns: a new #GEmblem. - * Since: 2.18 + * Returns: (transfer none): a #GFile, or %NULL. */ /** - * g_emblem_new_with_origin: - * @icon: a GIcon containing the icon. - * @origin: a GEmblemOrigin enum defining the emblem's origin + * g_file_icon_new: + * @file: a #GFile. * - * Creates a new emblem for @icon. + * Creates a new icon for a file. * - * Returns: a new #GEmblem. - * Since: 2.18 + * Returns: (transfer full) (type GFileIcon): a #GIcon for the given + * @file, or %NULL on error. */ /** - * g_emblemed_icon_add_emblem: - * @emblemed: a #GEmblemedIcon - * @emblem: a #GEmblem + * g_file_info_clear_status: + * @info: a #GFileInfo. * - * Adds @emblem to the #GList of #GEmblems. + * 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. * - * Since: 2.18 + * First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info, + * and then copies all of the file attributes from @src_info to @dest_info. */ /** - * g_emblemed_icon_clear_emblems: - * @emblemed: a #GEmblemedIcon + * g_file_info_dup: + * @other: a #GFileInfo. * - * Removes all the emblems from @icon. + * Duplicates a file info structure. * - * Since: 2.28 + * Returns: (transfer full): a duplicate #GFileInfo of @other. */ /** - * g_emblemed_icon_get_emblems: - * @emblemed: a #GEmblemedIcon + * g_file_info_get_attribute_as_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Gets the list of emblems for the @icon. + * Gets the value of a attribute, formated as a string. + * This escapes things as needed to make the string valid + * utf8. * - * Returns: (element-type Gio.Emblem) (transfer none): a #GList of - * #GEmblems that is owned by @emblemed - * Since: 2.18 + * 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_emblemed_icon_get_icon: - * @emblemed: a #GEmblemedIcon + * g_file_info_get_attribute_boolean: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Gets the main icon for @emblemed. + * Gets the value of a boolean attribute. If the attribute does not + * contain a boolean value, %FALSE will be returned. * - * Returns: (transfer none): a #GIcon that is owned by @emblemed - * Since: 2.18 + * Returns: the boolean value contained within the attribute. */ /** - * g_emblemed_icon_new: - * @icon: a #GIcon - * @emblem: (nullable): a #GEmblem, or %NULL + * g_file_info_get_attribute_byte_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Creates a new emblemed icon for @icon with the emblem @emblem. + * Gets the value of a byte string attribute. If the attribute does + * not contain a byte string, %NULL will be returned. * - * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon - * Since: 2.18 + * Returns: the contents of the @attribute value as a byte string, or + * %NULL otherwise. */ /** - * g_file_append_to: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): 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. + * g_file_info_get_attribute_data: + * @info: a #GFileInfo + * @attribute: a file attribute key + * @type: (out) (optional): return location for the attribute type, or %NULL + * @value_pp: (out) (optional) (not nullable): return location for the + * attribute value, or %NULL; the attribute value will not be %NULL + * @status: (out) (optional): return location for the attribute status, or %NULL * - * 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 attribute type, value and status for an 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. + * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, + * %FALSE otherwise. + */ + + +/** + * g_file_info_get_attribute_int32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * 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. + * 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: (transfer full): a #GFileOutputStream, or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: a signed 32-bit integer from the attribute. */ /** - * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call - * when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously opens @file for appending. + * g_file_info_get_attribute_int64: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * For more details, see g_file_append_to() which is - * the synchronous version of this call. + * 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. * - * 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: a signed 64-bit integer from the attribute. */ /** - * g_file_append_to_finish: - * @file: input #GFile - * @res: #GAsyncResult - * @error: a #GError, or %NULL + * g_file_info_get_attribute_object: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Finishes an asynchronous file append operation started with - * g_file_append_to_async(). + * Gets the value of a #GObject attribute. If the attribute does + * not contain a #GObject, %NULL will be returned. * - * Returns: (transfer full): a valid #GFileOutputStream - * or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: (transfer none): a #GObject associated with the given @attribute, or + * %NULL otherwise. */ /** - * 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. + * g_file_info_get_attribute_status: + * @info: a #GFileInfo + * @attribute: a file attribute key * - * Adds a new attribute with @name to the @list, setting - * its @type and @flags. + * Gets the attribute status for an attribute key. + * + * Returns: a #GFileAttributeStatus for the given @attribute, or + * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. */ /** - * g_file_attribute_info_list_dup: - * @list: a #GFileAttributeInfoList to duplicate. + * g_file_info_get_attribute_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Makes a duplicate of a file attribute info list. + * Gets the value of a string attribute. If the attribute does + * not contain a string, %NULL will be returned. * - * Returns: a copy of the given @list. + * Returns: the contents of the @attribute value as a UTF-8 string, or + * %NULL otherwise. */ /** - * g_file_attribute_info_list_lookup: - * @list: a #GFileAttributeInfoList. - * @name: the name of the attribute to lookup. + * g_file_info_get_attribute_stringv: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Gets the file attribute with the name @name from @list. + * Gets the value of a stringv attribute. If the attribute does + * not contain a stringv, %NULL will be returned. * - * Returns: a #GFileAttributeInfo for the @name, or %NULL if an - * attribute isn't found. + * 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_file_attribute_info_list_new: + * g_file_info_get_attribute_type: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Creates a new file attribute info list. + * Gets the attribute type for an attribute key. * - * Returns: a #GFileAttributeInfoList. + * Returns: a #GFileAttributeType for the given @attribute, or + * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. */ /** - * g_file_attribute_info_list_ref: - * @list: a #GFileAttributeInfoList to reference. + * g_file_info_get_attribute_uint32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * References a file attribute info list. + * 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: #GFileAttributeInfoList or %NULL on error. + * Returns: an unsigned 32-bit integer from the attribute. */ /** - * g_file_attribute_info_list_unref: - * @list: The #GFileAttributeInfoList to unreference. + * g_file_info_get_attribute_uint64: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Removes a reference from the given @list. If the reference count - * falls to zero, the @list is deleted. + * 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 unsigned 64-bit integer from the attribute. */ /** - * g_file_attribute_matcher_enumerate_namespace: - * @matcher: a #GFileAttributeMatcher. - * @ns: a string containing a file attribute namespace. - * - * 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.) + * g_file_info_get_content_type: + * @info: a #GFileInfo. * - * TODO: this is awkwardly worded. + * Gets the file's content type. * - * Returns: %TRUE if the matcher matches all of the entries - * in the given @ns, %FALSE otherwise. + * Returns: a string containing the file's content type. */ /** - * g_file_attribute_matcher_enumerate_next: - * @matcher: a #GFileAttributeMatcher. + * g_file_info_get_deletion_date: + * @info: a #GFileInfo. * - * Gets the next matched attribute from a #GFileAttributeMatcher. + * Returns the #GDateTime representing the deletion date of the file, as + * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the + * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. * - * Returns: a string containing the next attribute or %NULL if - * no more attribute exist. + * Returns: a #GDateTime, or %NULL. + * Since: 2.36 */ /** - * g_file_attribute_matcher_matches: - * @matcher: a #GFileAttributeMatcher. - * @attribute: a file attribute key. + * g_file_info_get_display_name: + * @info: a #GFileInfo. * - * 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. + * Gets a display name for a file. * - * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise. + * Returns: a string containing the display name. */ /** - * g_file_attribute_matcher_matches_only: - * @matcher: a #GFileAttributeMatcher. - * @attribute: a file attribute key. + * g_file_info_get_edit_name: + * @info: a #GFileInfo. * - * Checks if a attribute matcher only matches a given attribute. Always - * returns %FALSE if "*" was used when creating the matcher. + * Gets the edit name for a file. * - * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise. + * Returns: a string containing the edit name. */ /** - * g_file_attribute_matcher_new: - * @attributes: an attribute string to match. - * - * 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. - * - * 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. - * - * ## Examples of file attribute matcher strings and results + * g_file_info_get_etag: + * @info: a #GFileInfo. * - * - `"*"`: 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. + * Gets the [entity tag][gfile-etag] for a given + * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * - * Returns: a #GFileAttributeMatcher + * Returns: a string containing the value of the "etag:value" attribute. */ /** - * g_file_attribute_matcher_ref: - * @matcher: a #GFileAttributeMatcher. + * g_file_info_get_file_type: + * @info: a #GFileInfo. * - * References a file attribute matcher. + * 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(). * - * Returns: a #GFileAttributeMatcher. + * Returns: a #GFileType for the given file. */ /** - * g_file_attribute_matcher_subtract: - * @matcher: Matcher to subtract from - * @subtract: The matcher to subtract - * - * Subtracts all attributes of @subtract from @matcher and returns - * a matcher that supports those attributes. + * g_file_info_get_icon: + * @info: a #GFileInfo. * - * 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. + * Gets the icon for a file. * - * Returns: A file attribute matcher matching all attributes of - * @matcher that are not matched by @subtract + * Returns: (transfer none): #GIcon for the given @info. */ /** - * g_file_attribute_matcher_to_string: - * @matcher: (nullable): a #GFileAttributeMatcher. + * g_file_info_get_is_backup: + * @info: a #GFileInfo. * - * 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. + * Checks if a file is a backup file. * - * Returns: a string describing the attributes the matcher matches - * against or %NULL if @matcher was %NULL. - * Since: 2.32 + * Returns: %TRUE if file is a backup file, %FALSE otherwise. */ /** - * g_file_attribute_matcher_unref: - * @matcher: a #GFileAttributeMatcher. + * g_file_info_get_is_hidden: + * @info: a #GFileInfo. * - * Unreferences @matcher. If the reference count falls below 1, - * the @matcher is automatically freed. + * Checks if a file is hidden. + * + * Returns: %TRUE if the file is a hidden file, %FALSE otherwise. */ /** - * g_file_attribute_value_dup: - * @other: a #GFileAttributeValue to duplicate. + * g_file_info_get_is_symlink: + * @info: a #GFileInfo. * - * Duplicates a file attribute. + * Checks if a file is a symlink. * - * Returns: a duplicate of the @other. + * Returns: %TRUE if the given @info is a symlink. */ /** - * g_file_attribute_value_set: - * @attr: a #GFileAttributeValue to set the value in. - * @new_value: a #GFileAttributeValue to get the value from. + * g_file_info_get_modification_time: + * @info: a #GFileInfo. + * @result: (out caller-allocates): a #GTimeVal. * - * Sets an attribute's value from another attribute. + * Gets the modification time of the current @info and sets it + * in @result. */ /** - * g_file_copy: - * @source: input #GFile - * @destination: destination #GFile - * @flags: set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @progress_callback: (nullable) (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 the flag #G_FILE_COPY_ALL_METADATA is specified then all the metadata - * that is possible to copy is copied, not just the default subset (which, - * for instance, does not include the owner, see #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. - * - * 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. - * - * 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_info_get_name: + * @info: a #GFileInfo. * - * If you are interested in copying the #GFile object itself (not the on-disk - * file), see g_file_dup(). + * Gets the name for a file. * - * Returns: %TRUE on success, %FALSE otherwise. + * Returns: (type filename): a string containing the file name. */ /** - * g_file_copy_async: - * @source: input #GFile - * @destination: destination #GFile - * @flags: set of #GFileCopyFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @progress_callback: (nullable) (scope notified): function to callback with progress - * information, or %NULL if progress information is not needed - * @progress_callback_data: (closure progress_callback) (nullable): user data to pass to @progress_callback - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure callback): the data to pass to callback function - * - * Copies the file @source to the location specified by @destination - * asynchronously. For details of the behaviour, see g_file_copy(). + * g_file_info_get_size: + * @info: a #GFileInfo. * - * 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. + * Gets the file's size. * - * When the operation is finished, @callback will be called. You can then call - * g_file_copy_finish() to get the result of the operation. + * Returns: a #goffset containing the file's size. */ /** - * g_file_copy_attributes: - * @source: a #GFile with attributes - * @destination: a #GFile to copy attributes to - * @flags: a set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, %NULL to ignore - * - * Copies the file attributes from @source to @destination. + * g_file_info_get_sort_order: + * @info: a #GFileInfo. * - * 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. + * Gets the value of the sort_order attribute from the #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. * - * Returns: %TRUE if the attributes were copied successfully, - * %FALSE otherwise. + * Returns: a #gint32 containing the value of the "standard::sort_order" attribute. */ /** - * g_file_copy_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_file_info_get_symbolic_icon: + * @info: a #GFileInfo. * - * Finishes copying the file started with g_file_copy_async(). + * Gets the symbolic icon for a file. * - * Returns: a %TRUE on success, %FALSE on error. + * Returns: (transfer none): #GIcon for the given @info. + * Since: 2.34 */ /** - * g_file_create: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Creates a new file and returns an output stream for writing to it. - * The file must not already exist. - * - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level - * that is supported on the target filesystem. - * - * 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_info_get_symlink_target: + * @info: a #GFileInfo. * - * 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. + * Gets the symlink target for a given #GFileInfo. * - * Returns: (transfer full): a #GFileOutputStream for the newly created - * file, or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: a string containing the symlink target. */ /** - * g_file_create_async: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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. + * g_file_info_has_attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * For more details, see g_file_create() which is - * the synchronous version of this call. + * Checks if a file info structure has an attribute named @attribute. * - * When the operation is finished, @callback will be called. - * You can then call g_file_create_finish() to get the result - * of the operation. + * Returns: %TRUE if @Ginfo has an attribute named @attribute, + * %FALSE otherwise. */ /** - * g_file_create_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_file_info_has_namespace: + * @info: a #GFileInfo. + * @name_space: a file attribute namespace. * - * Finishes an asynchronous file create operation started with - * g_file_create_async(). + * Checks if a file info structure has an attribute in the + * specified @name_space. * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if @Ginfo has an attribute in @name_space, + * %FALSE otherwise. + * Since: 2.22 */ /** - * g_file_create_readwrite: - * @file: a #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: return location for a #GError, or %NULL - * - * Creates a new file and returns a stream for reading and - * writing to it. The file must not already exist. - * - * 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 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. + * g_file_info_list_attributes: + * @info: a #GFileInfo. + * @name_space: (nullable): a file attribute key's namespace, or %NULL to list + * all attributes. * - * 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. + * Lists the file info structure's attributes. * - * 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 + * Returns: (nullable) (array zero-terminated=1) (transfer full): a + * null-terminated array of strings of all of the possible attribute + * types for the given @name_space, or %NULL on error. */ /** - * g_file_create_readwrite_async: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call - * when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously creates a new file and returns a stream - * for reading and writing to it. The file must not already exist. - * - * For more details, see g_file_create_readwrite() which is - * the synchronous version of this call. + * g_file_info_new: * - * 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. + * Creates a new file info structure. * - * Since: 2.22 + * Returns: a #GFileInfo. */ /** - * g_file_create_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file create operation started with - * g_file_create_readwrite_async(). + * g_file_info_remove_attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * Removes all cases of @attribute from @info if it exists. */ /** - * g_file_delete: (virtual delete_file) - * @file: input #GFile - * @cancellable: (nullable): 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. This has the same semantics as g_unlink(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * g_file_info_set_attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @type: a #GFileAttributeType + * @value_p: (not nullable): pointer to the value * - * Returns: %TRUE if the file was deleted. %FALSE otherwise. + * Sets the @attribute to contain the given value, if possible. To unset the + * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type. */ /** - * g_file_delete_async: (virtual delete_file_async) - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: a #GAsyncReadyCallback to call - * when the request is satisfied - * @user_data: the data to pass to callback function - * - * Asynchronously delete a file. If the @file is a directory, it will - * only be deleted if it is empty. This has the same semantics as - * g_unlink(). + * g_file_info_set_attribute_boolean: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a boolean value. * - * Since: 2.34 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_delete_finish: (virtual delete_file_finish) - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes deleting a file started with g_file_delete_async(). + * g_file_info_set_attribute_byte_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a byte string. * - * Returns: %TRUE if the file was deleted. %FALSE otherwise. - * Since: 2.34 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_descriptor_based_get_fd: - * @fd_based: a #GFileDescriptorBased. - * - * Gets the underlying file descriptor. + * g_file_info_set_attribute_int32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a signed 32-bit integer * - * Returns: The file descriptor - * Since: 2.24 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_dup: - * @file: input #GFile - * - * Duplicates a #GFile handle. This operation does not duplicate - * the actual file or directory represented by the #GFile; see - * g_file_copy() if attempting to copy a file. - * - * This call does no blocking I/O. + * g_file_info_set_attribute_int64: + * @info: a #GFileInfo. + * @attribute: attribute name to set. + * @attr_value: int64 value to set attribute to. * - * Returns: (transfer full): a new #GFile that is a duplicate - * of the given #GFile. + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_eject_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Starts an asynchronous eject on a mountable. - * 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(). - * - * 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_info_set_attribute_mask: + * @info: a #GFileInfo. + * @mask: a #GFileAttributeMatcher. * - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead. + * Sets @mask on @info to match specific attribute types. */ /** - * g_file_eject_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous eject operation started by - * g_file_eject_mountable(). + * g_file_info_set_attribute_object: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a #GObject. * - * Returns: %TRUE if the @file was ejected successfully. - * %FALSE otherwise. - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() - * instead. + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_eject_mountable_with_operation: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function + * g_file_info_set_attribute_status: + * @info: a #GFileInfo + * @attribute: a file attribute key + * @status: a #GFileAttributeStatus * - * 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(). + * 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. * - * 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 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_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_info_set_attribute_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a UTF-8 string. * - * Returns: %TRUE if the @file was ejected successfully. - * %FALSE otherwise. - * Since: 2.22 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_enumerate_children: - * @file: input #GFile - * @attributes: an attribute query string - * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (nullable): 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. - * - * 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_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. * - * 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. + * Sets the @attribute to contain the given @attr_value, + * if possible. * - * Returns: (transfer full): A #GFileEnumerator if successful, - * %NULL on error. Free the returned object with g_object_unref(). + * Sinze: 2.22 */ /** - * 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: (nullable): 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. - * - * For more details, see g_file_enumerate_children() which is - * the synchronous version of this call. + * g_file_info_set_attribute_uint32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: an unsigned 32-bit integer. * - * 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. + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_enumerate_children_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError - * - * Finishes an async enumerate children operation. - * See g_file_enumerate_children_async(). + * g_file_info_set_attribute_uint64: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: an unsigned 64-bit integer. * - * Returns: (transfer full): a #GFileEnumerator or %NULL - * if an error occurred. - * Free the returned object with g_object_unref(). + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_enumerator_close: - * @enumerator: a #GFileEnumerator. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Releases all resources used by this enumerator, making the - * enumerator return %G_IO_ERROR_CLOSED on all calls. - * - * 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. + * g_file_info_set_content_type: + * @info: a #GFileInfo. + * @content_type: a content type. See [GContentType][gio-GContentType] * - * Returns: #TRUE on success or #FALSE on error. + * Sets the content type attribute for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. */ /** - * g_file_enumerator_close_async: - * @enumerator: a #GFileEnumerator. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 closes the file enumerator. + * g_file_info_set_display_name: + * @info: a #GFileInfo. + * @display_name: a string containing a display 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 in - * g_file_enumerator_close_finish(). + * Sets the display name for the current #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. */ /** - * g_file_enumerator_close_finish: - * @enumerator: a #GFileEnumerator. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). - * - * 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. + * g_file_info_set_edit_name: + * @info: a #GFileInfo. + * @edit_name: a string containing an edit name. * - * Returns: %TRUE if the close operation has finished successfully. + * Sets the edit name for the current file. + * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. */ /** - * 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: - * |[ - * gchar *name = g_file_info_get_name (info); - * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), - * name); - * ]| + * g_file_info_set_file_type: + * @info: a #GFileInfo. + * @type: a #GFileType. * - * Returns: (transfer full): a #GFile for the #GFileInfo passed it. - * Since: 2.36 + * Sets the file type in a #GFileInfo to @type. + * See %G_FILE_ATTRIBUTE_STANDARD_TYPE. */ /** - * g_file_enumerator_get_container: - * @enumerator: a #GFileEnumerator - * - * Get the #GFile container which is being enumerated. + * g_file_info_set_icon: + * @info: a #GFileInfo. + * @icon: a #GIcon. * - * Returns: (transfer none): the #GFile which is being enumerated. - * Since: 2.18 + * Sets the icon for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_ICON. */ /** - * g_file_enumerator_has_pending: - * @enumerator: a #GFileEnumerator. - * - * Checks if the file enumerator has pending operations. + * g_file_info_set_is_hidden: + * @info: a #GFileInfo. + * @is_hidden: a #gboolean. * - * Returns: %TRUE if the @enumerator has pending operations. + * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. + * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. */ /** - * g_file_enumerator_is_closed: - * @enumerator: a #GFileEnumerator. - * - * Checks if the file enumerator has been closed. + * g_file_info_set_is_symlink: + * @info: a #GFileInfo. + * @is_symlink: a #gboolean. * - * Returns: %TRUE if the @enumerator is closed. + * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. + * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. */ /** - * g_file_enumerator_iterate: - * @direnum: an open #GFileEnumerator - * @out_info: (out) (transfer none) (optional): Output location for the next #GFileInfo, or %NULL - * @out_child: (out) (transfer none) (optional): Output location for the next #GFile, or %NULL - * @cancellable: a #GCancellable - * @error: a #GError - * - * This is a version of g_file_enumerator_next_file() that's easier to - * use correctly from C programs. With g_file_enumerator_next_file(), - * the gboolean return value signifies "end of iteration or error", which - * requires allocation of a temporary #GError. - * - * In contrast, with this function, a %FALSE return from - * g_file_enumerator_iterate() *always* means - * "error". End of iteration is signaled by @out_info or @out_child being %NULL. - * - * Another crucial difference is that the references for @out_info and - * @out_child are owned by @direnum (they are cached as hidden - * properties). You must not unref them in your own code. This makes - * memory management significantly easier for C code in combination - * with loops. - * - * Finally, this function optionally allows retrieving a #GFile as - * well. - * - * You must specify at least one of @out_info or @out_child. - * - * The code pattern for correctly using g_file_enumerator_iterate() from C - * is: - * - * |[ - * direnum = g_file_enumerate_children (file, ...); - * while (TRUE) - * { - * GFileInfo *info; - * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error)) - * goto out; - * if (!info) - * break; - * ... do stuff with "info"; do not unref it! ... - * } - * - * out: - * g_object_unref (direnum); // Note: frees the last @info - * ]| + * g_file_info_set_modification_time: + * @info: a #GFileInfo. + * @mtime: a #GTimeVal. * - * Since: 2.44 + * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file + * info to the given time value. */ /** - * g_file_enumerator_next_file: - * @enumerator: a #GFileEnumerator. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * 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. - * - * 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. + * g_file_info_set_name: + * @info: a #GFileInfo. + * @name: (type filename): a string containing a name. * - * 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. + * Sets the name attribute for the current #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_NAME. */ /** - * 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: (nullable): 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 - * - * 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. - * - * See the documentation of #GFileEnumerator for information about the - * order of returned files. - * - * The callback can be called with less than @num_files files in case of error - * or at the end of the enumerator. In case of a partial error the callback will - * be called with any succeeding items and no error, and on the next request the - * error will be reported. If a request is cancelled the callback will be called - * with %G_IO_ERROR_CANCELLED. + * g_file_info_set_size: + * @info: a #GFileInfo. + * @size: a #goffset containing the file's size. * - * During an async request no other sync and async calls are allowed, and will - * result in %G_IO_ERROR_PENDING errors. + * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info + * to the given size. + */ + + +/** + * g_file_info_set_sort_order: + * @info: a #GFileInfo. + * @sort_order: a sort order integer. * - * 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. + * Sets the sort order attribute in the file info structure. See + * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. */ /** - * 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_info_set_symbolic_icon: + * @info: a #GFileInfo. + * @icon: a #GIcon. * - * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). + * Sets the symbolic icon for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. * - * 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. + * Since: 2.34 */ /** - * g_file_enumerator_set_pending: - * @enumerator: a #GFileEnumerator. - * @pending: a boolean value. + * g_file_info_set_symlink_target: + * @info: a #GFileInfo. + * @symlink_target: a static string containing a path to a symlink target. * - * Sets the file enumerator as having pending operations. + * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info + * to the given symlink target. */ /** - * g_file_equal: - * @file1: the first #GFile - * @file2: the second #GFile - * - * Checks if the two given #GFiles refer to the same file. - * - * Note that two #GFiles that differ can still refer to the same - * file on the filesystem due to various forms of filename - * aliasing. - * - * This call does no blocking I/O. + * g_file_info_unset_attribute_mask: + * @info: #GFileInfo. * - * Returns: %TRUE if @file1 and @file2 are equal. + * Unsets a mask set by g_file_info_set_attribute_mask(), if one + * is set. */ /** - * g_file_find_enclosing_mount: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError - * - * Gets a #GMount for the #GFile. - * - * If the #GFileIface for @file does not have a mount (e.g. - * possibly a remote share), @error will be set to %G_IO_ERROR_NOT_FOUND - * and %NULL will be returned. + * g_file_input_stream_query_info: + * @stream: a #GFileInputStream. + * @attributes: a file attribute query string. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * 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. + * 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: (transfer full): a #GMount where the @file is located - * or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo, or %NULL on error. */ /** - * g_file_find_enclosing_mount_async: - * @file: a #GFile + * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call - * when the request is satisfied + * @cancellable: (nullable): 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 * - * Asynchronously gets the mount for the file. - * - * For more details, see g_file_find_enclosing_mount() which is - * the synchronous version of this call. + * 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_file_find_enclosing_mount_finish() to - * get 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_file_find_enclosing_mount_finish: - * @file: a #GFile - * @res: a #GAsyncResult - * @error: a #GError + * 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. * - * Finishes an asynchronous find mount request. - * See g_file_find_enclosing_mount_async(). + * Finishes an asynchronous info query operation. * - * Returns: (transfer full): #GMount for given @file or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo. */ /** - * g_file_get_basename: - * @file: input #GFile - * - * Gets the base name (the last component of the path) for a given #GFile. - * - * 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(). + * g_file_io_stream_get_etag: + * @stream: a #GFileIOStream. * - * This call does no blocking I/O. + * 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: (type filename) (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. + * Returns: the entity tag for the stream. + * Since: 2.22 */ /** - * g_file_get_child: - * @file: input #GFile - * @name: (type filename): string containing the child's basename + * g_file_io_stream_query_info: + * @stream: a #GFileIOStream. + * @attributes: a file attribute query string. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Gets a child of @file with basename equal to @name. + * 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. * - * 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. + * 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. * - * 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 set, and %NULL will + * be returned. * - * Returns: (transfer full): a #GFile to a child specified by @name. - * Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. + * Since: 2.22 */ /** - * g_file_get_child_for_display_name: - * @file: input #GFile - * @display_name: string to a possible child - * @error: return location for an error + * 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: (nullable): 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 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. + * 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(). * - * This call does no blocking I/O. + * For the synchronous version of this function, see + * g_file_io_stream_query_info(). * - * 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(). + * Since: 2.22 */ /** - * 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_io_stream_query_info_finish: + * @stream: a #GFileIOStream. + * @result: a #GAsyncResult. + * @error: a #GError, %NULL to ignore. * - * This call does no blocking I/O. + * Finalizes the asynchronous query started + * by g_file_io_stream_query_info_async(). * - * 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(). + * Returns: (transfer full): A #GFileInfo for the finished query. + * Since: 2.22 */ /** - * g_file_get_parse_name: + * g_file_is_native: * @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(). + * Checks to see if a file is native to the platform. * - * 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. + * 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. * - * 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). + * On some systems non-native files may be available using the native + * filesystem via a userspace filesystem (FUSE), in these cases this call + * will return %FALSE, but g_file_get_path() will still return a native path. * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's parse name. - * The returned string should be freed with g_free() - * when no longer needed. + * Returns: %TRUE if @file is native */ /** - * g_file_get_path: - * @file: input #GFile - * - * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is - * guaranteed to be an absolute, canonical path. It might contain symlinks. + * g_file_load_bytes: + * @file: a #GFile + * @cancellable: (nullable): a #GCancellable or %NULL + * @etag_out: (out) (nullable) (optional): a location to place the current + * entity tag for the file, or %NULL if the entity tag is not needed + * @error: a location for a #GError or %NULL * - * This call does no blocking I/O. + * Loads the contents of @file and returns it as #GBytes. * - * Returns: (type filename) (nullable): string containing the #GFile's path, - * or %NULL if no such path exists. The returned string should be freed - * with g_free() when no longer needed. - */ - - -/** - * g_file_get_relative_path: - * @parent: input #GFile - * @descendant: input #GFile + * If @file is a resource:// based URI, the resulting bytes will reference the + * embedded resource instead of a copy. Otherwise, this is equivalent to calling + * g_file_load_contents() and g_bytes_new_take(). * - * Gets the path for @descendant relative to @parent. + * For resources, @etag_out will be set to %NULL. * - * This call does no blocking I/O. + * The data contained in the resulting #GBytes is always zero-terminated, but + * this is not included in the #GBytes length. The resulting #GBytes should be + * freed with g_bytes_unref() when no longer in use. * - * Returns: (type filename) (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. + * Returns: (transfer full): a #GBytes or %NULL and @error is set + * Since: 2.56 */ /** - * g_file_get_uri: - * @file: input #GFile + * g_file_load_bytes_async: + * @file: a #GFile + * @cancellable: (nullable): 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 * - * Gets the URI for the @file. + * Asynchronously loads the contents of @file as #GBytes. * - * This call does no blocking I/O. + * If @file is a resource:// based URI, the resulting bytes will reference the + * embedded resource instead of a copy. Otherwise, this is equivalent to calling + * g_file_load_contents_async() and g_bytes_new_take(). * - * Returns: a string containing the #GFile's URI. - * The returned string should be freed with g_free() - * when no longer needed. + * @callback should call g_file_load_bytes_finish() to get the result of this + * asynchronous operation. + * + * See g_file_load_bytes() for more information. + * + * Since: 2.56 */ /** - * g_file_get_uri_scheme: - * @file: input #GFile + * g_file_load_bytes_finish: + * @file: a #GFile + * @result: a #GAsyncResult provided to the callback + * @etag_out: (out) (nullable) (optional): a location to place the current + * entity tag for the file, or %NULL if the entity tag is not needed + * @error: a location for a #GError, or %NULL * - * 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. + * Completes an asynchronous request to g_file_load_bytes_async(). * - * This call does no blocking I/O. + * For resources, @etag_out will be set to %NULL. * - * Returns: a string containing the URI scheme for the given - * #GFile. The returned string should be freed with g_free() - * when no longer needed. + * The data contained in the resulting #GBytes is always zero-terminated, but + * this is not included in the #GBytes length. The resulting #GBytes should be + * freed with g_bytes_unref() when no longer in use. + * + * See g_file_load_bytes() for more information. + * + * Returns: (transfer full): a #GBytes or %NULL and @error is set + * Since: 2.56 */ /** - * g_file_has_parent: + * g_file_load_contents: * @file: input #GFile - * @parent: (nullable): the parent to check for, or %NULL + * @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) (optional): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (optional): 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 * - * Checks if @file has a parent, and optionally, if it is @parent. + * 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 @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 an immediate child of @parent. + * 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 @file is an immediate child of @parent (or any parent in - * the case that @parent is %NULL). - * Since: 2.24 + * Returns: %TRUE if the @file's contents were successfully loaded. + * %FALSE if there were errors. */ /** - * g_file_has_prefix: (virtual prefix_matches) + * g_file_load_contents_async: * @file: input #GFile - * @prefix: input #GFile - * - * Checks whether @file has the prefix specified by @prefix. + * @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 * - * 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. + * Starts an asynchronous load of the @file's contents. * - * A #GFile is not a prefix of itself. If you want to check for - * equality, use g_file_equal(). + * For more details, see g_file_load_contents() which is + * the synchronous version of this call. * - * 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. + * 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: %TRUE if the @files's parent, grandparent, etc is @prefix, - * %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. */ /** - * g_file_has_uri_scheme: + * g_file_load_contents_finish: * @file: input #GFile - * @uri_scheme: a string containing a URI scheme - * - * Checks to see if a #GFile has a given URI scheme. + * @res: a #GAsyncResult + * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file + * @length: (out) (optional): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (optional): 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 * - * This call does no blocking I/O. + * 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: %TRUE if #GFile's backend supports the - * given URI scheme, %FALSE if URI scheme is %NULL, - * not supported, or #GFile is invalid. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ /** - * g_file_hash: (virtual hash) - * @file: (type GFile): #gconstpointer to a #GFile + * g_file_load_partial_contents_async: (skip) + * @file: input #GFile + * @cancellable: optional #GCancellable object, %NULL to ignore + * @read_more_callback: (scope call) (closure user_data): a + * #GFileReadMoreCallback to receive partial data + * and to specify whether further data should be read + * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call + * when the request is satisfied + * @user_data: the data to pass to the callback functions * - * Creates a hash value for a #GFile. + * 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(). * - * This call does no blocking I/O. + * Users of this function should be aware that @user_data is passed to + * both the @read_more_callback and the @callback. * - * 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. + * 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_icon_get_file: - * @icon: a #GIcon. + * 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) (optional): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (optional): 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 #GFile associated with the given @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. * - * Returns: (transfer none): a #GFile, or %NULL. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ /** - * g_file_icon_new: - * @file: a #GFile. + * g_file_make_directory: + * @file: input #GFile + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Creates a new icon for a file. + * 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. * - * Returns: (transfer full) (type GFileIcon): a #GIcon for the given - * @file, or %NULL on error. - */ - - -/** - * g_file_info_clear_status: - * @info: a #GFileInfo. + * For a local #GFile the newly created directory will have the default + * (current) ownership and permissions of the current process. * - * 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. + * 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 clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info, - * and then copies all of the file attributes from @src_info to @dest_info. + * Returns: %TRUE on successful creation, %FALSE otherwise. */ /** - * g_file_info_dup: - * @other: a #GFileInfo. + * g_file_make_directory_async: (virtual make_directory_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 * - * Duplicates a file info structure. + * Asynchronously creates a directory. * - * Returns: (transfer full): a duplicate #GFileInfo of @other. + * Since: 2.38 */ /** - * g_file_info_get_attribute_as_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_make_directory_finish: (virtual make_directory_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * Gets the value of a attribute, formated as a string. - * This escapes things as needed to make the string valid - * utf8. + * Finishes an asynchronous directory creation, started with + * g_file_make_directory_async(). * - * Returns: a UTF-8 string associated with the given @attribute. - * When you're done with the string it must be freed with g_free(). + * Returns: %TRUE on successful directory creation, %FALSE otherwise. + * Since: 2.38 */ /** - * g_file_info_get_attribute_boolean: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_make_directory_with_parents: + * @file: input #GFile + * @cancellable: (nullable): 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. + * 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(). * - * Returns: the boolean value contained within the attribute. + * 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. + * + * Returns: %TRUE if all directories have been successfully created, %FALSE + * otherwise. + * Since: 2.18 */ /** - * g_file_info_get_attribute_byte_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_make_symbolic_link: + * @file: a #GFile with the name of the symlink to create + * @symlink_value: (type filename): a string with the path for the target + * of the new symlink + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError * - * Gets the value of a byte string attribute. If the attribute does - * not contain a byte string, %NULL will be returned. + * Creates a symbolic link named @file which contains the string + * @symlink_value. * - * Returns: the contents of the @attribute value as a byte string, or - * %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: %TRUE on the creation of a new symlink, %FALSE otherwise. */ /** - * g_file_info_get_attribute_data: - * @info: a #GFileInfo - * @attribute: a file attribute key - * @type: (out) (optional): return location for the attribute type, or %NULL - * @value_pp: (out) (optional) (not nullable): return location for the - * attribute value, or %NULL; the attribute value will not be %NULL - * @status: (out) (optional): return location for the attribute status, or %NULL + * g_file_measure_disk_usage: + * @file: a #GFile + * @flags: #GFileMeasureFlags + * @cancellable: (nullable): optional #GCancellable + * @progress_callback: (nullable): a #GFileMeasureProgressCallback + * @progress_data: user_data for @progress_callback + * @disk_usage: (out) (optional): the number of bytes of disk space used + * @num_dirs: (out) (optional): the number of directories encountered + * @num_files: (out) (optional): the number of non-directories encountered + * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer * - * Gets the attribute type, value and status for an attribute key. + * Recursively measures the disk usage of @file. * - * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, - * %FALSE otherwise. + * This is essentially an analog of the 'du' command, but it also + * reports the number of directories and non-directory files encountered + * (including things like symbolic links). + * + * By default, errors are only reported against the toplevel file + * itself. Errors found while recursing are silently ignored, unless + * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags. + * + * The returned size, @disk_usage, is in bytes and should be formatted + * with g_format_size() in order to get something reasonable for showing + * in a user interface. + * + * @progress_callback and @progress_data can be given to request + * periodic progress updates while scanning. See the documentation for + * #GFileMeasureProgressCallback for information about when and how the + * callback will be invoked. + * + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. + * Since: 2.38 */ /** - * g_file_info_get_attribute_int32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_measure_disk_usage_async: + * @file: a #GFile + * @flags: #GFileMeasureFlags + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): optional #GCancellable + * @progress_callback: (nullable): a #GFileMeasureProgressCallback + * @progress_data: user_data for @progress_callback + * @callback: (nullable): a #GAsyncReadyCallback to call when complete + * @user_data: 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. + * Recursively measures the disk usage of @file. * - * Returns: a signed 32-bit integer from the attribute. + * This is the asynchronous version of g_file_measure_disk_usage(). See + * there for more information. + * + * Since: 2.38 */ /** - * g_file_info_get_attribute_int64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_measure_disk_usage_finish: + * @file: a #GFile + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @disk_usage: (out) (optional): the number of bytes of disk space used + * @num_dirs: (out) (optional): the number of directories encountered + * @num_files: (out) (optional): the number of non-directories encountered + * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer * - * 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. + * 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 signed 64-bit integer from the attribute. + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. + * Since: 2.38 */ /** - * g_file_info_get_attribute_object: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_monitor: + * @file: input #GFile + * @flags: a set of #GFileMonitorFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Gets the value of a #GObject attribute. If the attribute does - * not contain a #GObject, %NULL will be returned. + * Obtains a file or directory monitor for the given file, + * depending on the type of the file. * - * Returns: (transfer none): a #GObject associated with the given @attribute, or - * %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 full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.18 */ /** - * g_file_info_get_attribute_status: - * @info: a #GFileInfo - * @attribute: a file attribute key + * g_file_monitor_cancel: + * @monitor: a #GFileMonitor. * - * Gets the attribute status for an attribute key. + * Cancels a file monitor. * - * Returns: a #GFileAttributeStatus for the given @attribute, or - * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. + * Returns: always %TRUE */ /** - * g_file_info_get_attribute_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_monitor_directory: (virtual monitor_dir) + * @file: input #GFile + * @flags: a set of #GFileMonitorFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Gets the value of a string attribute. If the attribute does - * not contain a string, %NULL will be returned. + * Obtains a directory monitor for the given file. + * This may fail if directory monitoring is not supported. * - * Returns: the contents of the @attribute value as a UTF-8 string, or - * %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. + * + * It does not make sense for @flags to contain + * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to + * directories. It is not possible to monitor all the files in a + * directory for changes made via hard links; if you want to do this then + * you must register individual watches with g_file_monitor(). + * + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_get_attribute_stringv: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_monitor_emit_event: + * @monitor: a #GFileMonitor. + * @child: a #GFile. + * @other_file: a #GFile. + * @event_type: a set of #GFileMonitorEvent flags. * - * Gets the value of a stringv attribute. If the attribute does - * not contain a stringv, %NULL will be returned. + * Emits the #GFileMonitor::changed signal if a change + * has taken place. Should be called from file monitor + * implementations only. * - * 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 + * Implementations are responsible to call this method from the + * [thread-default main context][g-main-context-push-thread-default] of the + * thread that the monitor was created in. */ /** - * g_file_info_get_attribute_type: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_monitor_file: + * @file: input #GFile + * @flags: a set of #GFileMonitorFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Gets the attribute type for an attribute key. + * Obtains a file monitor for the given file. If no file notification + * mechanism exists, then regular polling of the file is used. * - * Returns: a #GFileAttributeType for the given @attribute, or - * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. + * 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 @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor + * will also attempt to report changes made to the file via another + * filename (ie, a hard link). Without this flag, you can only rely on + * changes made through the filename contained in @file to be + * reported. Using this flag may result in an increase in resource + * usage, and may not have any effect depending on the #GFileMonitor + * backend and/or filesystem type. + * + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_get_attribute_uint32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_file_monitor_is_cancelled: + * @monitor: a #GFileMonitor * - * 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 whether the monitor is canceled. * - * Returns: an unsigned 32-bit integer from the attribute. + * Returns: %TRUE if monitor is canceled. %FALSE otherwise. */ /** - * g_file_info_get_attribute_uint64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * 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. + * 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 unsigned 64-bit integer from the attribute. + * Sets the rate limit to which the @monitor will report + * consecutive change events to the same file. */ /** - * g_file_info_get_content_type: - * @info: a #GFileInfo. + * g_file_mount_enclosing_volume: + * @location: input #GFile + * @flags: flags affecting the operation + * @mount_operation: (nullable): a #GMountOperation + * or %NULL to avoid user interaction + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL + * @user_data: the data to pass to callback function * - * Gets the file's content type. + * Starts a @mount_operation, mounting the volume that contains + * the file @location. * - * Returns: a string containing the file's content type. + * 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_info_get_deletion_date: - * @info: a #GFileInfo. + * g_file_mount_enclosing_volume_finish: + * @location: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * 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. + * Finishes a mount operation started by g_file_mount_enclosing_volume(). * - * Returns: a #GDateTime, or %NULL. - * Since: 2.36 + * Returns: %TRUE if successful. If an error has occurred, + * this function will return %FALSE and set @error + * appropriately if present. */ /** - * g_file_info_get_display_name: - * @info: a #GFileInfo. + * g_file_mount_mountable: + * @file: input #GFile + * @flags: flags affecting the operation + * @mount_operation: (nullable): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL + * @user_data: (closure): the data to pass to callback function * - * Gets a display name for a file. + * Mounts a file of type G_FILE_TYPE_MOUNTABLE. + * Using @mount_operation, you can request callbacks when, for instance, + * passwords are needed during authentication. * - * Returns: a string containing the display 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. + * + * 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_info_get_edit_name: - * @info: a #GFileInfo. + * g_file_mount_mountable_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * Gets the edit name for a file. + * Finishes a mount operation. See g_file_mount_mountable() for details. * - * Returns: a string containing the edit name. + * 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_info_get_etag: - * @info: a #GFileInfo. + * g_file_move: + * @source: #GFile pointing to the source location + * @destination: #GFile pointing to the destination location + * @flags: set of #GFileCopyFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (nullable) (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 * - * Gets the [entity tag][gfile-etag] for a given - * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. + * 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. * - * Returns: a string containing the value of the "etag:value" attribute. + * 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. + * + * If the source is a directory and the target does not exist, or + * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then + * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native + * move operation isn't available). + * + * Returns: %TRUE on successful move, %FALSE otherwise. */ /** - * g_file_info_get_file_type: - * @info: a #GFileInfo. + * g_file_new_build_filename: + * @first_element: (type filename): the first element in the path + * @...: remaining elements in path, terminated by %NULL * - * 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(). + * Constructs a #GFile from a series of elements using the correct + * separator for filenames. * - * Returns: a #GFileType for the given file. + * Using this function is equivalent to calling g_build_filename(), + * followed by g_file_new_for_path() on the result. + * + * Returns: (transfer full): a new #GFile + * Since: 2.56 */ /** - * g_file_info_get_icon: - * @info: a #GFileInfo. + * g_file_new_for_commandline_arg: + * @arg: (type filename): a command line string * - * Gets the icon for a file. + * 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. * - * Returns: (transfer none): #GIcon for the given @info. + * Note that on Windows, this function expects its argument to be in + * UTF-8 -- not the system code page. This means that you + * should not use this function with string from argv as it is passed + * to main(). g_win32_get_command_line() will return a UTF-8 version of + * the commandline. #GApplication also uses UTF-8 but + * g_application_command_line_create_file_for_arg() may be more useful + * for you there. It is also always possible to use this function with + * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. + * + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_get_is_backup: - * @info: a #GFileInfo. + * g_file_new_for_commandline_arg_and_cwd: + * @arg: (type filename): a command line string + * @cwd: (type filename): the current working directory of the commandline * - * Checks if a file is a backup file. + * Creates a #GFile with the given argument from the command line. * - * Returns: %TRUE if file is a backup file, %FALSE otherwise. + * This function is similar to g_file_new_for_commandline_arg() except + * that it allows for passing the current working directory as an + * argument instead of using the current working directory of the + * process. + * + * This is useful if the commandline argument was given in a context + * other than the invocation of the current process. + * + * See also g_application_command_line_create_file_for_arg(). + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 */ /** - * g_file_info_get_is_hidden: - * @info: a #GFileInfo. + * g_file_new_for_path: + * @path: (type filename): a string containing a relative or absolute path. + * The string must be encoded in the glib filename encoding. * - * Checks if a file is hidden. + * 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 file is a hidden file, %FALSE otherwise. + * Returns: (transfer full): a new #GFile for the given @path. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_get_is_symlink: - * @info: a #GFileInfo. + * g_file_new_for_uri: + * @uri: a UTF-8 string containing a URI * - * Checks if a file is a symlink. + * 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: %TRUE if the given @info is a symlink. + * Returns: (transfer full): a new #GFile for the given @uri. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_get_modification_time: - * @info: a #GFileInfo. - * @result: (out caller-allocates): a #GTimeVal. + * g_file_new_tmp: + * @tmpl: (type filename) (nullable): 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 * - * Gets the modification time of the current @info and sets it - * in @result. + * 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. + * + * @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. + * + * Unlike the other #GFile constructors, this will return %NULL if + * a temporary file could not be created. + * + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). + * Since: 2.32 */ /** - * g_file_info_get_name: - * @info: a #GFileInfo. + * g_file_open_readwrite: + * @file: #GFile to open + * @cancellable: (nullable): a #GCancellable + * @error: a #GError, or %NULL * - * Gets the name for a file. + * 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. * - * Returns: (type filename): a string containing the file 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 a directory, the %G_IO_ERROR_IS_DIRECTORY + * error will be returned. Other errors are possible too, and depend on + * what kind of filesystem the file is on. Note that in many non-local + * file cases read and write streams are not supported, so make sure you + * really need to do read and write streaming, rather than just opening + * for reading or writing. + * + * Returns: (transfer full): #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_file_info_get_size: - * @info: a #GFileInfo. + * g_file_open_readwrite_async: + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 file's size. + * Asynchronously opens @file for reading and writing. * - * Returns: a #goffset containing the file's size. + * For more details, see g_file_open_readwrite() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_open_readwrite_finish() to get + * the result of the operation. + * + * Since: 2.22 */ /** - * g_file_info_get_sort_order: - * @info: a #GFileInfo. + * g_file_open_readwrite_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Gets the value of the sort_order attribute from the #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. + * Finishes an asynchronous file read operation started with + * g_file_open_readwrite_async(). * - * Returns: a #gint32 containing the value of the "standard::sort_order" attribute. + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_file_info_get_symbolic_icon: - * @info: a #GFileInfo. + * g_file_output_stream_get_etag: + * @stream: a #GFileOutputStream. * - * Gets the symbolic icon for a file. + * 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: (transfer none): #GIcon for the given @info. - * Since: 2.34 + * Returns: the entity tag for the stream. */ /** - * g_file_info_get_symlink_target: - * @info: a #GFileInfo. + * 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. * - * Gets the symlink target for a given #GFileInfo. + * 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. + * + * 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: a string containing the symlink target. + * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. */ /** - * g_file_info_has_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * 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 * - * Checks if a file info structure has an attribute named @attribute. + * 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(). * - * Returns: %TRUE if @Ginfo has an attribute named @attribute, - * %FALSE otherwise. + * For the synchronous version of this function, see + * g_file_output_stream_query_info(). */ /** - * g_file_info_has_namespace: - * @info: a #GFileInfo. - * @name_space: a file attribute namespace. + * g_file_output_stream_query_info_finish: + * @stream: a #GFileOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError, %NULL to ignore. * - * Checks if a file info structure has an attribute in the - * specified @name_space. + * Finalizes the asynchronous query started + * by g_file_output_stream_query_info_async(). * - * Returns: %TRUE if @Ginfo has an attribute in @name_space, - * %FALSE otherwise. - * Since: 2.22 + * Returns: (transfer full): A #GFileInfo for the finished query. */ /** - * g_file_info_list_attributes: - * @info: a #GFileInfo. - * @name_space: (nullable): a file attribute key's namespace, or %NULL to list - * all attributes. + * g_file_parse_name: + * @parse_name: a file name or path to be parsed * - * Lists the file info structure's attributes. + * 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: (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. + * Returns: (transfer full): a new #GFile. */ /** - * g_file_info_new: + * g_file_poll_mountable: + * @file: input #GFile + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL + * @user_data: the data to pass to callback function * - * Creates a new file info structure. + * Polls a file of type #G_FILE_TYPE_MOUNTABLE. * - * Returns: a #GFileInfo. - */ - - -/** - * g_file_info_remove_attribute: - * @info: a #GFileInfo. - * @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. * - * Removes all cases of @attribute from @info if it exists. - */ - - -/** - * g_file_info_set_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @type: a #GFileAttributeType - * @value_p: (not nullable): pointer to the value + * 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. * - * Sets the @attribute to contain the given value, if possible. To unset the - * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type. + * Since: 2.22 */ /** - * g_file_info_set_attribute_boolean: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a boolean value. + * g_file_poll_mountable_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_byte_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a byte string. + * Finishes a poll operation. See g_file_poll_mountable() for details. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Finish an asynchronous poll operation that was polled + * with g_file_poll_mountable(). + * + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. + * 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_file_query_default_handler: + * @file: a #GFile to open + * @cancellable: optional #GCancellable object, %NULL to ignore + * @error: a #GError, or %NULL * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * 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. + * + * 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_info_set_attribute_int64: - * @info: a #GFileInfo. - * @attribute: attribute name to set. - * @attr_value: int64 value to set attribute to. + * g_file_query_exists: + * @file: input #GFile + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * 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. + * + * As an example of race-free checking, take the case of reading a file, + * and if it doesn't exist, creating it. There are two racy versions: read + * it, and on error create it; and: check if it exists, if not create it. + * These can both result in two processes creating the file (with perhaps + * a partially written file as the result). The correct approach is to + * always try to create the file with g_file_create() which will either + * atomically create the file or fail with a %G_IO_ERROR_EXISTS error. + * + * However, in many cases an existence check is useful in a user interface, + * for instance to make a menu item sensitive/insensitive, so that you don't + * have to fool users that something is possible and then just show an error + * dialog. If you do this, you should make sure to also handle the errors + * that can happen due to races when you execute the operation. + * + * Returns: %TRUE if the file exists (and can be detected without error), + * %FALSE otherwise (or if cancelled). */ /** - * g_file_info_set_attribute_mask: - * @info: a #GFileInfo. - * @mask: a #GFileAttributeMatcher. + * g_file_query_file_type: + * @file: input #GFile + * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info() + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore * - * Sets @mask on @info to match specific attribute types. + * 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. + * + * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN + * if the file does not exist + * Since: 2.18 */ /** - * g_file_info_set_attribute_object: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a #GObject. + * g_file_query_filesystem_info: + * @file: input #GFile + * @attributes: an attribute query string + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * 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 attributes + * that should be gathered. It is not an error if it's not possible + * to read a particular requested attribute from a file - it just + * won't be set. @attributes should be a comma-separated list of + * attributes or attribute wildcards. The wildcard "*" means all + * attributes, and a wildcard like "filesystem::*" means all attributes + * in the filesystem namespace. The standard namespace for filesystem + * attributes is "filesystem". Common attributes of interest are + * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem + * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), + * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). + * + * If @cancellable is not %NULL, then the operation can be cancelled + * by triggering the cancellable object from another thread. If the + * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be + * returned. + * + * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will + * be returned. Other errors are possible too, and depend on what + * kind of filesystem the file is on. + * + * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_set_attribute_status: - * @info: a #GFileInfo - * @attribute: a file attribute key - * @status: a #GFileAttributeStatus + * 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: (nullable): 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 attribute status for an attribute key. This is only - * needed by external code that implement g_file_set_attributes_from_info() - * or similar functions. + * 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). * - * The attribute must exist in @info for this to work. Otherwise %FALSE - * is returned and @info is unchanged. + * For more details, see g_file_query_filesystem_info() which is the + * synchronous version of this call. * - * Returns: %TRUE if the status was changed, %FALSE if the key was not set. - * 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_info_set_attribute_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a UTF-8 string. + * g_file_query_filesystem_info_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Finishes an asynchronous filesystem info query. + * See g_file_query_filesystem_info_async(). + * + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * 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. + * g_file_query_info: + * @file: input #GFile + * @attributes: an attribute query string + * @flags: a set of #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * 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). * - * Sinze: 2.22 + * The @attributes value is a string that specifies the file + * attributes that should be gathered. It is not an error if + * it's not possible to read a particular requested attribute + * from a file - it just won't be set. @attributes should be a + * comma-separated list of attributes or attribute wildcards. + * The wildcard "*" means all attributes, and a wildcard like + * "standard::*" means all attributes in the standard namespace. + * An example attribute query be "standard::*,owner::user". + * The standard attributes are available as defines, like + * #G_FILE_ATTRIBUTE_STANDARD_NAME. + * + * If @cancellable is not %NULL, then the operation can be cancelled + * by triggering the cancellable object from another thread. If the + * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be + * returned. + * + * For symlinks, normally the information about the target of the + * symlink is returned, rather than information about the symlink + * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS + * in @flags the information about the symlink itself will be returned. + * Also, for symlinks that point to non-existing files the information + * about the symlink itself will be returned. + * + * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be + * returned. Other errors are possible too, and depend on what kind of + * filesystem the file is on. + * + * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL + * on error. Free the returned object with g_object_unref(). */ /** - * g_file_info_set_attribute_uint32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: an unsigned 32-bit integer. + * 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: (nullable): 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 @attribute to contain the given @attr_value, - * if possible. + * Asynchronously gets the requested information about specified @file. + * The result is a #GFileInfo object that contains key-value attributes + * (such as type or size for the file). + * + * For more details, see g_file_query_info() which is the synchronous + * version of this call. + * + * 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_info_set_attribute_uint64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: an unsigned 64-bit integer. + * g_file_query_info_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * 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_info_set_content_type: - * @info: a #GFileInfo. - * @content_type: a content type. See [GContentType][gio-GContentType] + * g_file_query_settable_attributes: + * @file: input #GFile + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Sets the content type attribute for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. + * 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. + * + * Returns: a #GFileAttributeInfoList describing the settable attributes. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** - * g_file_info_set_display_name: - * @info: a #GFileInfo. - * @display_name: a string containing a display name. + * g_file_query_writable_namespaces: + * @file: input #GFile + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Sets the display name for the current #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. + * 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. + * + * Returns: a #GFileAttributeInfoList describing the writable namespaces. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** - * g_file_info_set_edit_name: - * @info: a #GFileInfo. - * @edit_name: a string containing an edit name. + * g_file_read: (virtual read_fn) + * @file: #GFile to read + * @cancellable: (nullable): a #GCancellable + * @error: a #GError, or %NULL * - * Sets the edit name for the current file. - * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. + * 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. + * + * Returns: (transfer full): #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_set_file_type: - * @info: a #GFileInfo. - * @type: a #GFileType. + * g_file_read_async: + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 file type in a #GFileInfo to @type. - * See %G_FILE_ATTRIBUTE_STANDARD_TYPE. + * Asynchronously opens @file for reading. + * + * For more details, see g_file_read() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_read_finish() to get the result + * of the operation. */ /** - * g_file_info_set_icon: - * @info: a #GFileInfo. - * @icon: a #GIcon. + * g_file_read_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Sets the icon for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_ICON. + * Finishes an asynchronous file read operation started with + * g_file_read_async(). + * + * Returns: (transfer full): a #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_set_is_hidden: - * @info: a #GFileInfo. - * @is_hidden: a #gboolean. + * g_file_replace: + * @file: input #GFile + * @etag: (nullable): 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: (nullable): 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 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. * - * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. - * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_info_set_is_symlink: - * @info: a #GFileInfo. - * @is_symlink: a #gboolean. + * g_file_replace_async: + * @file: input #GFile + * @etag: (nullable): 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: (nullable): 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 "is_symlink" attribute in a #GFileInfo according to @is_symlink. - * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. - */ - - -/** - * g_file_info_set_modification_time: - * @info: a #GFileInfo. - * @mtime: a #GTimeVal. + * Asynchronously overwrites the file, replacing the contents, + * possibly creating a backup copy of the file first. * - * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file - * info to the given time value. - */ - - -/** - * g_file_info_set_name: - * @info: a #GFileInfo. - * @name: (type filename): a string containing a name. + * For more details, see g_file_replace() which is + * the synchronous version of this call. * - * Sets the name attribute for the current #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_NAME. + * 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_info_set_size: - * @info: a #GFileInfo. - * @size: a #goffset containing the file's size. + * 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: (nullable): 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: (out) (optional): 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 * - * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info - * to the given size. - */ - - -/** - * g_file_info_set_sort_order: - * @info: a #GFileInfo. - * @sort_order: a sort order integer. + * Replaces the contents of @file with @contents of @length bytes. * - * Sets the sort order attribute in the file info structure. See - * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - */ - - -/** - * g_file_info_set_symbolic_icon: - * @info: a #GFileInfo. - * @icon: a #GIcon. + * If @etag is specified (not %NULL), any existing file must have that etag, + * or the error %G_IO_ERROR_WRONG_ETAG will be returned. * - * Sets the symbolic icon for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. + * If @make_backup is %TRUE, this function will attempt to make a backup + * of @file. Internally, it uses g_file_replace(), so will try to replace the + * file contents in the safest way possible. For example, atomic renames are + * used when replacing local files’ contents. * - * Since: 2.34 - */ - - -/** - * g_file_info_set_symlink_target: - * @info: a #GFileInfo. - * @symlink_target: a static string containing a path to a symlink target. + * 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. * - * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info - * to the given symlink target. - */ - - -/** - * g_file_info_unset_attribute_mask: - * @info: #GFileInfo. + * The returned @new_etag can be used to verify that the file hasn't + * changed the next time it is saved over. * - * Unsets a mask set by g_file_info_set_attribute_mask(), if one - * is set. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. */ /** - * g_file_input_stream_query_info: - * @stream: a #GFileInputStream. - * @attributes: a file attribute query string. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * 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: (nullable): 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 * - * 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. + * Starts an asynchronous replacement of @file with the given + * @contents of @length bytes. @etag will replace the document's + * current entity tag. * - * Returns: (transfer full): a #GFileInfo, or %NULL on error. + * 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(). + * + * 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 @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_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: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_file_replace_contents_bytes_async: + * @file: input #GFile + * @contents: a #GBytes + * @etag: (nullable): 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 * - * 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. + * 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. * - * For the synchronous version of this function, - * see g_file_input_stream_query_info(). + * 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(). * - * 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 + * Since: 2.40 */ /** - * 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_file_replace_contents_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @new_etag: (out) (optional): a location of a new [entity tag][gfile-etag] + * for the document. This should be freed with g_free() when it is no + * longer needed, or %NULL + * @error: a #GError, or %NULL * - * Finishes an asynchronous info query operation. + * 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: (transfer full): #GFileInfo. + * Returns: %TRUE on success, %FALSE on failure. */ /** - * g_file_io_stream_get_etag: - * @stream: a #GFileIOStream. + * g_file_replace_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * 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. + * Finishes an asynchronous file replace operation started with + * g_file_replace_async(). * - * Returns: the entity tag for the stream. - * Since: 2.22 + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_io_stream_query_info: - * @stream: a #GFileIOStream. - * @attributes: a file attribute query string. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_file_replace_readwrite: + * @file: a #GFile + * @etag: (nullable): 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: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: return location for a #GError, or %NULL * - * 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. + * 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. * - * 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. + * For details about the behaviour, see g_file_replace() which does the + * same thing but returns an output stream only. * - * 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. + * 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 @stream, 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_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: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied + * g_file_replace_readwrite_async: + * @file: input #GFile + * @etag: (nullable): 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: (nullable): 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 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(). + * Asynchronously overwrites the file in read-write mode, + * replacing the contents, possibly creating a backup copy + * of the file first. * - * For the synchronous version of this function, see - * g_file_io_stream_query_info(). + * For more details, see g_file_replace_readwrite() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_replace_readwrite_finish() to get + * the result of the operation. * * Since: 2.22 */ /** - * g_file_io_stream_query_info_finish: - * @stream: a #GFileIOStream. - * @result: a #GAsyncResult. - * @error: a #GError, %NULL to ignore. + * g_file_replace_readwrite_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Finalizes the asynchronous query started - * by g_file_io_stream_query_info_async(). + * Finishes an asynchronous file replace operation started with + * g_file_replace_readwrite_async(). * - * Returns: (transfer full): A #GFileInfo for the finished query. + * Returns: (transfer full): a #GFileIOStream, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ /** - * g_file_is_native: + * g_file_resolve_relative_path: * @file: input #GFile + * @relative_path: (type filename): a given relative path string * - * 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. + * Resolves a relative path for @file to an absolute path. * * This call does no blocking I/O. * - * Returns: %TRUE if @file is native - */ - - -/** - * g_file_load_bytes: - * @file: a #GFile - * @cancellable: (nullable): a #GCancellable or %NULL - * @etag_out: (out) (nullable) (optional): a location to place the current - * entity tag for the file, or %NULL if the entity tag is not needed - * @error: a location for a #GError or %NULL - * - * Loads the contents of @file and returns it as #GBytes. - * - * If @file is a resource:// based URI, the resulting bytes will reference the - * embedded resource instead of a copy. Otherwise, this is equivalent to calling - * g_file_load_contents() and g_bytes_new_take(). - * - * For resources, @etag_out will be set to %NULL. - * - * The data contained in the resulting #GBytes is always zero-terminated, but - * this is not included in the #GBytes length. The resulting #GBytes should be - * freed with g_bytes_unref() when no longer in use. - * - * Returns: (transfer full): a #GBytes or %NULL and @error is set - * Since: 2.56 + * 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_load_bytes_async: - * @file: a #GFile - * @cancellable: (nullable): 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 - * - * Asynchronously loads the contents of @file as #GBytes. + * g_file_set_attribute: + * @file: input #GFile + * @attribute: a string containing the attribute's name + * @type: The type of the attribute + * @value_p: (nullable): a pointer to the value (or the pointer + * itself if the type is a pointer type) + * @flags: a set of #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * If @file is a resource:// based URI, the resulting bytes will reference the - * embedded resource instead of a copy. Otherwise, this is equivalent to calling - * g_file_load_contents_async() and g_bytes_new_take(). + * Sets an attribute in the file with attribute name @attribute to @value. * - * @callback should call g_file_load_bytes_finish() to get the result of this - * asynchronous operation. + * Some attributes can be unset by setting @type to + * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. * - * See g_file_load_bytes() for more information. + * 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.56 + * Returns: %TRUE if the attribute was set, %FALSE otherwise. */ /** - * g_file_load_bytes_finish: - * @file: a #GFile - * @result: a #GAsyncResult provided to the callback - * @etag_out: (out) (nullable) (optional): a location to place the current - * entity tag for the file, or %NULL if the entity tag is not needed - * @error: a location for a #GError, or %NULL - * - * Completes an asynchronous request to g_file_load_bytes_async(). - * - * For resources, @etag_out will be set to %NULL. + * 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: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * The data contained in the resulting #GBytes is always zero-terminated, but - * this is not included in the #GBytes length. The resulting #GBytes should be - * freed with g_bytes_unref() when no longer in use. + * 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. * - * See g_file_load_bytes() for more information. + * 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 #GBytes or %NULL and @error is set - * Since: 2.56 + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ /** - * g_file_load_contents: + * g_file_set_attribute_int32: * @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) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @etag_out: (out) (optional): a location to place the current entity tag for the file, - * or %NULL if the entity tag is not needed + * @attribute: a string containing the attribute's name + * @value: a #gint32 containing the attribute's new value + * @flags: a #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore * @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. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 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. * - * Returns: %TRUE if the @file's contents were successfully loaded. - * %FALSE if there were errors. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ /** - * g_file_load_contents_async: + * g_file_set_attribute_int64: * @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. + * @attribute: a string containing the attribute's name + * @value: a #guint64 containing the attribute's new value + * @flags: a #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * 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. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 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. + * + * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. */ /** - * g_file_load_contents_finish: + * g_file_set_attribute_string: * @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) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @etag_out: (out) (optional): a location to place the current entity tag for the file, - * or %NULL if the entity tag is not needed + * @attribute: a string containing the attribute's name + * @value: a string containing the attribute's value + * @flags: #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * - * 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. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. + * If @attribute is of a different type, this operation will fail. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is - * present, it will be set appropriately. + * 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, %FALSE otherwise. */ /** - * g_file_load_partial_contents_async: (skip) + * g_file_set_attribute_uint32: * @file: input #GFile - * @cancellable: optional #GCancellable object, %NULL to ignore - * @read_more_callback: (scope call) (closure user_data): a - * #GFileReadMoreCallback to receive partial data - * and to specify whether further data should be read - * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call - * when the request is satisfied - * @user_data: the data to pass to the callback functions - * - * Reads the partial contents of a file. A #GFileReadMoreCallback should - * be used to stop reading from the file when appropriate, else this - * function will behave exactly as g_file_load_contents_async(). This - * operation can be finished by g_file_load_partial_contents_finish(). + * @attribute: a string containing the attribute's name + * @value: a #guint32 containing the attribute's new value + * @flags: a #GFileQueryInfoFlags + * @cancellable: (nullable): optional #GCancellable object, + * %NULL to ignore + * @error: a #GError, or %NULL * - * Users of this function should be aware that @user_data is passed to - * both the @read_more_callback and the @callback. + * 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_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) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @etag_out: (out) (optional): a location to place the current entity tag for the file, - * or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL - * - * Finishes an asynchronous partial load operation that was started - * 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. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is - * present, it will be set appropriately. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ /** - * g_file_make_directory: + * 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: (nullable): optional #GCancellable object, * %NULL to ignore * @error: a #GError, or %NULL * - * Creates a directory. Note that this will only create a child directory - * of the immediate parent directory of the path or URI given by the #GFile. - * To recursively create directories, see g_file_make_directory_with_parents(). - * 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. - * - * For a local #GFile the newly created directory will have the default - * (current) ownership and permissions of the current process. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 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. * - * Returns: %TRUE on successful creation, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ /** - * g_file_make_directory_async: (virtual make_directory_async) + * 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: (nullable): 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 + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): a #gpointer * - * Asynchronously creates a directory. + * Asynchronously sets the attributes of @file with @info. * - * Since: 2.38 + * For more details, see g_file_set_attributes_from_info(), + * which is the synchronous version of this call. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_set_attributes_finish() to get + * the result of the operation. */ /** - * g_file_make_directory_finish: (virtual make_directory_finish) + * g_file_set_attributes_finish: * @file: input #GFile * @result: a #GAsyncResult + * @info: (out) (transfer full): a #GFileInfo * @error: a #GError, or %NULL * - * Finishes an asynchronous directory creation, started with - * g_file_make_directory_async(). + * Finishes setting an attribute started in g_file_set_attributes_async(). * - * Returns: %TRUE on successful directory creation, %FALSE otherwise. - * Since: 2.38 + * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise. */ /** - * g_file_make_directory_with_parents: + * g_file_set_attributes_from_info: * @file: input #GFile + * @info: a #GFileInfo + * @flags: #GFileQueryInfoFlags * @cancellable: (nullable): optional #GCancellable object, * %NULL to ignore * @error: a #GError, or %NULL * - * Creates a directory and any parent directories that may not - * exist similar to 'mkdir -p'. If the file system does not support - * creating directories, this function will fail, setting @error to - * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, - * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike - * the similar g_mkdir_with_parents(). + * Tries to set all attributes in the #GFileInfo on the target + * values, not stopping on the first error. * - * For a local #GFile the newly created directories will have the default - * (current) ownership and permissions of the current process. + * If there is any error during this operation then @error will + * be set to the first error. Error on particular fields are flagged + * by setting the "status" field in the attribute value to + * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can + * also detect further errors. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if all directories have been successfully created, %FALSE - * otherwise. - * Since: 2.18 + * Returns: %FALSE if there was any error, %TRUE otherwise. */ /** - * g_file_make_symbolic_link: - * @file: a #GFile with the name of the symlink to create - * @symlink_value: (type filename): a string with the path for the target - * of the new symlink + * g_file_set_display_name: + * @file: input #GFile + * @display_name: a string * @cancellable: (nullable): optional #GCancellable object, * %NULL to ignore - * @error: a #GError + * @error: a #GError, or %NULL * - * Creates a symbolic link named @file which contains the string - * @symlink_value. + * Renames @file to the specified display name. + * + * The display name is converted from UTF-8 to the correct encoding + * for the target filesystem if possible and the @file is renamed to this. + * + * If you want to implement a rename operation in the user interface the + * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the + * initial value in the rename widget, and then the result after editing + * should be passed to g_file_set_display_name(). + * + * 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: %TRUE on the creation of a new symlink, %FALSE otherwise. + * 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_measure_disk_usage: - * @file: a #GFile - * @flags: #GFileMeasureFlags - * @cancellable: (nullable): optional #GCancellable - * @progress_callback: (nullable): a #GFileMeasureProgressCallback - * @progress_data: user_data for @progress_callback - * @disk_usage: (out) (optional): the number of bytes of disk space used - * @num_dirs: (out) (optional): the number of directories encountered - * @num_files: (out) (optional): the number of non-directories encountered - * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer - * - * Recursively measures the disk usage of @file. + * 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: (nullable): 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 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). + * Asynchronously sets the display name for a given #GFile. * - * 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. + * For more details, see g_file_set_display_name() which is + * the synchronous version of this call. * - * 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. + * When the operation is finished, @callback will be called. + * You can then call g_file_set_display_name_finish() to get + * the result of the operation. + */ + + +/** + * g_file_set_display_name_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * @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. + * Finishes setting a display name started with + * g_file_set_display_name_async(). * - * Returns: %TRUE if successful, with the out parameters set. - * %FALSE otherwise, with @error set. - * Since: 2.38 + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ /** - * g_file_measure_disk_usage_async: - * @file: a #GFile - * @flags: #GFileMeasureFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable - * @progress_callback: (nullable): a #GFileMeasureProgressCallback - * @progress_data: user_data for @progress_callback - * @callback: (nullable): a #GAsyncReadyCallback to call when complete + * g_file_start_mountable: + * @file: input #GFile + * @flags: flags affecting the operation + * @start_operation: (nullable): a #GMountOperation, or %NULL to avoid user interaction + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * - * Recursively measures the disk usage of @file. + * 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 is the asynchronous version of g_file_measure_disk_usage(). See - * there for more information. + * 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.38 + * 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_measure_disk_usage_finish: - * @file: a #GFile - * @result: the #GAsyncResult passed to your #GAsyncReadyCallback - * @disk_usage: (out) (optional): the number of bytes of disk space used - * @num_dirs: (out) (optional): the number of directories encountered - * @num_files: (out) (optional): the number of non-directories encountered - * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer + * g_file_start_mountable_finish: + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * Collects the results from an earlier call to - * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for - * more information. + * Finishes a start operation. See g_file_start_mountable() for details. * - * Returns: %TRUE if successful, with the out parameters set. - * %FALSE otherwise, with @error set. - * Since: 2.38 + * 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_monitor: + * g_file_stop_mountable: * @file: input #GFile - * @flags: a set of #GFileMonitorFlags + * @flags: flags affecting the operation + * @mount_operation: (nullable): a #GMountOperation, + * or %NULL to avoid user interaction. * @cancellable: (nullable): optional #GCancellable object, * %NULL to ignore - * @error: a #GError, or %NULL + * @callback: (nullable): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL + * @user_data: the data to pass to callback function * - * Obtains a file or directory monitor for the given file, - * depending on the type of the file. + * Stops a file of type #G_FILE_TYPE_MOUNTABLE. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFileMonitor for the given @file, - * or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.18 - */ - - -/** - * g_file_monitor_cancel: - * @monitor: a #GFileMonitor. - * - * Cancels a file monitor. + * 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. * - * Returns: always %TRUE + * Since: 2.22 */ /** - * g_file_monitor_directory: (virtual monitor_dir) + * g_file_stop_mountable_finish: * @file: input #GFile - * @flags: a set of #GFileMonitorFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore + * @result: a #GAsyncResult * @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. + * Finishes an stop operation, see g_file_stop_mountable() for details. * - * 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(). + * Finish an asynchronous stop operation that was started + * with g_file_stop_mountable(). * - * Returns: (transfer full): a #GFileMonitor for the given @file, - * or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. + * Since: 2.22 */ /** - * g_file_monitor_emit_event: - * @monitor: a #GFileMonitor. - * @child: a #GFile. - * @other_file: a #GFile. - * @event_type: a set of #GFileMonitorEvent flags. + * g_file_supports_thread_contexts: + * @file: a #GFile * - * Emits the #GFileMonitor::changed signal if a change - * has taken place. Should be called from file monitor - * implementations only. + * 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. * - * Implementations are responsible to call this method from the - * [thread-default main context][g-main-context-push-thread-default] of the - * thread that the monitor was created in. + * Returns: Whether or not @file supports thread-default contexts. + * Since: 2.22 */ /** - * g_file_monitor_file: - * @file: input #GFile - * @flags: a set of #GFileMonitorFlags + * g_file_trash: (virtual trash) + * @file: #GFile to send to trash * @cancellable: (nullable): optional #GCancellable object, * %NULL to ignore * @error: a #GError, or %NULL * - * Obtains a file monitor for the given file. If no file notification - * mechanism exists, then regular polling of the file is used. + * 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. * * 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 @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor - * will also attempt to report changes made to the file via another - * filename (ie, a hard link). Without this flag, you can only rely on - * changes made through the filename contained in @file to be - * reported. Using this flag may result in an increase in resource - * usage, and may not have any effect depending on the #GFileMonitor - * backend and/or filesystem type. - * - * Returns: (transfer full): a #GFileMonitor for the given @file, - * or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: %TRUE on successful trash, %FALSE otherwise. */ /** - * g_file_monitor_is_cancelled: - * @monitor: a #GFileMonitor + * g_file_trash_async: (virtual trash_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): 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 * - * Returns whether the monitor is canceled. + * Asynchronously sends @file to the Trash location, if possible. * - * Returns: %TRUE if monitor is canceled. %FALSE otherwise. + * Since: 2.38 */ /** - * 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_file_trash_finish: (virtual trash_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL * - * Sets the rate limit to which the @monitor will report - * consecutive change events to the same file. + * Finishes an asynchronous file trashing operation, started with + * g_file_trash_async(). + * + * Returns: %TRUE on successful trash, %FALSE otherwise. + * Since: 2.38 */ /** - * g_file_mount_enclosing_volume: - * @location: input #GFile + * g_file_unmount_mountable: + * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation - * or %NULL to avoid user interaction * @cancellable: (nullable): optional #GCancellable object, * %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call + * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call * when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function - * - * Starts a @mount_operation, mounting the volume that contains - * the file @location. + * @user_data: (closure): the data to pass to callback function * - * 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(). + * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * When the operation is finished, @callback will be called. + * You can then call g_file_unmount_mountable_finish() to get + * the result of the operation. + * + * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead. */ /** - * g_file_mount_enclosing_volume_finish: - * @location: input #GFile + * g_file_unmount_mountable_finish: + * @file: input #GFile * @result: a #GAsyncResult * @error: a #GError, or %NULL * - * Finishes a mount operation started by g_file_mount_enclosing_volume(). + * Finishes an unmount operation, see g_file_unmount_mountable() for details. * - * Returns: %TRUE if successful. If an error has occurred, - * this function will return %FALSE and set @error - * appropriately if present. + * 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_mount_mountable: + * g_file_unmount_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation * @mount_operation: (nullable): a #GMountOperation, @@ -23059,18427 +26504,18310 @@ * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * - * Mounts a file of type G_FILE_TYPE_MOUNTABLE. - * Using @mount_operation, you can request callbacks when, for instance, - * passwords are needed during authentication. + * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * When the operation is finished, @callback will be called. - * You can then call g_file_mount_mountable_finish() to get + * You can then call g_file_unmount_mountable_finish() to get * the result of the operation. + * + * Since: 2.22 */ /** - * g_file_mount_mountable_finish: + * g_file_unmount_mountable_with_operation_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(). - * - * Returns: (transfer full): a #GFile or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_move: - * @source: #GFile pointing to the source location - * @destination: #GFile pointing to the destination location - * @flags: set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @progress_callback: (nullable) (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. + * Finishes an unmount operation, + * see g_file_unmount_mountable_with_operation() for details. * - * 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). + * Finish an asynchronous unmount operation that was started + * with g_file_unmount_mountable_with_operation(). * - * Returns: %TRUE on successful move, %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. + * Since: 2.22 */ /** - * g_file_new_build_filename: - * @first_element: (type filename): the first element in the path - * @...: remaining elements in path, terminated by %NULL - * - * Constructs a #GFile from a series of elements using the correct - * separator for filenames. + * g_filename_completer_get_completion_suffix: + * @completer: the filename completer. + * @initial_text: text to be completed. * - * Using this function is equivalent to calling g_build_filename(), - * followed by g_file_new_for_path() on the result. + * Obtains a completion for @initial_text from @completer. * - * Returns: (transfer full): a new #GFile - * Since: 2.56 + * 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_new_for_commandline_arg: - * @arg: (type filename): 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_filename_completer_get_completions: + * @completer: the filename completer. + * @initial_text: text to be completed. * - * 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. + * Gets an array of completion strings for a given initial text. * - * Returns: (transfer full): a new #GFile. - * Free the returned object with g_object_unref(). + * 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_new_for_commandline_arg_and_cwd: - * @arg: (type filename): a command line string - * @cwd: (type filename): the current working directory of the commandline + * g_filename_completer_new: * - * Creates a #GFile with the given argument from the command line. + * Creates a new filename completer. * - * This function is similar to g_file_new_for_commandline_arg() except - * that it allows for passing the current working directory as an - * argument instead of using the current working directory of the - * process. + * Returns: a #GFilenameCompleter. + */ + + +/** + * g_filename_completer_set_dirs_only: + * @completer: the filename completer. + * @dirs_only: a #gboolean. * - * This is useful if the commandline argument was given in a context - * other than the invocation of the current process. + * If @dirs_only is %TRUE, @completer will only + * complete directory names, and not file names. + */ + + +/** + * g_filter_input_stream_get_base_stream: + * @stream: a #GFilterInputStream. * - * See also g_application_command_line_create_file_for_arg(). + * Gets the base stream for the filter stream. * - * Returns: (transfer full): a new #GFile - * Since: 2.36 + * Returns: (transfer none): a #GInputStream. */ /** - * g_file_new_for_path: - * @path: (type filename): a string containing a relative or absolute path. - * The string must be encoded in the glib filename encoding. + * g_filter_input_stream_get_close_base_stream: + * @stream: a #GFilterInputStream. * - * 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 whether the base stream will be closed when @stream is + * closed. * - * Returns: (transfer full): a new #GFile for the given @path. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if the base stream will be closed. */ /** - * g_file_new_for_uri: - * @uri: a UTF-8 string containing a URI - * - * Constructs a #GFile for a given URI. This operation never - * fails, but the returned object might not support any I/O - * operation if @uri is malformed or if the uri type is - * not supported. + * g_filter_input_stream_set_close_base_stream: + * @stream: a #GFilterInputStream. + * @close_base: %TRUE to close the base stream. * - * Returns: (transfer full): a new #GFile for the given @uri. - * Free the returned object with g_object_unref(). + * Sets whether the base stream will be closed when @stream is closed. */ /** - * g_file_new_tmp: - * @tmpl: (type filename) (nullable): 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 + * g_filter_output_stream_get_base_stream: + * @stream: a #GFilterOutputStream. * - * 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. + * Gets the base stream for the filter stream. * - * @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. + * Returns: (transfer none): a #GOutputStream. + */ + + +/** + * g_filter_output_stream_get_close_base_stream: + * @stream: a #GFilterOutputStream. * - * Unlike the other #GFile constructors, this will return %NULL if - * a temporary file could not be created. + * Returns whether the base stream will be closed when @stream is + * closed. * - * Returns: (transfer full): a new #GFile. - * Free the returned object with g_object_unref(). - * Since: 2.32 + * Returns: %TRUE if the base stream will be closed. */ /** - * g_file_open_readwrite: - * @file: #GFile to open - * @cancellable: (nullable): 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. + * g_filter_output_stream_set_close_base_stream: + * @stream: a #GFilterOutputStream. + * @close_base: %TRUE to close the base 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. + * Sets whether the base stream will be closed when @stream is closed. + */ + + +/** + * g_icon_deserialize: + * @value: a #GVariant created with g_icon_serialize() * - * 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. + * Deserializes a #GIcon previously serialized using g_icon_serialize(). * - * Returns: (transfer full): #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails. + * Since: 2.38 */ /** - * g_file_open_readwrite_async: - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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_icon_equal: + * @icon1: (nullable): pointer to the first #GIcon. + * @icon2: (nullable): pointer to the second #GIcon. * - * Asynchronously opens @file for reading and writing. + * Checks if two icons are equal. * - * For more details, see g_file_open_readwrite() which is - * the synchronous version of this call. + * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + */ + + +/** + * g_icon_hash: (virtual hash) + * @icon: (not nullable): #gconstpointer to an icon object. * - * 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. + * Gets a hash for an icon. * - * Since: 2.22 + * Returns: a #guint containing a hash for the @icon, suitable for + * use in a #GHashTable or similar data structure. */ /** - * g_file_open_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_icon_new_for_string: + * @str: A string obtained via g_icon_to_string(). + * @error: Return location for error. * - * Finishes an asynchronous file read operation started with - * g_file_open_readwrite_async(). + * Generate a #GIcon instance from @str. This function can fail if + * @str is not valid - see g_icon_to_string() for discussion. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * 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_output_stream_get_etag: - * @stream: a #GFileOutputStream. + * g_icon_serialize: + * @icon: a #GIcon * - * 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. + * 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: the entity tag for the stream. + * Returns: (transfer full): a #GVariant, or %NULL when serialization fails. + * Since: 2.38 */ /** - * 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. + * g_icon_to_string: (virtual to_tokens) + * @icon: a #GIcon. * - * 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. + * 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. * - * 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. + * The encoding of the returned string is proprietary to #GIcon except + * in the following two cases * - * 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. + * - 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`). * - * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. + * - 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_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 + * g_inet_address_equal: + * @address: A #GInetAddress. + * @other_address: Another #GInetAddress. * - * 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(). + * Checks if two #GInetAddress instances are equal, e.g. the same address. * - * For the synchronous version of this function, see - * g_file_output_stream_query_info(). + * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise. + * Since: 2.30 */ /** - * g_file_output_stream_query_info_finish: - * @stream: a #GFileOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError, %NULL to ignore. + * g_inet_address_get_family: + * @address: a #GInetAddress * - * Finalizes the asynchronous query started - * by g_file_output_stream_query_info_async(). + * Gets @address's family * - * Returns: (transfer full): A #GFileInfo for the finished query. + * Returns: @address's family + * Since: 2.22 */ /** - * g_file_parse_name: - * @parse_name: a file name or path to be parsed + * g_inet_address_get_is_any: + * @address: a #GInetAddress * - * 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. + * Tests whether @address is the "any" address for its family. * - * Returns: (transfer full): a new #GFile. + * Returns: %TRUE if @address is the "any" address for its family. + * Since: 2.22 */ /** - * g_file_peek_path: - * @file: input #GFile - * - * Exactly like g_file_get_path(), but caches the result via - * g_object_set_qdata_full(). This is useful for example in C - * applications which mix `g_file_*` APIs with native ones. It - * also avoids an extra duplicated string when possible, so will be - * generally more efficient. + * g_inet_address_get_is_link_local: + * @address: a #GInetAddress * - * This call does no blocking I/O. + * 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: (type filename) (nullable): string containing the #GFile's path, - * or %NULL if no such path exists. The returned string is owned by @file. - * Since: 2.56 + * Returns: %TRUE if @address is a link-local address. + * Since: 2.22 */ /** - * g_file_poll_mountable: - * @file: input #GFile - * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: (nullable): 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. - * - * 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_inet_address_get_is_loopback: + * @address: a #GInetAddress * - * 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. + * Tests whether @address is the loopback address for its family. * + * Returns: %TRUE if @address is the loopback address for its family. * Since: 2.22 */ /** - * g_file_poll_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes a poll operation. See g_file_poll_mountable() for details. + * g_inet_address_get_is_mc_global: + * @address: a #GInetAddress * - * Finish an asynchronous poll operation that was polled - * with g_file_poll_mountable(). + * Tests whether @address is a global multicast address. * - * Returns: %TRUE if the operation finished successfully. %FALSE - * otherwise. + * Returns: %TRUE if @address is a global multicast address. * Since: 2.22 */ /** - * g_file_query_default_handler: - * @file: a #GFile to open - * @cancellable: optional #GCancellable object, %NULL to ignore - * @error: a #GError, or %NULL - * - * Returns the #GAppInfo that is registered as the default - * application to handle the file specified by @file. + * g_inet_address_get_is_mc_link_local: + * @address: a #GInetAddress * - * 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. + * Tests whether @address is a link-local multicast address. * - * Returns: (transfer full): a #GAppInfo if the handle was found, - * %NULL if there were errors. - * When you are done with it, release it with g_object_unref() + * Returns: %TRUE if @address is a link-local multicast address. + * Since: 2.22 */ /** - * g_file_query_exists: - * @file: input #GFile - * @cancellable: (nullable): 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](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) - * 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. - * - * 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. + * g_inet_address_get_is_mc_node_local: + * @address: a #GInetAddress * - * 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. + * Tests whether @address is a node-local multicast address. * - * Returns: %TRUE if the file exists (and can be detected without error), - * %FALSE otherwise (or if cancelled). + * Returns: %TRUE if @address is a node-local multicast address. + * Since: 2.22 */ /** - * g_file_query_file_type: - * @file: input #GFile - * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info() - * @cancellable: (nullable): 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. + * g_inet_address_get_is_mc_org_local: + * @address: a #GInetAddress * - * The primary use case of this method is to check if a file is - * a regular file, directory, or symlink. + * Tests whether @address is an organization-local multicast address. * - * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN - * if the file does not exist - * Since: 2.18 + * Returns: %TRUE if @address is an organization-local multicast address. + * Since: 2.22 */ /** - * g_file_query_filesystem_info: - * @file: input #GFile - * @attributes: an attribute query string - * @cancellable: (nullable): 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 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_inet_address_get_is_mc_site_local: + * @address: a #GInetAddress * - * 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. + * Tests whether @address is a site-local multicast address. * - * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if @address is a site-local multicast address. + * Since: 2.22 */ /** - * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call - * when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously gets the requested information about the filesystem - * 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). + * g_inet_address_get_is_multicast: + * @address: a #GInetAddress * - * For more details, see g_file_query_filesystem_info() which is the - * synchronous version of this call. + * Tests whether @address is a multicast address. * - * 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. + * Returns: %TRUE if @address is a multicast address. + * Since: 2.22 */ /** - * g_file_query_filesystem_info_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError + * g_inet_address_get_is_site_local: + * @address: a #GInetAddress * - * Finishes an asynchronous filesystem info query. - * See g_file_query_filesystem_info_async(). + * 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: (transfer full): #GFileInfo for given @file - * or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if @address is a site-local address. + * Since: 2.22 */ /** - * g_file_query_info: - * @file: input #GFile - * @attributes: an attribute query string - * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError - * - * Gets the requested information about specified @file. - * The result is a #GFileInfo object that contains key-value - * attributes (such as the type or size of the file). - * - * The @attributes value is a string that specifies the file - * attributes that should be gathered. It is not an error if - * it's not possible to read a particular requested attribute - * from a file - it just won't be set. @attributes should be a - * comma-separated list of attributes or attribute wildcards. - * The wildcard "*" means all attributes, and a wildcard like - * "standard::*" means all attributes in the standard namespace. - * An example attribute query be "standard::*,owner::user". - * The standard attributes are available as defines, like - * #G_FILE_ATTRIBUTE_STANDARD_NAME. - * - * 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_inet_address_get_native_size: + * @address: a #GInetAddress * - * 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. + * 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(). * - * 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: the number of bytes used for the native version of @address. + * Since: 2.22 + */ + + +/** + * g_inet_address_mask_equal: + * @mask: a #GInetAddressMask + * @mask2: another #GInetAddressMask * - * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL - * on error. Free the returned object with g_object_unref(). + * Tests if @mask and @mask2 are the same mask. + * + * Returns: whether @mask and @mask2 are the same mask + * Since: 2.32 */ /** - * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the - * request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously gets the requested information about specified @file. - * The result is a #GFileInfo object that contains key-value attributes - * (such as type or size for the file). + * g_inet_address_mask_get_address: + * @mask: a #GInetAddressMask * - * For more details, see g_file_query_info() which is the synchronous - * version of this call. + * Gets @mask's base address * - * 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. + * Returns: (transfer none): @mask's base address + * Since: 2.32 */ /** - * g_file_query_info_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError + * g_inet_address_mask_get_family: + * @mask: a #GInetAddressMask * - * Finishes an asynchronous file info query. - * See g_file_query_info_async(). + * Gets the #GSocketFamily of @mask's address * - * Returns: (transfer full): #GFileInfo for given @file - * or %NULL on error. Free the returned object with - * g_object_unref(). + * Returns: the #GSocketFamily of @mask's address + * Since: 2.32 */ /** - * g_file_query_settable_attributes: - * @file: input #GFile - * @cancellable: (nullable): 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. + * g_inet_address_mask_get_length: + * @mask: a #GInetAddressMask * - * 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 @mask's length * - * Returns: a #GFileAttributeInfoList describing the settable attributes. - * When you are done with it, release it with - * g_file_attribute_info_list_unref() + * Returns: @mask's length + * Since: 2.32 */ /** - * g_file_query_writable_namespaces: - * @file: input #GFile - * @cancellable: (nullable): 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). + * g_inet_address_mask_matches: + * @mask: a #GInetAddressMask + * @address: a #GInetAddress * - * 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. + * Tests if @address falls within the range described by @mask. * - * Returns: a #GFileAttributeInfoList describing the writable namespaces. - * When you are done with it, release it with - * g_file_attribute_info_list_unref() + * Returns: whether @address falls within the range described by + * @mask. + * Since: 2.32 */ /** - * g_file_read: (virtual read_fn) - * @file: #GFile to read - * @cancellable: (nullable): a #GCancellable - * @error: a #GError, or %NULL + * g_inet_address_mask_new: + * @addr: a #GInetAddress + * @length: number of bits of @addr to use + * @error: return location for #GError, or %NULL * - * Opens a file for reading. The result is a #GFileInputStream that - * can be used to read the contents of the file. + * Creates a new #GInetAddressMask representing all addresses whose + * first @length bits match @addr. * - * 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 new #GInetAddressMask, or %NULL on error + * 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 * - * 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. + * 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: (transfer full): #GFileInputStream or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: a new #GInetAddressMask corresponding to @string, or %NULL + * on error. + * Since: 2.32 */ /** - * g_file_read_async: - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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_inet_address_mask_to_string: + * @mask: a #GInetAddressMask * - * For more details, see g_file_read() which is - * the synchronous version of this call. + * Converts @mask back to its corresponding string form. * - * 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: a string corresponding to @mask. + * Since: 2.32 */ /** - * g_file_read_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_inet_address_new_any: + * @family: the address family * - * Finishes an asynchronous file read operation started with - * g_file_read_async(). + * Creates a #GInetAddress for the "any" address (unassigned/"don't + * care") for @family. * - * Returns: (transfer full): a #GFileInputStream or %NULL on error. + * Returns: a new #GInetAddress corresponding to the "any" address + * for @family. * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_file_replace: - * @file: input #GFile - * @etag: (nullable): 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: (nullable): 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 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. + * g_inet_address_new_from_bytes: + * @bytes: (array) (element-type guint8): raw address data + * @family: the address family of @bytes * - * 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. + * 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: (transfer full): a #GFileOutputStream or %NULL on error. + * Returns: a new #GInetAddress corresponding to @family and @bytes. * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_file_replace_async: - * @file: input #GFile - * @etag: (nullable): 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: (nullable): 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_inet_address_new_from_string: + * @string: a string representation of an IP address * - * For more details, see g_file_replace() which is - * the synchronous version of this call. + * Parses @string as an IP address and creates a new #GInetAddress. * - * 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: a new #GInetAddress corresponding to @string, or %NULL if + * @string could not be parsed. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * 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: (nullable): 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: (out) (optional): a location to a new [entity tag][gfile-etag] - * for the document. This should be freed with g_free() when no longer - * needed, or %NULL - * @cancellable: optional #GCancellable object, %NULL to ignore - * @error: a #GError, or %NULL - * - * Replaces the contents of @file with @contents of @length bytes. - * - * If @etag is specified (not %NULL), any existing file must have that etag, - * or the error %G_IO_ERROR_WRONG_ETAG will be returned. - * - * If @make_backup is %TRUE, this function will attempt to make a backup - * of @file. Internally, it uses g_file_replace(), so will try to replace the - * file contents in the safest way possible. For example, atomic renames are - * used when replacing local files’ contents. - * - * 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_inet_address_new_loopback: + * @family: the address family * - * The returned @new_etag can be used to verify that the file hasn't - * changed the next time it is saved over. + * Creates a #GInetAddress for the loopback address for @family. * - * Returns: %TRUE if successful. If an error has occurred, this function - * will return %FALSE and set @error appropriately if present. + * Returns: a new #GInetAddress corresponding to the loopback address + * for @family. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * 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: (nullable): 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 - * - * Starts an asynchronous replacement of @file with the given - * @contents of @length bytes. @etag will replace the document's - * current entity tag. - * - * 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(). - * - * 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_inet_address_to_bytes: (skip) + * @address: a #GInetAddress * - * If @make_backup is %TRUE, this function will attempt to - * make a backup of @file. + * Gets the raw binary address data from @address. * - * 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. + * 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_replace_contents_bytes_async: - * @file: input #GFile - * @contents: a #GBytes - * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to callback function - * - * Same as g_file_replace_contents_async() but takes a #GBytes input instead. - * This function will keep a ref on @contents until the operation is done. - * Unlike g_file_replace_contents_async() this allows forgetting about the - * content without waiting for the callback. + * g_inet_address_to_string: + * @address: a #GInetAddress * - * 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(). + * Converts @address to string form. * - * Since: 2.40 + * Returns: a representation of @address as a string, which should be + * freed after use. + * Since: 2.22 */ /** - * g_file_replace_contents_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @new_etag: (out) (optional): 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 + * g_inet_socket_address_get_address: + * @address: a #GInetSocketAddress * - * 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. + * Gets @address's #GInetAddress. * - * Returns: %TRUE on success, %FALSE on failure. + * Returns: (transfer none): the #GInetAddress for @address, which must be + * g_object_ref()'d if it will be stored + * Since: 2.22 */ /** - * g_file_replace_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_inet_socket_address_get_flowinfo: + * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress * - * Finishes an asynchronous file replace operation started with - * g_file_replace_async(). + * Gets the `sin6_flowinfo` field from @address, + * which must be an IPv6 address. * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: the flowinfo field + * Since: 2.32 */ /** - * g_file_replace_readwrite: - * @file: a #GFile - * @etag: (nullable): 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: (nullable): 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_inet_socket_address_get_port: + * @address: a #GInetSocketAddress * - * 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 @address's port. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: the port for @address * Since: 2.22 */ /** - * g_file_replace_readwrite_async: - * @file: input #GFile - * @etag: (nullable): 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: (nullable): 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. - * - * For more details, see g_file_replace_readwrite() which is - * the synchronous version of this call. + * g_inet_socket_address_get_scope_id: + * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress * - * 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. + * Gets the `sin6_scope_id` field from @address, + * which must be an IPv6 address. * - * Since: 2.22 + * Returns: the scope id field + * Since: 2.32 */ /** - * g_file_replace_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_inet_socket_address_new: + * @address: a #GInetAddress + * @port: a port number * - * Finishes an asynchronous file replace operation started with - * g_file_replace_readwrite_async(). + * Creates a new #GInetSocketAddress for @address and @port. * - * Returns: (transfer full): a #GFileIOStream, or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: a new #GInetSocketAddress * Since: 2.22 */ /** - * g_file_resolve_relative_path: - * @file: input #GFile - * @relative_path: (type filename): a given relative path string + * g_inet_socket_address_new_from_string: + * @address: the string form of an IP address + * @port: a port number * - * Resolves a relative path for @file to an absolute path. + * Creates a new #GInetSocketAddress for @address and @port. * - * This call does no blocking I/O. + * If @address is an IPv6 address, it can also contain a scope ID + * (separated from the address by a `%`). * - * Returns: (transfer full): #GFile to the resolved path. - * %NULL if @relative_path is %NULL or if @file is invalid. - * Free the returned object with g_object_unref(). + * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be + * parsed. + * Since: 2.40 */ /** - * g_file_set_attribute: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @type: The type of the attribute - * @value_p: (nullable): a pointer to the value (or the pointer - * itself if the type is a pointer type) - * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL + * 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. * - * Sets an attribute in the file with attribute name @attribute to @value. + * Initializes the object implementing the interface. * - * Some attributes can be unset by setting @type to - * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. + * This method is intended for language bindings. If writing in C, + * g_initable_new() should typically be used instead. * - * 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 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. + * + * Callers should not assume that a class which implements #GInitable can be + * initialized multiple times, unless the class explicitly documents itself as + * supporting this. Generally, a class’ implementation of init() can assume + * (and assert) that it will only be called once. Previously, this documentation + * recommended all #GInitable implementations should be idempotent; that + * recommendation was relaxed in GLib 2.54. + * + * If a class explicitly supports being initialized multiple times, it is + * recommended that the method is idempotent: multiple calls with the same + * arguments should return the same results. Only the first call initializes + * the object; further calls return the result of the first call. + * + * One reason why a class might need to support idempotent initialization is if + * it is designed to be used via the singleton pattern, with a + * #GObjectClass.constructor that sometimes returns an existing instance. + * In this pattern, a caller would expect to be able to call g_initable_init() + * on the result of g_object_new(), regardless of whether it is in fact a new + * instance. * - * Returns: %TRUE if the attribute was set, %FALSE otherwise. + * 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_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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * 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. + * 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: (nullable): 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. * - * 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. + * 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: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error + * Since: 2.22 */ /** - * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. - * If @attribute is of a different type, this operation will fail. + * 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. * - * 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. + * Helper function for constructing #GInitable object. This is + * similar to g_object_new_valist() but also initializes the object + * and returns %NULL, setting an error on failure. * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error + * Since: 2.22 */ /** - * 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: (nullable): 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_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. * - * 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. + * 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: %TRUE if the @attribute was successfully set, %FALSE otherwise. + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error + * Since: 2.22 + * Deprecated: 2.54: Use g_object_new_with_properties() and + * g_initable_init() instead. See #GParameter for more information. */ /** - * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING 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_input_stream_clear_pending: + * @stream: input stream * - * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. + * Clears the pending flag on @stream. */ /** - * 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: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL + * g_input_stream_close: + * @stream: A #GInputStream. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. - * If @attribute is of a different type, this operation will fail. + * Closes the stream, releasing resources related to 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. + * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. + * Closing a stream multiple times will not return an error. * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_uint64: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a #guint64 containing the attribute's new value - * @flags: a #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL + * 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. * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. - * If @attribute is of a different type, this operation will fail. + * 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 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: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. + * Returns: %TRUE on success, %FALSE on failure */ /** - * g_file_set_attributes_async: - * @file: input #GFile - * @info: a #GFileInfo - * @flags: a #GFileQueryInfoFlags + * g_input_stream_close_async: + * @stream: A #GInputStream. * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): a #gpointer + * @cancellable: (nullable): 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 sets the attributes of @file with @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. * - * For more details, see g_file_set_attributes_from_info(), - * which is the synchronous version of this call. + * For behaviour details see g_input_stream_close(). * - * 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. + * 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_set_attributes_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @info: (out) (transfer full): a #GFileInfo - * @error: a #GError, or %NULL + * g_input_stream_close_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @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 closing a stream asynchronously, started from g_input_stream_close_async(). * - * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise. + * Returns: %TRUE if the stream was closed successfully. */ /** - * g_file_set_attributes_from_info: - * @file: input #GFile - * @info: a #GFileInfo - * @flags: #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL + * g_input_stream_has_pending: + * @stream: input stream. * - * Tries to set all attributes in the #GFileInfo on the target - * values, not stopping on the first error. + * Checks if an input stream has pending actions. * - * 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: %TRUE if @stream has pending actions. + */ + + +/** + * g_input_stream_is_closed: + * @stream: 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. + * Checks if an input stream is closed. * - * Returns: %FALSE if there was any error, %TRUE otherwise. + * Returns: %TRUE if the stream is closed. */ /** - * g_file_set_display_name: - * @file: input #GFile - * @display_name: a string - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Renames @file to the specified display name. + * Tries to read @count bytes from the stream into the buffer starting at + * @buffer. Will block during this read. * - * The display name is converted from UTF-8 to the correct encoding - * for the target filesystem if possible and the @file is renamed to this. + * If 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. * - * If you want to implement a rename operation in the user interface the - * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the - * initial value in the rename widget, and then the result after editing - * should be passed to g_file_set_display_name(). + * On success, the 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. * - * On success the resulting converted filename is returned. + * 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. * - * 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(). + * 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_set_display_name_async: - * @file: input #GFile - * @display_name: a string - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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_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: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Asynchronously sets the display name for a given #GFile. + * 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_set_display_name() which is - * the synchronous version of this call. + * 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. * - * When the operation is finished, @callback will be called. - * You can then call g_file_set_display_name_finish() to get - * the result of the operation. - */ - - -/** - * g_file_set_display_name_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * 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. * - * Finishes setting a display name started with - * g_file_set_display_name_async(). + * If there is an error during the operation %FALSE is returned and @error + * is set to indicate the error status. * - * Returns: (transfer full): a #GFile or %NULL on error. - * Free the returned object with g_object_unref(). + * As a special exception to the normal conventions for functions that + * use #GError, if this function returns %FALSE (and sets @error) then + * @bytes_read will be set to the number of bytes that were successfully + * read before the error was encountered. This functionality is only + * available from C. If you need it from another language then you must + * write your own loop around g_input_stream_read(). + * + * Returns: %TRUE on success, %FALSE if there was an error */ /** - * g_file_start_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @start_operation: (nullable): a #GMountOperation, or %NULL to avoid user interaction + * 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: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Starts a file of type #G_FILE_TYPE_MOUNTABLE. - * Using @start_operation, you can request callbacks when, for instance, - * passwords are needed during authentication. + * Request an asynchronous read of @count bytes from the stream into the + * buffer starting at @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. + * This is the asynchronous equivalent of g_input_stream_read_all(). * - * 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. + * Call g_input_stream_read_all_finish() to collect the result. * - * Since: 2.22 + * 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_start_mountable_finish: - * @file: input #GFile + * g_input_stream_read_all_finish: + * @stream: a #GInputStream * @result: a #GAsyncResult - * @error: a #GError, or %NULL + * @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 a start operation. See g_file_start_mountable() for details. + * Finishes an asynchronous stream read operation started with + * g_input_stream_read_all_async(). * - * Finish an asynchronous start operation that was started - * with g_file_start_mountable(). + * 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 operation finished successfully. %FALSE - * otherwise. - * Since: 2.22 + * Returns: %TRUE on success, %FALSE if there was an error + * Since: 2.44 */ /** - * g_file_stop_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction. - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function + * 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: (nullable): 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 * - * Stops a file of type #G_FILE_TYPE_MOUNTABLE. + * 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. * - * 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. * - * 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. + * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. * - * Since: 2.22 + * 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 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_stop_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Finishes an stop operation, see g_file_stop_mountable() for details. + * 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. * - * Finish an asynchronous stop operation that was started - * with g_file_stop_mountable(). + * 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. * - * Returns: %TRUE if the operation finished successfully. - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_file_supports_thread_contexts: - * @file: a #GFile + * 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. * - * 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. + * 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. * - * Returns: Whether or not @file supports thread-default contexts. - * Since: 2.22 + * On error %NULL is returned and @error is set accordingly. + * + * Returns: (transfer full): a new #GBytes, or %NULL on error + * Since: 2.34 */ /** - * g_file_trash: (virtual trash) - * @file: #GFile to send to trash - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL + * 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: (nullable): 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 * - * 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. + * 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. + * + * During an async request no other sync and async calls are allowed + * on @stream, 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. * - * 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. + * 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. * - * Returns: %TRUE on successful trash, %FALSE 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_trash_async: (virtual trash_async) - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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_bytes_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Asynchronously sends @file to the Trash location, if possible. + * Finishes an asynchronous stream read-into-#GBytes operation. * - * Since: 2.38 + * Returns: (transfer full): the newly-allocated #GBytes, or %NULL on error + * Since: 2.34 */ /** - * g_file_trash_finish: (virtual trash_finish) - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL + * g_input_stream_read_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Finishes an asynchronous file trashing operation, started with - * g_file_trash_async(). + * Finishes an asynchronous stream read operation. * - * Returns: %TRUE on successful trash, %FALSE otherwise. - * Since: 2.38 + * Returns: number of bytes read in, or -1 on error, or 0 on end of file. */ /** - * g_file_unmount_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. - * - * 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. * - * 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. + * Sets @stream to have actions pending. If the pending flag is + * already set or @stream is closed, it will return %FALSE and set + * @error. * - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead. + * Returns: %TRUE if pending was previously unset and is now set. */ /** - * 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_input_stream_skip: + * @stream: a #GInputStream. + * @count: the number of bytes that will be skipped from the stream + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Finish an asynchronous unmount operation that was started - * with g_file_unmount_mountable(). + * Tries to skip @count bytes from the stream. Will block during the operation. * - * Returns: %TRUE if the operation finished successfully. - * %FALSE otherwise. - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() - * instead. - */ - - -/** - * g_file_unmount_mountable_with_operation: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function + * 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. * - * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. + * 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. - * - * 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. + * 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.22 + * Returns: Number of bytes skipped, or -1 on error */ /** - * g_file_unmount_mountable_with_operation_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL + * 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: (nullable): 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 * - * Finishes an unmount operation, - * see g_file_unmount_mountable_with_operation() for details. + * 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. * - * Finish an asynchronous unmount operation that was started - * with g_file_unmount_mountable_with_operation(). + * During an async request no other sync and async calls are allowed, + * and will result in %G_IO_ERROR_PENDING errors. * - * Returns: %TRUE if the operation finished successfully. - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_filename_completer_get_completion_suffix: - * @completer: the filename completer. - * @initial_text: text to be completed. + * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. * - * Obtains a completion for @initial_text from @completer. + * 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. * - * 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. + * 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 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_filename_completer_get_completions: - * @completer: the filename completer. - * @initial_text: text to be completed. + * g_input_stream_skip_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets an array of completion strings for a given initial text. + * Finishes a stream skip operation. * - * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. - * This array must be freed by g_strfreev() when finished. + * Returns: the size of the bytes skipped, or %-1 on error. */ /** - * g_filename_completer_new: + * g_io_error_from_errno: + * @err_no: Error number as defined in errno.h. * - * Creates a new filename completer. + * 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: a #GFilenameCompleter. - */ - - -/** - * g_filename_completer_set_dirs_only: - * @completer: the filename completer. - * @dirs_only: a #gboolean. + * As %errno is global and may be modified by intermediate function + * calls, you should save its value as soon as the call which sets it * - * If @dirs_only is %TRUE, @completer will only - * complete directory names, and not file names. + * Returns: #GIOErrorEnum value for the given errno.h error number. */ /** - * g_filter_input_stream_get_base_stream: - * @stream: a #GFilterInputStream. + * g_io_error_from_win32_error: + * @error_code: Windows error number. * - * Gets the base stream for the filter stream. + * 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). * - * Returns: (transfer none): a #GInputStream. + * You can use g_win32_error_message() to get a localized string + * corresponding to @error_code. (But note that unlike g_strerror(), + * g_win32_error_message() returns a string that must be freed.) + * + * Returns: #GIOErrorEnum value for the given error number. + * Since: 2.26 */ /** - * g_filter_input_stream_get_close_base_stream: - * @stream: a #GFilterInputStream. + * g_io_error_quark: * - * Returns whether the base stream will be closed when @stream is - * closed. + * Gets the GIO Error Quark. * - * Returns: %TRUE if the base stream will be closed. + * Returns: a #GQuark. */ /** - * g_filter_input_stream_set_close_base_stream: - * @stream: a #GFilterInputStream. - * @close_base: %TRUE to close the base stream. + * g_io_extension_get_name: + * @extension: a #GIOExtension * - * Sets whether the base stream will be closed when @stream is closed. - */ - - -/** - * g_filter_output_stream_get_base_stream: - * @stream: a #GFilterOutputStream. + * Gets the name under which @extension was registered. * - * Gets the base stream for the filter stream. + * Note that the same type may be registered as extension + * for multiple extension points, under different names. * - * Returns: (transfer none): a #GOutputStream. + * Returns: the name of @extension. */ /** - * g_filter_output_stream_get_close_base_stream: - * @stream: a #GFilterOutputStream. + * g_io_extension_get_priority: + * @extension: a #GIOExtension * - * Returns whether the base stream will be closed when @stream is - * closed. + * Gets the priority with which @extension was registered. * - * Returns: %TRUE if the base stream will be closed. + * Returns: the priority of @extension */ /** - * g_filter_output_stream_set_close_base_stream: - * @stream: a #GFilterOutputStream. - * @close_base: %TRUE to close the base stream. + * g_io_extension_get_type: + * @extension: a #GIOExtension * - * Sets whether the base stream will be closed when @stream is closed. + * Gets the type associated with @extension. + * + * Returns: the type of @extension */ /** - * g_icon_deserialize: - * @value: a #GVariant created with g_icon_serialize() + * g_io_extension_point_get_extension_by_name: + * @extension_point: a #GIOExtensionPoint + * @name: the name of the extension to get * - * Deserializes a #GIcon previously serialized using g_icon_serialize(). + * Finds a #GIOExtension for an extension point by name. * - * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails. - * Since: 2.38 + * Returns: (transfer none): the #GIOExtension for @extension_point that has the + * given name, or %NULL if there is no extension with that name */ /** - * g_icon_equal: - * @icon1: (nullable): pointer to the first #GIcon. - * @icon2: (nullable): pointer to the second #GIcon. + * g_io_extension_point_get_extensions: + * @extension_point: a #GIOExtensionPoint * - * Checks if two icons are equal. + * Gets a list of all extensions that implement this extension point. + * The list is sorted by priority, beginning with the highest priority. * - * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + * Returns: (element-type GIOExtension) (transfer none): a #GList of + * #GIOExtensions. The list is owned by GIO and should not be + * modified. */ /** - * g_icon_hash: (virtual hash) - * @icon: (not nullable): #gconstpointer to an icon object. + * g_io_extension_point_get_required_type: + * @extension_point: a #GIOExtensionPoint * - * Gets a hash for an icon. + * Gets the required type for @extension_point. * - * Returns: a #guint containing a hash for the @icon, suitable for - * use in a #GHashTable or similar data structure. + * Returns: the #GType that all implementations must have, + * or #G_TYPE_INVALID if the extension point has no required type */ /** - * g_icon_new_for_string: - * @str: A string obtained via g_icon_to_string(). - * @error: Return location for error. + * 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 * - * Generate a #GIcon instance from @str. This function can fail if - * @str is not valid - see g_icon_to_string() for discussion. + * Registers @type as extension for the extension point with name + * @extension_point_name. * - * 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(). + * If @type has already been registered as an extension for this + * extension point, the existing #GIOExtension object is returned. * - * Returns: (transfer full): An object implementing the #GIcon - * interface or %NULL if @error is set. - * Since: 2.20 + * Returns: (transfer none): a #GIOExtension object for #GType */ /** - * g_icon_serialize: - * @icon: a #GIcon + * g_io_extension_point_lookup: + * @name: the name of the extension point * - * 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. + * Looks up an existing extension point. * - * Returns: (transfer full): a #GVariant, or %NULL when serialization fails. - * Since: 2.38 + * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there + * is no registered extension point with the given name. */ /** - * g_icon_to_string: (virtual to_tokens) - * @icon: a #GIcon. - * - * 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`). + * g_io_extension_point_register: + * @name: The name of the extension point * - * - If @icon is a #GThemedIcon with exactly one name, the encoding is - * simply the name (such as `network-server`). + * Registers an extension point. * - * Returns: (nullable): An allocated NUL-terminated UTF8 string or - * %NULL if @icon can't be serialized. Use g_free() to free. - * Since: 2.20 + * Returns: (transfer none): the new #GIOExtensionPoint. This object is + * owned by GIO and should not be freed. */ /** - * g_inet_address_equal: - * @address: A #GInetAddress. - * @other_address: Another #GInetAddress. - * - * Checks if two #GInetAddress instances are equal, e.g. the same address. + * g_io_extension_point_set_required_type: + * @extension_point: a #GIOExtensionPoint + * @type: the #GType to require * - * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise. - * Since: 2.30 + * Sets the required type for @extension_point to @type. + * All implementations must henceforth have this type. */ /** - * g_inet_address_get_family: - * @address: a #GInetAddress + * g_io_extension_ref_class: + * @extension: a #GIOExtension * - * Gets @address's family + * Gets a reference to the class for the type that is + * associated with @extension. * - * Returns: @address's family - * Since: 2.22 + * Returns: (transfer full): the #GTypeClass for the type of @extension */ /** - * g_inet_address_get_is_any: - * @address: a #GInetAddress + * g_io_module_new: + * @filename: (type filename): filename of the shared library module. * - * Tests whether @address is the "any" address for its family. + * Creates a new GIOModule that will load the specific + * shared library when in use. * - * Returns: %TRUE if @address is the "any" address for its family. - * Since: 2.22 + * Returns: a #GIOModule from given @filename, + * or %NULL on error. */ /** - * g_inet_address_get_is_link_local: - * @address: a #GInetAddress + * g_io_module_scope_block: + * @scope: a module loading scope + * @basename: the basename to block * - * 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). + * 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: %TRUE if @address is a link-local address. - * Since: 2.22 + * Since: 2.30 */ /** - * g_inet_address_get_is_loopback: - * @address: a #GInetAddress + * g_io_module_scope_free: + * @scope: a module loading scope * - * Tests whether @address is the loopback address for its family. + * Free a module scope. * - * Returns: %TRUE if @address is the loopback address for its family. - * Since: 2.22 + * Since: 2.30 */ /** - * g_inet_address_get_is_mc_global: - * @address: a #GInetAddress + * g_io_module_scope_new: + * @flags: flags for the new scope * - * Tests whether @address is a global multicast address. + * 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: %TRUE if @address is a global multicast address. - * Since: 2.22 + * 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_inet_address_get_is_mc_link_local: - * @address: a #GInetAddress + * g_io_modules_load_all_in_directory: + * @dirname: (type filename): pathname for a directory containing modules + * to load. * - * Tests whether @address is a link-local multicast address. + * Loads all the modules in the specified directory. * - * Returns: %TRUE if @address is a link-local multicast address. - * Since: 2.22 + * 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_inet_address_get_is_mc_node_local: - * @address: a #GInetAddress + * g_io_modules_load_all_in_directory_with_scope: + * @dirname: (type filename): pathname for a directory containing modules + * to load. + * @scope: a scope to use when scanning the modules. * - * Tests whether @address is a node-local multicast address. + * Loads all the modules in the specified directory. * - * Returns: %TRUE if @address is a node-local multicast address. - * Since: 2.22 + * 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(). + * Since: 2.30 */ /** - * g_inet_address_get_is_mc_org_local: - * @address: a #GInetAddress + * g_io_modules_scan_all_in_directory: + * @dirname: (type filename): pathname for a directory containing modules + * to scan. * - * Tests whether @address is an organization-local multicast address. + * Scans all the modules in the specified directory, ensuring that + * any extension point implemented by a module is registered. * - * Returns: %TRUE if @address is an organization-local multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_mc_site_local: - * @address: a #GInetAddress + * 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(). * - * Tests whether @address is a site-local multicast address. + * 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 @address is a site-local multicast address. - * Since: 2.22 + * Since: 2.24 */ /** - * g_inet_address_get_is_multicast: - * @address: a #GInetAddress + * g_io_modules_scan_all_in_directory_with_scope: + * @dirname: (type filename): 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(). * - * Tests whether @address is a multicast address. + * 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 @address is a multicast address. - * Since: 2.22 + * Since: 2.30 */ /** - * g_inet_address_get_is_site_local: - * @address: a #GInetAddress + * g_io_scheduler_cancel_all_jobs: * - * 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). + * Cancels all cancellable I/O jobs. * - * Returns: %TRUE if @address is a site-local address. - * Since: 2.22 + * A job is cancellable if a #GCancellable was passed into + * g_io_scheduler_push_job(). + * + * Deprecated: You should never call this function, since you don't + * know how other libraries in your program might be making use of + * gioscheduler. */ /** - * g_inet_address_get_native_size: - * @address: a #GInetAddress + * 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: (nullable): a #GDestroyNotify for @user_data, or %NULL * - * 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(). + * 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 number of bytes used for the native version of @address. - * Since: 2.22 + * Returns: The return value of @func + * Deprecated: Use g_main_context_invoke(). */ /** - * g_inet_address_mask_equal: - * @mask: a #GInetAddressMask - * @mask2: another #GInetAddressMask + * 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: (nullable): a #GDestroyNotify for @user_data, or %NULL * - * Tests if @mask and @mask2 are the same mask. + * 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. * - * Returns: whether @mask and @mask2 are the same mask - * Since: 2.32 + * 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. + * + * Deprecated: Use g_main_context_invoke(). */ /** - * g_inet_address_mask_get_address: - * @mask: a #GInetAddressMask + * g_io_scheduler_push_job: + * @job_func: a #GIOSchedulerJobFunc. + * @user_data: data to pass to @job_func + * @notify: (nullable): 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. * - * Gets @mask's base address + * Schedules the I/O job to run in another thread. * - * Returns: (transfer none): @mask's base address - * Since: 2.32 + * @notify will be called on @user_data after @job_func has returned, + * regardless whether the job was cancelled or has run to completion. + * + * 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_inet_address_mask_get_family: - * @mask: a #GInetAddressMask + * g_io_stream_clear_pending: + * @stream: a #GIOStream * - * Gets the #GSocketFamily of @mask's address + * Clears the pending flag on @stream. * - * Returns: the #GSocketFamily of @mask's address - * Since: 2.32 + * Since: 2.22 */ /** - * g_inet_address_mask_get_length: - * @mask: a #GInetAddressMask + * g_io_stream_close: + * @stream: a #GIOStream + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @error: location to store the error occurring, or %NULL to ignore * - * Gets @mask's length + * Closes the stream, releasing resources related to it. This will also + * close the individual input and output streams, if they are not already + * closed. * - * Returns: @mask's length - * Since: 2.32 + * 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. + * + * 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. + * + * The default implementation of this method just calls close on the + * individual input/output streams. + * + * Returns: %TRUE on success, %FALSE on failure + * Since: 2.22 */ /** - * g_inet_address_mask_matches: - * @mask: a #GInetAddressMask - * @address: a #GInetAddress + * g_io_stream_close_async: + * @stream: a #GIOStream + * @io_priority: the io priority of the request + * @cancellable: (nullable): optional cancellable object + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Tests if @address falls within the range described by @mask. + * 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. * - * Returns: whether @address falls within the range described by - * @mask. - * Since: 2.32 + * For behaviour details see g_io_stream_close(). + * + * 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_inet_address_mask_new: - * @addr: a #GInetAddress - * @length: number of bits of @addr to use - * @error: return location for #GError, or %NULL + * g_io_stream_close_finish: + * @stream: a #GIOStream + * @result: a #GAsyncResult + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * - * Creates a new #GInetAddressMask representing all addresses whose - * first @length bits match @addr. + * Closes a stream. * - * Returns: a new #GInetAddressMask, or %NULL on error - * Since: 2.32 + * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. + * Since: 2.22 */ /** - * g_inet_address_mask_new_from_string: - * @mask_string: an IP address or address/length string - * @error: return location for #GError, or %NULL + * g_io_stream_get_input_stream: + * @stream: a #GIOStream * - * 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. + * Gets the input stream for this object. This is used + * for reading. * - * Returns: a new #GInetAddressMask corresponding to @string, or %NULL - * on error. - * Since: 2.32 + * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. + * Do not free. + * Since: 2.22 */ /** - * g_inet_address_mask_to_string: - * @mask: a #GInetAddressMask + * g_io_stream_get_output_stream: + * @stream: a #GIOStream * - * Converts @mask back to its corresponding string form. + * Gets the output stream for this object. This is used for + * writing. * - * Returns: a string corresponding to @mask. - * Since: 2.32 + * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. + * Do not free. + * Since: 2.22 */ /** - * g_inet_address_new_any: - * @family: the address family + * g_io_stream_has_pending: + * @stream: a #GIOStream * - * Creates a #GInetAddress for the "any" address (unassigned/"don't - * care") for @family. + * Checks if a stream has pending actions. * - * Returns: a new #GInetAddress corresponding to the "any" address - * for @family. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if @stream has pending actions. * Since: 2.22 */ /** - * g_inet_address_new_from_bytes: - * @bytes: (array) (element-type guint8): raw address data - * @family: the address family of @bytes + * g_io_stream_is_closed: + * @stream: a #GIOStream * - * 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. + * Checks if a stream is closed. * - * Returns: a new #GInetAddress corresponding to @family and @bytes. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if the stream is closed. * Since: 2.22 */ /** - * g_inet_address_new_from_string: - * @string: a string representation of an IP address + * g_io_stream_set_pending: + * @stream: a #GIOStream + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * - * Parses @string as an IP address and creates a new #GInetAddress. + * 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: a new #GInetAddress corresponding to @string, or %NULL if - * @string could not be parsed. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if pending was previously unset and is now set. * Since: 2.22 */ /** - * g_inet_address_new_loopback: - * @family: the address family + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. * - * Creates a #GInetAddress for the loopback address for @family. + * 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. * - * Returns: a new #GInetAddress corresponding to the loopback address - * for @family. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * 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. + * + * Since: 2.28 */ /** - * g_inet_address_to_bytes: (skip) - * @address: a #GInetAddress + * g_io_stream_splice_finish: + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets the raw binary address data from @address. + * Finishes an asynchronous io stream splice operation. * - * 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 + * Returns: %TRUE on success, %FALSE otherwise. + * Since: 2.28 */ /** - * g_inet_address_to_string: - * @address: a #GInetAddress + * g_keyfile_settings_backend_new: + * @filename: the filename of the keyfile + * @root_path: the path under which all settings keys appear + * @root_group: (nullable): the group name corresponding to + * @root_path, or %NULL * - * Converts @address to string form. + * Creates a keyfile-backed #GSettingsBackend. * - * Returns: a representation of @address as a string, which should be - * freed after use. - * Since: 2.22 + * 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 + * ]| + * + * 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). + * + * 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: (transfer full): a keyfile-backed #GSettingsBackend */ /** - * g_inet_socket_address_get_address: - * @address: a #GInetSocketAddress + * g_list_model_get_item: (skip) + * @list: a #GListModel + * @position: the position of the item to fetch * - * Gets @address's #GInetAddress. + * Get the item at @position. If @position is greater than the number of + * items in @list, %NULL is returned. * - * Returns: (transfer none): the #GInetAddress for @address, which must be - * g_object_ref()'d if it will be stored - * Since: 2.22 + * %NULL is never returned for an index that is smaller than the length + * of the list. See g_list_model_get_n_items(). + * + * Returns: (transfer full) (nullable): the item at @position. + * Since: 2.44 */ /** - * g_inet_socket_address_get_flowinfo: - * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress + * g_list_model_get_item_type: + * @list: a #GListModel * - * Gets the `sin6_flowinfo` field from @address, - * which must be an IPv6 address. + * 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. * - * Returns: the flowinfo field - * Since: 2.32 + * The item type of a #GListModel can not change during the life of the + * model. + * + * Returns: the #GType of the items contained in @list. + * Since: 2.44 */ /** - * g_inet_socket_address_get_port: - * @address: a #GInetSocketAddress + * g_list_model_get_n_items: + * @list: a #GListModel * - * Gets @address's port. + * Gets the number of items in @list. * - * Returns: the port for @address - * Since: 2.22 + * Depending on the model implementation, calling this function may be + * less efficient than iterating the list with increasing values for + * @position until g_list_model_get_item() returns %NULL. + * + * Returns: the number of items in @list. + * Since: 2.44 */ /** - * g_inet_socket_address_get_scope_id: - * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress + * g_list_model_get_object: (rename-to g_list_model_get_item) + * @list: a #GListModel + * @position: the position of the item to fetch * - * Gets the `sin6_scope_id` field from @address, - * which must be an IPv6 address. + * Get the item at @position. If @position is greater than the number of + * items in @list, %NULL is returned. * - * Returns: the scope id field - * Since: 2.32 + * %NULL is never returned for an index that is smaller than the length + * of the list. See g_list_model_get_n_items(). + * + * Returns: (transfer full) (nullable): the object at @position. + * Since: 2.44 */ /** - * g_inet_socket_address_new: - * @address: a #GInetAddress - * @port: a port number + * 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 * - * Creates a new #GInetSocketAddress for @address and @port. + * Emits the #GListModel::items-changed signal on @list. * - * Returns: a new #GInetSocketAddress - * Since: 2.22 + * This function should only be called by classes implementing + * #GListModel. It has to be called after the internal representation + * of @list has been updated, because handlers connected to this signal + * might query the new state of the list. + * + * Implementations must only make changes to the model (as visible to + * its consumer) in places that will not cause problems for that + * consumer. For models that are driven directly by a write API (such + * as #GListStore), changes can be reported in response to uses of that + * API. For models that represent remote data, changes should only be + * made from a fresh mainloop dispatch. It is particularly not + * permitted to make changes in response to a call to the #GListModel + * consumer API. + * + * Stated another way: in general, it is assumed that code making a + * series of accesses to the model via the API, without returning to the + * mainloop, and without calling other code, will continue to view the + * same contents of the model. + * + * Since: 2.44 */ /** - * g_inet_socket_address_new_from_string: - * @address: the string form of an IP address - * @port: a port number + * g_list_store_append: + * @store: a #GListStore + * @item: (type GObject): the new item * - * Creates a new #GInetSocketAddress for @address and @port. + * Appends @item to @store. @item must be of type #GListStore:item-type. * - * If @address is an IPv6 address, it can also contain a scope ID - * (separated from the address by a `%`). + * This function takes a ref on @item. * - * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be - * parsed. - * Since: 2.40 + * Use g_list_store_splice() to append multiple items at the same time + * efficiently. + * + * Since: 2.44 */ /** - * 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. - * - * Initializes the object implementing the interface. + * g_list_store_insert: + * @store: a #GListStore + * @position: the position at which to insert the new item + * @item: (type GObject): the new item * - * This method is intended for language bindings. If writing in C, - * g_initable_new() should typically be used instead. + * 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. * - * The object must be initialized before any real use after initial - * construction, either with this function or g_async_initable_init_async(). + * This function takes a ref on @item. * - * 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. + * Use g_list_store_splice() to insert multiple items at the same time + * efficiently. * - * 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. + * Since: 2.44 + */ + + +/** + * g_list_store_insert_sorted: + * @store: a #GListStore + * @item: (type GObject): the new item + * @compare_func: (scope call): pairwise comparison function for sorting + * @user_data: (closure): user data for @compare_func * - * Callers should not assume that a class which implements #GInitable can be - * initialized multiple times, unless the class explicitly documents itself as - * supporting this. Generally, a class’ implementation of init() can assume - * (and assert) that it will only be called once. Previously, this documentation - * recommended all #GInitable implementations should be idempotent; that - * recommendation was relaxed in GLib 2.54. + * Inserts @item into @store at a position to be determined by the + * @compare_func. * - * If a class explicitly supports being initialized multiple times, it is - * recommended that the method is idempotent: multiple calls with the same - * arguments should return the same results. Only the first call initializes - * the object; further calls return the result of the first call. + * 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. * - * One reason why a class might need to support idempotent initialization is if - * it is designed to be used via the singleton pattern, with a - * #GObjectClass.constructor that sometimes returns an existing instance. - * In this pattern, a caller would expect to be able to call g_initable_init() - * on the result of g_object_new(), regardless of whether it is in fact a new - * instance. + * This function takes a ref on @item. * - * Returns: %TRUE if successful. If an error has occurred, this function will - * return %FALSE and set @error appropriately if present. - * Since: 2.22 + * Returns: the position at which @item was inserted + * Since: 2.44 */ /** - * 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: (nullable): 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_list_store_new: + * @item_type: the #GType of items in the list * - * 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. + * Creates a new #GListStore with items of type @item_type. @item_type + * must be a subclass of #GObject. * - * Returns: (type GObject.Object) (transfer full): a newly allocated - * #GObject, or %NULL on error - * Since: 2.22 + * Returns: a new #GListStore + * Since: 2.44 */ /** - * 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_list_store_remove: + * @store: a #GListStore + * @position: the position of the item that is to be removed * - * 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. + * Removes the item from @store that is at @position. @position must be + * smaller than the current length of the list. * - * Returns: (type GObject.Object) (transfer full): a newly allocated - * #GObject, or %NULL on error - * Since: 2.22 + * Use g_list_store_splice() to remove multiple items at the same time + * efficiently. + * + * Since: 2.44 */ /** - * 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. + * g_list_store_remove_all: + * @store: a #GListStore * - * 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. + * Removes all items from @store. * - * Returns: (type GObject.Object) (transfer full): a newly allocated - * #GObject, or %NULL on error - * Since: 2.22 - * Deprecated: 2.54: Use g_object_new_with_properties() and - * g_initable_init() instead. See #GParameter for more information. + * Since: 2.44 */ /** - * g_input_stream_clear_pending: - * @stream: input stream + * g_list_store_sort: + * @store: a #GListStore + * @compare_func: (scope call): pairwise comparison function for sorting + * @user_data: (closure): user data for @compare_func * - * Clears the pending flag on @stream. + * Sort the items in @store according to @compare_func. + * + * Since: 2.46 */ /** - * g_input_stream_close: - * @stream: A #GInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore + * 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) (element-type GObject): the items to add + * @n_additions: the number of items to add * - * Closes the stream, releasing resources related to it. + * 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. * - * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a stream multiple times will not return an error. + * 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. * - * 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. + * This function takes a ref on each item in @additions. * - * 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. + * 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). * - * 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. + * Since: 2.44 + */ + + +/** + * g_loadable_icon_load: + * @icon: a #GLoadableIcon. + * @size: an integer. + * @type: (out) (optional): a location to store the type of the loaded + * icon, %NULL to ignore. + * @cancellable: (nullable): optional #GCancellable object, %NULL to + * ignore. + * @error: a #GError location to store the error occurring, or %NULL + * to ignore. * - * 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. + * Loads a loadable icon. For the asynchronous version of this function, + * see g_loadable_icon_load_async(). * - * Returns: %TRUE on success, %FALSE on failure + * Returns: (transfer full): a #GInputStream to read the icon from. */ /** - * g_input_stream_close_async: - * @stream: A #GInputStream. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional cancellable object - * @callback: (scope async): callback to call when the request is satisfied + * g_loadable_icon_load_async: + * @icon: a #GLoadableIcon. + * @size: an integer. + * @cancellable: (nullable): 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 * - * 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. - * - * For behaviour details see g_input_stream_close(). - * - * 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. + * 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_input_stream_close_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. + * 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 closing a stream asynchronously, started from g_input_stream_close_async(). + * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). * - * Returns: %TRUE if the stream was closed successfully. + * Returns: (transfer full): a #GInputStream to read the icon from. */ /** - * g_input_stream_has_pending: - * @stream: input stream. + * g_local_vfs_new: * - * Checks if an input stream has pending actions. + * Returns a new #GVfs handle for a local vfs. * - * Returns: %TRUE if @stream has pending actions. + * Returns: a new #GVfs handle. */ /** - * g_input_stream_is_closed: - * @stream: input stream. + * g_memory_input_stream_add_bytes: + * @stream: a #GMemoryInputStream + * @bytes: input data * - * Checks if an input stream is closed. + * Appends @bytes to data that can be read from the input stream. * - * Returns: %TRUE if the stream is closed. + * Since: 2.34 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore + * 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: (nullable): function that is called to free @data, or %NULL * - * Tries to read @count bytes from the stream into the buffer starting at - * @buffer. Will block during this read. + * Appends @data to data that can be read from the input stream + */ + + +/** + * g_memory_input_stream_new: * - * 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. + * Creates a new empty #GMemoryInputStream. * - * 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. + * Returns: a new #GInputStream + */ + + +/** + * g_memory_input_stream_new_from_bytes: + * @bytes: a #GBytes * - * 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. + * 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. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * 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: (nullable): function that is called to free @data, or %NULL * - * On error -1 is returned and @error is set accordingly. + * Creates a new #GMemoryInputStream with data in memory of a given size. * - * Returns: Number of bytes read, or -1 on error, or 0 on end of file. + * Returns: new #GInputStream read from @data of @len bytes. */ /** - * 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: (nullable): 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. + * g_memory_output_stream_get_data: + * @ostream: a #GMemoryOutputStream * - * 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. + * Gets any loaded data from the @ostream. * - * 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. + * Note that the returned pointer may become invalid on the next + * write or truncate operation on the stream. * - * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status. + * Returns: (transfer none): pointer to the stream's data, or %NULL if the data + * has been stolen + */ + + +/** + * g_memory_output_stream_get_data_size: + * @ostream: a #GMemoryOutputStream * - * 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 the number of bytes from the start up to including the last + * byte written in the stream that has not been truncated away. * - * Returns: %TRUE on success, %FALSE if there was an error + * Returns: the number of bytes written to the stream + * Since: 2.18 */ /** - * 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: (nullable): 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_memory_output_stream_get_size: + * @ostream: a #GMemoryOutputStream * - * Request an asynchronous read of @count bytes from the stream into the - * buffer starting at @buffer. + * Gets the size of the currently allocated data area (available from + * g_memory_output_stream_get_data()). * - * This is the asynchronous equivalent of g_input_stream_read_all(). + * 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. * - * Call g_input_stream_read_all_finish() to collect the result. + * 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. * - * 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. + * In any case, if you want the number of bytes currently written to the + * stream, use g_memory_output_stream_get_data_size(). * - * Since: 2.44 + * Returns: the number of bytes allocated for the data buffer */ /** - * 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 + * g_memory_output_stream_new: (skip) + * @data: (nullable): pointer to a chunk of memory to use, or %NULL + * @size: the size of @data + * @realloc_function: (nullable): a function with realloc() semantics (like g_realloc()) + * to be called when @data needs to be grown, or %NULL + * @destroy_function: (nullable): a function to be called on @data when the stream is + * finalized, or %NULL * - * Finishes an asynchronous stream read operation started with - * g_input_stream_read_all_async(). + * Creates a new #GMemoryOutputStream. * - * 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(). + * In most cases this is not the function you want. See + * g_memory_output_stream_new_resizable() instead. * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.44 - */ - - -/** - * 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: (nullable): 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 @data is non-%NULL, the stream will use that for its internal storage. * - * 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. + * 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. * - * During an async request no other sync and async calls are allowed on @stream, and will - * result in %G_IO_ERROR_PENDING errors. + * 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. * - * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * 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). * - * 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. + * |[ + * // a stream that can grow + * stream = g_memory_output_stream_new (NULL, 0, realloc, free); * - * 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. + * // another stream that can grow + * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); * - * 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. + * // a fixed-size stream + * data = malloc (200); + * stream3 = g_memory_output_stream_new (data, 200, NULL, free); + * ]| + * + * Returns: A newly created #GMemoryOutputStream object. */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * 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. - * - * 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. + * g_memory_output_stream_new_resizable: * - * 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. + * Creates a new #GMemoryOutputStream, using g_realloc() and g_free() + * for memory allocation. * - * 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.36 + */ + + +/** + * g_memory_output_stream_steal_as_bytes: + * @ostream: a #GMemoryOutputStream * - * On error %NULL is returned and @error is set accordingly. + * Returns data from the @ostream as a #GBytes. @ostream must be + * closed before calling this function. * - * Returns: (transfer full): a new #GBytes, or %NULL on error + * Returns: (transfer full): the stream's data * Since: 2.34 */ /** - * g_input_stream_read_bytes_async: - * @stream: A #GInputStream. - * @count: the number of bytes that will be read from the stream - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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_memory_output_stream_steal_data: + * @ostream: a #GMemoryOutputStream * - * 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. + * 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. * - * During an async request no other sync and async calls are allowed - * on @stream, and will result in %G_IO_ERROR_PENDING errors. + * @ostream must be closed before calling this function. * - * A value of @count larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. + * Returns: (transfer full): the stream's data, or %NULL if it has previously + * been stolen + * Since: 2.26 + */ + + +/** + * g_memory_settings_backend_new: * - * 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. + * Creates a memory-backed #GSettingsBackend. * - * 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 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. * - * Since: 2.34 + * Returns: (transfer full): a newly created #GSettingsBackend + * Since: 2.28 */ /** - * 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. + * g_menu_append: + * @menu: a #GMenu + * @label: (nullable): the section label, or %NULL + * @detailed_action: (nullable): the detailed action string, or %NULL * - * Finishes an asynchronous stream read-into-#GBytes operation. + * 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: (transfer full): the newly-allocated #GBytes, or %NULL on error - * Since: 2.34 + * Since: 2.32 */ /** - * 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_menu_append_item: + * @menu: a #GMenu + * @item: a #GMenuItem to append + * + * Appends @item to the end of @menu. * - * Finishes an asynchronous stream read operation. + * See g_menu_insert_item() for more information. * - * Returns: number of bytes read in, or -1 on error, or 0 on end of file. + * Since: 2.32 */ /** - * g_input_stream_set_pending: - * @stream: input stream - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_menu_append_section: + * @menu: a #GMenu + * @label: (nullable): the section label, or %NULL + * @section: a #GMenuModel with the items of the section * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set - * @error. + * 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. * - * Returns: %TRUE if pending was previously unset and is now set. + * Since: 2.32 */ /** - * g_input_stream_skip: - * @stream: a #GInputStream. - * @count: the number of bytes that will be skipped from the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore + * g_menu_append_submenu: + * @menu: a #GMenu + * @label: (nullable): the section label, or %NULL + * @submenu: a #GMenuModel with the items of the submenu * - * Tries to skip @count bytes from the stream. Will block during 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. * - * 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. + * Since: 2.32 + */ + + +/** + * g_menu_attribute_iter_get_name: + * @iter: a #GMenuAttributeIter * - * This function is optional for inherited classes, as the default implementation - * emulates it using read. + * Gets the name of the attribute at the current iterator position, as + * a string. * - * 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 iterator is not advanced. * - * Returns: Number of bytes skipped, or -1 on error + * Returns: the name of the attribute + * Since: 2.32 */ /** - * 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: (nullable): 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_menu_attribute_iter_get_next: + * @iter: a #GMenuAttributeIter + * @out_name: (out) (optional) (transfer none): the type of the attribute + * @value: (out) (optional) (transfer full): the attribute value * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. + * This function combines g_menu_attribute_iter_next() with + * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). * - * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * First the iterator is advanced to the next (possibly first) attribute. + * If that fails, then %FALSE is returned and there are no other + * effects. * - * 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. + * 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. * - * 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 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. * - * 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 on success, or %FALSE if there is no additional + * attribute + * Since: 2.32 */ /** - * 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_menu_attribute_iter_get_value: + * @iter: a #GMenuAttributeIter * - * Finishes a stream skip operation. + * Gets the value of the attribute at the current iterator position. * - * Returns: the size of the bytes skipped, or %-1 on error. + * The iterator is not advanced. + * + * Returns: (transfer full): the value of the current attribute + * Since: 2.32 */ /** - * g_io_error_from_errno: - * @err_no: Error number as defined in errno.h. + * g_menu_attribute_iter_next: + * @iter: a #GMenuAttributeIter * - * 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). + * Attempts to advance the iterator to the next (possibly first) + * attribute. * - * As %errno is global and may be modified by intermediate function - * calls, you should save its value as soon as the call which sets it + * %TRUE is returned on success, or %FALSE if there are no more + * attributes. * - * Returns: #GIOErrorEnum value for the given errno.h error number. + * 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_io_error_from_win32_error: - * @error_code: Windows error number. + * g_menu_freeze: + * @menu: a #GMenu * - * 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). + * Marks @menu as frozen. * - * 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.) + * 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: #GIOErrorEnum value for the given error number. - * Since: 2.26 + * This function causes g_menu_model_is_mutable() to begin returning + * %FALSE, which has some positive performance implications. + * + * Since: 2.32 */ /** - * g_io_error_quark: + * g_menu_insert: + * @menu: a #GMenu + * @position: the position at which to insert the item + * @label: (nullable): the section label, or %NULL + * @detailed_action: (nullable): the detailed action string, or %NULL * - * Gets the GIO Error Quark. + * 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 #GQuark. + * Since: 2.32 */ /** - * g_io_extension_get_name: - * @extension: a #GIOExtension + * g_menu_insert_item: + * @menu: a #GMenu + * @position: the position at which to insert the item + * @item: the #GMenuItem to insert * - * Gets the name under which @extension was registered. + * Inserts @item into @menu. * - * Note that the same type may be registered as extension - * for multiple extension points, under different names. + * 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. * - * Returns: the name of @extension. - */ - - -/** - * g_io_extension_get_priority: - * @extension: a #GIOExtension + * 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). * - * Gets the priority with which @extension was registered. + * You should probably just free @item once you're done. * - * Returns: the priority of @extension + * 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_io_extension_get_type: - * @extension: a #GIOExtension + * g_menu_insert_section: + * @menu: a #GMenu + * @position: the position at which to insert the item + * @label: (nullable): the section label, or %NULL + * @section: a #GMenuModel with the items of the section * - * Gets the type associated with @extension. + * 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: the type of @extension + * Since: 2.32 */ /** - * g_io_extension_point_get_extension_by_name: - * @extension_point: a #GIOExtensionPoint - * @name: the name of the extension to get + * g_menu_insert_submenu: + * @menu: a #GMenu + * @position: the position at which to insert the item + * @label: (nullable): the section label, or %NULL + * @submenu: a #GMenuModel with the items of the submenu * - * Finds a #GIOExtension for an extension point by name. + * 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: (transfer none): the #GIOExtension for @extension_point that has the - * given name, or %NULL if there is no extension with that name + * Since: 2.32 */ /** - * g_io_extension_point_get_extensions: - * @extension_point: a #GIOExtensionPoint + * 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 * - * Gets a list of all extensions that implement this extension point. - * The list is sorted by priority, beginning with the highest priority. + * Queries the named @attribute on @menu_item. * - * Returns: (element-type GIOExtension) (transfer none): a #GList of - * #GIOExtensions. The list is owned by GIO and should not be - * modified. - */ - - -/** - * g_io_extension_point_get_required_type: - * @extension_point: a #GIOExtensionPoint + * 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. * - * Gets the required type for @extension_point. + * 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: the #GType that all implementations must have, - * or #G_TYPE_INVALID if the extension point has no required type + * Returns: %TRUE if the named attribute was found with the expected + * type + * Since: 2.34 */ /** - * 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 + * g_menu_item_get_attribute_value: + * @menu_item: a #GMenuItem + * @attribute: the attribute name to query + * @expected_type: (nullable): the expected type of the attribute * - * Registers @type as extension for the extension point with name - * @extension_point_name. + * Queries the named @attribute on @menu_item. * - * If @type has already been registered as an extension for this - * extension point, the existing #GIOExtension object is returned. + * 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 none): a #GIOExtension object for #GType + * Returns: (transfer full): the attribute value, or %NULL + * Since: 2.34 */ /** - * g_io_extension_point_lookup: - * @name: the name of the extension point + * g_menu_item_get_link: + * @menu_item: a #GMenuItem + * @link: the link name to query * - * Looks up an existing extension point. + * Queries the named @link on @menu_item. * - * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there - * is no registered extension point with the given name. + * Returns: (transfer full): the link, or %NULL + * Since: 2.34 */ /** - * g_io_extension_point_register: - * @name: The name of the extension point + * g_menu_item_new: + * @label: (nullable): the section label, or %NULL + * @detailed_action: (nullable): the detailed action string, or %NULL * - * Registers an extension point. + * Creates a new #GMenuItem. * - * Returns: (transfer none): the new #GIOExtensionPoint. This object is - * owned by GIO and should not be freed. + * 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_io_extension_point_set_required_type: - * @extension_point: a #GIOExtensionPoint - * @type: the #GType to require + * g_menu_item_new_from_model: + * @model: a #GMenuModel + * @item_index: the index of an item in @model * - * Sets the required type for @extension_point to @type. - * All implementations must henceforth have this type. + * Creates a #GMenuItem as an exact copy of an existing menu item in a + * #GMenuModel. + * + * @item_index must be valid (ie: be sure to call + * g_menu_model_get_n_items() first). + * + * Returns: a new #GMenuItem. + * Since: 2.34 */ /** - * g_io_extension_ref_class: - * @extension: a #GIOExtension + * g_menu_item_new_section: + * @label: (nullable): the section label, or %NULL + * @section: a #GMenuModel with the items of the section * - * Gets a reference to the class for the type that is - * associated with @extension. + * Creates a new #GMenuItem representing a section. * - * Returns: (transfer full): the #GTypeClass for the type of @extension + * This is a convenience API around g_menu_item_new() and + * g_menu_item_set_section(). + * + * 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. + * + * 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: + * |[ + * + *
+ * + * + *
+ *
+ * + * + * + *
+ * + * ]| + * + * 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). + * |[ + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ]| + * + * Returns: a new #GMenuItem + * Since: 2.32 */ /** - * g_io_module_new: - * @filename: (type filename): filename of the shared library module. + * g_menu_item_new_submenu: + * @label: (nullable): the section label, or %NULL + * @submenu: a #GMenuModel with the items of the submenu * - * Creates a new GIOModule that will load the specific - * shared library when in use. + * Creates a new #GMenuItem representing a submenu. * - * Returns: a #GIOModule from given @filename, - * or %NULL on error. + * This is a convenience API around g_menu_item_new() and + * g_menu_item_set_submenu(). + * + * Returns: a new #GMenuItem + * Since: 2.32 */ /** - * g_io_module_scope_block: - * @scope: a module loading scope - * @basename: the basename to block + * g_menu_item_set_action_and_target: + * @menu_item: a #GMenuItem + * @action: (nullable): the name of the action for this item + * @format_string: (nullable): a GVariant format string + * @...: positional parameters, as per @format_string * - * 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(). + * Sets or unsets the "action" and "target" attributes of @menu_item. * - * 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_io_module_scope_free: - * @scope: a module loading scope + * g_menu_item_set_action_and_target_value: + * @menu_item: a #GMenuItem + * @action: (nullable): the name of the action for this item + * @target_value: (nullable): a #GVariant to use as the action target * - * Free a module scope. + * Sets or unsets the "action" and "target" attributes of @menu_item. * - * Since: 2.30 + * 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_io_module_scope_new: - * @flags: flags for the new scope + * g_menu_item_set_attribute: + * @menu_item: a #GMenuItem + * @attribute: the attribute to set + * @format_string: (nullable): a #GVariant format string, or %NULL + * @...: positional parameters, as per @format_string * - * 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. + * 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. + * + * 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. * - * 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. + * See also g_menu_item_set_attribute_value() for an equivalent call + * that directly accepts a #GVariant. * - * Returns: (transfer full): the new module scope - * Since: 2.30 + * Since: 2.32 */ /** - * g_io_modules_load_all_in_directory: - * @dirname: (type filename): pathname for a directory containing modules - * to load. + * g_menu_item_set_attribute_value: + * @menu_item: a #GMenuItem + * @attribute: the attribute to set + * @value: (nullable): a #GVariant to use as the value, or %NULL * - * Loads all the modules in the specified directory. + * Sets or unsets an attribute on @menu_item. * - * 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 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: (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_io_modules_load_all_in_directory_with_scope: - * @dirname: (type filename): pathname for a directory containing modules - * to load. - * @scope: a scope to use when scanning the modules. + * must consist only of lowercase + * ASCII characters, digits and '-'. * - * Loads all the modules in the specified directory. + * 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. * - * 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. + * See also g_menu_item_set_attribute() for a more convenient way to do + * the same. * - * 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 + * Since: 2.32 */ /** - * g_io_modules_scan_all_in_directory: - * @dirname: (type filename): pathname for a directory containing modules - * to scan. + * g_menu_item_set_detailed_action: + * @menu_item: a #GMenuItem + * @detailed_action: the "detailed" action string * - * Scans all the modules in the specified directory, ensuring that - * any extension point implemented by a module is registered. + * Sets the "action" and possibly the "target" attribute of @menu_item. * - * 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(). + * The format of @detailed_action is the same format parsed by + * g_action_parse_detailed_name(). * - * If you need to guarantee that all types are loaded in all the modules, - * use g_io_modules_load_all_in_directory(). + * 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. * - * Since: 2.24 + * 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_io_modules_scan_all_in_directory_with_scope: - * @dirname: (type filename): pathname for a directory containing modules - * to scan. - * @scope: a scope to use when scanning the modules + * g_menu_item_set_icon: + * @menu_item: a #GMenuItem + * @icon: a #GIcon, or %NULL * - * Scans all the modules in the specified directory, ensuring that - * any extension point implemented by a module is registered. + * Sets (or unsets) the icon on @menu_item. * - * 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(). + * 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. * - * If you need to guarantee that all types are loaded in all the modules, - * use g_io_modules_load_all_in_directory(). + * 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'). * - * Since: 2.30 + * If @icon is %NULL then the icon is unset. + * + * Since: 2.38 */ /** - * g_io_scheduler_cancel_all_jobs: + * g_menu_item_set_label: + * @menu_item: a #GMenuItem + * @label: (nullable): the label to set, or %NULL to unset * - * Cancels all cancellable I/O jobs. + * Sets or unsets the "label" attribute of @menu_item. * - * A job is cancellable if a #GCancellable was passed into - * g_io_scheduler_push_job(). + * 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. * - * Deprecated: You should never call this function, since you don't - * know how other libraries in your program might be making use of - * gioscheduler. + * 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: (nullable): a #GDestroyNotify for @user_data, or %NULL + * g_menu_item_set_link: + * @menu_item: a #GMenuItem + * @link: type of link to establish or unset + * @model: (nullable): the #GMenuModel to link to (or %NULL to unset) * - * 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). + * Creates a link from @menu_item to @model if non-%NULL, or unsets it. * - * Returns: The return value of @func - * Deprecated: Use g_main_context_invoke(). + * 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_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: (nullable): a #GDestroyNotify for @user_data, or %NULL + * g_menu_item_set_section: + * @menu_item: a #GMenuItem + * @section: (nullable): a #GMenuModel, 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. + * Sets or unsets the "section" link of @menu_item to @section. * - * 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. + * 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. * - * Deprecated: Use g_main_context_invoke(). + * Since: 2.32 */ /** - * g_io_scheduler_push_job: - * @job_func: a #GIOSchedulerJobFunc. - * @user_data: data to pass to @job_func - * @notify: (nullable): 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. + * g_menu_item_set_submenu: + * @menu_item: a #GMenuItem + * @submenu: (nullable): a #GMenuModel, or %NULL * - * Schedules the I/O job to run in another thread. + * Sets or unsets the "submenu" link of @menu_item to @submenu. * - * @notify will be called on @user_data after @job_func has returned, - * regardless whether the job was cancelled or has run to completion. + * If @submenu is non-%NULL, it is linked to. If it is %NULL then the + * link is unset. * - * 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(). + * The effect of having one menu appear as a submenu of another is + * exactly as it sounds. * - * Deprecated: use #GThreadPool or g_task_run_in_thread() + * Since: 2.32 */ /** - * g_io_stream_clear_pending: - * @stream: a #GIOStream + * g_menu_link_iter_get_name: + * @iter: a #GMenuLinkIter * - * Clears the pending flag on @stream. + * Gets the name of the link at the current iterator position. * - * Since: 2.22 + * The iterator is not advanced. + * + * Returns: the type of the link + * Since: 2.32 */ /** - * g_io_stream_close: - * @stream: a #GIOStream - * @cancellable: (nullable): 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 - * close 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_menu_link_iter_get_next: + * @iter: a #GMenuLinkIter + * @out_link: (out) (optional) (transfer none): the name of the link + * @value: (out) (optional) (transfer full): the linked #GMenuModel * - * 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. + * This function combines g_menu_link_iter_next() with + * g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). * - * 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. + * 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 @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 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 default implementation of this method just calls close on the - * individual input/output streams. + * 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, %FALSE on failure - * Since: 2.22 + * Returns: %TRUE on success, or %FALSE if there is no additional link + * Since: 2.32 */ /** - * g_io_stream_close_async: - * @stream: a #GIOStream - * @io_priority: the io priority of the request - * @cancellable: (nullable): 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. + * g_menu_link_iter_get_value: + * @iter: a #GMenuLinkIter * - * For behaviour details see g_io_stream_close(). + * Gets the linked #GMenuModel at the current iterator position. * - * 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. + * The iterator is not advanced. * - * Since: 2.22 + * Returns: (transfer full): the #GMenuModel that is linked to + * 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_menu_link_iter_next: + * @iter: a #GMenuLinkIter * - * Closes a stream. + * Attempts to advance the iterator to the next (possibly first) + * link. * - * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. - * Since: 2.22 + * %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_io_stream_get_input_stream: - * @stream: a #GIOStream + * 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 the input stream for this object. This is used - * for reading. + * Queries item at position @item_index in @model for the attribute + * specified by @attribute. * - * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. - * Do not free. - * Since: 2.22 + * 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_io_stream_get_output_stream: - * @stream: a #GIOStream + * g_menu_model_get_item_attribute_value: + * @model: a #GMenuModel + * @item_index: the index of the item + * @attribute: the attribute to query + * @expected_type: (nullable): the expected type of the attribute, or + * %NULL * - * Gets the output stream for this object. This is used for - * writing. + * Queries the item at position @item_index in @model for the attribute + * specified by @attribute. * - * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. - * Do not free. - * Since: 2.22 + * 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. + * + * 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_io_stream_has_pending: - * @stream: a #GIOStream + * g_menu_model_get_item_link: + * @model: a #GMenuModel + * @item_index: the index of the item + * @link: the link to query * - * Checks if a stream has pending actions. + * Queries the item at position @item_index in @model for the link + * specified by @link. * - * Returns: %TRUE if @stream has pending actions. - * Since: 2.22 + * 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_io_stream_is_closed: - * @stream: a #GIOStream + * g_menu_model_get_n_items: + * @model: a #GMenuModel * - * Checks if a stream is closed. + * Query the number of items in @model. * - * Returns: %TRUE if the stream is closed. - * Since: 2.22 + * Returns: the number of items + * Since: 2.32 */ /** - * g_io_stream_set_pending: - * @stream: a #GIOStream - * @error: a #GError location to store the error occurring, or %NULL to - * ignore + * g_menu_model_is_mutable: + * @model: a #GMenuModel * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set - * @error. + * Queries if @model is mutable. * - * Returns: %TRUE if pending was previously unset and is now set. - * Since: 2.22 + * An immutable #GMenuModel will never emit the #GMenuModel::items-changed + * signal. Consumers of the model may make optimisations accordingly. + * + * Returns: %TRUE if the model is mutable (ie: "items-changed" may be + * emitted). + * Since: 2.32 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. + * 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 * - * 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. + * Requests emission of the #GMenuModel::items-changed signal on @model. * - * 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. + * 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. * - * Since: 2.28 + * 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. + * + * 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. + * + * Since: 2.32 */ /** - * g_io_stream_splice_finish: - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_menu_model_iterate_item_attributes: + * @model: a #GMenuModel + * @item_index: the index of the item * - * Finishes an asynchronous io stream splice operation. + * Creates a #GMenuAttributeIter to iterate over the attributes of + * the item at position @item_index in @model. * - * Returns: %TRUE on success, %FALSE otherwise. - * Since: 2.28 + * You must free the iterator with g_object_unref() when you are done. + * + * Returns: (transfer full): a new #GMenuAttributeIter + * Since: 2.32 */ /** - * g_keyfile_settings_backend_new: - * @filename: the filename of the keyfile - * @root_path: the path under which all settings keys appear - * @root_group: (nullable): 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_menu_model_iterate_item_links: + * @model: a #GMenuModel + * @item_index: the index of the item * - * 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). + * Creates a #GMenuLinkIter to iterate over the links of the item at + * position @item_index in @model. * - * 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. + * You must free the iterator with g_object_unref() when you are done. * - * Returns: (transfer full): a keyfile-backed #GSettingsBackend + * Returns: (transfer full): a new #GMenuLinkIter + * Since: 2.32 */ /** - * g_list_model_get_item: (skip) - * @list: a #GListModel - * @position: the position of the item to fetch + * g_menu_new: * - * Get the item at @position. If @position is greater than the number of - * items in @list, %NULL is returned. + * Creates a new #GMenu. * - * %NULL is never returned for an index that is smaller than the length - * of the list. See g_list_model_get_n_items(). + * The new menu has no items. * - * Returns: (transfer full) (nullable): the item at @position. - * Since: 2.44 + * Returns: a new #GMenu + * Since: 2.32 */ /** - * g_list_model_get_item_type: - * @list: a #GListModel - * - * 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. + * g_menu_prepend: + * @menu: a #GMenu + * @label: (nullable): the section label, or %NULL + * @detailed_action: (nullable): the detailed action string, or %NULL * - * The item type of a #GListModel can not change during the life of the - * model. + * 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: the #GType of the items contained in @list. - * Since: 2.44 + * Since: 2.32 */ /** - * g_list_model_get_n_items: - * @list: a #GListModel + * g_menu_prepend_item: + * @menu: a #GMenu + * @item: a #GMenuItem to prepend * - * Gets the number of items in @list. + * Prepends @item to the start of @menu. * - * 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. + * See g_menu_insert_item() for more information. * - * Returns: the number of items in @list. - * Since: 2.44 + * Since: 2.32 */ /** - * g_list_model_get_object: (rename-to g_list_model_get_item) - * @list: a #GListModel - * @position: the position of the item to fetch - * - * Get the item at @position. If @position is greater than the number of - * items in @list, %NULL is returned. + * g_menu_prepend_section: + * @menu: a #GMenu + * @label: (nullable): the section label, or %NULL + * @section: a #GMenuModel with the items of the section * - * %NULL is never returned for an index that is smaller than the length - * of the list. See g_list_model_get_n_items(). + * 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: (transfer full) (nullable): the object at @position. - * Since: 2.44 + * Since: 2.32 */ /** - * 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 - * - * Emits the #GListModel::items-changed signal on @list. - * - * This function should only be called by classes implementing - * #GListModel. It has to be called after the internal representation - * of @list has been updated, because handlers connected to this signal - * might query the new state of the list. - * - * Implementations must only make changes to the model (as visible to - * its consumer) in places that will not cause problems for that - * consumer. For models that are driven directly by a write API (such - * as #GListStore), changes can be reported in response to uses of that - * API. For models that represent remote data, changes should only be - * made from a fresh mainloop dispatch. It is particularly not - * permitted to make changes in response to a call to the #GListModel - * consumer API. + * g_menu_prepend_submenu: + * @menu: a #GMenu + * @label: (nullable): the section label, or %NULL + * @submenu: a #GMenuModel with the items of the submenu * - * 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. + * 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. * - * Since: 2.44 + * Since: 2.32 */ /** - * g_list_store_append: - * @store: a #GListStore - * @item: (type GObject): the new item + * g_menu_remove: + * @menu: a #GMenu + * @position: the position of the item to remove * - * Appends @item to @store. @item must be of type #GListStore:item-type. + * Removes an item from the menu. * - * This function takes a ref on @item. + * @position gives the index of the item to remove. * - * Use g_list_store_splice() to append multiple items at the same time - * efficiently. + * 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. * - * Since: 2.44 + * 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). + * + * Since: 2.32 */ /** - * g_list_store_insert: - * @store: a #GListStore - * @position: the position at which to insert the new item - * @item: (type GObject): the new item - * - * Inserts @item into @store at @position. @item must be of type - * #GListStore:item-type or derived from it. @position must be smaller - * than the length of the list, or equal to it to append. - * - * This function takes a ref on @item. + * g_menu_remove_all: + * @menu: a #GMenu * - * Use g_list_store_splice() to insert multiple items at the same time - * efficiently. + * Removes all items in the menu. * - * Since: 2.44 + * Since: 2.38 */ /** - * g_list_store_insert_sorted: - * @store: a #GListStore - * @item: (type GObject): the new item - * @compare_func: (scope call): pairwise comparison function for sorting - * @user_data: (closure): user data for @compare_func - * - * Inserts @item into @store at a position to be determined by the - * @compare_func. - * - * The list must already be sorted before calling this function or the - * result is undefined. Usually you would approach this by only ever - * inserting items by way of this function. + * g_mount_can_eject: + * @mount: a #GMount. * - * This function takes a ref on @item. + * Checks if @mount can be ejected. * - * Returns: the position at which @item was inserted - * Since: 2.44 + * Returns: %TRUE if the @mount can be ejected. */ /** - * g_list_store_new: - * @item_type: the #GType of items in the list + * g_mount_can_unmount: + * @mount: a #GMount. * - * Creates a new #GListStore with items of type @item_type. @item_type - * must be a subclass of #GObject. + * Checks if @mount can be unmounted. * - * Returns: a new #GListStore - * Since: 2.44 + * Returns: %TRUE if the @mount can be unmounted. */ /** - * g_list_store_remove: - * @store: a #GListStore - * @position: the position of the item that is to be removed - * - * Removes the item from @store that is at @position. @position must be - * smaller than the current length of the list. + * g_mount_eject: + * @mount: a #GMount. + * @flags: flags affecting the unmount if required for eject + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Use g_list_store_splice() to remove multiple items at the same time - * efficiently. + * 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. * - * Since: 2.44 + * Deprecated: 2.22: Use g_mount_eject_with_operation() instead. */ /** - * g_list_store_remove_all: - * @store: a #GListStore + * g_mount_eject_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Removes all items from @store. + * Finishes ejecting a mount. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * Since: 2.44 + * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. + * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead. */ /** - * g_list_store_sort: - * @store: a #GListStore - * @compare_func: (scope call): pairwise comparison function for sorting - * @user_data: (closure): user data for @compare_func + * g_mount_eject_with_operation: + * @mount: a #GMount. + * @flags: flags affecting the unmount if required for eject + * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid + * user interaction. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Sort the items in @store according to @compare_func. + * 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. * - * Since: 2.46 + * Since: 2.22 */ /** - * 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) (element-type GObject): the items to add - * @n_additions: the number of items to add - * - * Changes @store by removing @n_removals items and adding @n_additions - * items to it. @additions must contain @n_additions items of type - * #GListStore:item-type. %NULL is not permitted. - * - * This function is more efficient than g_list_store_insert() and - * g_list_store_remove(), because it only emits - * #GListModel::items-changed once for the change. - * - * This function takes a ref on each item in @additions. + * 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. * - * 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). + * Finishes ejecting a mount. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * Since: 2.44 + * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. + * Since: 2.22 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to - * ignore. - * @error: a #GError location to store the error occurring, or %NULL - * to ignore. + * g_mount_get_default_location: + * @mount: a #GMount. * - * Loads a loadable icon. For the asynchronous version of this function, - * see g_loadable_icon_load_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: (transfer full): a #GInputStream to read the icon from. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ /** - * g_loadable_icon_load_async: - * @icon: a #GLoadableIcon. - * @size: an integer. - * @cancellable: (nullable): 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_mount_get_drive: + * @mount: a #GMount. * - * Loads an icon asynchronously. To finish this function, see - * g_loadable_icon_load_finish(). For the synchronous, blocking - * version of this function, see g_loadable_icon_load(). + * Gets the drive for the @mount. + * + * 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_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. + * g_mount_get_icon: + * @mount: a #GMount. * - * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). + * Gets the icon for @mount. * - * Returns: (transfer full): a #GInputStream to read the icon from. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ /** - * g_local_vfs_new: + * g_mount_get_name: + * @mount: a #GMount. * - * Returns a new #GVfs handle for a local vfs. + * Gets the name of @mount. * - * Returns: a new #GVfs handle. + * Returns: the name for the given @mount. + * The returned string should be freed with g_free() + * when no longer needed. */ /** - * g_memory_input_stream_add_bytes: - * @stream: a #GMemoryInputStream - * @bytes: input data + * g_mount_get_root: + * @mount: a #GMount. * - * Appends @bytes to data that can be read from the input stream. + * Gets the root directory on @mount. * - * Since: 2.34 + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ /** - * 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: (nullable): function that is called to free @data, or %NULL + * g_mount_get_sort_key: + * @mount: A #GMount. * - * Appends @data to data that can be read from the input stream + * Gets the sort key for @mount, if any. + * + * Returns: Sorting key for @mount or %NULL if no such key is available. + * Since: 2.32 */ /** - * g_memory_input_stream_new: + * g_mount_get_symbolic_icon: + * @mount: a #GMount. * - * Creates a new empty #GMemoryInputStream. + * Gets the symbolic icon for @mount. * - * Returns: a new #GInputStream + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. + * Since: 2.34 */ /** - * g_memory_input_stream_new_from_bytes: - * @bytes: a #GBytes + * g_mount_get_uuid: + * @mount: a #GMount. * - * Creates a new #GMemoryInputStream with data from the given @bytes. + * 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. * - * Returns: new #GInputStream read from @bytes - * Since: 2.34 + * 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_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: (nullable): function that is called to free @data, or %NULL + * g_mount_get_volume: + * @mount: a #GMount. * - * Creates a new #GMemoryInputStream with data in memory of a given size. + * Gets the volume for the @mount. * - * Returns: new #GInputStream read from @data of @len bytes. + * 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_memory_output_stream_get_data: - * @ostream: a #GMemoryOutputStream + * 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: (nullable): optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback + * @user_data: user data passed to @callback * - * Gets any loaded data from the @ostream. + * 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. * - * Note that the returned pointer may become invalid on the next - * write or truncate operation on the stream. + * 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. * - * Returns: (transfer none): pointer to the stream's data, or %NULL if the data - * has been stolen + * Since: 2.18 */ /** - * g_memory_output_stream_get_data_size: - * @ostream: a #GMemoryOutputStream + * 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 * - * Returns the number of bytes from the start up to including the last - * byte written in the stream that has not been truncated away. + * 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. * - * Returns: the number of bytes written to the stream + * 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_memory_output_stream_get_size: - * @ostream: a #GMemoryOutputStream - * - * Gets the size of the currently allocated data area (available from - * g_memory_output_stream_get_data()). - * - * You probably don't want to use this function on resizable streams. - * See g_memory_output_stream_get_data_size() instead. For resizable - * streams the size returned by this function is an implementation - * detail and may be change at any time in response to operations on the - * stream. + * 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: (nullable): optional #GCancellable object, %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * - * 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. + * 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. * - * In any case, if you want the number of bytes currently written to the - * stream, use g_memory_output_stream_get_data_size(). + * This is an synchronous operation and as such may block doing IO; + * see g_mount_guess_content_type() for the asynchronous version. * - * Returns: the number of bytes allocated for the data buffer + * 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_memory_output_stream_new: (skip) - * @data: (nullable): pointer to a chunk of memory to use, or %NULL - * @size: the size of @data - * @realloc_function: (nullable): a function with realloc() semantics (like g_realloc()) - * to be called when @data needs to be grown, or %NULL - * @destroy_function: (nullable): a function to be called on @data when the stream is - * finalized, or %NULL - * - * Creates a new #GMemoryOutputStream. - * - * 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. + * g_mount_is_shadowed: + * @mount: A #GMount. * - * 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). + * Determines if @mount is shadowed. Applications or libraries should + * avoid displaying @mount in the user interface if it is shadowed. * - * |[ - * // a stream that can grow - * stream = g_memory_output_stream_new (NULL, 0, realloc, free); + * 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. * - * // another stream that can grow - * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); + * 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. * - * // a fixed-size stream - * data = malloc (200); - * stream3 = g_memory_output_stream_new (data, 200, NULL, free); - * ]| + * 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. * - * Returns: A newly created #GMemoryOutputStream object. + * Returns: %TRUE if @mount is shadowed. + * Since: 2.20 */ /** - * g_memory_output_stream_new_resizable: + * g_mount_operation_get_anonymous: + * @op: a #GMountOperation. * - * Creates a new #GMemoryOutputStream, using g_realloc() and g_free() - * for memory allocation. + * Check to see whether the mount operation is being used + * for an anonymous user. * - * Since: 2.36 + * Returns: %TRUE if mount operation is anonymous. */ /** - * g_memory_output_stream_steal_as_bytes: - * @ostream: a #GMemoryOutputStream + * g_mount_operation_get_choice: + * @op: a #GMountOperation. * - * Returns data from the @ostream as a #GBytes. @ostream must be - * closed before calling this function. + * Gets a choice from the mount operation. * - * Returns: (transfer full): the stream's data - * Since: 2.34 + * Returns: an integer containing an index of the user's choice from + * the choice's list, or %0. */ /** - * 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_mount_operation_get_domain: + * @op: a #GMountOperation. * - * @ostream must be closed before calling this function. + * Gets the domain of the mount operation. * - * Returns: (transfer full): the stream's data, or %NULL if it has previously - * been stolen - * Since: 2.26 + * Returns: a string set to the domain. */ /** - * g_memory_settings_backend_new: - * - * Creates a memory-backed #GSettingsBackend. + * g_mount_operation_get_password: + * @op: a #GMountOperation. * - * 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. + * Gets a password from the mount operation. * - * Returns: (transfer full): a newly created #GSettingsBackend - * Since: 2.28 + * Returns: a string containing the password within @op. */ /** - * g_menu_append: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL + * g_mount_operation_get_password_save: + * @op: a #GMountOperation. * - * 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. + * Gets the state of saving passwords for the mount operation. * - * Since: 2.32 + * Returns: a #GPasswordSave flag. */ /** - * g_menu_append_item: - * @menu: a #GMenu - * @item: a #GMenuItem to append - * - * Appends @item to the end of @menu. + * g_mount_operation_get_username: + * @op: a #GMountOperation. * - * See g_menu_insert_item() for more information. + * Get the user name from the mount operation. * - * Since: 2.32 + * Returns: a string containing the user name. */ /** - * g_menu_append_section: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section + * g_mount_operation_new: * - * 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. + * Creates a new mount operation. * - * Since: 2.32 + * Returns: a #GMountOperation. */ /** - * g_menu_append_submenu: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu - * - * 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. + * g_mount_operation_reply: + * @op: a #GMountOperation + * @result: a #GMountOperationResult * - * Since: 2.32 + * Emits the #GMountOperation::reply signal. */ /** - * g_menu_attribute_iter_get_name: - * @iter: a #GMenuAttributeIter - * - * Gets the name of the attribute at the current iterator position, as - * a string. - * - * The iterator is not advanced. + * g_mount_operation_set_anonymous: + * @op: a #GMountOperation. + * @anonymous: boolean value. * - * Returns: the name of the attribute - * Since: 2.32 + * Sets the mount operation to use an anonymous user if @anonymous is %TRUE. */ /** - * g_menu_attribute_iter_get_next: - * @iter: a #GMenuAttributeIter - * @out_name: (out) (optional) (transfer none): the type of the attribute - * @value: (out) (optional) (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_attribute_iter_get_name() and g_menu_attribute_iter_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_mount_operation_set_choice: + * @op: a #GMountOperation. + * @choice: an integer. * - * Returns: %TRUE on success, or %FALSE if there is no additional - * attribute - * Since: 2.32 + * Sets a default choice for the mount operation. */ /** - * g_menu_attribute_iter_get_value: - * @iter: a #GMenuAttributeIter - * - * Gets the value of the attribute at the current iterator position. - * - * The iterator is not advanced. + * g_mount_operation_set_domain: + * @op: a #GMountOperation. + * @domain: the domain to set. * - * Returns: (transfer full): the value of the current attribute - * Since: 2.32 + * Sets the mount operation's domain. */ /** - * g_menu_attribute_iter_next: - * @iter: a #GMenuAttributeIter - * - * Attempts to advance the iterator to the next (possibly first) - * attribute. + * g_mount_operation_set_password: + * @op: a #GMountOperation. + * @password: password to set. * - * %TRUE is returned on success, or %FALSE if there are no more - * attributes. + * Sets the mount operation's password to @password. + */ + + +/** + * g_mount_operation_set_password_save: + * @op: a #GMountOperation. + * @save: a set of #GPasswordSave flags. * - * 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). + * Sets the state of saving passwords for the mount operation. + */ + + +/** + * g_mount_operation_set_username: + * @op: a #GMountOperation. + * @username: input username. * - * Returns: %TRUE on success, or %FALSE when there are no more attributes - * Since: 2.32 + * Sets the user name within @op to @username. */ /** - * g_menu_freeze: - * @menu: a #GMenu + * g_mount_remount: + * @mount: a #GMount. + * @flags: flags affecting the operation + * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid + * user interaction. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Marks @menu as frozen. + * 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. * - * 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. + * 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_mount_remount_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * This function causes g_menu_model_is_mutable() to begin returning - * %FALSE, which has some positive performance implications. + * Finishes remounting a mount. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * Since: 2.32 + * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise. */ /** - * g_menu_insert: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL + * g_mount_shadow: + * @mount: A #GMount. * - * 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. + * 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. * - * Since: 2.32 + * Since: 2.20 */ /** - * g_menu_insert_item: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @item: the #GMenuItem to insert + * g_mount_unmount: + * @mount: a #GMount. + * @flags: flags affecting the operation + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Inserts @item into @menu. + * 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. * - * 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. + * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead. + */ + + +/** + * g_mount_unmount_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * 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). + * Finishes unmounting a mount. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * You should probably just free @item once you're done. + * 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: (nullable): a #GMountOperation or %NULL to avoid + * user interaction. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * 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. + * 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. * - * Since: 2.32 + * Since: 2.22 */ /** - * g_menu_insert_section: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section + * 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. * - * 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. + * Finishes unmounting a mount. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * Since: 2.32 + * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. + * Since: 2.22 */ /** - * g_menu_insert_submenu: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu + * g_mount_unshadow: + * @mount: A #GMount. * - * 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. + * 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. * - * Since: 2.32 + * Since: 2.20 */ /** - * 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 + * g_native_socket_address_new: + * @native: a native address object + * @len: the length of @native, in bytes * - * Queries the named @attribute on @menu_item. + * Creates a new #GNativeSocketAddress for @native and @len. * - * 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: a new #GNativeSocketAddress + * Since: 2.46 + */ + + +/** + * g_network_address_get_hostname: + * @addr: a #GNetworkAddress * - * 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. + * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, + * depending on what @addr was created with. * - * Returns: %TRUE if the named attribute was found with the expected - * type - * Since: 2.34 + * Returns: @addr's hostname + * Since: 2.22 */ /** - * g_menu_item_get_attribute_value: - * @menu_item: a #GMenuItem - * @attribute: the attribute name to query - * @expected_type: (nullable): the expected type of the attribute - * - * Queries the named @attribute on @menu_item. + * g_network_address_get_port: + * @addr: a #GNetworkAddress * - * 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. + * Gets @addr's port number * - * Returns: (transfer full): the attribute value, or %NULL - * Since: 2.34 + * Returns: @addr's port (which may be 0) + * Since: 2.22 */ /** - * g_menu_item_get_link: - * @menu_item: a #GMenuItem - * @link: the link name to query + * g_network_address_get_scheme: + * @addr: a #GNetworkAddress * - * Queries the named @link on @menu_item. + * Gets @addr's scheme * - * Returns: (transfer full): the link, or %NULL - * Since: 2.34 + * Returns: @addr's scheme (%NULL if not built from URI) + * Since: 2.26 */ /** - * g_menu_item_new: - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL - * - * Creates a new #GMenuItem. + * g_network_address_new: + * @hostname: the hostname + * @port: the port * - * If @label is non-%NULL it is used to set the "label" attribute of the - * new item. + * Creates a new #GSocketConnectable for connecting to the given + * @hostname and @port. * - * 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. + * 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: a new #GMenuItem - * Since: 2.32 + * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress + * Since: 2.22 */ /** - * g_menu_item_new_from_model: - * @model: a #GMenuModel - * @item_index: the index of an item in @model + * g_network_address_new_loopback: + * @port: the port * - * Creates a #GMenuItem as an exact copy of an existing menu item in a - * #GMenuModel. + * 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. * - * @item_index must be valid (ie: be sure to call - * g_menu_model_get_n_items() first). + * 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`. * - * Returns: a new #GMenuItem. - * Since: 2.34 + * g_network_address_get_hostname() will always return `localhost` for + * #GNetworkAddresses created with this constructor. + * + * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress + * Since: 2.44 */ /** - * g_menu_item_new_section: - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section - * - * Creates a new #GMenuItem representing a section. - * - * This is a convenience API around g_menu_item_new() and - * g_menu_item_set_section(). + * 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 * - * 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. + * Creates a new #GSocketConnectable for connecting to the given + * @hostname and @port. May fail and return %NULL in case + * parsing @host_and_port fails. * - * 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. + * @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. * - * 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". + * If no port is specified in @host_and_port then @default_port will be + * used as the port number to connect to. * - * 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: - * |[ - * - *
- * - * - *
- *
- * - * - * - *
- * - * ]| + * 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 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 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: a new #GMenuItem - * Since: 2.32 + * Returns: (transfer full) (type GNetworkAddress): the new + * #GNetworkAddress, or %NULL on error + * Since: 2.22 */ /** - * g_menu_item_new_submenu: - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu + * 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 #GMenuItem representing a submenu. + * Creates a new #GSocketConnectable for connecting to the given + * @uri. May fail and return %NULL in case parsing @uri fails. * - * This is a convenience API around g_menu_item_new() and - * g_menu_item_set_submenu(). + * Using this rather than g_network_address_new() or + * g_network_address_parse() allows #GSocketClient to determine + * when to use application-specific proxy protocols. * - * Returns: a new #GMenuItem - * Since: 2.32 + * Returns: (transfer full) (type GNetworkAddress): the new + * #GNetworkAddress, or %NULL on error + * Since: 2.26 */ /** - * g_menu_item_set_action_and_target: - * @menu_item: a #GMenuItem - * @action: (nullable): the name of the action for this item - * @format_string: (nullable): a GVariant format string - * @...: positional parameters, as per @format_string - * - * Sets or unsets the "action" and "target" attributes of @menu_item. - * - * 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. + * g_network_monitor_base_add_network: + * @monitor: the #GNetworkMonitorBase + * @network: a #GInetAddressMask * - * See also g_menu_item_set_action_and_target_value() for a - * description of the semantics of the action and target attributes. + * Adds @network to @monitor's list of available networks. * * Since: 2.32 */ /** - * g_menu_item_set_action_and_target_value: - * @menu_item: a #GMenuItem - * @action: (nullable): the name of the action for this item - * @target_value: (nullable): a #GVariant to use as the action target - * - * Sets or unsets the "action" and "target" attributes of @menu_item. - * - * 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. + * g_network_monitor_base_remove_network: + * @monitor: the #GNetworkMonitorBase + * @network: a #GInetAddressMask * - * 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. + * Removes @network from @monitor's list of available networks. * * Since: 2.32 */ /** - * g_menu_item_set_attribute: - * @menu_item: a #GMenuItem - * @attribute: the attribute to set - * @format_string: (nullable): a #GVariant format string, or %NULL - * @...: positional parameters, as per @format_string - * - * 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. - * - * 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. + * g_network_monitor_base_set_networks: + * @monitor: the #GNetworkMonitorBase + * @networks: (array length=length): an array of #GInetAddressMask + * @length: length of @networks * - * Since: 2.32 + * Drops @monitor's current list of available networks and replaces + * it with @networks. */ /** - * g_menu_item_set_attribute_value: - * @menu_item: a #GMenuItem - * @attribute: the attribute to set - * @value: (nullable): a #GVariant to use as the value, or %NULL - * - * Sets or unsets an attribute on @menu_item. + * g_network_monitor_can_reach: + * @monitor: a #GNetworkMonitor + * @connectable: a #GSocketConnectable + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * 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. + * Attempts to determine whether or not the host pointed to by + * @connectable can be reached, without actually trying to connect to + * it. * - * must consist only of lowercase - * ASCII characters, digits and '-'. + * 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 @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. + * 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). * - * See also g_menu_item_set_attribute() for a more convenient way to do - * the same. + * 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_menu_item_set_detailed_action: - * @menu_item: a #GMenuItem - * @detailed_action: the "detailed" action string + * g_network_monitor_can_reach_async: + * @monitor: a #GNetworkMonitor + * @connectable: a #GSocketConnectable + * @cancellable: (nullable): 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 * - * Sets the "action" and possibly the "target" attribute of @menu_item. + * Asynchronously attempts to determine whether or not the host + * pointed to by @connectable can be reached, without actually + * trying to connect to it. * - * The format of @detailed_action is the same format parsed by - * g_action_parse_detailed_name(). + * For more details, see g_network_monitor_can_reach(). * - * 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. + * 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_network_monitor_can_reach_finish: + * @monitor: a #GNetworkMonitor + * @result: a #GAsyncResult + * @error: return location for errors, or %NULL * - * See also g_menu_item_set_action_and_target_value() for a description of - * the semantics of the action and target attributes. + * Finishes an async network connectivity test. + * See g_network_monitor_can_reach_async(). * - * Since: 2.32 + * Returns: %TRUE if network is reachable, %FALSE if not. */ /** - * g_menu_item_set_icon: - * @menu_item: a #GMenuItem - * @icon: a #GIcon, or %NULL + * g_network_monitor_get_connectivity: + * @monitor: the #GNetworkMonitor * - * Sets (or unsets) the icon on @menu_item. + * Gets a more detailed networking state than + * g_network_monitor_get_network_available(). * - * 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. + * If #GNetworkMonitor:network-available is %FALSE, then the + * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL. * - * This API is only intended for use with "noun" menu items; things like - * bookmarks or applications in an "Open With" menu. Don't use it on - * menu items corresponding to verbs (eg: stock icons for 'Save' or - * 'Quit'). + * If #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). * - * If @icon is %NULL then the icon is unset. + * 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. * - * Since: 2.38 + * Returns: the network connectivity state + * Since: 2.44 */ /** - * g_menu_item_set_label: - * @menu_item: a #GMenuItem - * @label: (nullable): the label to set, or %NULL to unset - * - * Sets or unsets the "label" attribute of @menu_item. + * g_network_monitor_get_default: * - * 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. + * Gets the default #GNetworkMonitor for the system. * + * Returns: (transfer none): a #GNetworkMonitor * Since: 2.32 */ /** - * g_menu_item_set_link: - * @menu_item: a #GMenuItem - * @link: type of link to establish or unset - * @model: (nullable): the #GMenuModel to link to (or %NULL to unset) - * - * Creates a link from @menu_item to @model if non-%NULL, or unsets it. + * g_network_monitor_get_network_available: + * @monitor: the #GNetworkMonitor * - * 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. + * 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: whether the network is available * Since: 2.32 */ /** - * g_menu_item_set_section: - * @menu_item: a #GMenuItem - * @section: (nullable): a #GMenuModel, or %NULL - * - * Sets or unsets the "section" link of @menu_item to @section. + * g_network_monitor_get_network_metered: + * @monitor: the #GNetworkMonitor * - * 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. + * Checks if the network is metered. + * See #GNetworkMonitor:network-metered for more details. * - * Since: 2.32 + * Returns: whether the connection is metered + * Since: 2.46 */ /** - * g_menu_item_set_submenu: - * @menu_item: a #GMenuItem - * @submenu: (nullable): a #GMenuModel, or %NULL - * - * Sets or unsets the "submenu" link of @menu_item to @submenu. - * - * If @submenu is non-%NULL, it is linked to. If it is %NULL then the - * link is unset. + * g_network_service_get_domain: + * @srv: a #GNetworkService * - * The effect of having one menu appear as a submenu of another is - * exactly as it sounds. + * Gets the domain that @srv serves. This might be either UTF-8 or + * ASCII-encoded, depending on what @srv was created with. * - * Since: 2.32 + * Returns: @srv's domain name + * Since: 2.22 */ /** - * g_menu_link_iter_get_name: - * @iter: a #GMenuLinkIter - * - * Gets the name of the link at the current iterator position. + * g_network_service_get_protocol: + * @srv: a #GNetworkService * - * The iterator is not advanced. + * Gets @srv's protocol name (eg, "tcp"). * - * Returns: the type of the link - * Since: 2.32 + * Returns: @srv's protocol name + * Since: 2.22 */ /** - * g_menu_link_iter_get_next: - * @iter: a #GMenuLinkIter - * @out_link: (out) (optional) (transfer none): the name of the link - * @value: (out) (optional) (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(). + * g_network_service_get_scheme: + * @srv: a #GNetworkService * - * First the iterator is advanced to the next (possibly first) link. - * If that fails, then %FALSE is returned and there are no other effects. + * Get's the URI scheme used to resolve proxies. By default, the service name + * is used as scheme. * - * 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. + * Returns: @srv's scheme name + * Since: 2.26 + */ + + +/** + * g_network_service_get_service: + * @srv: a #GNetworkService * - * 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. + * Gets @srv's service name (eg, "ldap"). * - * Returns: %TRUE on success, or %FALSE if there is no additional link - * Since: 2.32 + * Returns: @srv's service name + * Since: 2.22 */ /** - * g_menu_link_iter_get_value: - * @iter: a #GMenuLinkIter - * - * Gets the linked #GMenuModel at the current iterator position. + * 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 * - * The iterator is not advanced. + * Creates a new #GNetworkService representing the given @service, + * @protocol, and @domain. This will initially be unresolved; use the + * #GSocketConnectable interface to resolve it. * - * Returns: (transfer full): the #GMenuModel that is linked to - * Since: 2.32 + * Returns: (transfer full) (type GNetworkService): a new #GNetworkService + * Since: 2.22 */ /** - * g_menu_link_iter_next: - * @iter: a #GMenuLinkIter + * g_network_service_set_scheme: + * @srv: a #GNetworkService + * @scheme: a URI scheme * - * Attempts to advance the iterator to the next (possibly first) - * link. + * Set's the URI scheme used to resolve proxies. By default, the service name + * is used as scheme. * - * %TRUE is returned on success, or %FALSE if there are no more links. + * Since: 2.26 + */ + + +/** + * g_networking_init: * - * 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). + * 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, or %FALSE when there are no more links - * Since: 2.32 + * Since: 2.36 */ /** - * 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 + * g_notification_add_button: + * @notification: a #GNotification + * @label: label of the button + * @detailed_action: a detailed action name * - * Queries item at position @item_index in @model for the attribute - * specified by @attribute. + * 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. * - * 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. + * See g_action_parse_detailed_name() for a description of the format + * for @detailed_action. * - * 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. + * Since: 2.40 + */ + + +/** + * g_notification_add_button_with_target: (skip) + * @notification: a #GNotification + * @label: label of the button + * @action: an action name + * @target_format: (nullable): a #GVariant format string, or %NULL + * @...: positional parameters, as determined by @target_format * - * 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. + * Adds a button to @notification that activates @action when clicked. + * @action must be an application-wide action (it must start with "app."). * - * Returns: %TRUE if the named attribute was found with the expected - * type - * Since: 2.32 + * 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_menu_model_get_item_attribute_value: - * @model: a #GMenuModel - * @item_index: the index of the item - * @attribute: the attribute to query - * @expected_type: (nullable): the expected type of the attribute, or - * %NULL + * 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: (nullable): a #GVariant to use as @action's parameter, or %NULL * - * Queries the item at position @item_index in @model for the attribute - * specified by @attribute. + * Adds a button to @notification that activates @action when clicked. + * @action must be an application-wide action (it must start with "app."). * - * 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. + * If @target is non-%NULL, @action will be activated with @target as + * its parameter. * - * If the attribute exists and matches @expected_type (or if the - * expected type is unspecified) then the value is returned. + * Since: 2.40 + */ + + +/** + * g_notification_new: + * @title: the title of the notification * - * If the attribute does not exist, or does not match the expected type - * then %NULL is returned. + * Creates a new #GNotification with @title as its title. * - * Returns: (transfer full): the value of the attribute - * Since: 2.32 + * 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_menu_model_get_item_link: - * @model: a #GMenuModel - * @item_index: the index of the item - * @link: the link to query - * - * Queries the item at position @item_index in @model for the link - * specified by @link. + * g_notification_set_body: + * @notification: a #GNotification + * @body: (nullable): the new body for @notification, or %NULL * - * If the link exists, the linked #GMenuModel is returned. If the link - * does not exist, %NULL is returned. + * Sets the body of @notification to @body. * - * Returns: (transfer full): the linked #GMenuModel, or %NULL - * Since: 2.32 + * Since: 2.40 */ /** - * g_menu_model_get_n_items: - * @model: a #GMenuModel + * g_notification_set_default_action: + * @notification: a #GNotification + * @detailed_action: a detailed action name + * + * Sets the default action of @notification to @detailed_action. This + * action is activated when the notification is clicked on. + * + * The action in @detailed_action must be an application-wide action (it + * must start with "app."). If @detailed_action contains a target, the + * given action will be activated with that target as its parameter. + * See g_action_parse_detailed_name() for a description of the format + * for @detailed_action. * - * Query the number of items in @model. + * When no default action is set, the application that the notification + * was sent on is activated. * - * Returns: the number of items - * Since: 2.32 + * Since: 2.40 */ /** - * g_menu_model_is_mutable: - * @model: a #GMenuModel + * g_notification_set_default_action_and_target: (skip) + * @notification: a #GNotification + * @action: an action name + * @target_format: (nullable): a #GVariant format string, or %NULL + * @...: positional parameters, as determined by @target_format * - * Queries if @model is mutable. + * 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."). * - * An immutable #GMenuModel will never emit the #GMenuModel::items-changed - * signal. Consumers of the model may make optimisations accordingly. + * 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 model is mutable (ie: "items-changed" may be - * emitted). - * Since: 2.32 + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 */ /** - * 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. + * 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: (nullable): a #GVariant to use as @action's parameter, or %NULL * - * 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. + * 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."). * - * 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. + * If @target is non-%NULL, @action will be activated with @target as + * its parameter. * - * 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. + * When no default action is set, the application that the notification + * was sent on is activated. * - * Since: 2.32 + * Since: 2.40 */ /** - * 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_notification_set_icon: + * @notification: a #GNotification + * @icon: the icon to be shown in @notification, as a #GIcon * - * You must free the iterator with g_object_unref() when you are done. + * Sets the icon of @notification to @icon. * - * Returns: (transfer full): a new #GMenuAttributeIter - * Since: 2.32 + * Since: 2.40 */ /** - * 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. - * - * You must free the iterator with g_object_unref() when you are done. + * g_notification_set_priority: + * @notification: a #GNotification + * @priority: a #GNotificationPriority * - * Returns: (transfer full): a new #GMenuLinkIter - * Since: 2.32 + * Sets the priority of @notification to @priority. See + * #GNotificationPriority for possible values. */ /** - * g_menu_new: - * - * Creates a new #GMenu. + * g_notification_set_title: + * @notification: a #GNotification + * @title: the new title for @notification * - * The new menu has no items. + * Sets the title of @notification to @title. * - * Returns: a new #GMenu - * Since: 2.32 + * Since: 2.40 */ /** - * g_menu_prepend: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL + * g_notification_set_urgent: + * @notification: a #GNotification + * @urgent: %TRUE if @notification is urgent * - * 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. + * Deprecated in favor of g_notification_set_priority(). * - * Since: 2.32 + * Since: 2.40 */ /** - * g_menu_prepend_item: - * @menu: a #GMenu - * @item: a #GMenuItem to prepend + * g_null_settings_backend_new: * - * Prepends @item to the start of @menu. + * Creates a readonly #GSettingsBackend. * - * See g_menu_insert_item() for more information. + * This backend does not allow changes to settings, so all settings + * will always have their default values. * - * Since: 2.32 + * Returns: (transfer full): a newly created #GSettingsBackend + * Since: 2.28 */ /** - * g_menu_prepend_section: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section - * - * 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. + * g_output_stream_clear_pending: + * @stream: output stream * - * Since: 2.32 + * Clears the pending flag on @stream. */ /** - * g_menu_prepend_submenu: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu + * g_output_stream_close: + * @stream: A #GOutputStream. + * @cancellable: (nullable): optional cancellable object + * @error: location to store the error occurring, or %NULL to ignore * - * 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. + * Closes the stream, releasing resources related to it. * - * Since: 2.32 - */ - - -/** - * g_menu_remove: - * @menu: a #GMenu - * @position: the position of the item to remove + * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. + * Closing a stream multiple times will not return an error. * - * Removes an item from the menu. + * Closing a stream will automatically flush any outstanding buffers in the + * stream. * - * @position gives the index of the item to remove. + * 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. * - * 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. + * 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. * - * 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). + * 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. * - * Since: 2.32 + * 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_menu_remove_all: - * @menu: a #GMenu + * g_output_stream_close_async: + * @stream: A #GOutputStream. + * @io_priority: the io priority of the request. + * @cancellable: (nullable): optional cancellable object + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Removes all items in the menu. + * 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. * - * Since: 2.38 + * For behaviour details see g_output_stream_close(). + * + * 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_mount_can_eject: - * @mount: a #GMount. + * g_output_stream_close_finish: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Checks if @mount can be ejected. + * Closes an output stream. * - * Returns: %TRUE if the @mount can be ejected. + * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. */ /** - * g_mount_can_unmount: - * @mount: a #GMount. + * g_output_stream_flush: + * @stream: a #GOutputStream. + * @cancellable: (nullable): optional cancellable object + * @error: location to store the error occurring, or %NULL to ignore * - * Checks if @mount can be unmounted. + * 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. * - * Returns: %TRUE if the @mount can be unmounted. + * This function is optional for inherited classes. + * + * 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, %FALSE on error */ /** - * g_mount_eject: - * @mount: a #GMount. - * @flags: flags affecting the unmount if required for eject + * g_output_stream_flush_async: + * @stream: a #GOutputStream. + * @io_priority: the io priority of the request. * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * 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. + * Forces an asynchronous write of all user-space buffered data for + * the given @stream. + * For behaviour details see g_output_stream_flush(). * - * Deprecated: 2.22: Use g_mount_eject_with_operation() instead. + * 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_mount_eject_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. + * g_output_stream_flush_finish: + * @stream: a #GOutputStream. + * @result: a GAsyncResult. * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * ignore. * - * Finishes ejecting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. + * Finishes flushing an output stream. * - * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. - * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead. + * Returns: %TRUE if flush operation succeeded, %FALSE otherwise. */ /** - * g_mount_eject_with_operation: - * @mount: a #GMount. - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_output_stream_has_pending: + * @stream: a #GOutputStream. * - * 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. + * Checks if an output stream has pending actions. * - * Since: 2.22 + * Returns: %TRUE if @stream has pending actions. */ /** - * 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_output_stream_is_closed: + * @stream: a #GOutputStream. * - * Finishes ejecting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. + * Checks if an output stream has already been closed. * - * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. - * Since: 2.22 + * Returns: %TRUE if @stream is closed. %FALSE otherwise. */ /** - * g_mount_get_default_location: - * @mount: a #GMount. + * g_output_stream_is_closing: + * @stream: a #GOutputStream. * - * 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). + * 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. * - * Returns: (transfer full): a #GFile. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * Returns: %TRUE if @stream is being closed. %FALSE otherwise. + * Since: 2.24 */ /** - * g_mount_get_drive: - * @mount: a #GMount. + * g_output_stream_printf: + * @stream: a #GOutputStream. + * @bytes_written: (out) (optional): location to store the number of bytes that was + * written to the stream + * @cancellable: (nullable): 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 * - * Gets the drive for the @mount. + * 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. * - * This is a convenience method for getting the #GVolume and then - * using that object to get the #GDrive. + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. * - * 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. + * 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_mount_get_icon: - * @mount: a #GMount. + * g_output_stream_set_pending: + * @stream: a #GOutputStream. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets the icon for @mount. + * 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 #GIcon. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * Returns: %TRUE if pending was previously unset and is now set. */ /** - * g_mount_get_name: - * @mount: a #GMount. + * g_output_stream_splice: + * @stream: a #GOutputStream. + * @source: a #GInputStream. + * @flags: a set of #GOutputStreamSpliceFlags. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets the name of @mount. + * Splices an input stream into an output stream. * - * Returns: the name for the given @mount. - * The returned string should be freed with g_free() - * when no longer needed. + * 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_mount_get_root: - * @mount: a #GMount. + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. * - * Gets the root directory on @mount. + * 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: (transfer full): a #GFile. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * For the synchronous, blocking version of this function, see + * g_output_stream_splice(). */ /** - * g_mount_get_sort_key: - * @mount: A #GMount. + * g_output_stream_splice_finish: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets the sort key for @mount, if any. + * Finishes an asynchronous stream splice operation. * - * Returns: Sorting key for @mount or %NULL if no such key is available. - * 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_mount_get_symbolic_icon: - * @mount: a #GMount. + * g_output_stream_vprintf: + * @stream: a #GOutputStream. + * @bytes_written: (out) (optional): location to store the number of bytes that was + * written to the stream + * @cancellable: (nullable): 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 * - * Gets the symbolic icon for @mount. + * 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. * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - * Since: 2.34 + * 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_mount_get_uuid: - * @mount: a #GMount. + * 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: (nullable): optional cancellable object + * @error: location to store the error occurring, or %NULL to ignore * - * 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. + * Tries to write @count bytes from @buffer into the stream. Will block + * during the operation. * - * 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. + * 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). + * + * 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. + * + * Returns: Number of bytes written, or -1 on error */ /** - * g_mount_get_volume: - * @mount: a #GMount. + * 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) (optional): location to store the number of bytes that was + * written to the stream + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Gets the volume for the @mount. + * Tries to write @count bytes from @buffer into the stream. Will block + * during the operation. * - * 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. + * This function is similar to g_output_stream_write(), except it tries to + * write as many bytes as requested, only stopping on an error. + * + * On a successful write of @count bytes, %TRUE is returned, and @bytes_written + * is set to @count. + * + * 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(). + * + * Returns: %TRUE on success, %FALSE if there was an error */ /** - * 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 + * 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: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback - * @user_data: user data passed to @callback + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * 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. + * Request an asynchronous write of @count bytes from @buffer into + * the stream. When the operation is finished @callback will be called. + * You can then call g_output_stream_write_all_finish() to get the result of the + * operation. * - * This is 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. + * This is the asynchronous version of g_output_stream_write_all(). * - * Since: 2.18 + * Call g_output_stream_write_all_finish() to collect the result. + * + * Any outstanding I/O request with higher priority (lower numerical + * value) will be executed before an outstanding request with lower + * priority. Default priority is %G_PRIORITY_DEFAULT. + * + * Note that no copy of @buffer will be made, so it must stay valid + * until @callback is called. + * + * Since: 2.44 */ /** - * g_mount_guess_content_type_finish: - * @mount: a #GMount + * g_output_stream_write_all_finish: + * @stream: a #GOutputStream * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore + * @bytes_written: (out) (optional): location to store the number of bytes that was written to the stream + * @error: a #GError location to store the error occurring, or %NULL to ignore. * - * Finishes 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. + * Finishes an asynchronous stream write operation started with + * g_output_stream_write_all_async(). * - * 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 + * As a special exception to the normal conventions for functions that + * use #GError, if this function returns %FALSE (and sets @error) then + * @bytes_written will be set to the number of bytes that were + * successfully written before the error was encountered. This + * functionality is only available from C. If you need it from another + * language then you must write your own loop around + * g_output_stream_write_async(). + * + * Returns: %TRUE on success, %FALSE if there was an error + * Since: 2.44 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore - * @error: a #GError location to store the error occurring, or %NULL to - * ignore + * 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: (nullable): 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 * - * 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. + * 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. * - * This is an synchronous operation and as such may block doing IO; - * see g_mount_guess_content_type() for the asynchronous version. + * During an async request no other sync and async calls are allowed, + * and will result in %G_IO_ERROR_PENDING errors. * - * 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_is_shadowed: - * @mount: A #GMount. + * A value of @count larger than %G_MAXSSIZE will cause a + * %G_IO_ERROR_INVALID_ARGUMENT error. * - * Determines if @mount is shadowed. Applications or libraries should - * avoid displaying @mount in the user interface if it is shadowed. + * 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. * - * 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. + * 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. * - * 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 + * For the synchronous, blocking version of this function, see + * g_output_stream_write(). + * + * Note that no copy of @buffer will be made, so it must stay valid + * until @callback is called. See g_output_stream_write_bytes_async() + * for a #GBytes version that will automatically hold a reference to + * the contents (without copying) for the duration of the call. */ /** - * g_mount_operation_get_anonymous: - * @op: a #GMountOperation. + * g_output_stream_write_bytes: + * @stream: a #GOutputStream. + * @bytes: the #GBytes to write + * @cancellable: (nullable): optional cancellable object + * @error: location to store the error occurring, or %NULL to ignore * - * Check to see whether the mount operation is being used - * for an anonymous user. + * 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. * - * Returns: %TRUE if mount operation is anonymous. + * However, note that this function may still perform partial writes, + * just like g_output_stream_write(). If that occurs, to continue + * writing, you will need to create a new #GBytes containing just the + * remaining bytes, using g_bytes_new_from_bytes(). Passing the same + * #GBytes instance multiple times potentially can result in duplicated + * data in the output stream. + * + * Returns: Number of bytes written, or -1 on error */ /** - * g_mount_operation_get_choice: - * @op: a #GMountOperation. + * g_output_stream_write_bytes_async: + * @stream: A #GOutputStream. + * @bytes: The bytes to write + * @io_priority: the io priority of the request. + * @cancellable: (nullable): 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 a choice from the mount operation. + * 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. * - * Returns: an integer containing an index of the user's choice from - * the choice's list, or %0. + * However, note that this function may still perform partial writes, + * just like g_output_stream_write_async(). If that occurs, to continue + * writing, you will need to create a new #GBytes containing just the + * remaining bytes, using g_bytes_new_from_bytes(). Passing the same + * #GBytes instance multiple times potentially can result in duplicated + * data in the output stream. + * + * For the synchronous, blocking version of this function, see + * g_output_stream_write_bytes(). */ /** - * g_mount_operation_get_domain: - * @op: a #GMountOperation. + * 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. * - * Gets the domain of the mount operation. + * Finishes a stream write-from-#GBytes operation. * - * Returns: a string set to the domain. + * Returns: a #gssize containing the number of bytes written to the stream. */ /** - * g_mount_operation_get_password: - * @op: a #GMountOperation. + * g_output_stream_write_finish: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets a password from the mount operation. + * Finishes a stream write operation. * - * Returns: a string containing the password within @op. + * Returns: a #gssize containing the number of bytes written to the stream. */ /** - * g_mount_operation_get_password_save: - * @op: a #GMountOperation. + * g_permission_acquire: + * @permission: a #GPermission instance + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a pointer to a %NULL #GError, or %NULL * - * Gets the state of saving passwords for the mount operation. + * Attempts to acquire the permission represented by @permission. * - * Returns: a #GPasswordSave flag. - */ - - -/** - * g_mount_operation_get_username: - * @op: a #GMountOperation. + * 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. * - * Get the user name from the mount operation. + * You should check with g_permission_get_can_acquire() before calling + * this function. * - * Returns: a string containing the user name. + * If the permission is acquired then %TRUE is returned. Otherwise, + * %FALSE is returned and @error is set appropriately. + * + * 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_mount_operation_new: + * g_permission_acquire_async: + * @permission: a #GPermission instance + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: the #GAsyncReadyCallback to call when done + * @user_data: the user data to pass to @callback * - * Creates a new mount operation. + * Attempts to acquire the permission represented by @permission. * - * Returns: a #GMountOperation. + * This is the first half of the asynchronous version of + * g_permission_acquire(). + * + * Since: 2.26 */ /** - * g_mount_operation_reply: - * @op: a #GMountOperation - * @result: a #GMountOperationResult + * g_permission_acquire_finish: + * @permission: a #GPermission instance + * @result: the #GAsyncResult given to the #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL * - * Emits the #GMountOperation::reply signal. + * Collects the result of attempting to acquire the permission + * represented by @permission. + * + * This is the second half of the asynchronous version of + * g_permission_acquire(). + * + * Returns: %TRUE if the permission was successfully acquired + * Since: 2.26 */ /** - * g_mount_operation_set_anonymous: - * @op: a #GMountOperation. - * @anonymous: boolean value. + * g_permission_get_allowed: + * @permission: a #GPermission instance * - * Sets the mount operation to use an anonymous user if @anonymous is %TRUE. + * 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. + * + * Returns: the value of the 'allowed' property + * Since: 2.26 */ /** - * g_mount_operation_set_choice: - * @op: a #GMountOperation. - * @choice: an integer. + * g_permission_get_can_acquire: + * @permission: a #GPermission instance * - * Sets a default choice for the mount operation. + * 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 */ /** - * g_mount_operation_set_domain: - * @op: a #GMountOperation. - * @domain: the domain to set. + * g_permission_get_can_release: + * @permission: a #GPermission instance * - * Sets the mount operation's domain. + * 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 + * Since: 2.26 */ /** - * g_mount_operation_set_password: - * @op: a #GMountOperation. - * @password: password to set. + * 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 * - * Sets the mount operation's password to @password. + * 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. + * + * GObject notify signals are generated, as appropriate. + * + * Since: 2.26 */ /** - * g_mount_operation_set_password_save: - * @op: a #GMountOperation. - * @save: a set of #GPasswordSave flags. + * g_permission_release: + * @permission: a #GPermission instance + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a pointer to a %NULL #GError, or %NULL * - * Sets the state of saving passwords for the mount operation. + * Attempts to release the permission represented by @permission. + * + * 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. + * + * You should check with g_permission_get_can_release() before calling + * this function. + * + * If the permission is released then %TRUE is returned. Otherwise, + * %FALSE is returned and @error is set appropriately. + * + * 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. + * + * Returns: %TRUE if the permission was successfully released + * Since: 2.26 */ /** - * g_mount_operation_set_username: - * @op: a #GMountOperation. - * @username: input username. + * g_permission_release_async: + * @permission: a #GPermission instance + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: the #GAsyncReadyCallback to call when done + * @user_data: the user data to pass to @callback * - * Sets the user name within @op to @username. + * Attempts to release the permission represented by @permission. + * + * This is the first half of the asynchronous version of + * g_permission_release(). + * + * Since: 2.26 */ /** - * g_mount_remount: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_permission_release_finish: + * @permission: a #GPermission instance + * @result: the #GAsyncResult given to the #GAsyncReadyCallback + * @error: a pointer to a %NULL #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. + * Collects the result of attempting to release the permission + * represented by @permission. * - * 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. + * This is the second half of the asynchronous version of + * g_permission_release(). + * + * Returns: %TRUE if the permission was successfully released + * Since: 2.26 */ /** - * g_mount_remount_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_pollable_input_stream_can_poll: + * @stream: a #GPollableInputStream. * - * Finishes remounting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. + * 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. * - * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise. + * 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 if @stream is pollable, %FALSE if not. + * Since: 2.28 */ /** - * g_mount_shadow: - * @mount: A #GMount. + * g_pollable_input_stream_create_source: + * @stream: a #GPollableInputStream. + * @cancellable: (nullable): a #GCancellable, or %NULL * - * 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. + * 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. * - * Since: 2.20 + * 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: (transfer full): a new #GSource + * Since: 2.28 */ /** - * g_mount_unmount: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_pollable_input_stream_is_readable: + * @stream: a #GPollableInputStream. * - * 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. + * Checks if @stream can be read. * - * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead. + * 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 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_mount_unmount_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * 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: (nullable): a #GCancellable, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Finishes unmounting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. + * 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. * - * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. - * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead. + * 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 number of bytes read, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ /** - * g_mount_unmount_with_operation: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_pollable_output_stream_can_poll: + * @stream: a #GPollableOutputStream. * - * 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. + * 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. * - * Since: 2.22 + * 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 if @stream is pollable, %FALSE if not. + * Since: 2.28 */ /** - * 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_pollable_output_stream_create_source: + * @stream: a #GPollableOutputStream. + * @cancellable: (nullable): a #GCancellable, 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. + * 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. * - * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. - * Since: 2.22 + * 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): a new #GSource + * Since: 2.28 */ /** - * g_mount_unshadow: - * @mount: A #GMount. + * g_pollable_output_stream_is_writable: + * @stream: a #GPollableOutputStream. * - * 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. + * Checks if @stream can be written. * - * Since: 2.20 + * 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: %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_native_socket_address_new: - * @native: a native address object - * @len: the length of @native, in bytes + * 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: (nullable): a #GCancellable, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Creates a new #GNativeSocketAddress for @native and @len. + * 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. * - * Returns: a new #GNativeSocketAddress - * Since: 2.46 + * 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 number of bytes written, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ /** - * g_network_address_get_hostname: - * @addr: a #GNetworkAddress + * g_pollable_source_new: + * @pollable_stream: the stream associated with the new source * - * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, - * depending on what @addr was created with. + * 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. * - * Returns: @addr's hostname - * Since: 2.22 + * Returns: (transfer full): the new #GSource. + * Since: 2.28 */ /** - * g_network_address_get_port: - * @addr: a #GNetworkAddress + * g_pollable_source_new_full: + * @pollable_stream: (type GObject): the stream associated with the + * new source + * @child_source: (nullable): optional child source to attach + * @cancellable: (nullable): optional #GCancellable to attach * - * Gets @addr's port number + * 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. * - * Returns: @addr's port (which may be 0) - * Since: 2.22 + * Returns: (transfer full): the new #GSource. + * Since: 2.34 */ /** - * g_network_address_get_scheme: - * @addr: a #GNetworkAddress + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Gets @addr's scheme + * 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: @addr's scheme (%NULL if not built from URI) - * Since: 2.26 + * 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_network_address_new: - * @hostname: the hostname - * @port: the port + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * Creates a new #GSocketConnectable for connecting to the given - * @hostname and @port. + * 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. * - * 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. + * 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) (type GNetworkAddress): the new #GNetworkAddress - * Since: 2.22 + * Returns: the number of bytes written, or -1 on error. + * Since: 2.34 */ /** - * g_network_address_new_loopback: - * @port: the port + * 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: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore * - * 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. + * 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(). * - * 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`. + * On a successful write of @count bytes, %TRUE is returned, and + * @bytes_written is set to @count. * - * g_network_address_get_hostname() will always return `localhost` for - * #GNetworkAddresses created with this constructor. + * 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. * - * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress - * Since: 2.44 + * 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: %TRUE on success, %FALSE if there was an error + * Since: 2.34 */ /** - * 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. - * - * @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. + * 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 * - * If no port is specified in @host_and_port then @default_port will be - * used as the port number to connect to. + * Creates a #GAction corresponding to the value of property + * @property_name on @object. * - * 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 property must be existent and readable and writable (and not + * construct-only). * - * (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.) + * This function takes a reference on @object and doesn't release it + * until the action is destroyed. * - * Returns: (transfer full) (type GNetworkAddress): the new - * #GNetworkAddress, or %NULL on error - * Since: 2.22 + * Returns: a new #GPropertyAction + * Since: 2.38 */ /** - * 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_proxy_address_get_destination_hostname: + * @proxy: a #GProxyAddress * - * Using this rather than g_network_address_new() or - * g_network_address_parse() allows #GSocketClient to determine - * when to use application-specific proxy protocols. + * 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: (transfer full) (type GNetworkAddress): the new - * #GNetworkAddress, or %NULL on error + * Returns: the @proxy's destination hostname * Since: 2.26 */ /** - * g_network_monitor_base_add_network: - * @monitor: the #GNetworkMonitorBase - * @network: a #GInetAddressMask + * g_proxy_address_get_destination_port: + * @proxy: a #GProxyAddress * - * Adds @network to @monitor's list of available networks. + * 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. * - * Since: 2.32 + * Returns: the @proxy's destination port + * Since: 2.26 */ /** - * g_network_monitor_base_remove_network: - * @monitor: the #GNetworkMonitorBase - * @network: a #GInetAddressMask + * g_proxy_address_get_destination_protocol: + * @proxy: a #GProxyAddress * - * Removes @network from @monitor's list of available networks. + * 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_network_monitor_base_set_networks: - * @monitor: the #GNetworkMonitorBase - * @networks: (array length=length): an array of #GInetAddressMask - * @length: length of @networks + * g_proxy_address_get_password: + * @proxy: a #GProxyAddress * - * Drops @monitor's current list of available networks and replaces - * it with @networks. + * Gets @proxy's password. + * + * Returns: the @proxy's password + * Since: 2.26 */ /** - * g_network_monitor_can_reach: - * @monitor: a #GNetworkMonitor - * @connectable: a #GSocketConnectable - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Attempts to determine whether or not the host pointed to by - * @connectable can be reached, without actually trying to connect to - * it. - * - * 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). + * g_proxy_address_get_protocol: + * @proxy: a #GProxyAddress * - * 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(). + * Gets @proxy's protocol. eg, "socks" or "http" * - * Returns: %TRUE if @connectable is reachable, %FALSE if not. - * Since: 2.32 + * Returns: the @proxy's protocol + * Since: 2.26 */ /** - * g_network_monitor_can_reach_async: - * @monitor: a #GNetworkMonitor - * @connectable: a #GSocketConnectable - * @cancellable: (nullable): 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 - * - * Asynchronously attempts to determine whether or not the host - * pointed to by @connectable can be reached, without actually - * trying to connect to it. + * g_proxy_address_get_uri: + * @proxy: a #GProxyAddress * - * For more details, see g_network_monitor_can_reach(). + * Gets the proxy URI that @proxy was constructed from. * - * 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. + * Returns: the @proxy's URI, or %NULL if unknown + * Since: 2.34 */ /** - * g_network_monitor_can_reach_finish: - * @monitor: a #GNetworkMonitor - * @result: a #GAsyncResult - * @error: return location for errors, or %NULL + * g_proxy_address_get_username: + * @proxy: a #GProxyAddress * - * Finishes an async network connectivity test. - * See g_network_monitor_can_reach_async(). + * Gets @proxy's username. * - * Returns: %TRUE if network is reachable, %FALSE if not. + * Returns: the @proxy's username + * Since: 2.26 */ /** - * g_network_monitor_get_connectivity: - * @monitor: the #GNetworkMonitor - * - * Gets a more detailed networking state than - * g_network_monitor_get_network_available(). - * - * If #GNetworkMonitor:network-available is %FALSE, then the - * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL. + * 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: (nullable): The username to authenticate to the proxy server + * (or %NULL). + * @password: (nullable): The password to authenticate to the proxy server + * (or %NULL). * - * 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). + * Creates a new #GProxyAddress for @inetaddr with @protocol that should + * tunnel through @dest_hostname and @dest_port. * - * 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. + * (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.) * - * Returns: the network connectivity state - * Since: 2.44 + * Returns: a new #GProxyAddress + * Since: 2.26 */ /** - * g_network_monitor_get_default: + * g_proxy_connect: + * @proxy: a #GProxy + * @connection: a #GIOStream + * @proxy_address: a #GProxyAddress + * @cancellable: (nullable): a #GCancellable + * @error: return #GError * - * Gets the default #GNetworkMonitor for the system. + * 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. * - * Returns: (transfer none): a #GNetworkMonitor - * 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_network_monitor_get_network_available: - * @monitor: the #GNetworkMonitor + * g_proxy_connect_async: + * @proxy: a #GProxy + * @connection: a #GIOStream + * @proxy_address: a #GProxyAddress + * @cancellable: (nullable): a #GCancellable + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): callback data * - * 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. + * Asynchronous version of g_proxy_connect(). * - * Returns: whether the network is available - * Since: 2.32 + * Since: 2.26 */ /** - * g_network_monitor_get_network_metered: - * @monitor: the #GNetworkMonitor + * g_proxy_connect_finish: + * @proxy: a #GProxy + * @result: a #GAsyncResult + * @error: return #GError * - * Checks if the network is metered. - * See #GNetworkMonitor:network-metered for more details. + * See g_proxy_connect(). * - * Returns: whether the connection is metered - * Since: 2.46 + * Returns: (transfer full): a #GIOStream. + * Since: 2.26 */ /** - * g_network_service_get_domain: - * @srv: a #GNetworkService + * g_proxy_get_default_for_protocol: + * @protocol: the proxy protocol name (e.g. http, socks, etc) * - * Gets the domain that @srv serves. This might be either UTF-8 or - * ASCII-encoded, depending on what @srv was created with. + * Lookup "gio-proxy" extension point for a proxy implementation that supports + * specified protocol. * - * Returns: @srv's domain name - * Since: 2.22 + * Returns: (transfer full): return a #GProxy or NULL if protocol + * is not supported. + * Since: 2.26 */ /** - * g_network_service_get_protocol: - * @srv: a #GNetworkService + * g_proxy_resolver_get_default: * - * Gets @srv's protocol name (eg, "tcp"). + * Gets the default #GProxyResolver for the system. * - * Returns: @srv's protocol name - * Since: 2.22 + * Returns: (transfer none): the default #GProxyResolver. + * Since: 2.26 */ /** - * g_network_service_get_scheme: - * @srv: a #GNetworkService + * g_proxy_resolver_is_supported: + * @resolver: a #GProxyResolver * - * Get's the URI scheme used to resolve proxies. By default, the service name - * is used as scheme. + * 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.) * - * Returns: @srv's scheme name + * Returns: %TRUE if @resolver is supported. * Since: 2.26 */ /** - * g_network_service_get_service: - * @srv: a #GNetworkService + * g_proxy_resolver_lookup: + * @resolver: a #GProxyResolver + * @uri: a URI representing the destination to connect to + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Gets @srv's service name (eg, "ldap"). + * 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 `://[user[:password]@]host:port` or + * `direct://`, where could be http, rtsp, socks + * or other proxying protocol. * - * Returns: @srv's service name - * Since: 2.22 + * 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). + * + * `direct://` is used when no proxy is needed. + * Direct connection should not be attempted unless it is part of the + * returned array of proxies. + * + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). + * Since: 2.26 */ /** - * 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 + * g_proxy_resolver_lookup_async: + * @resolver: a #GProxyResolver + * @uri: a URI representing the destination to connect to + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * Creates a new #GNetworkService representing the given @service, - * @protocol, and @domain. This will initially be unresolved; use the - * #GSocketConnectable interface to resolve it. + * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more + * details. * - * Returns: (transfer full) (type GNetworkService): a new #GNetworkService - * Since: 2.22 + * Since: 2.26 */ /** - * g_network_service_set_scheme: - * @srv: a #GNetworkService - * @scheme: a URI scheme + * g_proxy_resolver_lookup_finish: + * @resolver: a #GProxyResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Set's the URI scheme used to resolve proxies. By default, the service name - * is used as scheme. + * 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) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ /** - * g_networking_init: + * g_proxy_supports_hostname: + * @proxy: a #GProxy * - * 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). + * 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(). * - * Since: 2.36 + * Returns: %TRUE if hostname resolution is supported. + * Since: 2.26 */ /** - * g_notification_add_button: - * @notification: a #GNotification - * @label: label of the button - * @detailed_action: a detailed action name + * g_remote_action_group_activate_action_full: + * @remote: a #GDBusActionGroup + * @action_name: the name of the action to activate + * @parameter: (nullable): the optional parameter to the activation + * @platform_data: the platform data to send * - * 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. + * Activates the remote action. * - * See g_action_parse_detailed_name() for a description of the format - * for @detailed_action. + * 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. * - * Since: 2.40 + * @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_notification_add_button_with_target: (skip) - * @notification: a #GNotification - * @label: label of the button - * @action: an action name - * @target_format: (nullable): a #GVariant format string, or %NULL - * @...: positional parameters, as determined by @target_format + * 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 * - * Adds a button to @notification that activates @action when clicked. - * @action must be an application-wide action (it must start with "app."). + * Changes the state of a remote action. * - * 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. + * 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. * - * Since: 2.40 + * @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_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: (nullable): a #GVariant to use as @action's parameter, or %NULL - * - * Adds a button to @notification that activates @action when clicked. - * @action must be an application-wide action (it must start with "app."). + * g_resolver_error_quark: * - * If @target is non-%NULL, @action will be activated with @target as - * its parameter. + * Gets the #GResolver Error Quark. * - * Since: 2.40 + * Returns: a #GQuark. + * Since: 2.22 */ /** - * g_notification_new: - * @title: the title of the notification - * - * Creates a new #GNotification with @title as its title. + * g_resolver_free_addresses: (skip) + * @addresses: a #GList of #GInetAddress * - * 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. + * 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: a new #GNotification instance - * Since: 2.40 + * Since: 2.22 */ /** - * g_notification_set_body: - * @notification: a #GNotification - * @body: (nullable): the new body for @notification, or %NULL + * g_resolver_free_targets: (skip) + * @targets: a #GList of #GSrvTarget * - * Sets the body of @notification to @body. + * 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.) * - * Since: 2.40 + * Since: 2.22 */ /** - * g_notification_set_default_action: - * @notification: a #GNotification - * @detailed_action: a detailed action name - * - * Sets the default action of @notification to @detailed_action. This - * action is activated when the notification is clicked on. - * - * The action in @detailed_action must be an application-wide action (it - * must start with "app."). If @detailed_action contains a target, the - * given action will be activated with that target as its parameter. - * See g_action_parse_detailed_name() for a description of the format - * for @detailed_action. + * g_resolver_get_default: * - * When no default action is set, the application that the notification - * was sent on is activated. + * 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. * - * Since: 2.40 + * Returns: (transfer full): the default #GResolver. + * Since: 2.22 */ /** - * g_notification_set_default_action_and_target: (skip) - * @notification: a #GNotification - * @action: an action name - * @target_format: (nullable): a #GVariant format string, or %NULL - * @...: positional parameters, as determined by @target_format + * g_resolver_lookup_by_address: + * @resolver: a #GResolver + * @address: the address to reverse-resolve + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: return location for a #GError, 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 (it must start with "app."). + * Synchronously reverse-resolves @address to determine its + * associated hostname. * - * 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. + * If the DNS resolution fails, @error (if non-%NULL) will be set to + * a value from #GResolverError. * - * When no default action is set, the application that the notification - * was sent on is activated. + * 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. * - * Since: 2.40 + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. + * Since: 2.22 */ /** - * 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: (nullable): a #GVariant to use as @action's parameter, or %NULL - * - * Sets the default action of @notification to @action. This action is - * activated when the notification is clicked on. It must be an - * application-wide action (start with "app."). - * - * If @target is non-%NULL, @action will be activated with @target as - * its parameter. + * g_resolver_lookup_by_address_async: + * @resolver: a #GResolver + * @address: the address to reverse-resolve + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * When no default action is set, the application that the notification - * was sent on is activated. + * 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. * - * Since: 2.40 + * Since: 2.22 */ /** - * g_notification_set_icon: - * @notification: a #GNotification - * @icon: the icon to be shown in @notification, as a #GIcon + * g_resolver_lookup_by_address_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Sets the icon of @notification to @icon. + * Retrieves the result of a previous call to + * g_resolver_lookup_by_address_async(). * - * Since: 2.40 + * 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: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. + * Since: 2.22 */ /** - * g_notification_set_priority: - * @notification: a #GNotification - * @priority: a #GNotificationPriority + * g_resolver_lookup_by_name: + * @resolver: a #GResolver + * @hostname: the hostname to look up + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Sets the priority of @notification to @priority. See - * #GNotificationPriority for possible values. + * 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()). + * + * 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(). + * + * 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 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_notification_set_title: - * @notification: a #GNotification - * @title: the new title for @notification + * g_resolver_lookup_by_name_async: + * @resolver: a #GResolver + * @hostname: the hostname to look up the address of + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * Sets the title of @notification to @title. + * 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. * - * Since: 2.40 + * Since: 2.22 */ /** - * g_notification_set_urgent: - * @notification: a #GNotification - * @urgent: %TRUE if @notification is urgent + * g_resolver_lookup_by_name_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Deprecated in favor of g_notification_set_priority(). + * Retrieves the result of a call to + * g_resolver_lookup_by_name_async(). * - * Since: 2.40 - * Deprecated: 2.42: Since 2.42, this has been deprecated in favour of - * g_notification_set_priority(). + * 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 GInetAddress) (transfer full): a #GList + * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() + * for more details. + * Since: 2.22 */ /** - * g_null_settings_backend_new: + * 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: (nullable): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Creates a readonly #GSettingsBackend. + * 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. * - * This backend does not allow changes to settings, so all settings - * will always have their default values. + * If the DNS resolution fails, @error (if non-%NULL) will be set to + * a value from #GResolverError and %NULL will be returned. * - * Returns: (transfer full): a newly created #GSettingsBackend - * Since: 2.28 + * 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_output_stream_clear_pending: - * @stream: output stream + * 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: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * Clears the pending flag on @stream. + * 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. + * + * Since: 2.34 */ /** - * g_output_stream_close: - * @stream: A #GOutputStream. - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore + * g_resolver_lookup_records_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Closes the stream, releasing resources related to it. + * 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. * - * 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 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. * - * Closing a stream will automatically flush any outstanding buffers in the - * stream. + * 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_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: (nullable): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * 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. + * 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. * - * 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 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.) * - * 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 the DNS resolution fails, @error (if non-%NULL) will be set to + * a value from #GResolverError and %NULL will be returned. * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * 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. + * 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 on success, %FALSE on failure + * 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_output_stream_close_async: - * @stream: A #GOutputStream. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): 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_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: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * For behaviour details see g_output_stream_close(). + * 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. * - * 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_output_stream_close_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_resolver_lookup_service_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Closes an output stream. + * Retrieves the result of a previous call to + * g_resolver_lookup_service_async(). * - * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. + * 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_output_stream_flush: - * @stream: a #GOutputStream. - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * 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. + * g_resolver_set_default: + * @resolver: the new default #GResolver * - * This function is optional for inherited classes. + * 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. * - * 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 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. * - * Returns: %TRUE on success, %FALSE on error + * Since: 2.22 */ /** - * g_output_stream_flush_async: - * @stream: a #GOutputStream. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): 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_resource_enumerate_children: + * @resource: A #GResource + * @path: A pathname inside the resource + * @lookup_flags: A #GResourceLookupFlags + * @error: return location for a #GError, or %NULL + * + * 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(). * - * Forces an asynchronous write of all user-space buffered data for - * the given @stream. - * For behaviour details see g_output_stream_flush(). + * If @path is invalid or does not exist in the #GResource, + * %G_RESOURCE_ERROR_NOT_FOUND will be returned. * - * 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. + * @lookup_flags controls the behaviour of the lookup. + * + * Returns: (array zero-terminated=1) (transfer full): an array of constant strings + * Since: 2.32 */ /** - * g_output_stream_flush_finish: - * @stream: a #GOutputStream. - * @result: a GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_resource_error_quark: * - * Finishes flushing an output stream. + * Gets the #GResource Error Quark. * - * Returns: %TRUE if flush operation succeeded, %FALSE otherwise. + * Returns: a #GQuark + * Since: 2.32 */ /** - * g_output_stream_has_pending: - * @stream: a #GOutputStream. + * g_resource_get_info: + * @resource: A #GResource + * @path: A pathname inside the resource + * @lookup_flags: A #GResourceLookupFlags + * @size: (out) (optional): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (optional): 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 * - * Checks if an output stream has pending actions. + * Looks for a file at the specified @path in the resource and + * if found returns information about it. * - * Returns: %TRUE if @stream has pending actions. + * @lookup_flags controls the behaviour of the lookup. + * + * Returns: %TRUE if the file was found. %FALSE if there were errors + * Since: 2.32 */ /** - * g_output_stream_is_closed: - * @stream: a #GOutputStream. + * 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 * - * Checks if an output stream has already been closed. + * Loads a binary resource bundle and creates a #GResource representation of it, allowing + * you to query it for data. * - * Returns: %TRUE if @stream is closed. %FALSE otherwise. + * 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_output_stream_is_closing: - * @stream: a #GOutputStream. + * 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 * - * 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. + * Looks for a file at the specified @path in the resource and + * returns a #GBytes that lets you directly access the data in + * memory. * - * Returns: %TRUE if @stream is being closed. %FALSE otherwise. - * Since: 2.24 + * 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_output_stream_printf: - * @stream: a #GOutputStream. - * @bytes_written: (out) (optional): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): 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 + * g_resource_new_from_data: + * @data: A #GBytes + * @error: return location for a #GError, or %NULL * - * 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. + * 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. * - * See the documentation of g_output_stream_write_all() about the - * behavior of the actual write operation. + * If you want to use this resource in the global resource namespace you need + * to register it with g_resources_register(). * - * 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(). + * Note: @data must be backed by memory that is at least pointer aligned. + * Otherwise this function will internally create a copy of the memory since + * GLib 2.56, or in older versions fail and exit the process. * - * Since: 2.40 - * Returns: %TRUE on success, %FALSE if there was an error + * Returns: (transfer full): a new #GResource, or %NULL on error + * Since: 2.32 */ /** - * g_output_stream_set_pending: - * @stream: a #GOutputStream. - * @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 * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set - * @error. + * Looks for a file at the specified @path in the resource and + * returns a #GInputStream that lets you read the data. * - * Returns: %TRUE if pending was previously unset and is now set. + * @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_output_stream_splice: - * @stream: a #GOutputStream. - * @source: a #GInputStream. - * @flags: a set of #GOutputStreamSpliceFlags. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_resource_ref: + * @resource: A #GResource * - * Splices an input stream into an output stream. + * Atomically increments the reference count of @resource by one. This + * function is MT-safe and may be called from any thread. * - * Returns: a #gssize containing the size of the data spliced, or - * -1 if an error occurred. Note that if the number of bytes - * spliced is greater than %G_MAXSSIZE, then that will be - * returned, and there is no way to determine the actual number - * of bytes spliced. + * Returns: The passed in #GResource + * Since: 2.32 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. + * g_resource_unref: + * @resource: A #GResource * - * 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. + * Atomically decrements the reference count of @resource by one. If the + * reference count drops to 0, all memory allocated by the resource is + * released. This function is MT-safe and may be called from any + * thread. * - * For the synchronous, blocking version of this function, see - * g_output_stream_splice(). + * Since: 2.32 */ /** - * 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_resources_enumerate_children: + * @path: A pathname inside the resource + * @lookup_flags: A #GResourceLookupFlags + * @error: return location for a #GError, or %NULL * - * Finishes an asynchronous stream splice operation. + * 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: 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. + * @lookup_flags controls the behaviour of the lookup. + * + * Returns: (array zero-terminated=1) (transfer full): an array of constant strings + * Since: 2.32 */ /** - * g_output_stream_vprintf: - * @stream: a #GOutputStream. - * @bytes_written: (out) (optional): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * @format: the format string. See the printf() documentation - * @args: the parameters to insert into the format string - * - * This is a utility function around g_output_stream_write_all(). It - * uses g_strdup_vprintf() to turn @format and @args into a string that - * is then written to @stream. + * g_resources_get_info: + * @path: A pathname inside the resource + * @lookup_flags: A #GResourceLookupFlags + * @size: (out) (optional): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (optional): a location to place the #GResourceFlags about the file, + * or %NULL if the flags are not needed + * @error: return location for a #GError, or %NULL * - * See the documentation of g_output_stream_write_all() about the - * behavior of the actual write operation. + * Looks for a file at the specified @path in the set of + * globally registered resources and if found returns information about it. * - * 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(). + * @lookup_flags controls the behaviour of the lookup. * - * Since: 2.40 - * Returns: %TRUE on success, %FALSE if there was an error + * Returns: %TRUE if the file was found. %FALSE if there were errors + * Since: 2.32 */ /** - * 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: (nullable): 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. + * g_resources_lookup_data: + * @path: A pathname inside the resource + * @lookup_flags: A #GResourceLookupFlags + * @error: return location for a #GError, or %NULL * - * 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. + * 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. * - * 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). + * 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. * - * 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. + * 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. * - * On error -1 is returned and @error is set accordingly. + * @lookup_flags controls the behaviour of the lookup. * - * Returns: Number of bytes written, or -1 on error + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() + * Since: 2.32 */ /** - * 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) (optional): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): 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. - * - * This function is similar to g_output_stream_write(), except it tries to - * write as many bytes as requested, only stopping on an error. - * - * On a successful write of @count bytes, %TRUE is returned, and @bytes_written - * is set to @count. + * g_resources_open_stream: + * @path: A pathname inside the resource + * @lookup_flags: A #GResourceLookupFlags + * @error: return location for a #GError, or %NULL * - * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status. + * 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. * - * 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(). + * @lookup_flags controls the behaviour of the lookup. * - * Returns: %TRUE on success, %FALSE if there was an error + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() + * Since: 2.32 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous write of @count bytes from @buffer into - * the stream. When the operation is finished @callback will be called. - * You can then call g_output_stream_write_all_finish() to get the result of the - * operation. - * - * This is the asynchronous version of g_output_stream_write_all(). - * - * Call g_output_stream_write_all_finish() to collect the result. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. + * g_resources_register: + * @resource: A #GResource * - * Note that no copy of @buffer will be made, so it must stay valid - * until @callback is called. + * 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(). * - * Since: 2.44 + * Since: 2.32 */ /** - * g_output_stream_write_all_finish: - * @stream: a #GOutputStream - * @result: a #GAsyncResult - * @bytes_written: (out) (optional): location to store the number of bytes that was written to the stream - * @error: a #GError location to store the error occurring, or %NULL to ignore. - * - * Finishes an asynchronous stream write operation started with - * g_output_stream_write_all_async(). + * g_resources_unregister: + * @resource: A #GResource * - * 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(). + * Unregisters the resource from the process-global set of resources. * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.44 + * Since: 2.32 */ /** - * 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: (nullable): 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. - * - * 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 written will be passed to the - * @callback. It is not an error if this is not the same as the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the - * method will just wait until this changes. - * - * 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 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_seekable_can_seek: + * @seekable: a #GSeekable. * - * For the synchronous, blocking version of this function, see - * g_output_stream_write(). + * Tests if the stream supports the #GSeekableIface. * - * 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. + * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise. */ /** - * g_output_stream_write_bytes: - * @stream: a #GOutputStream. - * @bytes: the #GBytes to write - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * 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. + * g_seekable_can_truncate: + * @seekable: a #GSeekable. * - * 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. + * Tests if the length of the stream can be adjusted with + * g_seekable_truncate(). * - * Returns: Number of bytes written, or -1 on error + * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. */ /** - * g_output_stream_write_bytes_async: - * @stream: A #GOutputStream. - * @bytes: The bytes to write - * @io_priority: the io priority of the request. + * g_seekable_seek: + * @seekable: a #GSeekable. + * @offset: a #goffset. + * @type: a #GSeekType. * @cancellable: (nullable): 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 + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * 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. + * Seeks in the stream by the given @offset, modified by @type. * - * 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. + * 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. * - * For the synchronous, blocking version of this function, see - * g_output_stream_write_bytes(). + * Any operation that would result in a negative offset will fail. + * + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ /** - * 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. + * g_seekable_tell: + * @seekable: a #GSeekable. * - * Finishes a stream write-from-#GBytes operation. + * Tells the current position within the stream. * - * Returns: a #gssize containing the number of bytes written to the stream. + * Returns: the offset from the beginning of the buffer. */ /** - * g_output_stream_write_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. + * g_seekable_truncate: (virtual truncate_fn) + * @seekable: a #GSeekable. + * @offset: new length for @seekable, in bytes. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occurring, or %NULL to * ignore. * - * Finishes a stream write operation. + * Sets the length of the stream to @offset. If the stream was previously + * larger than @offset, the extra data is discarded. If the stream was + * previouly shorter than @offset, it is extended with NUL ('\0') 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. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. + */ + + +/** + * g_settings_apply: + * @settings: a #GSettings instance * - * Returns: a #gssize containing the number of bytes written to the stream. + * 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_permission_acquire: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a %NULL #GError, or %NULL + * g_settings_backend_changed: + * @backend: a #GSettingsBackend implementation + * @key: the name of the key + * @origin_tag: the origin tag * - * Attempts to acquire the permission represented by @permission. + * Signals that a single key has possibly changed. Backend + * implementations should call this if a key has possibly changed its + * value. * - * 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. + * @key must be a valid key (ie starting with a slash, not containing + * '//', and not ending with a slash). * - * You should check with g_permission_get_can_acquire() before calling - * this function. + * 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. * - * If the permission is acquired then %TRUE is returned. Otherwise, - * %FALSE is returned and @error is set appropriately. + * 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()). * - * 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. + * 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. * - * Returns: %TRUE if the permission was successfully acquired * Since: 2.26 */ /** - * g_permission_acquire_async: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback to call when done - * @user_data: the user data to pass to @callback - * - * Attempts to acquire the permission represented by @permission. + * g_settings_backend_changed_tree: + * @backend: a #GSettingsBackend implementation + * @tree: a #GTree containing the changes + * @origin_tag: the origin tag * - * This is the first half of the asynchronous version of - * g_permission_acquire(). + * 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(). * * 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 + * 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) (optional) (transfer container) (array zero-terminated=1): + * the location to save the values, or %NULL * - * Collects the result of attempting to acquire the permission - * represented by @permission. + * 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. * - * This is the second half of the asynchronous version of - * g_permission_acquire(). + * 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. * - * Returns: %TRUE if the permission was successfully acquired * Since: 2.26 */ /** - * g_permission_get_allowed: - * @permission: a #GPermission instance + * g_settings_backend_get_default: * - * 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. + * 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: the value of the 'allowed' property - * Since: 2.26 + * The user gets a reference to the backend. + * + * Returns: (transfer full): the default #GSettingsBackend + * Since: 2.28 */ /** - * g_permission_get_can_acquire: - * @permission: a #GPermission instance + * 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 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(). + * 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). + * + * 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: the value of the 'can-acquire' property * Since: 2.26 */ /** - * g_permission_get_can_release: - * @permission: a #GPermission instance + * g_settings_backend_path_changed: + * @backend: a #GSettingsBackend implementation + * @path: the path containing the changes + * @origin_tag: the origin tag * - * 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(). + * 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. + * + * 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. * - * 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 + * g_settings_backend_path_writable_changed: + * @backend: a #GSettingsBackend implementation + * @path: the name of the path * - * 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. + * Signals that the writability of all keys below a given path may have + * changed. * - * GObject notify signals are generated, as appropriate. + * Since GSettings performs no locking operations for itself, this call + * will always be made in response to external events. * * Since: 2.26 */ /** - * g_permission_release: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a %NULL #GError, or %NULL - * - * Attempts to release the permission represented by @permission. - * - * 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. - * - * You should check with g_permission_get_can_release() before calling - * this function. + * g_settings_backend_writable_changed: + * @backend: a #GSettingsBackend implementation + * @key: the name of the key * - * If the permission is released then %TRUE is returned. Otherwise, - * %FALSE is returned and @error is set appropriately. + * Signals that the writability of a single key has possibly changed. * - * 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 GSettings performs no locking operations for itself, this call + * will always be made in response to external events. * - * Returns: %TRUE if the permission was successfully released * Since: 2.26 */ /** - * g_permission_release_async: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback to call when done - * @user_data: the user data to pass to @callback + * 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 * - * Attempts to release the permission represented by @permission. + * Create a binding between the @key in the @settings object + * and the property @property of @object. * - * This is the first half of the asynchronous version of - * g_permission_release(). + * 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. + * + * 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. + * + * Note that the lifecycle of the binding is tied to @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. * * 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_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 * - * Collects the result of attempting to release the permission - * represented by @permission. + * Create a binding between the @key in the @settings object + * and the property @property of @object. * - * This is the second half of the asynchronous version of - * g_permission_release(). + * The binding uses the provided mapping functions to map between + * settings and property values. + * + * Note that the lifecycle of the binding is tied to @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: %TRUE if the permission was successfully released * Since: 2.26 */ /** - * g_pollable_input_stream_can_poll: - * @stream: a #GPollableInputStream. + * 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 * - * 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. + * 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. * - * For any given stream, the value returned by this method is constant; - * a stream cannot switch from pollable to non-pollable or vice versa. + * 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: %TRUE if @stream is pollable, %FALSE if not. - * Since: 2.28 + * 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. + * + * Note that the lifecycle of the binding is tied to @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. + * + * Since: 2.26 */ /** - * g_pollable_input_stream_create_source: - * @stream: a #GPollableInputStream. - * @cancellable: (nullable): a #GCancellable, or %NULL + * g_settings_create_action: + * @settings: a #GSettings + * @key: the name of a key in @settings * - * 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. + * Creates a #GAction corresponding to a given #GSettings 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. + * The action has the same name as the key. * - * Returns: (transfer full): a new #GSource - * Since: 2.28 + * 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. + * + * 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: (transfer full): a new #GAction + * Since: 2.32 */ /** - * g_pollable_input_stream_is_readable: - * @stream: a #GPollableInputStream. - * - * Checks if @stream can be read. + * g_settings_delay: + * @settings: a #GSettings object * - * 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. + * 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: %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 + * Since: 2.26 */ /** - * 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: (nullable): a #GCancellable, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_settings_get: + * @settings: a #GSettings object + * @key: the key to get the value for + * @format: a #GVariant format string + * @...: arguments as per @format * - * 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. + * Gets the value that is stored at @key in @settings. * - * 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. + * A convenience function that combines g_settings_get_value() with + * g_variant_get(). * - * Returns: the number of bytes read, or -1 on error (including - * %G_IO_ERROR_WOULD_BLOCK). + * 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. + * + * Since: 2.26 */ /** - * g_pollable_output_stream_can_poll: - * @stream: a #GPollableOutputStream. + * g_settings_get_boolean: + * @settings: a #GSettings object + * @key: the key to get the value for * - * 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 value that is stored at @key in @settings. * - * For any given stream, the value returned by this method is constant; - * a stream cannot switch from pollable to non-pollable or vice versa. + * A convenience variant of g_settings_get() for booleans. * - * Returns: %TRUE if @stream is pollable, %FALSE if not. - * Since: 2.28 + * It is a programmer error to give a @key that isn't specified as + * having a boolean type in the schema for @settings. + * + * Returns: a boolean + * Since: 2.26 */ /** - * g_pollable_output_stream_create_source: - * @stream: a #GPollableOutputStream. - * @cancellable: (nullable): a #GCancellable, or %NULL + * g_settings_get_child: + * @settings: a #GSettings object + * @name: the name of the child schema * - * 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. + * Creates a child settings object which has a base path of + * `base-path/@name`, where `base-path` is the base path of + * @settings. * - * 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. + * The schema for the child settings object must have been declared + * in the schema of @settings using a element. * - * Returns: (transfer full): a new #GSource - * Since: 2.28 + * Returns: (transfer full): a 'child' settings object + * Since: 2.26 */ /** - * g_pollable_output_stream_is_writable: - * @stream: a #GPollableOutputStream. + * g_settings_get_default_value: + * @settings: a #GSettings object + * @key: the key to get the default value for * - * Checks if @stream can be written. + * Gets the "default value" of a 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. + * This is the value that would be read if g_settings_reset() were to be + * called on the key. * - * Returns: %TRUE if @stream is writable, %FALSE if not. If an error - * has occurred on @stream, this will result in - * g_pollable_output_stream_is_writable() returning %TRUE, and the - * next attempt to write will return the error. - * Since: 2.28 - */ - - -/** - * g_pollable_output_stream_write_nonblocking: (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: (nullable): a #GCancellable, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * 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. * - * 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. + * 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. * - * 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. + * This function may be useful for adding an indication to a UI of what + * the default value was before the user set it. * - * Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying - * transports like D/TLS require that you send the same @buffer and @count. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. * - * Returns: the number of bytes written, or -1 on error (including - * %G_IO_ERROR_WOULD_BLOCK). + * Returns: (nullable) (transfer full): the default value + * Since: 2.40 */ /** - * g_pollable_source_new: - * @pollable_stream: the stream associated with the new source + * g_settings_get_double: + * @settings: a #GSettings object + * @key: the key to get the value for * - * 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 value that is stored at @key in @settings. * - * Returns: (transfer full): the new #GSource. - * Since: 2.28 - */ - - -/** - * g_pollable_source_new_full: - * @pollable_stream: (type GObject): the stream associated with the - * new source - * @child_source: (nullable): optional child source to attach - * @cancellable: (nullable): optional #GCancellable to attach + * A convenience variant of g_settings_get() for doubles. * - * 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. + * It is a programmer error to give a @key that isn't specified as + * having a 'double' type in the schema for @settings. * - * Returns: (transfer full): the new #GSource. - * Since: 2.34 + * Returns: a double + * Since: 2.26 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @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 * - * 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. + * Gets the value that is stored in @settings for @key and converts it + * to the enum value that it represents. * - * 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. + * 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. * - * Returns: the number of bytes read, or -1 on error. - * Since: 2.34 + * 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. + * + * Returns: the enum value + * Since: 2.26 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore + * g_settings_get_flags: + * @settings: a #GSettings object + * @key: the key to get the value for * - * 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. + * Gets the value that is stored in @settings for @key and converts it + * to the flags value that it represents. * - * 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. + * 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. * - * Returns: the number of bytes written, or -1 on error. - * Since: 2.34 + * 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. + * + * Returns: the flags value + * Since: 2.26 */ /** - * 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * 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(). - * - * On a successful write of @count bytes, %TRUE is returned, and - * @bytes_written is set to @count. - * - * 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. + * g_settings_get_has_unapplied: + * @settings: a #GSettings object * - * 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 whether the #GSettings object has any unapplied + * changes. This can only be the case if it is in 'delayed-apply' mode. * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.34 + * Returns: %TRUE if @settings has unapplied changes + * Since: 2.26 */ /** - * 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 + * g_settings_get_int: + * @settings: a #GSettings object + * @key: the key to get the value for * - * Creates a #GAction corresponding to the value of property - * @property_name on @object. + * Gets the value that is stored at @key in @settings. * - * The property must be existent and readable and writable (and not - * construct-only). + * A convenience variant of g_settings_get() for 32-bit integers. * - * This function takes a reference on @object and doesn't release it - * until the action is destroyed. + * It is a programmer error to give a @key that isn't specified as + * having a int32 type in the schema for @settings. * - * Returns: a new #GPropertyAction - * Since: 2.38 + * Returns: an integer + * Since: 2.26 */ /** - * g_proxy_address_get_destination_hostname: - * @proxy: a #GProxyAddress + * g_settings_get_int64: + * @settings: a #GSettings object + * @key: the key to get the value for * - * 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. + * Gets the value that is stored at @key in @settings. * - * Returns: the @proxy's destination hostname - * Since: 2.26 + * A convenience variant of g_settings_get() for 64-bit integers. + * + * It is a programmer error to give a @key that isn't specified as + * having a int64 type in the schema for @settings. + * + * Returns: a 64-bit integer + * Since: 2.50 */ /** - * g_proxy_address_get_destination_port: - * @proxy: a #GProxyAddress + * 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 @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. + * Gets the value that is stored at @key in @settings, subject to + * application-level validation/mapping. * - * Returns: the @proxy's destination port - * Since: 2.26 + * 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. + * + * Returns: (transfer full): the result, which may be %NULL */ /** - * g_proxy_address_get_destination_protocol: - * @proxy: a #GProxyAddress + * g_settings_get_range: + * @settings: a #GSettings + * @key: the key to query the range of * - * Gets the protocol that is being spoken to the destination - * server; eg, "http" or "ftp". + * Queries the range of a key. * - * Returns: the @proxy's destination protocol - * Since: 2.34 + * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead. */ /** - * g_proxy_address_get_password: - * @proxy: a #GProxyAddress + * g_settings_get_string: + * @settings: a #GSettings object + * @key: the key to get the value for * - * Gets @proxy's password. + * Gets the value that is stored at @key in @settings. * - * Returns: the @proxy's password + * 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. + * + * Returns: a newly-allocated string * Since: 2.26 */ /** - * g_proxy_address_get_protocol: - * @proxy: a #GProxyAddress + * g_settings_get_strv: + * @settings: a #GSettings object + * @key: the key to get the value for * - * Gets @proxy's protocol. eg, "socks" or "http" + * A convenience variant of g_settings_get() for string arrays. * - * Returns: the @proxy's protocol + * It is a programmer error to give a @key that isn't specified as + * having an array of strings type in the schema for @settings. + * + * Returns: (array zero-terminated=1) (transfer full): a + * newly-allocated, %NULL-terminated array of strings, the value that + * is stored at @key in @settings. * Since: 2.26 */ /** - * g_proxy_address_get_uri: - * @proxy: a #GProxyAddress + * g_settings_get_uint: + * @settings: a #GSettings object + * @key: the key to get the value for * - * Gets the proxy URI that @proxy was constructed from. + * Gets the value that is stored at @key in @settings. * - * Returns: the @proxy's URI, or %NULL if unknown - * Since: 2.34 + * A convenience variant of g_settings_get() 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: an unsigned integer + * Since: 2.30 */ /** - * g_proxy_address_get_username: - * @proxy: a #GProxyAddress + * g_settings_get_uint64: + * @settings: a #GSettings object + * @key: the key to get the value for * - * Gets @proxy's username. + * Gets the value that is stored at @key in @settings. * - * Returns: the @proxy's username - * Since: 2.26 + * A convenience variant of g_settings_get() for 64-bit unsigned + * integers. + * + * It is a programmer error to give a @key that isn't specified as + * having a uint64 type in the schema for @settings. + * + * Returns: a 64-bit unsigned integer + * Since: 2.50 */ /** - * 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: (nullable): The username to authenticate to the proxy server - * (or %NULL). - * @password: (nullable): The password to authenticate to the proxy server - * (or %NULL). + * g_settings_get_user_value: + * @settings: a #GSettings object + * @key: the key to get the user value for * - * Creates a new #GProxyAddress for @inetaddr with @protocol that should - * tunnel through @dest_hostname and @dest_port. + * Checks the "user value" of a key, if there is one. * - * (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.) + * The user value of a key is the last value that was set by the user. * - * Returns: a new #GProxyAddress - * Since: 2.26 + * After calling g_settings_reset() this function should always return + * %NULL (assuming something is not wrong with the system + * configuration). + * + * It is possible that g_settings_get_value() will return a different + * value than this function. This can happen in the case that the user + * set a value for a key that was subsequently locked down by the system + * administrator -- this function will return the user's old value. + * + * This function may be useful for adding a "reset" option to a UI or + * for providing indication that a particular value has been changed. + * + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. + * + * Returns: (nullable) (transfer full): the user's value, if set + * Since: 2.40 */ /** - * g_proxy_connect: - * @proxy: a #GProxy - * @connection: a #GIOStream - * @proxy_address: a #GProxyAddress - * @cancellable: (nullable): a #GCancellable - * @error: return #GError + * g_settings_get_value: + * @settings: a #GSettings object + * @key: the key to get the value for * - * 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 value that is stored in @settings for @key. * - * Returns: (transfer full): a #GIOStream that will replace @connection. This might - * be the same as @connection, in which case a reference - * will be added. + * 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_proxy_connect_async: - * @proxy: a #GProxy - * @connection: a #GIOStream - * @proxy_address: a #GProxyAddress - * @cancellable: (nullable): a #GCancellable - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): callback data + * g_settings_is_writable: + * @settings: a #GSettings object + * @name: the name of a key * - * Asynchronous version of g_proxy_connect(). + * Finds out if a key can be written or not * + * Returns: %TRUE if the key @name is writable * Since: 2.26 */ /** - * g_proxy_connect_finish: - * @proxy: a #GProxy - * @result: a #GAsyncResult - * @error: return #GError + * g_settings_list_children: + * @settings: a #GSettings object * - * See g_proxy_connect(). + * Gets the list of children on @settings. * - * Returns: (transfer full): a #GIOStream. - * Since: 2.26 + * The list is exactly the list of strings for which it is not an error + * to call g_settings_get_child(). + * + * 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. + * + * 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. + * + * 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 */ /** - * g_proxy_get_default_for_protocol: - * @protocol: the proxy protocol name (e.g. http, socks, etc) + * g_settings_list_keys: + * @settings: a #GSettings object * - * Lookup "gio-proxy" extension point for a proxy implementation that supports - * specified protocol. + * Introspects the list of keys on @settings. * - * Returns: (transfer full): return a #GProxy or NULL if protocol - * is not supported. - * Since: 2.26 + * 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: (transfer full) (element-type utf8): a list of the keys on @settings */ /** - * g_proxy_resolver_get_default: + * g_settings_list_relocatable_schemas: * - * Gets the default #GProxyResolver for the system. + * * - * Returns: (transfer none): the default #GProxyResolver. - * 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_proxy_resolver_is_supported: - * @resolver: a #GProxyResolver + * g_settings_list_schemas: * - * 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.) + * * - * Returns: %TRUE if @resolver is supported. + * 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_proxy_resolver_lookup: - * @resolver: a #GProxyResolver - * @uri: a URI representing the destination to connect to - * @cancellable: (nullable): 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 `://[user[:password]@]host:port` or - * `direct://`, where could be http, rtsp, socks - * or other proxying protocol. + * g_settings_new: + * @schema_id: the id of the schema * - * 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). + * Creates a new #GSettings object with the schema specified by + * @schema_id. * - * `direct://` is used when no proxy is needed. - * Direct connection should not be attempted unless it is part of the - * returned array of proxies. + * 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: (transfer full) (array zero-terminated=1): A - * NULL-terminated array of proxy URIs. Must be freed - * with g_strfreev(). + * Returns: a new #GSettings object * Since: 2.26 */ /** - * g_proxy_resolver_lookup_async: - * @resolver: a #GProxyResolver - * @uri: a URI representing the destination to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_settings_new_full: + * @schema: a #GSettingsSchema + * @backend: (nullable): a #GSettingsBackend + * @path: (nullable): the path to use * - * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more - * details. + * Creates a new #GSettings object with a given schema, backend and + * path. * - * Since: 2.26 + * 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). + * + * 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. + * + * 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()). + * + * If @backend is %NULL then the default backend is used. + * + * If @path is %NULL then the path from the schema is used. It is an + * error 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_proxy_resolver_lookup_finish: - * @resolver: a #GProxyResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL + * g_settings_new_with_backend: + * @schema_id: the id of the schema + * @backend: the #GSettingsBackend to use * - * 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. + * Creates a new #GSettings object with the schema specified by + * @schema_id and a given #GSettingsBackend. * - * Returns: (transfer full) (array zero-terminated=1): A - * NULL-terminated array of proxy URIs. Must be freed - * with g_strfreev(). + * 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_proxy_supports_hostname: - * @proxy: a #GProxy + * g_settings_new_with_backend_and_path: + * @schema_id: the id of the schema + * @backend: the #GSettingsBackend to use + * @path: the path to use * - * 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(). + * Creates a new #GSettings object with the schema specified by + * @schema_id and a given #GSettingsBackend and path. + * + * This is a mix of g_settings_new_with_backend() and + * g_settings_new_with_path(). * - * Returns: %TRUE if hostname resolution is supported. + * Returns: a new #GSettings object * Since: 2.26 */ /** - * g_remote_action_group_activate_action_full: - * @remote: a #GDBusActionGroup - * @action_name: the name of the action to activate - * @parameter: (nullable): the optional parameter to the activation - * @platform_data: the platform data to send + * g_settings_new_with_path: + * @schema_id: the id of the schema + * @path: the path to use * - * Activates the remote action. + * Creates a new #GSettings object with the relocatable schema specified + * by @schema_id and a given path. * - * 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. + * 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. * - * @platform_data must be non-%NULL and must have the type - * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. + * It is a programmer error to call this function for a schema that + * has an explicitly specified path. * - * Since: 2.32 + * 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_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 - * - * 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. + * g_settings_range_check: + * @settings: a #GSettings + * @key: the key to check + * @value: the value to check * - * @platform_data must be non-%NULL and must have the type - * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. + * Checks if the given @value is of the correct type and within the + * permitted range for @key. * - * Since: 2.32 + * Returns: %TRUE if @value is valid for @key + * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead. */ /** - * g_resolver_error_quark: + * g_settings_reset: + * @settings: a #GSettings object + * @key: the name of a key * - * Gets the #GResolver Error Quark. + * Resets @key to its default value. * - * Returns: a #GQuark. - * Since: 2.22 + * 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_resolver_free_addresses: (skip) - * @addresses: a #GList of #GInetAddress + * g_settings_revert: + * @settings: a #GSettings instance * - * 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.) + * 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. * - * Since: 2.22 + * Change notifications will be emitted for affected keys. */ /** - * g_resolver_free_targets: (skip) - * @targets: a #GList of #GSrvTarget + * g_settings_schema_get_id: + * @schema: a #GSettingsSchema * - * 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.) + * Get the ID of @schema. * - * Since: 2.22 + * Returns: (transfer none): the ID */ /** - * g_resolver_get_default: + * g_settings_schema_get_key: + * @schema: a #GSettingsSchema + * @name: the name of a key * - * 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. + * Gets the key named @name from @schema. * - * Returns: (transfer full): the default #GResolver. - * Since: 2.22 + * It is a programmer error to request a key that does not exist. See + * g_settings_schema_list_keys(). + * + * Returns: (transfer full): the #GSettingsSchemaKey for @name + * Since: 2.40 */ /** - * g_resolver_lookup_by_address: - * @resolver: a #GResolver - * @address: the address to reverse-resolve - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL + * g_settings_schema_get_path: + * @schema: a #GSettingsSchema * - * Synchronously reverse-resolves @address to determine its - * associated hostname. + * Gets the path associated with @schema, or %NULL. * - * If the DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError. + * 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. * - * 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. + * 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: a hostname (either ASCII-only, or in ASCII-encoded - * form), or %NULL on error. - * Since: 2.22 + * Returns: (transfer none): the path of the schema, or %NULL + * Since: 2.32 */ /** - * g_resolver_lookup_by_address_async: - * @resolver: a #GResolver - * @address: the address to reverse-resolve - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_settings_schema_has_key: + * @schema: a #GSettingsSchema + * @name: the name of a key * - * 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. + * Checks if @schema has a key named @name. * - * Since: 2.22 + * Returns: %TRUE if such a key exists + * Since: 2.40 */ /** - * 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_schema_key_get_default_value: + * @key: a #GSettingsSchemaKey * - * Retrieves the result of a previous call to - * g_resolver_lookup_by_address_async(). + * Gets the default value for @key. * - * 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. + * Note that this is the default value according to the schema. System + * administrator defaults and lockdown are not visible via this API. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded - * form), or %NULL on error. - * Since: 2.22 + * Returns: (transfer full): the default value for the key + * Since: 2.40 */ /** - * g_resolver_lookup_by_name: - * @resolver: a #GResolver - * @hostname: the hostname to look up - * @cancellable: (nullable): 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_schema_key_get_description: + * @key: a #GSettingsSchemaKey * - * 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(). + * Gets the description for @key. * - * If the DNS resolution fails, @error (if non-%NULL) will be set to a - * value from #GResolverError and %NULL will be returned. + * If no description has been provided in the schema for @key, returns + * %NULL. * - * 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. + * 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. * - * 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. + * 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: (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 + * Returns: the description for @key, or %NULL + * Since: 2.34 */ /** - * g_resolver_lookup_by_name_async: - * @resolver: a #GResolver - * @hostname: the hostname to look up the address of - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_settings_schema_key_get_name: + * @key: a #GSettingsSchemaKey * - * 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. + * Gets the name of @key. * - * Since: 2.22 + * Returns: the name of @key. + * Since: 2.44 */ /** - * 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_settings_schema_key_get_range: + * @key: a #GSettingsSchemaKey * - * Retrieves the result of a call to - * g_resolver_lookup_by_name_async(). + * Queries the range of a key. * - * 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. + * This function will return a #GVariant that fully describes the range + * of values that are valid for @key. * - * 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_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: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL + * 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. * - * 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. + * 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 DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError and %NULL will be returned. + * 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 @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 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']`. * - * 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 + * 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_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: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_settings_schema_key_get_summary: + * @key: a #GSettingsSchemaKey * - * 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. + * Gets the summary for @key. + * + * If no summary has been provided in the schema for @key, returns + * %NULL. + * + * The summary is a short description of the purpose of the key; usually + * one short sentence. Summaries can be translated and the value + * returned from this function is is the current locale. + * + * This function is slow. The summary and description information for + * the schemas is not stored in the compiled schema database so this + * function has to parse all of the source XML files in the schema + * directory. * + * Returns: the summary for @key, or %NULL * Since: 2.34 */ /** - * g_resolver_lookup_records_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_records_async(). Returns a non-empty list of records as - * #GVariant tuples. See #GResolverRecordType for information on what the - * records contain. + * g_settings_schema_key_get_value_type: + * @key: a #GSettingsSchemaKey * - * 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. + * Gets the #GVariantType of @key. * - * 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 + * Returns: (transfer none): the type of @key + * Since: 2.40 */ /** - * 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: (nullable): 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 do not include the leading underscore - * that appears in the actual DNS entry. - * - * 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. + * g_settings_schema_key_range_check: + * @key: a #GSettingsSchemaKey + * @value: the value to check * - * 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. + * Checks if the given @value is of the correct type and within the + * permitted range for @key. * - * If you are planning to connect to the service, it is usually easier - * to create a #GNetworkService and use its #GSocketConnectable - * interface. + * It is a programmer error if @value is not of the correct type -- you + * must check for this first. * - * 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 + * Returns: %TRUE if @value is valid for @key + * Since: 2.40 */ /** - * 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: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_settings_schema_key_ref: + * @key: a #GSettingsSchemaKey * - * 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. + * Increase the reference count of @key, returning a new reference. * - * Since: 2.22 + * Returns: a new reference to @key + * Since: 2.40 */ /** - * 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_settings_schema_key_unref: + * @key: a #GSettingsSchemaKey * - * 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. + * Decrease the reference count of @key, possibly freeing it. * - * 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 + * Since: 2.40 */ /** - * g_resolver_set_default: - * @resolver: the new default #GResolver + * g_settings_schema_list_children: + * @schema: a #GSettingsSchema * - * 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. + * Gets the list of children in @schema. * - * 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. + * You should free the return value with g_strfreev() when you are done + * with it. * - * Since: 2.22 + * Returns: (transfer full) (element-type utf8): a list of the children on @settings + * Since: 2.44 */ /** - * 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 - * - * 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(). + * g_settings_schema_list_keys: + * @schema: a #GSettingsSchema * - * If @path is invalid or does not exist in the #GResource, - * %G_RESOURCE_ERROR_NOT_FOUND will be returned. + * Introspects the list of keys on @schema. * - * @lookup_flags controls the behaviour of the lookup. + * 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. * - * Returns: (array zero-terminated=1) (transfer full): an array of constant strings - * Since: 2.32 + * Returns: (transfer full) (element-type utf8): a list of the keys on + * @schema + * Since: 2.46 */ /** - * g_resource_error_quark: + * g_settings_schema_ref: + * @schema: a #GSettingsSchema * - * Gets the #GResource Error Quark. + * Increase the reference count of @schema, returning a new reference. * - * Returns: a #GQuark + * Returns: a new reference to @schema * Since: 2.32 */ /** - * g_resource_get_info: - * @resource: A #GResource - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @flags: (out) (optional): a location to place the flags about the file, - * or %NULL if the length is not needed - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the resource and - * if found returns information about it. + * g_settings_schema_source_get_default: * - * @lookup_flags controls the behaviour of the lookup. + * Gets the default system schema source. * - * Returns: %TRUE if the file was found. %FALSE if there were errors - * Since: 2.32 - */ - - -/** - * 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 + * 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. * - * Loads a binary resource bundle and creates a #GResource representation of it, allowing - * you to query it for data. + * If no schemas are installed, %NULL will be returned. * - * If you want to use this resource in the global resource namespace you need - * to register it with g_resources_register(). + * 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 full): a new #GResource, or %NULL on error + * Returns: (transfer none) (nullable): the default schema source * Since: 2.32 */ /** - * 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 + * 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 * - * Looks for a file at the specified @path in the resource and - * returns a #GBytes that lets you directly access the data in - * memory. + * Lists the schemas in a given source. * - * 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. + * 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. * - * 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. + * 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(). * - * @lookup_flags controls the behaviour of the lookup. + * Do not call this function from normal programs. This is designed for + * use by database editors, commandline tools, etc. * - * Returns: (transfer full): #GBytes or %NULL on error. - * Free the returned object with g_bytes_unref() - * Since: 2.32 + * Since: 2.40 */ /** - * g_resource_new_from_data: - * @data: A #GBytes - * @error: return location for a #GError, or %NULL + * g_settings_schema_source_lookup: + * @source: a #GSettingsSchemaSource + * @schema_id: a schema ID + * @recursive: %TRUE if the lookup should be recursive * - * 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. + * Looks up a schema with the identifier @schema_id in @source. * - * If you want to use this resource in the global resource namespace you need - * to register it with g_resources_register(). + * 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. * - * Note: @data must be backed by memory that is at least pointer aligned. - * Otherwise this function will internally create a copy of the memory since - * GLib 2.56, or in older versions fail and exit the process. + * If the schema isn't found directly in @source and @recursive is %TRUE + * then the parent sources will also be checked. * - * Returns: (transfer full): a new #GResource, or %NULL on error + * If the schema isn't found, %NULL is returned. + * + * Returns: (nullable) (transfer full): a new #GSettingsSchema * Since: 2.32 */ /** - * 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 + * g_settings_schema_source_new_from_directory: + * @directory: (type filename): the filename of a directory + * @parent: (nullable): a #GSettingsSchemaSource, or %NULL + * @trusted: %TRUE, if the directory is trusted + * @error: a pointer to a #GError pointer set to %NULL, or %NULL * - * Looks for a file at the specified @path in the resource and - * returns a #GInputStream that lets you read the data. + * Attempts to create a new schema source corresponding to the contents + * of the given directory. * - * @lookup_flags controls the behaviour of the lookup. + * This function is not required for normal uses of #GSettings but it + * may be useful to authors of plugin management systems. + * + * The directory should contain a file called `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(). * - * Returns: (transfer full): #GInputStream or %NULL on error. - * Free the returned object with g_object_unref() * Since: 2.32 */ /** - * g_resource_ref: - * @resource: A #GResource + * g_settings_schema_source_ref: + * @source: a #GSettingsSchemaSource * - * Atomically increments the reference count of @resource by one. This - * function is MT-safe and may be called from any thread. + * Increase the reference count of @source, returning a new reference. * - * Returns: The passed in #GResource + * Returns: a new reference to @source * Since: 2.32 */ /** - * g_resource_unref: - * @resource: A #GResource + * g_settings_schema_source_unref: + * @source: a #GSettingsSchemaSource * - * Atomically decrements the reference count of @resource by one. If the - * reference count drops to 0, all memory allocated by the resource is - * released. This function is MT-safe and may be called from any - * thread. + * Decrease the reference count of @source, possibly freeing it. * * Since: 2.32 */ /** - * g_resources_enumerate_children: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * 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(). + * g_settings_schema_unref: + * @schema: a #GSettingsSchema * - * @lookup_flags controls the behaviour of the lookup. + * Decrease the reference count of @schema, possibly freeing it. * - * Returns: (array zero-terminated=1) (transfer full): an array of constant strings * Since: 2.32 */ /** - * g_resources_get_info: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @flags: (out) (optional): a location to place the #GResourceFlags about the file, - * or %NULL if the flags are not needed - * @error: return location for a #GError, or %NULL + * g_settings_set: + * @settings: a #GSettings object + * @key: the name of the key to set + * @format: a #GVariant format string + * @...: arguments as per @format * - * Looks for a file at the specified @path in the set of - * globally registered resources and if found returns information about it. + * Sets @key in @settings to @value. * - * @lookup_flags controls the behaviour of the lookup. + * A convenience function that combines g_settings_set_value() with + * g_variant_new(). * - * Returns: %TRUE if the file was found. %FALSE if there were errors - * Since: 2.32 + * 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_resources_lookup_data: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * 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. + * g_settings_set_boolean: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to * - * 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. + * Sets @key in @settings to @value. * - * 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. + * A convenience variant of g_settings_set() for booleans. * - * @lookup_flags controls the behaviour of the lookup. + * It is a programmer error to give a @key that isn't specified as + * having a boolean type in the schema for @settings. * - * Returns: (transfer full): #GBytes or %NULL on error. - * Free the returned object with g_bytes_unref() - * Since: 2.32 + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable + * Since: 2.26 */ /** - * g_resources_open_stream: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL + * g_settings_set_double: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to * - * 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. + * Sets @key in @settings to @value. * - * @lookup_flags controls the behaviour of the lookup. + * A convenience variant of g_settings_set() for doubles. * - * Returns: (transfer full): #GInputStream or %NULL on error. - * Free the returned object with g_object_unref() - * Since: 2.32 + * 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_resources_register: - * @resource: A #GResource + * g_settings_set_enum: + * @settings: a #GSettings object + * @key: a key, within @settings + * @value: an enumerated value * - * 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(). + * Looks up the enumerated type nick for @value and writes it to @key, + * within @settings. * - * Since: 2.32 + * 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. + * + * After performing the write, accessing @key directly with + * g_settings_get_string() will return the 'nick' associated with + * @value. + * + * Returns: %TRUE, if the set succeeds */ /** - * g_resources_unregister: - * @resource: A #GResource + * g_settings_set_flags: + * @settings: a #GSettings object + * @key: a key, within @settings + * @value: a flags value * - * Unregisters the resource from the process-global set of resources. + * 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. * - * Since: 2.32 + * 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. + * + * 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: %TRUE, if the set succeeds */ /** - * g_seekable_can_seek: - * @seekable: a #GSeekable. + * g_settings_set_int: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to * - * Tests if the stream supports the #GSeekableIface. + * Sets @key in @settings to @value. * - * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise. + * A convenience variant of g_settings_set() for 32-bit integers. + * + * It is a programmer error to give a @key that isn't specified as + * having a int32 type in the schema for @settings. + * + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable + * Since: 2.26 */ /** - * g_seekable_can_truncate: - * @seekable: a #GSeekable. + * g_settings_set_int64: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to * - * Tests if the length of the stream can be adjusted with - * g_seekable_truncate(). + * Sets @key in @settings to @value. * - * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. + * A convenience variant of g_settings_set() for 64-bit integers. + * + * It is a programmer error to give a @key that isn't specified as + * having a int64 type in the schema for @settings. + * + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable + * Since: 2.50 */ /** - * g_seekable_seek: - * @seekable: a #GSeekable. - * @offset: a #goffset. - * @type: a #GSeekType. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Seeks in the stream by the given @offset, modified by @type. + * g_settings_set_string: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it 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. + * Sets @key in @settings to @value. * - * Any operation that would result in a negative offset will fail. + * A convenience variant of g_settings_set() for strings. * - * 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 specified as + * having a string type in the schema for @settings. * - * Returns: %TRUE if successful. If an error - * has occurred, this function will return %FALSE and set @error - * appropriately if present. + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable + * Since: 2.26 */ /** - * g_seekable_tell: - * @seekable: a #GSeekable. + * g_settings_set_strv: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: (nullable) (array zero-terminated=1): the value to set it to, or %NULL * - * Tells the current position within the stream. + * Sets @key in @settings to @value. * - * Returns: the offset from the beginning of the buffer. + * A convenience variant of g_settings_set() for string arrays. If + * @value is %NULL, then @key is set to be the empty array. + * + * It is a programmer error to give a @key that isn't specified as + * having an array of strings type in the schema for @settings. + * + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable + * Since: 2.26 */ /** - * g_seekable_truncate: (virtual truncate_fn) - * @seekable: a #GSeekable. - * @offset: new length for @seekable, in bytes. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_settings_set_uint: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to * - * Sets the length of the stream to @offset. If the stream was previously - * larger than @offset, the extra data is discarded. If the stream was - * previouly shorter than @offset, it is extended with NUL ('\0') bytes. + * Sets @key in @settings to @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. 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_set() for 32-bit unsigned + * integers. * - * Returns: %TRUE if successful. If an error - * has occurred, this function will return %FALSE and set @error - * appropriately if present. + * 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_settings_apply: - * @settings: a #GSettings instance + * g_settings_set_uint64: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to * - * 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. + * Sets @key in @settings to @value. + * + * A convenience variant of g_settings_set() for 64-bit unsigned + * integers. + * + * It is a programmer error to give a @key that isn't specified as + * having a uint64 type in the schema for @settings. + * + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable + * Since: 2.50 */ /** - * 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). + * g_settings_set_value: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: a #GVariant of the correct type * - * 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. + * Sets @key in @settings to @value. * - * 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()). + * 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. * - * 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. + * If @value is floating then this function consumes the reference. * + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ /** - * g_settings_backend_changed_tree: - * @backend: a #GSettingsBackend implementation - * @tree: a #GTree containing the changes - * @origin_tag: the origin tag + * g_settings_sync: * - * 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(). + * Ensures that all pending operations are complete for the default backend. * - * Since: 2.26 + * 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. + * + * 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_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) (optional) (transfer container) (array zero-terminated=1): - * the location to save the values, or %NULL + * g_settings_unbind: + * @object: (type GObject.Object): the object + * @property: the property whose binding is removed * - * 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. + * Removes an existing binding for @property on @object. * - * 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. + * Note that bindings are automatically removed when the + * object is finalized, so it is rarely necessary to call this + * function. * * Since: 2.26 */ /** - * g_settings_backend_get_default: - * - * 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. + * 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 * - * The user gets a reference to the backend. + * A convenience function for creating multiple #GSimpleAction instances + * and adding them to the action group. * - * Returns: (transfer full): the default #GSettingsBackend - * Since: 2.28 + * Since: 2.30 + * Deprecated: 2.38: Use g_action_map_add_action_entries() */ /** - * 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. + * g_simple_action_group_insert: + * @simple: a #GSimpleActionGroup + * @action: a #GAction * - * 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). + * Adds an action to the action group. * - * 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. + * If the action group already contains an action with the same name as + * @action then the old action is dropped from the group. * - * Since: 2.26 + * The action group takes its own reference on @action. + * + * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_add_action() */ /** - * 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. + * g_simple_action_group_lookup: + * @simple: a #GSimpleActionGroup + * @action_name: the name of an action * - * @path must be a valid path (ie starting and ending with a slash and - * not containing '//'). + * Looks up the action with the name @action_name in the group. * - * The meaning of this signal is that any of the key which has a name - * starting with @path may have changed. + * If no such action exists, returns %NULL. * - * 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. + * Returns: (transfer none): a #GAction, or %NULL + * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_lookup_action() + */ + + +/** + * g_simple_action_group_new: * - * 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. + * Creates a new, empty, #GSimpleActionGroup. * - * Since: 2.26 + * Returns: a new #GSimpleActionGroup + * Since: 2.28 */ /** - * g_settings_backend_path_writable_changed: - * @backend: a #GSettingsBackend implementation - * @path: the name of the path + * g_simple_action_group_remove: + * @simple: a #GSimpleActionGroup + * @action_name: the name of the action * - * Signals that the writability of all keys below a given path may have - * changed. + * Removes the named action from the action group. * - * Since GSettings performs no locking operations for itself, this call - * will always be made in response to external events. + * If no action of this name is in the group then nothing happens. * - * Since: 2.26 + * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_remove_action() */ /** - * g_settings_backend_writable_changed: - * @backend: a #GSettingsBackend implementation - * @key: the name of the key + * g_simple_action_new: + * @name: the name of the action + * @parameter_type: (nullable): the type of parameter to the activate function * - * Signals that the writability of a single key has possibly changed. + * Creates a new action. * - * Since GSettings performs no locking operations for itself, this call - * will always be made in response to external events. + * The created action is stateless. See g_simple_action_new_stateful(). * - * Since: 2.26 + * Returns: a new #GSimpleAction + * Since: 2.28 */ /** - * 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. + * g_simple_action_new_stateful: + * @name: the name of the action + * @parameter_type: (nullable): the type of the parameter to the activate function + * @state: the initial state of the action * - * 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. + * Creates a new stateful action. * - * 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. + * @state is the initial state of the action. All future state values + * must have the same #GVariantType as the initial state. * - * Note that the lifecycle of the binding is tied to @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 the @state GVariant is floating, it is consumed. * - * Since: 2.26 + * Returns: a new #GSimpleAction + * Since: 2.28 */ /** - * 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_action_set_enabled: + * @simple: a #GSimpleAction + * @enabled: whether the action is enabled * - * Create a binding between the @key in the @settings object - * and the property @property of @object. + * Sets the action as enabled or not. * - * The binding uses the provided mapping functions to map between - * settings and property values. + * An action must be enabled in order to be activated or in order to + * have its state changed from outside callers. * - * Note that the lifecycle of the binding is tied to @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. + * This should only be called by the implementor of the action. Users + * of the action should not attempt to modify its enabled flag. * - * Since: 2.26 + * Since: 2.28 */ /** - * 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 + * g_simple_action_set_state: + * @simple: a #GSimpleAction + * @value: the new #GVariant for the state * - * 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. + * Sets the state of the action. * - * Writable bindings are always uni-directional; changes of the - * writability of the setting will be propagated to the object - * property, not the other way. + * This directly updates the 'state' property to the given value. * - * 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. + * 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. * - * Note that the lifecycle of the binding is tied to @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 the @value GVariant is floating, it is consumed. * - * Since: 2.26 + * Since: 2.30 */ /** - * g_settings_create_action: - * @settings: a #GSettings - * @key: the name of a key in @settings - * - * Creates a #GAction corresponding to a given #GSettings key. - * - * The action has the same name as the key. + * g_simple_action_set_state_hint: + * @simple: a #GSimpleAction + * @state_hint: (nullable): a #GVariant representing the state hint * - * 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. + * Sets the state hint for the action. * - * 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). + * See g_action_get_state_hint() for more information about + * action state hints. * - * Returns: (transfer full): a new #GAction - * Since: 2.32 + * Since: 2.44 */ /** - * g_settings_delay: - * @settings: a #GSettings object + * g_simple_async_report_error_in_idle: (skip) + * @object: (nullable): 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. * - * 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. + * Reports an error in an asynchronous function in an idle function by + * directly setting the contents of the #GAsyncResult with the given error + * information. * - * Since: 2.26 + * Deprecated: 2.46: Use g_task_report_error(). */ /** - * 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_report_gerror_in_idle: + * @object: (nullable): a #GObject, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. + * @error: the #GError to report * - * 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. + * 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. * - * Since: 2.26 + * Deprecated: 2.46: Use g_task_report_error(). */ /** - * 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. - * - * A convenience variant of g_settings_get() for booleans. + * g_simple_async_report_take_gerror_in_idle: (skip) + * @object: (nullable): a #GObject, or %NULL + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * @error: the #GError to report * - * It is a programmer error to give a @key that isn't specified as - * having a boolean type in the schema for @settings. + * 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. * - * Returns: a boolean - * Since: 2.26 + * Since: 2.28 + * Deprecated: 2.46: Use g_task_report_error(). */ /** - * g_settings_get_child: - * @settings: a #GSettings object - * @name: the name of the child schema + * g_simple_async_result_complete: + * @simple: a #GSimpleAsyncResult. * - * Creates a child settings object which has a base path of - * `base-path/@name`, where `base-path` is the base path of - * @settings. + * 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(). * - * The schema for the child settings object must have been declared - * in the schema of @settings using a element. + * Calling this function takes a reference to @simple for as long as + * is needed to complete the call. * - * Returns: (transfer full): a 'child' settings object - * Since: 2.26 + * Deprecated: 2.46: Use #GTask instead. */ /** - * g_settings_get_default_value: - * @settings: a #GSettings object - * @key: the key to get the default value for - * - * Gets the "default value" of a key. - * - * This is the value that would be read if g_settings_reset() were to be - * called on the key. + * g_simple_async_result_complete_in_idle: + * @simple: a #GSimpleAsyncResult. * - * 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. + * 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). * - * 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. + * Calling this function takes a reference to @simple for as long as + * is needed to complete the call. * - * This function may be useful for adding an indication to a UI of what - * the default value was before the user set it. + * Deprecated: 2.46: Use #GTask instead. + */ + + +/** + * g_simple_async_result_get_op_res_gboolean: + * @simple: a #GSimpleAsyncResult. * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. + * Gets the operation result boolean from within the asynchronous result. * - * Returns: (nullable) (transfer full): the default value - * Since: 2.40 + * Returns: %TRUE if the operation's result was %TRUE, %FALSE + * if the operation's result was %FALSE. + * Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead. */ /** - * g_settings_get_double: - * @settings: a #GSettings object - * @key: the key to get the value for + * g_simple_async_result_get_op_res_gpointer: (skip) + * @simple: a #GSimpleAsyncResult. * - * Gets the value that is stored at @key in @settings. + * Gets a pointer result as returned by the asynchronous function. * - * A convenience variant of g_settings_get() for doubles. + * Returns: a pointer from the result. + * Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead. + */ + + +/** + * g_simple_async_result_get_op_res_gssize: + * @simple: a #GSimpleAsyncResult. * - * It is a programmer error to give a @key that isn't specified as - * having a 'double' type in the schema for @settings. + * Gets a gssize from the asynchronous result. * - * Returns: a double - * Since: 2.26 + * Returns: a gssize returned from the asynchronous function. + * Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead. */ /** - * g_settings_get_enum: - * @settings: a #GSettings object - * @key: the key to get the value for + * g_simple_async_result_get_source_tag: (skip) + * @simple: a #GSimpleAsyncResult. * - * Gets the value that is stored in @settings for @key and converts it - * to the enum value that it represents. + * Gets the source tag for the #GSimpleAsyncResult. * - * 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. + * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. + * Deprecated: 2.46.: Use #GTask and g_task_get_source_tag() instead. + */ + + +/** + * g_simple_async_result_is_valid: + * @result: the #GAsyncResult passed to the _finish function. + * @source: (nullable): the #GObject passed to the _finish function. + * @source_tag: (nullable): the asynchronous function. * - * 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. + * Ensures that the data passed to the _finish function of an async + * operation is consistent. Three checks are performed. * - * 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. + * 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.) * - * Returns: the enum value - * Since: 2.26 + * Returns: #TRUE if all checks passed or #FALSE if any failed. + * Since: 2.20 + * Deprecated: 2.46: Use #GTask and g_task_is_valid() instead. */ /** - * 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. + * g_simple_async_result_new: + * @source_object: (nullable): a #GObject, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. + * @source_tag: the asynchronous function. * - * 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. + * Creates a #GSimpleAsyncResult. * - * 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. + * 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. * - * 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. + * 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. * - * Returns: the flags value - * Since: 2.26 + * Returns: a #GSimpleAsyncResult. + * Deprecated: 2.46: Use g_task_new() instead. */ /** - * g_settings_get_has_unapplied: - * @settings: a #GSettings object + * g_simple_async_result_new_error: + * @source_object: (nullable): 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. * - * Returns whether the #GSettings object has any unapplied - * changes. This can only be the case if it is in 'delayed-apply' mode. + * Creates a new #GSimpleAsyncResult with a set error. * - * Returns: %TRUE if @settings has unapplied changes - * Since: 2.26 + * Returns: a #GSimpleAsyncResult. + * Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead. */ /** - * 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_new_from_error: + * @source_object: (nullable): 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 specified as - * having a int32 type in the schema for @settings. + * Creates a #GSimpleAsyncResult from an error condition. * - * Returns: an integer - * Since: 2.26 + * Returns: a #GSimpleAsyncResult. + * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. */ /** - * g_settings_get_int64: - * @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 64-bit integers. + * g_simple_async_result_new_take_error: (skip) + * @source_object: (nullable): 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 specified as - * having a int64 type in the schema for @settings. + * 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. * - * Returns: a 64-bit integer - * Since: 2.50 + * Returns: a #GSimpleAsyncResult + * Since: 2.28 + * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. */ /** - * 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). + * g_simple_async_result_propagate_error: + * @simple: a #GSimpleAsyncResult. + * @dest: (out): a location to propagate the error to. * - * 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. + * Propagates an error from within the simple asynchronous result to + * a given destination. * - * 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. + * 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: (transfer full): the result, which may be %NULL + * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. + * Deprecated: 2.46: Use #GTask instead. */ /** - * g_settings_get_range: - * @settings: a #GSettings - * @key: the key to query the range of + * g_simple_async_result_run_in_thread: (skip) + * @simple: a #GSimpleAsyncResult. + * @func: a #GSimpleAsyncThreadFunc. + * @io_priority: the io priority of the request. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. * - * Queries the range of a key. + * 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. * - * Since: 2.28 - * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead. + * Calling this function takes a reference to @simple for as long as + * is needed to run the job and report its completion. + * + * Deprecated: 2.46: Use #GTask and g_task_run_in_thread() instead. */ /** - * g_settings_get_string: - * @settings: a #GSettings object - * @key: the key to get the value for + * g_simple_async_result_set_check_cancellable: + * @simple: a #GSimpleAsyncResult + * @check_cancellable: (nullable): 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 strings. + * 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 string 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 newly-allocated string - * 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 + * Deprecated: 2.46: Use #GTask instead. */ /** - * 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. + * 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. * - * 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 an error within the asynchronous result without a #GError. * - * 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 + * Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead. */ /** - * 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_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. * - * It is a programmer error to give a @key that isn't specified as - * having a uint32 type in the schema for @settings. + * Sets an error within the asynchronous result without a #GError. + * Unless writing a binding, see g_simple_async_result_set_error(). * - * Returns: an unsigned integer - * Since: 2.30 + * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. */ /** - * g_settings_get_uint64: - * @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 64-bit unsigned - * integers. + * g_simple_async_result_set_from_error: + * @simple: a #GSimpleAsyncResult. + * @error: #GError. * - * It is a programmer error to give a @key that isn't specified as - * having a uint64 type in the schema for @settings. + * Sets the result from a #GError. * - * Returns: a 64-bit unsigned integer - * Since: 2.50 + * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. */ /** - * g_settings_get_user_value: - * @settings: a #GSettings object - * @key: the key to get the user value for - * - * Checks the "user value" of a key, if there is one. - * - * The user value of a key is the last value that was set by the user. - * - * After calling g_settings_reset() this function should always return - * %NULL (assuming something is not wrong with the system - * configuration). - * - * It is possible that g_settings_get_value() will return a different - * value than this function. This can happen in the case that the user - * set a value for a key that was subsequently locked down by the system - * administrator -- this function will return the user's old value. + * g_simple_async_result_set_handle_cancellation: + * @simple: a #GSimpleAsyncResult. + * @handle_cancellation: a #gboolean. * - * This function may be useful for adding a "reset" option to a UI or - * for providing indication that a particular value has been changed. + * Sets whether to handle cancellation within the asynchronous operation. * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. + * 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(). * - * Returns: (nullable) (transfer full): the user's value, if set - * Since: 2.40 + * Deprecated: 2.46 */ /** - * g_settings_get_value: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored in @settings for @key. + * g_simple_async_result_set_op_res_gboolean: + * @simple: a #GSimpleAsyncResult. + * @op_res: a #gboolean. * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. + * Sets the operation result to a boolean within the asynchronous result. * - * Returns: a new #GVariant - * Since: 2.26 + * Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead. */ /** - * g_settings_is_writable: - * @settings: a #GSettings object - * @name: the name of a key + * 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. * - * Finds out if a key can be written or not + * Sets the operation result within the asynchronous result to a pointer. * - * Returns: %TRUE if the key @name is writable - * Since: 2.26 + * Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead. */ /** - * g_settings_list_children: - * @settings: a #GSettings object - * - * Gets the list of children on @settings. - * - * The list is exactly the list of strings for which it is not an error - * to call g_settings_get_child(). - * - * 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. - * - * 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. + * g_simple_async_result_set_op_res_gssize: + * @simple: a #GSimpleAsyncResult. + * @op_res: a #gssize. * - * You should free the return value with g_strfreev() when you are done - * with it. + * Sets the operation result within the asynchronous result to + * the given @op_res. * - * Returns: (transfer full) (element-type utf8): a list of the children on @settings + * Deprecated: 2.46: Use #GTask and g_task_return_int() instead. */ /** - * g_settings_list_keys: - * @settings: a #GSettings object - * - * 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. + * g_simple_async_result_take_error: (skip) + * @simple: a #GSimpleAsyncResult + * @error: a #GError * - * You should free the return value with g_strfreev() when you are done - * with it. + * 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: (transfer full) (element-type utf8): a list of the keys on @settings + * Since: 2.28 + * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. */ /** - * g_settings_list_relocatable_schemas: + * g_simple_io_stream_new: + * @input_stream: a #GInputStream. + * @output_stream: a #GOutputStream. * - * Deprecated. + * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. + * See also #GIOStream. * - * 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 + * Returns: a new #GSimpleIOStream instance. + * Since: 2.44 */ /** - * g_settings_list_schemas: + * g_simple_permission_new: + * @allowed: %TRUE if the action is allowed * - * Deprecated. + * Creates a new #GPermission instance that represents an action that is + * either always or never allowed. * - * Returns: (element-type utf8) (transfer none): a list of #GSettings - * schemas that are available. The list must not be modified or - * freed. + * Returns: the #GSimplePermission, as a #GPermission * 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_settings_new: - * @schema_id: the id of the schema - * - * Creates a new #GSettings object with the schema specified by - * @schema_id. + * g_simple_proxy_resolver_new: + * @default_proxy: (nullable): the default proxy to use, eg + * "socks://192.168.1.1" + * @ignore_hosts: (nullable): an optional list of hosts/IP addresses + * to not use a proxy for. * - * 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(). + * Creates a new #GSimpleProxyResolver. See + * #GSimpleProxyResolver:default-proxy and + * #GSimpleProxyResolver:ignore-hosts for more details on how the + * arguments are interpreted. * - * Returns: a new #GSettings object - * Since: 2.26 + * Returns: (transfer full): a new #GSimpleProxyResolver + * Since: 2.36 */ /** - * g_settings_new_full: - * @schema: a #GSettingsSchema - * @backend: (nullable): a #GSettingsBackend - * @path: (nullable): the path to use - * - * Creates a new #GSettings object with a given schema, backend and - * path. + * g_simple_proxy_resolver_set_default_proxy: + * @resolver: a #GSimpleProxyResolver + * @default_proxy: the default proxy to use * - * 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). + * 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(). * - * 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 @default_proxy starts with "socks://", + * #GSimpleProxyResolver will treat it as referring to all three of + * the socks5, socks4a, and socks4 proxy types. * - * 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()). + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_ignore_hosts: + * @resolver: a #GSimpleProxyResolver + * @ignore_hosts: %NULL-terminated list of hosts/IP addresses + * to not use a proxy for * - * If @backend is %NULL then the default backend is used. + * Sets the list of ignored hosts. * - * 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. + * See #GSimpleProxyResolver:ignore-hosts for more details on how the + * @ignore_hosts argument is interpreted. * - * Returns: a new #GSettings object - * Since: 2.32 + * Since: 2.36 */ /** - * g_settings_new_with_backend: - * @schema_id: the id of the schema - * @backend: the #GSettingsBackend to use + * 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 * - * Creates a new #GSettings object with the schema specified by - * @schema_id and a given #GSettingsBackend. + * 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. * - * 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. + * 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: a new #GSettings object - * Since: 2.26 + * Since: 2.36 */ /** - * 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_accept: + * @socket: a #GSocket. + * @cancellable: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Creates a new #GSettings object with the schema specified by - * @schema_id and a given #GSettingsBackend and path. + * 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. * - * This is a mix of g_settings_new_with_backend() and - * g_settings_new_with_path(). + * The @socket must be bound to a local address with g_socket_bind() and + * must be listening for incoming connections (g_socket_listen()). * - * Returns: a new #GSettings object - * Since: 2.26 + * 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): a new #GSocket, or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_settings_new_with_path: - * @schema_id: the id of the schema - * @path: the path to use + * g_socket_address_enumerator_next: + * @enumerator: a #GSocketAddressEnumerator + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: a #GError. * - * Creates a new #GSettings object with the relocatable schema specified - * by @schema_id and a given 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. * - * 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. + * 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. * - * It is a programmer error to call this function for a schema that - * has an explicitly specified path. + * 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: (nullable): 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 * - * 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. + * 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_socket_address_enumerator_next_finish: + * @enumerator: a #GSocketAddressEnumerator + * @result: a #GAsyncResult + * @error: a #GError * - * Returns: a new #GSettings object - * Since: 2.26 + * 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. + * + * 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_settings_range_check: - * @settings: a #GSettings - * @key: the key to check - * @value: the value to check + * g_socket_address_get_family: + * @address: a #GSocketAddress * - * Checks if the given @value is of the correct type and within the - * permitted range for @key. + * Gets the socket family type of @address. * - * Returns: %TRUE if @value is valid for @key - * Since: 2.28 - * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead. + * Returns: the socket family type of @address + * Since: 2.22 */ /** - * g_settings_reset: - * @settings: a #GSettings object - * @key: the name of a key + * g_socket_address_get_native_size: + * @address: a #GSocketAddress * - * Resets @key to its default value. + * Gets the size of @address's native struct sockaddr. + * You can use this to allocate memory to pass to + * g_socket_address_to_native(). * - * 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: the size of the native struct sockaddr that + * @address represents + * Since: 2.22 */ /** - * g_settings_revert: - * @settings: a #GSettings instance + * g_socket_address_new_from_native: + * @native: (not nullable): a pointer to a struct sockaddr + * @len: the size of the memory location pointed to by @native * - * 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. + * Creates a #GSocketAddress subclass corresponding to the native + * struct sockaddr @native. * - * Change notifications will be emitted for affected keys. + * Returns: a new #GSocketAddress if @native could successfully + * be converted, otherwise %NULL + * Since: 2.22 */ /** - * g_settings_schema_get_id: - * @schema: a #GSettingsSchema + * 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 * - * Get the ID of @schema. + * Converts a #GSocketAddress to a native struct sockaddr, which can + * be passed to low-level functions like connect() or bind(). * - * Returns: (transfer none): the ID + * If not enough space is available, a %G_IO_ERROR_NO_SPACE error + * is returned. If the address type is not known on the system + * then a %G_IO_ERROR_NOT_SUPPORTED error is returned. + * + * Returns: %TRUE if @dest was filled in, %FALSE on error + * Since: 2.22 */ /** - * g_settings_schema_get_key: - * @schema: a #GSettingsSchema - * @name: the name of a key + * 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. * - * Gets the key named @name from @schema. + * 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. * - * It is a programmer error to request a key that does not exist. See - * g_settings_schema_list_keys(). + * 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 @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: (transfer full): the #GSettingsSchemaKey for @name - * Since: 2.40 + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.22 */ /** - * g_settings_schema_get_path: - * @schema: a #GSettingsSchema - * - * Gets the path associated with @schema, or %NULL. - * - * 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. + * g_socket_check_connect_result: + * @socket: a #GSocket + * @error: #GError for error reporting, or %NULL to ignore. * - * 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. + * 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: (transfer none): the path of the schema, or %NULL - * Since: 2.32 + * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error + * Since: 2.22 */ /** - * g_settings_schema_has_key: - * @schema: a #GSettingsSchema - * @name: the name of a key + * g_socket_client_add_application_proxy: + * @client: a #GSocketClient + * @protocol: The proxy protocol * - * Checks if @schema has a key named @name. + * 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. * - * Returns: %TRUE if such a key exists - * Since: 2.40 + * 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. + * + * 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_schema_key_get_default_value: - * @key: a #GSettingsSchemaKey + * g_socket_client_connect: + * @client: a #GSocketClient. + * @connectable: a #GSocketConnectable specifying the remote address. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the default value for @key. + * Tries to resolve the @connectable and make a network connection to it. * - * Note that this is the default value according to the schema. System - * administrator defaults and lockdown are not visible via this API. + * 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. * - * Returns: (transfer full): the default value for the key - * Since: 2.40 + * 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(). + * + * If a local address is specified with g_socket_client_set_local_address() the + * socket will be bound to this address before connecting. + * + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_settings_schema_key_get_description: - * @key: a #GSettingsSchemaKey - * - * Gets the description for @key. - * - * If no description has been provided in the schema for @key, returns - * %NULL. + * g_socket_client_connect_async: + * @client: a #GSocketClient + * @connectable: a #GSocketConnectable specifying the remote address. + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * The description can be one sentence to several paragraphs in length. - * Paragraphs are delimited with a double newline. Descriptions can be - * translated and the value returned from this function is is the - * current locale. + * This is the asynchronous version of g_socket_client_connect(). * - * 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. + * 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: the description for @key, or %NULL - * Since: 2.34 + * Since: 2.22 */ /** - * g_settings_schema_key_get_name: - * @key: a #GSettingsSchemaKey + * g_socket_client_connect_finish: + * @client: a #GSocketClient. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * Gets the name of @key. + * Finishes an async connect operation. See g_socket_client_connect_async() * - * Returns: the name of @key. - * Since: 2.44 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_settings_schema_key_get_range: - * @key: a #GSettingsSchemaKey - * - * Queries the range of a key. + * 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: (nullable): a #GCancellable, or %NULL + * @error: a pointer to a #GError, or %NULL * - * This function will return a #GVariant that fully describes the range - * of values that are valid for @key. + * This is a helper function for g_socket_client_connect(). * - * 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. + * Attempts to create a TCP connection to the named host. * - * 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. + * @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). * - * 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 no port override is given in @host_and_port then @default_port will be + * used as the port number to connect to. * - * 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']`. + * 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. * - * 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. + * 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. * - * 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. + * 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. * - * You should free the returned value with g_variant_unref() when it is - * no longer needed. + * 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 #GVariant describing the range - * Since: 2.40 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_settings_schema_key_get_summary: - * @key: a #GSettingsSchemaKey - * - * Gets the summary for @key. - * - * If no summary has been provided in the schema for @key, returns - * %NULL. + * 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: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * 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 is the asynchronous version of g_socket_client_connect_to_host(). * - * 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. + * 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: the summary for @key, or %NULL - * Since: 2.34 + * Since: 2.22 */ /** - * g_settings_schema_key_get_value_type: - * @key: a #GSettingsSchemaKey + * 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. * - * Gets the #GVariantType of @key. + * Finishes an async connect operation. See g_socket_client_connect_to_host_async() * - * Returns: (transfer none): the type of @key - * Since: 2.40 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_settings_schema_key_range_check: - * @key: a #GSettingsSchemaKey - * @value: the value to check + * g_socket_client_connect_to_service: + * @client: a #GSocketConnection + * @domain: a domain name + * @service: the name of the service to connect to + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a pointer to a #GError, or %NULL * - * Checks if the given @value is of the correct type and within the - * permitted range for @key. + * Attempts to create a TCP connection to a service. * - * It is a programmer error if @value is not of the correct type -- you - * must check for this first. + * 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: %TRUE if @value is valid for @key - * Since: 2.40 + * 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 if successful, or %NULL on error */ /** - * g_settings_schema_key_ref: - * @key: a #GSettingsSchemaKey + * g_socket_client_connect_to_service_async: + * @client: a #GSocketClient + * @domain: a domain name + * @service: the name of the service to connect to + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Increase the reference count of @key, returning a new reference. + * This is the asynchronous version of + * g_socket_client_connect_to_service(). * - * Returns: a new reference to @key - * Since: 2.40 + * Since: 2.22 */ /** - * g_settings_schema_key_unref: - * @key: a #GSettingsSchemaKey + * 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. * - * Decrease the reference count of @key, possibly freeing it. + * Finishes an async connect operation. See g_socket_client_connect_to_service_async() * - * Since: 2.40 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_settings_schema_list_children: - * @schema: a #GSettingsSchema + * g_socket_client_connect_to_uri: + * @client: a #GSocketClient + * @uri: A network URI + * @default_port: the default port to connect to + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a pointer to a #GError, or %NULL * - * Gets the list of children in @schema. + * This is a helper function for g_socket_client_connect(). * - * You should free the return value with g_strfreev() when you are done - * with it. + * Attempts to create a TCP connection with a network URI. * - * Returns: (transfer full) (element-type utf8): a list of the children on @settings - * Since: 2.44 - */ - - -/** - * g_settings_schema_list_keys: - * @schema: a #GSettingsSchema + * @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.) * - * Introspects the list of keys on @schema. + * 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. * - * 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. + * 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. * - * Returns: (transfer full) (element-type utf8): a list of the keys on - * @schema - * Since: 2.46 + * 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.26 */ /** - * g_settings_schema_ref: - * @schema: a #GSettingsSchema + * g_socket_client_connect_to_uri_async: + * @client: a #GSocketClient + * @uri: a network uri + * @default_port: the default port to connect to + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Increase the reference count of @schema, returning a new reference. + * This is the asynchronous version of g_socket_client_connect_to_uri(). * - * Returns: a new reference to @schema - * 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_get_default: - * - * 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. - * - * If no schemas are installed, %NULL will be returned. + * 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. * - * 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. + * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() * - * Returns: (transfer none) (nullable): the default schema source - * Since: 2.32 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.26 */ /** - * g_settings_schema_source_list_schemas: - * @source: a #GSettingsSchemaSource - * @recursive: if we should recurse - * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the - * list of non-relocatable schemas - * @relocatable: (out) (transfer full) (array zero-terminated=1): the list - * of relocatable schemas - * - * Lists the schemas in a given source. - * - * If @recursive is %TRUE then include parent sources. If %FALSE then - * only include the schemas from one source (ie: one directory). You - * probably want %TRUE. - * - * Non-relocatable schemas are those for which you can call - * g_settings_new(). Relocatable schemas are those for which you must - * use g_settings_new_with_path(). + * g_socket_client_get_enable_proxy: + * @client: a #GSocketClient. * - * Do not call this function from normal programs. This is designed for - * use by database editors, commandline tools, etc. + * Gets the proxy enable state; see g_socket_client_set_enable_proxy() * - * Since: 2.40 + * Returns: whether proxying is enabled + * Since: 2.26 */ /** - * 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. + * g_socket_client_get_family: + * @client: a #GSocketClient. * - * If the schema isn't found directly in @source and @recursive is %TRUE - * then the parent sources will also be checked. + * Gets the socket family of the socket client. * - * If the schema isn't found, %NULL is returned. + * See g_socket_client_set_family() for details. * - * Returns: (nullable) (transfer full): a new #GSettingsSchema - * Since: 2.32 + * Returns: a #GSocketFamily + * Since: 2.22 */ /** - * g_settings_schema_source_new_from_directory: - * @directory: (type filename): the filename of a directory - * @parent: (nullable): a #GSettingsSchemaSource, or %NULL - * @trusted: %TRUE, if the directory is trusted - * @error: a pointer to a #GError pointer set to %NULL, or %NULL - * - * Attempts to create a new schema source corresponding to the contents - * of the given directory. - * - * This function is not required for normal uses of #GSettings but it - * may be useful to authors of plugin management systems. - * - * The directory should contain a file called `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. + * g_socket_client_get_local_address: + * @client: a #GSocketClient. * - * Second, any references to other schemas specified within this - * source (ie: `child` or `extends`) references may be resolved - * from the @parent. + * Gets the local address of the socket client. * - * 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(). + * See g_socket_client_set_local_address() for details. * - * Since: 2.32 + * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free. + * Since: 2.22 */ /** - * g_settings_schema_source_ref: - * @source: a #GSettingsSchemaSource + * g_socket_client_get_protocol: + * @client: a #GSocketClient * - * Increase the reference count of @source, returning a new reference. + * Gets the protocol name type of the socket client. * - * Returns: a new reference to @source - * Since: 2.32 + * See g_socket_client_set_protocol() for details. + * + * Returns: a #GSocketProtocol + * Since: 2.22 */ /** - * g_settings_schema_source_unref: - * @source: a #GSettingsSchemaSource + * g_socket_client_get_proxy_resolver: + * @client: a #GSocketClient. * - * Decrease the reference count of @source, possibly freeing it. + * 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(). * - * Since: 2.32 + * Returns: (transfer none): The #GProxyResolver being used by + * @client. + * Since: 2.36 */ /** - * g_settings_schema_unref: - * @schema: a #GSettingsSchema + * g_socket_client_get_socket_type: + * @client: a #GSocketClient. * - * Decrease the reference count of @schema, possibly freeing it. + * Gets the socket type of the socket client. * - * Since: 2.32 + * See g_socket_client_set_socket_type() for details. + * + * Returns: a #GSocketFamily + * Since: 2.22 */ /** - * 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. + * g_socket_client_get_timeout: + * @client: a #GSocketClient * - * A convenience function that combines g_settings_set_value() with - * g_variant_new(). + * Gets the I/O timeout time for sockets created by @client. * - * 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. + * See g_socket_client_set_timeout() for details. * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable + * Returns: the timeout in seconds * Since: 2.26 */ /** - * g_settings_set_boolean: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to + * g_socket_client_get_tls: + * @client: a #GSocketClient. * - * Sets @key in @settings to @value. + * Gets whether @client creates TLS connections. See + * g_socket_client_set_tls() for details. * - * A convenience variant of g_settings_set() for booleans. + * Returns: whether @client uses TLS + * Since: 2.28 + */ + + +/** + * g_socket_client_get_tls_validation_flags: + * @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 TLS validation flags used creating TLS connections via + * @client. * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 + * Returns: the TLS validation flags + * Since: 2.28 */ /** - * g_settings_set_double: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to + * 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 doubles. + * 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 a 'double' 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. + * + * See also g_socket_client_set_proxy_resolver(). * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable * Since: 2.26 */ /** - * 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. + * g_socket_client_set_family: + * @client: a #GSocketClient. + * @family: a #GSocketFamily * - * 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. + * 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. * - * After performing the write, accessing @key directly with - * g_settings_get_string() will return the 'nick' associated with - * @value. + * 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 the set succeeds + * Since: 2.22 */ /** - * 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_set_local_address: + * @client: a #GSocketClient. + * @address: (nullable): a #GSocketAddress, or %NULL * - * 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. + * 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. * - * After performing the write, accessing @key directly with - * g_settings_get_strv() will return an array of 'nicks'; one for each - * bit in @value. + * 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 the set succeeds + * 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. + * g_socket_client_set_protocol: + * @client: a #GSocketClient. + * @protocol: a #GSocketProtocol * - * A convenience variant of g_settings_set() for 32-bit integers. + * Sets the protocol of the socket client. + * The sockets created by this object will use of the specified + * protocol. * - * It is a programmer error to give a @key that isn't specified as - * having a int32 type in the schema for @settings. + * If @protocol is %0 that means to use the default + * protocol for the socket family and type. * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 + * Since: 2.22 */ /** - * g_settings_set_int64: - * @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_set_proxy_resolver: + * @client: a #GSocketClient. + * @proxy_resolver: (nullable): a #GProxyResolver, or %NULL for the + * default. * - * A convenience variant of g_settings_set() for 64-bit integers. + * 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. * - * It is a programmer error to give a @key that isn't specified as - * having a int64 type in the schema for @settings. + * Note that whether or not the proxy resolver is actually used + * depends on the setting of #GSocketClient:enable-proxy, which is not + * changed by this function (but which is %TRUE by default) * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.50 + * Since: 2.36 */ /** - * 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_set_socket_type: + * @client: a #GSocketClient. + * @type: a #GSocketType * - * A convenience variant of g_settings_set() for strings. + * Sets the socket type of the socket client. + * The sockets created by this object will be of the specified + * type. * - * It is a programmer error to give a @key that isn't specified as - * having a string type in the schema for @settings. + * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, + * as GSocketClient is used for connection oriented services. * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 + * Since: 2.22 */ /** - * g_settings_set_strv: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: (nullable) (array zero-terminated=1): the value to set it to, or %NULL - * - * Sets @key in @settings to @value. + * g_socket_client_set_timeout: + * @client: a #GSocketClient. + * @timeout: the timeout * - * A convenience variant of g_settings_set() for string arrays. If - * @value is %NULL, then @key is set to be the empty array. + * Sets the I/O timeout for sockets created by @client. @timeout is a + * time in seconds, or 0 for no timeout (the default). * - * 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. + * 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: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable * 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 + * g_socket_client_set_tls: + * @client: a #GSocketClient. + * @tls: whether to use TLS * - * Sets @key in @settings to @value. + * 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. * - * A convenience variant of g_settings_set() for 32-bit unsigned - * integers. + * 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. * - * It is a programmer error to give a @key that isn't specified as - * having a uint32 type in the schema for @settings. + * 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: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.30 + * Since: 2.28 */ /** - * g_settings_set_uint64: - * @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 64-bit unsigned - * integers. + * g_socket_client_set_tls_validation_flags: + * @client: a #GSocketClient. + * @flags: the validation flags * - * It is a programmer error to give a @key that isn't specified as - * having a uint64 type in the schema for @settings. + * Sets the TLS validation flags used when creating TLS connections + * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.50 + * Since: 2.28 */ /** - * g_settings_set_value: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: a #GVariant of the correct type + * g_socket_close: + * @socket: a #GSocket + * @error: #GError for error reporting, or %NULL to ignore. * - * Sets @key in @settings to @value. + * Closes the socket, shutting down any active connection. * - * 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. + * 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. * - * If @value is floating then this function consumes the reference. + * Once the socket is closed, all other operations will return + * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not + * return an error. * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 + * 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.) + * + * Returns: %TRUE on success, %FALSE on error + * Since: 2.22 */ /** - * g_settings_sync: + * g_socket_condition_check: + * @socket: a #GSocket + * @condition: a #GIOCondition mask to check * - * Ensures that all pending operations are complete for the default backend. + * 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. * - * 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. + * 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. * - * 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). + * 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. + * + * This call never blocks. + * + * Returns: the @GIOCondition mask of the current state + * Since: 2.22 */ /** - * g_settings_unbind: - * @object: (type GObject.Object): the object - * @property: the property whose binding is removed + * 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: (nullable): a #GCancellable, or %NULL + * @error: a #GError pointer, or %NULL * - * Removes an existing binding for @property on @object. + * Waits for up to @timeout microseconds for @condition to become true + * on @socket. If the condition is met, %TRUE is returned. * - * Note that bindings are automatically removed when the - * object is finalized, so it is rarely necessary to call this - * function. + * 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). * - * Since: 2.26 - */ - - -/** - * 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 + * If you don't want a timeout, use g_socket_condition_wait(). + * (Alternatively, you can pass -1 for @timeout.) * - * A convenience function for creating multiple #GSimpleAction instances - * and adding them to the action group. + * 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. * - * Since: 2.30 - * Deprecated: 2.38: Use g_action_map_add_action_entries() + * 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: (nullable): 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 - * Deprecated: 2.38: Use g_action_map_add_action() + * 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: (nullable): 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 - * Deprecated: 2.38: Use g_action_map_lookup_action() + * 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 - * Deprecated: 2.38: Use g_action_map_remove_action() + * Returns: (transfer full): a new #GSocketAddressEnumerator. + * Since: 2.26 */ /** - * g_simple_action_new: - * @name: the name of the action - * @parameter_type: (nullable): the type of parameter to the activate function + * g_socket_connectable_to_string: + * @connectable: a #GSocketConnectable * - * Creates a new action. + * Format a #GSocketConnectable as a string. This is a human-readable format for + * use in debugging output, and is not a stable serialization format. It is not + * suitable for use in user interfaces as it exposes too much information for a + * user. * - * The created action is stateless. See g_simple_action_new_stateful(). + * If the #GSocketConnectable implementation does not support string formatting, + * the implementation’s type name will be returned as a fallback. * - * Returns: a new #GSimpleAction - * Since: 2.28 + * Returns: (transfer full): the formatted string + * Since: 2.48 */ /** - * g_simple_action_new_stateful: - * @name: the name of the action - * @parameter_type: (nullable): the type of the parameter to the activate function - * @state: the initial state of the action - * - * Creates a new stateful action. - * - * @state is the initial state of the action. All future state values - * must have the same #GVariantType as the initial state. + * g_socket_connection_connect: + * @connection: a #GSocketConnection + * @address: a #GSocketAddress specifying the remote address. + * @cancellable: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * If the @state GVariant is floating, it is consumed. + * 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_set_enabled: - * @simple: a #GSimpleAction - * @enabled: whether the action is enabled + * g_socket_connection_connect_async: + * @connection: a #GSocketConnection + * @address: a #GSocketAddress specifying the remote address. + * @cancellable: (nullable): a %GCancellable or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Sets the action as enabled or not. + * Asynchronously connect @connection to the specified remote address. * - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. + * This clears the #GSocket:blocking flag on @connection's underlying + * socket if it is currently set. * - * This should only be called by the implementor of the action. Users - * of the action should not attempt to modify its enabled flag. + * Use g_socket_connection_connect_finish() to retrieve the result. * - * Since: 2.28 + * 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. - * - * 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. + * g_socket_connection_connect_finish: + * @connection: a #GSocketConnection + * @result: the #GAsyncResult + * @error: #GError for error reporting, or %NULL to ignore. * - * If the @value GVariant is floating, it is consumed. + * Gets the result of a g_socket_connection_connect_async() call. * - * Since: 2.30 + * Returns: %TRUE if the connection succeeded, %FALSE on error + * Since: 2.32 */ /** - * g_simple_action_set_state_hint: - * @simple: a #GSimpleAction - * @state_hint: (nullable): a #GVariant representing the state hint - * - * Sets the state hint for the action. + * g_socket_connection_factory_create_connection: + * @socket: a #GSocket * - * See g_action_get_state_hint() for more information about - * action state hints. + * Creates a #GSocketConnection subclass of the right type for + * @socket. * - * Since: 2.44 + * Returns: (transfer full): a #GSocketConnection + * Since: 2.22 */ /** - * g_simple_async_report_error_in_idle: (skip) - * @object: (nullable): 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 * - * Reports an error in an asynchronous function in an idle function by - * directly setting the contents of the #GAsyncResult with the given error - * information. + * Looks up the #GType to be used when creating socket connections on + * sockets with the specified @family, @type and @protocol_id. * - * Deprecated: 2.46: Use g_task_report_error(). + * 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: (nullable): 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. * - * Deprecated: 2.46: Use g_task_report_error(). + * If no type is registered, the #GSocketConnection base type is returned. + * + * Since: 2.22 */ /** - * g_simple_async_report_take_gerror_in_idle: (skip) - * @object: (nullable): 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 - * Deprecated: 2.46: Use g_task_report_error(). + * 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)...". * - * Deprecated: 2.46: Use #GTask instead. + * 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 - * [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). + * 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 #GSocket or %NULL on error. + * Since: 2.22 + */ + + +/** + * g_socket_connection_is_connected: + * @connection: a #GSocketConnection * - * Deprecated: 2.46: Use #GTask instead. + * Checks if @connection is connected. This is equivalent to calling + * g_socket_is_connected() on @connection's underlying #GSocket. + * + * Returns: whether @connection is connected + * Since: 2.32 */ /** - * g_simple_async_result_get_op_res_gboolean: - * @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 the operation result boolean from within the asynchronous result. + * 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: %TRUE if the operation's result was %TRUE, %FALSE - * if the operation's result was %FALSE. - * Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead. + * 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_gpointer: (skip) - * @simple: a #GSimpleAsyncResult. + * g_socket_control_message_get_level: + * @message: a #GSocketControlMessage * - * Gets a pointer result as returned by the asynchronous function. + * Returns the "level" (i.e. the originating protocol) of the control message. + * This is often SOL_SOCKET. * - * Returns: a pointer from the result. - * Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead. + * Returns: an integer describing the level + * Since: 2.22 */ /** - * g_simple_async_result_get_op_res_gssize: - * @simple: a #GSimpleAsyncResult. + * g_socket_control_message_get_msg_type: + * @message: a #GSocketControlMessage * - * Gets a gssize from the asynchronous result. + * Returns the protocol specific type of the control message. + * For instance, for UNIX fd passing this would be SCM_RIGHTS. * - * Returns: a gssize returned from the asynchronous function. - * Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead. + * Returns: an integer describing the type of control message + * Since: 2.22 */ /** - * g_simple_async_result_get_source_tag: (skip) - * @simple: a #GSimpleAsyncResult. + * g_socket_control_message_get_size: + * @message: a #GSocketControlMessage * - * Gets the source tag for the #GSimpleAsyncResult. + * Returns the space required for the control message, not including + * headers or alignment. * - * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. - * Deprecated: 2.46.: Use #GTask and g_task_get_source_tag() instead. + * Returns: The number of bytes required. + * Since: 2.22 */ /** - * g_simple_async_result_is_valid: - * @result: the #GAsyncResult passed to the _finish function. - * @source: (nullable): the #GObject passed to the _finish function. - * @source_tag: (nullable): the asynchronous function. + * g_socket_control_message_serialize: + * @message: a #GSocketControlMessage + * @data: (not nullable): A buffer to write data to * - * Ensures that the data passed to the _finish function of an async - * operation is consistent. Three checks are performed. + * Converts the data in the message to bytes placed in the + * message. * - * 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.) + * @data is guaranteed to have enough space to fit the size + * returned by g_socket_control_message_get_size() on this + * object. * - * Returns: #TRUE if all checks passed or #FALSE if any failed. - * Since: 2.20 - * Deprecated: 2.46: Use #GTask and g_task_is_valid() instead. + * Since: 2.22 */ /** - * g_simple_async_result_new: - * @source_object: (nullable): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @source_tag: the asynchronous function. + * g_socket_create_source: (skip) + * @socket: a #GSocket + * @condition: a #GIOCondition mask to monitor + * @cancellable: (nullable): a %GCancellable or %NULL * - * Creates a #GSimpleAsyncResult. + * Creates a #GSource that can be attached to a %GMainContext to monitor + * for the availability of the specified @condition on the socket. The #GSource + * keeps a reference to the @socket. * - * The common convention is to create the #GSimpleAsyncResult in the - * function that starts the asynchronous operation and use that same - * function as the @source_tag. + * The callback on the source is of the #GSocketSourceFunc type. * - * 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. + * 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. * - * Returns: a #GSimpleAsyncResult. - * Deprecated: 2.46: Use g_task_new() instead. + * @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_error: - * @source_object: (nullable): 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_get_available_bytes: + * @socket: a #GSocket * - * Creates a new #GSimpleAsyncResult with a set error. + * Get the amount of data pending in the OS input buffer, without blocking. * - * Returns: a #GSimpleAsyncResult. - * Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead. + * 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_from_error: - * @source_object: (nullable): 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. + * Gets the blocking mode of the socket. For details on blocking I/O, + * see g_socket_set_blocking(). * - * Returns: a #GSimpleAsyncResult. - * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. + * Returns: %TRUE if blocking I/O is used, %FALSE otherwise. + * Since: 2.22 */ /** - * g_simple_async_result_new_take_error: (skip) - * @source_object: (nullable): a #GObject, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data passed to @callback - * @error: a #GError + * g_socket_get_broadcast: + * @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 broadcast setting on @socket; if %TRUE, + * it is possible to send packets to broadcast + * addresses. * - * Returns: a #GSimpleAsyncResult - * Since: 2.28 - * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. + * Returns: the broadcast setting on @socket + * Since: 2.32 */ /** - * g_simple_async_result_propagate_error: - * @simple: a #GSimpleAsyncResult. - * @dest: (out): a location to propagate the error to. + * g_socket_get_credentials: + * @socket: a #GSocket. + * @error: #GError for error reporting, or %NULL to ignore. * - * Propagates an error from within the simple asynchronous result to - * a given destination. + * 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 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. + * 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. * - * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. - * Deprecated: 2.46: Use #GTask instead. + * 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_run_in_thread: (skip) - * @simple: a #GSimpleAsyncResult. - * @func: a #GSimpleAsyncThreadFunc. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %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. + * g_socket_get_family: + * @socket: a #GSocket. * - * Calling this function takes a reference to @simple for as long as - * is needed to run the job and report its completion. + * Gets the socket family of the socket. * - * Deprecated: 2.46: Use #GTask and g_task_run_in_thread() instead. + * Returns: a #GSocketFamily + * Since: 2.22 */ /** - * g_simple_async_result_set_check_cancellable: - * @simple: a #GSimpleAsyncResult - * @check_cancellable: (nullable): a #GCancellable to check, or %NULL to unset - * - * Sets a #GCancellable to check before dispatching results. - * - * 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). - * - * 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). + * g_socket_get_fd: + * @socket: a #GSocket. * - * The checking described above is done regardless of any call to the - * unrelated g_simple_async_result_set_handle_cancellation() function. + * 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. * - * Since: 2.32 - * Deprecated: 2.46: Use #GTask instead. + * Returns: the file descriptor of the socket. + * Since: 2.22 */ /** - * 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_keepalive: + * @socket: a #GSocket. * - * Sets an error within the asynchronous result without a #GError. + * Gets the keepalive mode of the socket. For details on this, + * see g_socket_set_keepalive(). * - * Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead. + * Returns: %TRUE if keepalive is active, %FALSE otherwise. + * 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_listen_backlog: + * @socket: a #GSocket. * - * Sets an error within the asynchronous result without a #GError. - * Unless writing a binding, see g_simple_async_result_set_error(). + * Gets the listen backlog setting of the socket. For details on this, + * see g_socket_set_listen_backlog(). * - * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. + * Returns: the maximum number of pending connections. + * Since: 2.22 */ /** - * g_simple_async_result_set_from_error: - * @simple: a #GSimpleAsyncResult. - * @error: #GError. + * g_socket_get_local_address: + * @socket: a #GSocket. + * @error: #GError for error reporting, or %NULL to ignore. * - * Sets the result from a #GError. + * 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. * - * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. + * 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_handle_cancellation: - * @simple: a #GSimpleAsyncResult. - * @handle_cancellation: a #gboolean. - * - * Sets whether to handle cancellation within the asynchronous operation. + * g_socket_get_multicast_loopback: + * @socket: a #GSocket. * - * 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(). + * 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. * - * Deprecated: 2.46 + * Returns: the multicast loopback setting on @socket + * Since: 2.32 */ /** - * g_simple_async_result_set_op_res_gboolean: - * @simple: a #GSimpleAsyncResult. - * @op_res: a #gboolean. + * g_socket_get_multicast_ttl: + * @socket: a #GSocket. * - * Sets the operation result to a boolean within the asynchronous result. + * Gets the multicast time-to-live setting on @socket; see + * g_socket_set_multicast_ttl() for more details. * - * Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead. + * Returns: the multicast time-to-live setting on @socket + * Since: 2.32 */ /** - * 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_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 operation result within the asynchronous result to a pointer. + * 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.) * - * Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead. + * The [][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_async_result_set_op_res_gssize: - * @simple: a #GSimpleAsyncResult. - * @op_res: a #gssize. + * g_socket_get_protocol: + * @socket: a #GSocket. * - * Sets the operation result within the asynchronous result to - * the given @op_res. + * Gets the socket protocol id the socket was created with. + * In case the protocol is unknown, -1 is returned. * - * Deprecated: 2.46: Use #GTask and g_task_return_int() instead. + * Returns: a protocol id, or -1 if unknown + * Since: 2.22 */ /** - * g_simple_async_result_take_error: (skip) - * @simple: a #GSimpleAsyncResult - * @error: a #GError + * g_socket_get_remote_address: + * @socket: a #GSocket. + * @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. + * Try to get the remote address of a connected socket. This is only + * useful for connection oriented sockets that have been connected. * - * Since: 2.28 - * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.22 */ /** - * g_simple_io_stream_new: - * @input_stream: a #GInputStream. - * @output_stream: a #GOutputStream. - * - * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. - * See also #GIOStream. + * g_socket_get_socket_type: + * @socket: a #GSocket. * - * Returns: a new #GSimpleIOStream instance. - * Since: 2.44 + * Gets the socket type of the socket. + * + * Returns: a #GSocketType + * Since: 2.22 */ /** - * g_simple_permission_new: - * @allowed: %TRUE if the action is allowed + * g_socket_get_timeout: + * @socket: a #GSocket. * - * Creates a new #GPermission instance that represents an action that is - * either always or never allowed. + * Gets the timeout setting of the socket. For details on this, see + * g_socket_set_timeout(). * - * Returns: the #GSimplePermission, as a #GPermission + * Returns: the timeout in seconds * Since: 2.26 */ /** - * g_simple_proxy_resolver_new: - * @default_proxy: (nullable): the default proxy to use, eg - * "socks://192.168.1.1" - * @ignore_hosts: (nullable): an optional list of hosts/IP addresses - * to not use a proxy for. + * g_socket_get_ttl: + * @socket: a #GSocket. * - * Creates a new #GSimpleProxyResolver. See - * #GSimpleProxyResolver:default-proxy and - * #GSimpleProxyResolver:ignore-hosts for more details on how the - * arguments are interpreted. + * Gets the unicast time-to-live setting on @socket; see + * g_socket_set_ttl() for more details. * - * Returns: (transfer full): a new #GSimpleProxyResolver - * Since: 2.36 + * Returns: the time-to-live setting on @socket + * Since: 2.32 */ /** - * g_simple_proxy_resolver_set_default_proxy: - * @resolver: a #GSimpleProxyResolver - * @default_proxy: the default proxy to use - * - * Sets the default proxy on @resolver, to be used for any URIs that - * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set - * via g_simple_proxy_resolver_set_uri_proxy(). + * g_socket_is_closed: + * @socket: a #GSocket * - * If @default_proxy starts with "socks://", - * #GSimpleProxyResolver will treat it as referring to all three of - * the socks5, socks4a, and socks4 proxy types. + * Checks whether a socket is closed. * - * Since: 2.36 + * Returns: %TRUE if socket is closed, %FALSE otherwise + * Since: 2.22 */ /** - * 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 + * g_socket_is_connected: + * @socket: a #GSocket. * - * Sets the list of ignored hosts. + * Check whether the socket is connected. This is only useful for + * connection-oriented sockets. * - * See #GSimpleProxyResolver:ignore-hosts for more details on how the - * @ignore_hosts argument is interpreted. + * If using g_socket_shutdown(), this function will return %TRUE until the + * socket has been shut down for reading and writing. If you do a non-blocking + * connect, this function will not return %TRUE until after you call + * g_socket_check_connect_result(). * - * Since: 2.36 + * Returns: %TRUE if socket is connected, %FALSE otherwise. + * Since: 2.22 */ /** - * 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 + * g_socket_join_multicast_group: + * @socket: a #GSocket. + * @group: a #GInetAddress specifying the group address to join. + * @iface: (nullable): 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. * - * 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. + * 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(). * - * 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. + * If @iface is %NULL, the system will automatically pick an interface + * to bind to based on @group. * - * Since: 2.36 + * 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. + * + * To bind to a given source-specific multicast address, use + * g_socket_join_multicast_group_ssm() instead. + * + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.32 */ /** - * g_socket_accept: + * g_socket_join_multicast_group_ssm: * @socket: a #GSocket. - * @cancellable: (nullable): a %GCancellable or %NULL + * @group: a #GInetAddress specifying the group address to join. + * @source_specific: (nullable): a #GInetAddress specifying the + * source-specific multicast address or %NULL to ignore. + * @iface: (nullable): Name of the interface to use, 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. + * 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(). * - * The @socket must be bound to a local address with g_socket_bind() and - * must be listening for incoming connections (g_socket_listen()). + * If @iface is %NULL, the system will automatically pick an interface + * to bind to based on @group. * - * 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. + * If @source_specific is not %NULL, use source-specific multicast as + * defined in RFC 4604. Note that on older platforms this may fail + * with a %G_IO_ERROR_NOT_SUPPORTED error. * - * Returns: (transfer full): a new #GSocket, or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * Note that this function can be called multiple times for the same + * @group with different @source_specific in order to receive multicast + * packets from more than one source. + * + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.56 */ /** - * g_socket_address_enumerator_next: - * @enumerator: a #GSocketAddressEnumerator - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * g_socket_leave_multicast_group: + * @socket: a #GSocket. + * @group: a #GInetAddress specifying the group address to leave. + * @iface: (nullable): Interface used + * @source_specific: %TRUE if source-specific multicast was used + * @error: #GError for error reporting, or %NULL to ignore. * - * 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. + * 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 @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. + * @socket remains bound to its address and port, and can still receive + * unicast messages after calling this. * - * 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: (nullable): 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 + * To unbind to a given source-specific multicast address, use + * g_socket_leave_multicast_group_ssm() instead. * - * Asynchronously retrieves the next #GSocketAddress from @enumerator - * and then calls @callback, which must call - * g_socket_address_enumerator_next_finish() to get the result. + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.32 */ /** - * g_socket_address_enumerator_next_finish: - * @enumerator: a #GSocketAddressEnumerator - * @result: a #GAsyncResult - * @error: a #GError + * g_socket_leave_multicast_group_ssm: + * @socket: a #GSocket. + * @group: a #GInetAddress specifying the group address to leave. + * @source_specific: (nullable): a #GInetAddress specifying the + * source-specific multicast address or %NULL to ignore. + * @iface: (nullable): Name of the interface to use, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * 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. + * 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). * - * 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. + * @socket remains bound to its address and port, and can still receive + * unicast messages after calling this. + * + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.56 */ /** - * g_socket_address_get_family: - * @address: a #GSocketAddress + * g_socket_listen: + * @socket: a #GSocket. + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the socket family type of @address. + * Marks the socket as a server socket, i.e. a socket that is used + * to accept incoming requests using g_socket_accept(). * - * Returns: the socket family type of @address + * Before calling this the socket must be bound to a local address using + * g_socket_bind(). + * + * 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_address_get_native_size: - * @address: a #GSocketAddress + * g_socket_listener_accept: + * @listener: a #GSocketListener + * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the size of @address's native struct sockaddr. - * You can use this to allocate memory to pass to - * g_socket_address_to_native(). + * 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 size of the native struct sockaddr that - * @address represents + * 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_address_new_from_native: - * @native: (not nullable): a pointer to a struct sockaddr - * @len: the size of the memory location pointed to by @native + * g_socket_listener_accept_async: + * @listener: a #GSocketListener + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Creates a #GSocketAddress subclass corresponding to the native - * struct sockaddr @native. + * 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. * - * Returns: a new #GSocketAddress if @native could successfully - * be converted, otherwise %NULL * Since: 2.22 */ /** - * g_socket_address_to_native: - * @address: a #GSocketAddress - * @dest: a pointer to a memory location that will contain the native - * struct sockaddr - * @destlen: the size of @dest. Must be at least as large as - * g_socket_address_get_native_size() - * @error: #GError for error reporting, or %NULL to ignore - * - * Converts a #GSocketAddress to a native struct sockaddr, which can - * be passed to low-level functions like connect() or bind(). + * g_socket_listener_accept_finish: + * @listener: a #GSocketListener + * @result: a #GAsyncResult. + * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * 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. + * Finishes an async accept operation. See g_socket_listener_accept_async() * - * Returns: %TRUE if @dest was filled in, %FALSE on error + * Returns: (transfer full): a #GSocketConnection on success, %NULL 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 + * g_socket_listener_accept_socket: + * @listener: a #GSocketListener + * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. * @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. + * Blocks waiting for a client to connect to any of the sockets added + * to the listener. Returns the #GSocket that was accepted. * - * 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 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. * - * 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 @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 @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.) + * 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, %FALSE on error. + * Returns: (transfer full): a #GSocket on success, %NULL on error. * Since: 2.22 */ /** - * g_socket_check_connect_result: - * @socket: a #GSocket - * @error: #GError for error reporting, or %NULL to ignore. + * g_socket_listener_accept_socket_async: + * @listener: a #GSocketListener + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * 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. + * 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_listener_accept_socket_finish() + * to get the result of the operation. * - * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error * Since: 2.22 */ /** - * g_socket_client_add_application_proxy: - * @client: a #GSocketClient - * @protocol: The proxy protocol - * - * 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. + * g_socket_listener_accept_socket_finish: + * @listener: a #GSocketListener + * @result: a #GAsyncResult. + * @source_object: (out) (transfer none) (optional) (nullable): 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_socket_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 #GSocket on success, %NULL on error. + * Since: 2.22 */ /** - * g_socket_client_connect: - * @client: a #GSocketClient. - * @connectable: a #GSocketConnectable specifying the remote address. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * g_socket_listener_add_address: + * @listener: a #GSocketListener + * @address: a #GSocketAddress + * @type: a #GSocketType + * @protocol: a #GSocketProtocol + * @source_object: (nullable): Optional #GObject identifying this source + * @effective_address: (out) (optional): location to store the address that was bound to, or %NULL. * @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. + * 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. * - * 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. + * 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(). * - * 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(). + * @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 a local address is specified with g_socket_client_set_local_address() the - * socket will be bound to this address before connecting. + * 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. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Returns: %TRUE on success, %FALSE on error. * Since: 2.22 */ /** - * g_socket_client_connect_async: - * @client: a #GSocketClient - * @connectable: a #GSocketConnectable specifying the remote address. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * g_socket_listener_add_any_inet_port: + * @listener: a #GSocketListener + * @source_object: (nullable): Optional #GObject identifying this source + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * - * This is the asynchronous version of g_socket_client_connect(). + * Listens for TCP connections on any available port number for both + * IPv6 and IPv4 (if each is available). * - * 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. + * This is useful if you need to have a socket for incoming connections + * but don't care about the specific port number. * - * Since: 2.22 + * @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: the port number, or 0 in case of failure. + * Since: 2.24 */ /** - * g_socket_client_connect_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_socket_listener_add_inet_port: + * @listener: a #GSocketListener + * @port: an IP port number (non-zero) + * @source_object: (nullable): Optional #GObject identifying this source + * @error: #GError for error reporting, or %NULL to ignore. * - * Finishes an async connect operation. See g_socket_client_connect_async() + * 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. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * @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: - * @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: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * - * This is a helper function for g_socket_client_connect(). - * - * Attempts to create a TCP connection to the named host. - * - * @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). - * - * 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. + * g_socket_listener_add_socket: + * @listener: a #GSocketListener + * @socket: a listening #GSocket + * @source_object: (nullable): Optional #GObject identifying this source + * @error: #GError for error reporting, 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. + * 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. * - * 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. + * @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. * - * 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. + * 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: (transfer full): a #GSocketConnection on success, %NULL on error. + * 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: (nullable): 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_to_host(). + * g_socket_listener_close: + * @listener: a #GSocketListener * - * 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. + * Closes all the sockets in the listener. * * 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_new: * - * Finishes an async connect operation. See g_socket_client_connect_to_host_async() + * 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(). * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Returns: a new #GSocketListener. * 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: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * - * Attempts to create a TCP connection to a service. - * - * 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. + * 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: (nullable): 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. * - * This is the asynchronous version of - * g_socket_client_connect_to_service(). + * 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. + * + * 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. + * + * On success, the returned #GSocket takes ownership of @fd. On failure, the + * caller must close @fd themselves. + * + * Since GLib 2.46, it is no longer a fatal error to call this on a non-socket + * descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED + * + * 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: (nullable): 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: (nullable): 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: (nullable): 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) (optional): 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: (nullable): 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) (optional): 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) (out) (optional) (nullable): a pointer + * which may be filled with an array of #GSocketControlMessages, or %NULL + * @num_messages: (out): a pointer which will be filled with the number of + * elements in @messages, or %NULL + * @flags: (inout): a pointer to an int containing #GSocketMsgFlags flags + * @cancellable: 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. For receiving multiple messages, see + * g_socket_receive_messages(); 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). + * Flags passed in to the parameter affect the receive operation; flags returned + * out of it are relevant to the specific returned message. + * + * 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. + * g_socket_receive_messages: + * @socket: a #GSocket + * @messages: (array length=num_messages): an array of #GInputMessage structs + * @num_messages: the number of elements in @messages + * @flags: an int containing #GSocketMsgFlags flags for the overall operation + * @cancellable: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore * - * Gets the local address of the socket client. + * Receive 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_receive(), g_socket_receive_from(), and g_socket_receive_message(). * - * See g_socket_client_set_local_address() for details. + * @messages must point to an array of #GInputMessage structs and + * @num_messages must be the length of this array. Each #GInputMessage + * contains a pointer to an array of #GInputVector structs describing the + * buffers that the data received in each message will be written to. Using + * multiple #GInputVectors is more memory-efficient than manually copying data + * out of a single buffer to multiple sources, and more system-call-efficient + * than making multiple calls to g_socket_receive(), such as in scenarios where + * a lot of data packets need to be received (e.g. high-bandwidth video + * streaming over RTP/UDP). * - * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free. - * Since: 2.22 + * @flags modify how all messages are received. 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. These + * flags affect the overall receive operation. Flags affecting individual + * messages are returned in #GInputMessage.flags. + * + * The other members of #GInputMessage are treated as described in its + * documentation. + * + * If #GSocket:blocking is %TRUE the call will block until @num_messages have + * been received, or the end of the stream is reached. + * + * If #GSocket:blocking is %FALSE the call will return up to @num_messages + * without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the + * operating system to be received. + * + * In blocking mode, if #GSocket:timeout is positive and is reached before any + * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to + * @num_messages are returned. (Note: This is effectively the + * behaviour of `MSG_WAITFORONE` with recvmmsg().) + * + * To be notified when messages are available, wait for the + * %G_IO_IN condition. Note though that you may still receive + * %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were + * previously notified of a %G_IO_IN condition. + * + * If the remote peer closes the connection, any messages queued in the + * operating system will be returned, and subsequent calls to + * g_socket_receive_messages() will return 0 (with no error set). + * + * On error -1 is returned and @error is set accordingly. An error will only + * be returned if zero messages could be received; otherwise the number of + * messages successfully received before the error will be returned. + * + * Returns: number of messages received, or -1 on error. Note that the number + * of messages received may be smaller than @num_messages if in non-blocking + * mode, if the peer closed the connection, or if @num_messages + * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try + * to receive the remaining messages. + * Since: 2.48 */ /** - * g_socket_client_get_protocol: - * @client: a #GSocketClient - * - * Gets the protocol name type 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: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * See g_socket_client_set_protocol() 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: a #GSocketProtocol - * 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_proxy_resolver: - * @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: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * 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(). + * 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. * - * Returns: (transfer none): The #GProxyResolver being used by - * @client. - * Since: 2.36 + * 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.) + * + * 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: (nullable): 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) (nullable): 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: (nullable): 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. For sending multiple messages see + * g_socket_send_messages(); for easier use, see + * g_socket_send() and g_socket_send_to(). * - * See g_socket_client_set_socket_type() for details. + * If @address is %NULL then the message is sent to the default receiver + * (set by g_socket_connect()). * - * Returns: a #GSocketFamily + * @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(). + * + * @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. + * + * @flags modify how the message is sent. The commonly available arguments + * for this are available in the #GSocketMsgFlags enum, but the + * values there are the same as the system values, and the flags + * are passed in as-is, so you can pass in system-specific flags too. + * + * If the socket is in blocking mode the call will block until there is + * space for 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.) + * + * 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_timeout: - * @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: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the I/O timeout time for sockets created by @client. + * 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(). * - * See g_socket_client_set_timeout() for details. + * @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: the timeout in seconds - * Since: 2.26 + * @flags modify how the message is sent. The commonly available arguments + * for this are available in the #GSocketMsgFlags enum, but the + * values there are the same as the system values, and the flags + * are passed in as-is, so you can pass in system-specific flags too. + * + * If the socket is in blocking mode the call will block until there is + * space for all the data in the socket queue. If there is no space available + * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error + * will be returned if no data was written at all, otherwise the number of + * messages sent will be returned. To be notified when space is available, + * wait for the %G_IO_OUT condition. Note though that you may still receive + * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously + * notified of a %G_IO_OUT condition. (On Windows in particular, this is + * very common due to the way the underlying APIs work.) + * + * On error -1 is returned and @error is set accordingly. An error will only + * be returned if zero messages could be sent; otherwise the number of messages + * successfully sent before the error will be returned. + * + * 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_get_tls: - * @client: a #GSocketClient. + * g_socket_send_to: + * @socket: a #GSocket + * @address: (nullable): 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: (nullable): 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. + * 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()). * - * Returns: whether @client uses TLS - * Since: 2.28 + * See g_socket_send() for additional information. + * + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error + * Since: 2.22 */ /** - * g_socket_client_get_tls_validation_flags: - * @client: a #GSocketClient. + * 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: (nullable): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the TLS validation flags used creating TLS connections via - * @client. + * 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: the TLS validation flags - * Since: 2.28 + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error + * Since: 2.26 */ /** - * g_socket_client_new: + * g_socket_service_is_active: + * @service: a #GSocketService * - * Creates a new #GSocketClient with the default options. + * 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: a #GSocketClient. - * Free the returned object with g_object_unref(). + * Returns: %TRUE if the service is active, %FALSE otherwise * Since: 2.22 */ /** - * g_socket_client_set_enable_proxy: - * @client: a #GSocketClient. - * @enable: whether to enable proxies + * g_socket_service_new: * - * 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. + * 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(). * - * See also g_socket_client_set_proxy_resolver(). + * New services are created active, there is no need to call + * g_socket_service_start(), unless g_socket_service_stop() has been + * called before. * - * Since: 2.26 + * Returns: a new #GSocketService. + * Since: 2.22 */ /** - * g_socket_client_set_family: - * @client: a #GSocketClient. - * @family: a #GSocketFamily + * g_socket_service_start: + * @service: a #GSocketService * - * 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. + * Restarts the service, i.e. start accepting connections + * from the added sockets when the mainloop runs. This only needs + * to be called after the service has been stopped from + * g_socket_service_stop(). * - * 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. + * 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_local_address: - * @client: a #GSocketClient. - * @address: (nullable): a #GSocketAddress, or %NULL + * g_socket_service_stop: + * @service: a #GSocketService * - * 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. + * Stops the service, i.e. stops accepting connections + * from the added sockets when the mainloop runs. * - * 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. + * 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.) + * + * This must be called before calling g_socket_listener_close() as + * the socket service will start accepting connections immediately + * when a new socket is added. * * Since: 2.22 */ /** - * g_socket_client_set_protocol: - * @client: a #GSocketClient. - * @protocol: a #GSocketProtocol + * g_socket_set_blocking: + * @socket: a #GSocket. + * @blocking: Whether to use blocking I/O or not. * - * Sets the protocol of the socket client. - * The sockets created by this object will use of the specified - * protocol. + * Sets the blocking mode of the socket. In blocking mode + * all operations (which don’t take an explicit blocking parameter) 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. * - * If @protocol is %0 that means to use the default - * protocol for the socket family and type. + * 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.22 */ /** - * g_socket_client_set_proxy_resolver: - * @client: a #GSocketClient. - * @proxy_resolver: (nullable): a #GProxyResolver, or %NULL for the - * default. - * - * Overrides the #GProxyResolver used by @client. You can call this if - * you want to use specific proxies, rather than using the system - * default proxy settings. + * g_socket_set_broadcast: + * @socket: a #GSocket. + * @broadcast: whether @socket should allow sending to broadcast + * addresses * - * 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) + * Sets whether @socket should allow sending to broadcast addresses. + * This is %FALSE by default. * - * Since: 2.36 + * Since: 2.32 */ /** - * g_socket_client_set_socket_type: - * @client: a #GSocketClient. - * @type: a #GSocketType + * g_socket_set_keepalive: + * @socket: a #GSocket. + * @keepalive: Value for the keepalive flag * - * Sets the socket type of the socket client. - * The sockets created by this object will be of the specified - * type. + * 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. * - * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, - * as GSocketClient is used for connection oriented services. + * 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_client_set_timeout: - * @client: a #GSocketClient. - * @timeout: the timeout + * g_socket_set_listen_backlog: + * @socket: a #GSocket. + * @backlog: the maximum number of pending connections. * - * 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 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. * - * 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. + * Note that this must be called before g_socket_listen() and has no + * effect if called after that. * - * 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. - * - * 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. + * g_socket_set_multicast_loopback: + * @socket: a #GSocket. + * @loopback: whether @socket should receive messages sent to its + * multicast groups from the local host * - * 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. + * Sets whether outgoing multicast packets will be received by sockets + * listening on that multicast address on the same host. This is %TRUE + * 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_multicast_ttl: + * @socket: a #GSocket. + * @ttl: the time-to-live value for all multicast datagrams on @socket * - * Sets the TLS validation flags used when creating TLS connections - * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. + * 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. * - * Since: 2.28 + * Since: 2.32 */ /** - * g_socket_close: + * g_socket_set_option: * @socket: a #GSocket + * @level: the "API level" of the option (eg, `SOL_SOCKET`) + * @optname: the "name" of the option (eg, `SO_BROADCAST`) + * @value: the value to set the option to * @error: #GError for error reporting, or %NULL to ignore. * - * 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. + * 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.) * - * 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.) + * The [][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 on success, %FALSE on error - * 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_condition_check: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to check + * g_socket_set_timeout: + * @socket: a #GSocket. + * @timeout: the timeout for @socket, in seconds, or 0 for none * - * 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. + * Sets the time in seconds after which I/O operations on @socket will + * time out if they have not yet completed. * - * 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. + * 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. * - * 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. + * 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. * - * This call never blocks. + * If @timeout is 0 (the default), operations will never time out + * on their own. * - * Returns: the @GIOCondition mask of the current state - * 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_condition_timed_wait: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to wait for - * @timeout: the maximum time (in microseconds) to wait, or -1 - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError pointer, or %NULL - * - * Waits for up to @timeout microseconds for @condition to become true - * on @socket. If the condition is met, %TRUE is returned. - * - * 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.) + * g_socket_set_ttl: + * @socket: a #GSocket. + * @ttl: the time-to-live value for all unicast packets on @socket * - * 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. + * Sets the time-to-live for outgoing unicast packets on @socket. + * By default the platform-specific default value is used. * - * Returns: %TRUE if the condition was met, %FALSE otherwise * Since: 2.32 */ /** - * g_socket_condition_wait: + * g_socket_shutdown: * @socket: a #GSocket - * @condition: a #GIOCondition mask to wait for - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError pointer, or %NULL - * - * Waits for @condition to become true on @socket. When the condition - * is met, %TRUE is returned. - * - * 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). - * - * See also g_socket_condition_timed_wait(). - * - * Returns: %TRUE if the condition was met, %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_socket_connect: - * @socket: a #GSocket. - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (nullable): a %GCancellable or %NULL + * @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. * - * Connect the socket to the specified remote address. - * - * 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. + * Shut down part or all of a full-duplex connection. * - * Generally connection oriented sockets can only connect once, but - * connection-less sockets can connect multiple times to change the - * default address. + * If @shutdown_read is %TRUE then the receiving side of the connection + * is shut down, and further reading is disallowed. * - * 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 @shutdown_write is %TRUE then the sending side of the connection + * is shut down, and further writing is disallowed. * - * Returns: %TRUE if connected, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_socket_connectable_enumerate: - * @connectable: a #GSocketConnectable + * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. * - * Creates a #GSocketAddressEnumerator for @connectable. + * One example where it is useful to shut down only one side of a connection 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: (transfer full): a new #GSocketAddressEnumerator. + * Returns: %TRUE on success, %FALSE on error * Since: 2.22 */ /** - * g_socket_connectable_proxy_enumerate: - * @connectable: a #GSocketConnectable - * - * Creates a #GSocketAddressEnumerator for @connectable that will - * return #GProxyAddresses for addresses that you must connect - * to via a proxy. - * - * If @connectable does not implement - * g_socket_connectable_proxy_enumerate(), this will fall back to - * calling g_socket_connectable_enumerate(). + * g_socket_speaks_ipv4: + * @socket: a #GSocket * - * Returns: (transfer full): a new #GSocketAddressEnumerator. - * Since: 2.26 - */ - - -/** - * g_socket_connectable_to_string: - * @connectable: a #GSocketConnectable + * Checks if a socket is capable of speaking IPv4. * - * Format a #GSocketConnectable as a string. This is a human-readable format for - * use in debugging output, and is not a stable serialization format. It is not - * suitable for use in user interfaces as it exposes too much information for a - * user. + * 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. * - * If the #GSocketConnectable implementation does not support string formatting, - * the implementation’s type name will be returned as a fallback. + * No other types of sockets are currently considered as being capable + * of speaking IPv4. * - * Returns: (transfer full): the formatted string - * Since: 2.48 + * Returns: %TRUE if this socket can be used with IPv4. + * Since: 2.22 */ /** - * g_socket_connection_connect: - * @connection: a #GSocketConnection - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_srv_target_copy: + * @target: a #GSrvTarget * - * Connect @connection to the specified remote address. + * Copies @target * - * Returns: %TRUE if the connection succeeded, %FALSE on error - * Since: 2.32 + * Returns: a copy of @target + * Since: 2.22 */ /** - * g_socket_connection_connect_async: - * @connection: a #GSocketConnection - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (nullable): a %GCancellable or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * Asynchronously connect @connection to the specified remote address. - * - * This clears the #GSocket:blocking flag on @connection's underlying - * socket if it is currently set. + * g_srv_target_free: + * @target: a #GSrvTarget * - * Use g_socket_connection_connect_finish() to retrieve the result. + * Frees @target * - * Since: 2.32 + * Since: 2.22 */ /** - * g_socket_connection_connect_finish: - * @connection: a #GSocketConnection - * @result: the #GAsyncResult - * @error: #GError for error reporting, or %NULL to ignore. + * g_srv_target_get_hostname: + * @target: a #GSrvTarget * - * Gets the result of a g_socket_connection_connect_async() call. + * 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: %TRUE if the connection succeeded, %FALSE on error - * Since: 2.32 + * Returns: @target's hostname + * Since: 2.22 */ /** - * g_socket_connection_factory_create_connection: - * @socket: a #GSocket + * g_srv_target_get_port: + * @target: a #GSrvTarget * - * Creates a #GSocketConnection subclass of the right type for - * @socket. + * Gets @target's port * - * Returns: (transfer full): a #GSocketConnection + * Returns: @target's port * 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_get_priority: + * @target: a #GSrvTarget * - * If no type is registered, the #GSocketConnection base type is returned. + * 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: a #GType + * Returns: @target's priority * 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_get_weight: + * @target: a #GSrvTarget * - * If no type is registered, the #GSocketConnection base type is 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: @target's weight * Since: 2.22 */ /** - * g_socket_connection_get_local_address: - * @connection: a #GSocketConnection - * @error: #GError for error reporting, or %NULL to ignore. + * g_srv_target_list_sort: (skip) + * @targets: a #GList of #GSrvTarget * - * Try to get the local address of a socket connection. + * Sorts @targets in place according to the algorithm in RFC 2782. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: (transfer full): the head of the sorted list. * Since: 2.22 */ /** - * g_socket_connection_get_remote_address: - * @connection: a #GSocketConnection - * @error: #GError for error reporting, or %NULL to ignore. + * 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 * - * Try to get the remote address of a socket connection. + * Creates a new #GSrvTarget with the given parameters. * - * 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)...". + * You should not need to use this; normally #GSrvTargets are + * created by #GResolver. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). + * Returns: a new #GSrvTarget. * Since: 2.22 */ /** - * g_socket_connection_get_socket: - * @connection: a #GSocketConnection + * g_static_resource_fini: + * @static_resource: pointer to a static #GStaticResource * - * 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. + * Finalized a GResource initialized by g_static_resource_init(). * - * Returns: (transfer none): a #GSocket or %NULL on error. - * Since: 2.22 + * 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_socket_connection_is_connected: - * @connection: a #GSocketConnection + * g_static_resource_get_resource: + * @static_resource: pointer to a static #GStaticResource * - * Checks if @connection is connected. This is equivalent to calling - * g_socket_is_connected() on @connection's underlying #GSocket. + * Gets the GResource that was registered by a call to g_static_resource_init(). * - * Returns: whether @connection is connected + * This is normally used by code generated by + * [glib-compile-resources][glib-compile-resources] + * and is not typically used by other code. + * + * Returns: (transfer none): a #GResource * Since: 2.32 */ /** - * g_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 + * g_static_resource_init: + * @static_resource: pointer to a static #GStaticResource * - * 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. + * Initializes a GResource from static data using a + * GStaticResource. * - * If there is no implementation for this kind of control message, %NULL - * will be returned. + * This is normally used by code generated by + * [glib-compile-resources][glib-compile-resources] + * and is not typically used by other code. * - * Returns: (transfer full): the deserialized message or %NULL - * Since: 2.22 + * Since: 2.32 */ /** - * g_socket_control_message_get_level: - * @message: a #GSocketControlMessage + * g_subprocess_communicate: + * @subprocess: a #GSubprocess + * @stdin_buf: (nullable): 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 the "level" (i.e. the originating protocol) of the control message. - * This is often SOL_SOCKET. + * Communicate with the subprocess until it terminates, and all input + * and output has been completed. * - * Returns: an integer describing the level - * Since: 2.22 + * If @stdin_buf is given, the subprocess must have been created with + * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the + * stdin of the subprocess and the pipe is closed (ie: EOF). + * + * At the same time (as not to cause blocking when dealing with large + * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or + * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those + * streams. The data that was read is returned in @stdout and/or + * the @stderr. + * + * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, + * @stdout_buf will contain the data read from stdout. Otherwise, for + * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, + * @stdout_buf will be set to %NULL. Similar provisions apply to + * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. + * + * As usual, any output variable may be given as %NULL to ignore it. + * + * If you desire the stdout and stderr data to be interleaved, create + * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and + * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned + * in @stdout_buf and @stderr_buf will be set to %NULL. + * + * In case of any error (including cancellation), %FALSE will be + * returned with @error set. Some or all of the stdin data may have + * been written. Any stdout or stderr data that has been read will be + * discarded. None of the out variables (aside from @error) will have + * been set to anything in particular and should not be inspected. + * + * In the case that %TRUE is returned, the subprocess has exited and the + * exit status inspection APIs (eg: g_subprocess_get_if_exited(), + * g_subprocess_get_exit_status()) may be used. + * + * You should not attempt to use any of the subprocess pipes after + * starting this function, since they may be left in strange states, + * even if the operation was cancelled. You should especially not + * attempt to interact with the pipes while the operation is in progress + * (either from another thread or if using the asynchronous version). + * + * Returns: %TRUE if successful + * Since: 2.40 */ /** - * g_socket_control_message_get_msg_type: - * @message: a #GSocketControlMessage - * - * Returns the protocol specific type of the control message. - * For instance, for UNIX fd passing this would be SCM_RIGHTS. + * g_subprocess_communicate_async: + * @subprocess: Self + * @stdin_buf: (nullable): Input data, or %NULL + * @cancellable: (nullable): Cancellable + * @callback: Callback + * @user_data: User data * - * Returns: an integer describing the type of control message - * Since: 2.22 + * Asynchronous version of g_subprocess_communicate(). Complete + * invocation with g_subprocess_communicate_finish(). */ /** - * g_socket_control_message_get_size: - * @message: a #GSocketControlMessage - * - * Returns the space required for the control message, not including - * headers or alignment. + * 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 number of bytes required. - * Since: 2.22 + * Complete an invocation of g_subprocess_communicate_async(). */ /** - * g_socket_control_message_serialize: - * @message: a #GSocketControlMessage - * @data: (not nullable): A buffer to write data to - * - * Converts the data in the message to bytes placed in the - * message. - * - * @data is guaranteed to have enough space to fit the size - * returned by g_socket_control_message_get_size() on this - * object. + * g_subprocess_communicate_utf8: + * @subprocess: a #GSubprocess + * @stdin_buf: (nullable): 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 * - * Since: 2.22 + * 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_create_source: (skip) - * @socket: a #GSocket - * @condition: a #GIOCondition mask to monitor - * @cancellable: (nullable): a %GCancellable or %NULL - * - * 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. + * g_subprocess_communicate_utf8_async: + * @subprocess: Self + * @stdin_buf: (nullable): Input data, or %NULL + * @cancellable: Cancellable + * @callback: Callback + * @user_data: User data * - * The callback on the source is of the #GSocketSourceFunc type. + * 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 * - * 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. + * Complete an invocation of g_subprocess_communicate_utf8_async(). + */ + + +/** + * g_subprocess_force_exit: + * @subprocess: a #GSubprocess * - * @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(). + * 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. * - * 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. + * On Unix, this function sends %SIGKILL. * - * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref(). - * Since: 2.22 + * Since: 2.40 */ /** - * g_socket_get_available_bytes: - * @socket: a #GSocket + * g_subprocess_get_exit_status: + * @subprocess: a #GSubprocess * - * Get the amount of data pending in the OS input buffer, without blocking. + * 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. * - * 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. + * This is equivalent to the system WEXITSTATUS macro. * - * 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. + * It is an error to call this function before g_subprocess_wait() and + * unless g_subprocess_get_if_exited() returned %TRUE. * - * Returns: the number of bytes that can be read from the socket - * without blocking or truncating, or -1 on error. - * Since: 2.32 + * Returns: the exit status + * 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_get_identifier: + * @subprocess: a #GSubprocess * - * Returns: %TRUE if blocking I/O is used, %FALSE otherwise. - * 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_broadcast: - * @socket: a #GSocket. + * g_subprocess_get_if_exited: + * @subprocess: a #GSubprocess * - * Gets the broadcast setting on @socket; if %TRUE, - * it is possible to send packets to broadcast - * addresses. + * Check if the given subprocess exited normally (ie: by way of exit() + * or return from main()). * - * Returns: the broadcast setting on @socket - * Since: 2.32 + * This is equivalent to the system WIFEXITED macro. + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the case of a normal exit + * Since: 2.40 */ /** - * g_socket_get_credentials: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_get_if_signaled: + * @subprocess: a #GSubprocess * - * 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). + * Check if the given subprocess terminated in response to a signal. * - * 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. + * This is equivalent to the system WIFSIGNALED macro. * - * 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. + * It is an error to call this function before g_subprocess_wait() has + * returned. * - * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object - * that must be freed with g_object_unref(). - * Since: 2.26 + * Returns: %TRUE if the case of termination due to a signal + * Since: 2.40 */ /** - * g_socket_get_family: - * @socket: a #GSocket. + * g_subprocess_get_status: + * @subprocess: a #GSubprocess * - * Gets the socket family of the socket. + * Gets the raw status code of the process, as from waitpid(). * - * Returns: a #GSocketFamily - * Since: 2.22 + * This value has no particular meaning, but it can be used with the + * macros defined by the system headers such as WIFEXITED. It can also + * be used with g_spawn_check_exit_status(). + * + * It is more likely that you want to use g_subprocess_get_if_exited() + * followed by g_subprocess_get_exit_status(). + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: the (meaningless) waitpid() exit status from the kernel + * Since: 2.40 */ /** - * g_socket_get_fd: - * @socket: a #GSocket. + * g_subprocess_get_stderr_pipe: + * @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. + * Gets the #GInputStream from which to read the stderr output of + * @subprocess. * - * Returns: the file descriptor of the socket. - * 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_keepalive: - * @socket: a #GSocket. + * g_subprocess_get_stdin_pipe: + * @subprocess: a #GSubprocess * - * Gets the keepalive mode of the socket. For details on this, - * see g_socket_set_keepalive(). + * Gets the #GOutputStream that you can write to in order to give data + * to the stdin of @subprocess. * - * Returns: %TRUE if keepalive is active, %FALSE otherwise. - * Since: 2.22 + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDIN_PIPE. + * + * Returns: (transfer none): the stdout pipe + * Since: 2.40 */ /** - * g_socket_get_listen_backlog: - * @socket: a #GSocket. + * g_subprocess_get_stdout_pipe: + * @subprocess: a #GSubprocess * - * Gets the listen backlog setting of the socket. For details on this, - * see g_socket_set_listen_backlog(). + * Gets the #GInputStream from which to read the stdout output of + * @subprocess. * - * Returns: the maximum number of pending connections. - * 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_get_local_address: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_get_successful: + * @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. + * 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: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). - * 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_get_multicast_loopback: - * @socket: a #GSocket. + * g_subprocess_get_term_sig: + * @subprocess: a #GSubprocess * - * 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. + * Get the signal number that caused the subprocess to terminate, given + * that it terminated due to a signal. * - * Returns: the multicast loopback setting on @socket - * Since: 2.32 + * This is equivalent to the system WTERMSIG macro. + * + * It is an error to call this function before g_subprocess_wait() and + * unless g_subprocess_get_if_signaled() returned %TRUE. + * + * Returns: the signal causing termination + * Since: 2.40 */ /** - * g_socket_get_multicast_ttl: - * @socket: a #GSocket. + * g_subprocess_launcher_getenv: + * @self: a #GSubprocess + * @variable: (type filename): the environment variable to get * - * Gets the multicast time-to-live setting on @socket; see - * g_socket_set_multicast_ttl() for more details. + * Returns the value of the environment variable @variable in the + * environment of processes launched from this launcher. * - * Returns: the multicast time-to-live setting on @socket - * Since: 2.32 + * On UNIX, the returned string can be an arbitrary byte string. + * On Windows, it will be UTF-8. + * + * Returns: (type filename): the value of the environment variable, + * %NULL if unset + * Since: 2.40 */ /** - * g_socket_get_option: - * @socket: a #GSocket - * @level: the "API level" of the option (eg, `SOL_SOCKET`) - * @optname: the "name" of the option (eg, `SO_BROADCAST`) - * @value: (out): return location for the option value - * @error: #GError for error reporting, or %NULL to ignore. - * - * Gets the value of an integer-valued option on @socket, as with - * getsockopt(). (If you need to fetch a non-integer-valued option, - * you will need to call getsockopt() directly.) + * g_subprocess_launcher_new: + * @flags: #GSubprocessFlags * - * The [][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. + * Creates a new #GSubprocessLauncher. * - * 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. + * 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. * - * 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 + * Since: 2.40 */ /** - * g_socket_get_protocol: - * @socket: a #GSocket. + * g_subprocess_launcher_set_child_setup: (skip) + * @self: a #GSubprocessLauncher + * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function + * @user_data: user data for @child_setup + * @destroy_notify: a #GDestroyNotify for @user_data + * + * Sets up a child setup function. + * + * The child setup function will be called after fork() but before + * exec() on the child's side. + * + * @destroy_notify will not be automatically called on the child's side + * of the fork(). It will only be called when the last reference on the + * #GSubprocessLauncher is dropped or when a new child setup function is + * given. * - * Gets the socket protocol id the socket was created with. - * In case the protocol is unknown, -1 is returned. + * %NULL can be given as @child_setup to disable the functionality. * - * Returns: a protocol id, or -1 if unknown - * Since: 2.22 + * Child setup functions are only available on UNIX. + * + * Since: 2.40 */ /** - * g_socket_get_remote_address: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_launcher_set_cwd: + * @self: a #GSubprocess + * @cwd: (type filename): the cwd for launched processes * - * Try to get the remote address of a connected socket. This is only - * useful for connection oriented sockets that have been connected. + * Sets the current working directory that processes will be launched + * with. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). - * 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_get_socket_type: - * @socket: a #GSocket. + * g_subprocess_launcher_set_environ: + * @self: a #GSubprocess + * @env: (array zero-terminated=1) (element-type filename) (transfer none): + * the replacement environment * - * Gets the socket type of the socket. + * Replace the entire environment of processes launched from this + * launcher with the given 'environ' variable. * - * Returns: a #GSocketType - * Since: 2.22 - */ - - -/** - * g_socket_get_timeout: - * @socket: a #GSocket. + * 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. * - * Gets the timeout setting of the socket. For details on this, see - * g_socket_set_timeout(). + * As an alternative, you can use g_subprocess_launcher_setenv(), + * g_subprocess_launcher_unsetenv(), etc. * - * Returns: the timeout in seconds - * Since: 2.26 + * Pass an empty array to set an empty environment. Pass %NULL to inherit the + * parent process’ environment. As of GLib 2.54, the parent process’ environment + * will be copied when g_subprocess_launcher_set_environ() is called. + * Previously, it was copied when the subprocess was executed. This means the + * copied environment may now be modified (using g_subprocess_launcher_setenv(), + * etc.) before launching the subprocess. + * + * On UNIX, all strings in this array can be arbitrary byte strings. + * On Windows, they should be in UTF-8. + * + * Since: 2.40 */ /** - * g_socket_get_ttl: - * @socket: a #GSocket. + * g_subprocess_launcher_set_flags: + * @self: a #GSubprocessLauncher + * @flags: #GSubprocessFlags * - * Gets the unicast time-to-live setting on @socket; see - * g_socket_set_ttl() for more details. + * Sets the flags on the launcher. * - * Returns: the time-to-live setting on @socket - * Since: 2.32 + * The default flags are %G_SUBPROCESS_FLAGS_NONE. + * + * You may not set flags that specify conflicting options for how to + * handle a particular stdio stream (eg: specifying both + * %G_SUBPROCESS_FLAGS_STDIN_PIPE and + * %G_SUBPROCESS_FLAGS_STDIN_INHERIT). + * + * You may also not set a flag that conflicts with a previous call to a + * function like g_subprocess_launcher_set_stdin_file_path() or + * g_subprocess_launcher_take_stdout_fd(). + * + * Since: 2.40 */ /** - * g_socket_is_closed: - * @socket: a #GSocket + * g_subprocess_launcher_set_stderr_file_path: + * @self: a #GSubprocessLauncher + * @path: (type filename) (nullable): a filename or %NULL * - * Checks whether a socket is closed. + * Sets the file path to use as the stderr for spawned processes. * - * Returns: %TRUE if socket is closed, %FALSE otherwise - * Since: 2.22 + * If @path is %NULL then any previously given path is unset. + * + * The file will be created or truncated when the process is spawned, as + * would be the case if using '2>' at the shell. + * + * If you want to send both stdout and stderr to the same file then use + * %G_SUBPROCESS_FLAGS_STDERR_MERGE. + * + * You may not set a stderr file path if a stderr fd is already set or + * if the launcher flags contain any flags directing stderr elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 */ /** - * g_socket_is_connected: - * @socket: a #GSocket. + * g_subprocess_launcher_set_stdin_file_path: + * @self: a #GSubprocessLauncher + * @path: * - * Check whether the socket is connected. This is only useful for - * connection-oriented sockets. + * Sets the file path to use as the stdin for spawned processes. * - * If using g_socket_shutdown(), this function will return %TRUE until the - * socket has been shut down for reading and writing. If you do a non-blocking - * connect, this function will not return %TRUE until after you call - * g_socket_check_connect_result(). + * If @path is %NULL then any previously given path is unset. * - * Returns: %TRUE if socket is connected, %FALSE otherwise. - * Since: 2.22 + * The file must exist or spawning the process will fail. + * + * You may not set a stdin file path if a stdin fd is already set or if + * the launcher flags contain any flags directing stdin elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 */ /** - * g_socket_join_multicast_group: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to join. - * @iface: (nullable): 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. + * g_subprocess_launcher_set_stdout_file_path: + * @self: a #GSubprocessLauncher + * @path: (type filename) (nullable): a filename or %NULL * - * 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(). + * Sets the file path to use as the stdout for spawned processes. * - * If @iface is %NULL, the system will automatically pick an interface - * to bind to based on @group. + * If @path is %NULL then any previously given path is unset. * - * 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. + * The file will be created or truncated when the process is spawned, as + * would be the case if using '>' at the shell. * - * To bind to a given source-specific multicast address, use - * g_socket_join_multicast_group_ssm() instead. + * 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. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.32 + * This feature is only available on UNIX. + * + * Since: 2.40 */ /** - * g_socket_join_multicast_group_ssm: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to join. - * @source_specific: (nullable): a #GInetAddress specifying the - * source-specific multicast address or %NULL to ignore. - * @iface: (nullable): Name of the interface to use, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * 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(). - * - * If @iface is %NULL, the system will automatically pick an interface - * to bind to based on @group. + * g_subprocess_launcher_setenv: + * @self: a #GSubprocess + * @variable: (type filename): the environment variable to set, + * must not contain '=' + * @value: (type filename): the new value for the variable + * @overwrite: whether to change the variable if it already exists * - * If @source_specific is not %NULL, use source-specific multicast as - * defined in RFC 4604. Note that on older platforms this may fail - * with a %G_IO_ERROR_NOT_SUPPORTED error. + * Sets the environment variable @variable in the environment of + * processes launched from this launcher. * - * Note that this function can be called multiple times for the same - * @group with different @source_specific in order to receive multicast - * packets from more than one source. + * On UNIX, both the variable's name and value can be arbitrary byte + * strings, except that the variable's name cannot contain '='. + * On Windows, they should be in UTF-8. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.56 + * Since: 2.40 */ /** - * g_socket_leave_multicast_group: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to leave. - * @iface: (nullable): Interface used - * @source_specific: %TRUE if source-specific multicast was used - * @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 * - * 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). + * Creates a #GSubprocess given a provided varargs list of arguments. * - * @socket remains bound to its address and port, and can still receive - * unicast messages after calling this. + * Since: 2.40 + * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + */ + + +/** + * g_subprocess_launcher_spawnv: + * @self: a #GSubprocessLauncher + * @argv: (array zero-terminated=1) (element-type filename): Command line arguments + * @error: Error * - * To unbind to a given source-specific multicast address, use - * g_socket_leave_multicast_group_ssm() instead. + * Creates a #GSubprocess given a provided array of arguments. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.32 + * Since: 2.40 + * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) */ /** - * g_socket_leave_multicast_group_ssm: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to leave. - * @source_specific: (nullable): a #GInetAddress specifying the - * source-specific multicast address or %NULL to ignore. - * @iface: (nullable): Name of the interface to use, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_launcher_take_fd: + * @self: a #GSubprocessLauncher + * @source_fd: File descriptor in parent process + * @target_fd: Target descriptor for child process * - * 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). + * 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. * - * @socket remains bound to its address and port, and can still receive - * unicast messages after calling this. + * 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. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.56 + * 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_listen: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_launcher_take_stderr_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 * - * Marks the socket as a server socket, i.e. a socket that is used - * to accept incoming requests using g_socket_accept(). + * Sets the file descriptor to use as the stderr for spawned processes. * - * Before calling this the socket must be bound to a local address using - * g_socket_bind(). + * If @fd is -1 then any previously given fd is unset. * - * To set the maximum amount of outstanding clients, use - * g_socket_set_listen_backlog(). + * Note that the default behaviour is to pass stderr through to the + * stderr of the parent process. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * 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_listener_accept: - * @listener: a #GSocketListener - * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_launcher_take_stdin_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 * - * 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. + * Sets the file descriptor to use as the stdin for spawned processes. * - * 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 @fd is -1 then any previously given fd is unset. * - * 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 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. * - * Returns: (transfer full): a #GSocketConnection on success, %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 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_listener_accept_async: - * @listener: a #GSocketListener - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * g_subprocess_launcher_take_stdout_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 * - * This is the asynchronous version of g_socket_listener_accept(). + * Sets the file descriptor to use as the stdout for spawned processes. * - * 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. + * If @fd is -1 then any previously given fd is unset. * - * Since: 2.22 + * Note that the default behaviour is to pass stdout through to the + * stdout of the parent process. + * + * The passed @fd is noted but will not be touched in the current + * process. It is therefore necessary that it be kept open by the + * caller until the subprocess is spawned. The file descriptor will + * also not be explicitly closed on the child side, so it must be marked + * O_CLOEXEC if that's what you want. + * + * You may not set a stdout fd if a stdout file path is already set or + * if the launcher flags contain any flags directing stdout elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 */ /** - * g_socket_listener_accept_finish: - * @listener: a #GSocketListener - * @result: a #GAsyncResult. - * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_subprocess_launcher_unsetenv: + * @self: a #GSubprocess + * @variable: (type filename): the environment variable to unset, + * must not contain '=' * - * Finishes an async accept operation. See g_socket_listener_accept_async() + * Removes the environment variable @variable from the environment of + * processes launched from this launcher. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 + * On UNIX, the variable's name can be an arbitrary byte string not + * containing '='. On Windows, it should be in UTF-8. + * + * Since: 2.40 */ /** - * g_socket_listener_accept_socket: - * @listener: a #GSocketListener - * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Blocks waiting for a client to connect to any of the sockets added - * to the listener. Returns the #GSocket that was accepted. - * - * 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. + * g_subprocess_new: (skip) + * @flags: flags that define the behaviour of the subprocess + * @error: (nullable): return location for an error, or %NULL + * @argv0: first commandline argument to pass to the subprocess + * @...: more commandline arguments, followed by %NULL * - * 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. + * 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. * - * 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 argument list must be terminated with %NULL. * - * Returns: (transfer full): a #GSocket on success, %NULL on error. - * Since: 2.22 + * Returns: A newly created #GSubprocess, or %NULL on error (and @error + * will be set) + * Since: 2.40 */ /** - * g_socket_listener_accept_socket_async: - * @listener: a #GSocketListener - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * g_subprocess_newv: (rename-to g_subprocess_new) + * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess + * @flags: flags that define the behaviour of the subprocess + * @error: (nullable): return location for an error, or %NULL * - * This is the asynchronous version of g_socket_listener_accept_socket(). + * Create a new process with the given flags and argument list. * - * 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 argument list is expected to be %NULL-terminated. * - * Since: 2.22 + * Returns: A newly created #GSubprocess, or %NULL on error (and @error + * will be set) + * Since: 2.40 */ /** - * g_socket_listener_accept_socket_finish: - * @listener: a #GSocketListener - * @result: a #GAsyncResult. - * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. + * g_subprocess_send_signal: + * @subprocess: a #GSubprocess + * @signal_num: the signal number to send * - * Finishes an async accept operation. See g_socket_listener_accept_socket_async() + * Sends the UNIX signal @signal_num to the subprocess, if it is still + * running. * - * Returns: (transfer full): a #GSocket on success, %NULL on error. - * 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_listener_add_address: - * @listener: a #GSocketListener - * @address: a #GSocketAddress - * @type: a #GSocketType - * @protocol: a #GSocketProtocol - * @source_object: (nullable): Optional #GObject identifying this source - * @effective_address: (out) (optional): location to store the address that was bound to, or %NULL. - * @error: #GError for error reporting, or %NULL to ignore. + * g_subprocess_wait: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable + * @error: a #GError * - * 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. + * Synchronously wait for the subprocess to terminate. * - * 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(). + * 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(). * - * @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. + * This function does not fail in the case of the subprocess having + * abnormal termination. See g_subprocess_wait_check() for that. * - * 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. + * Cancelling @cancellable doesn't kill the subprocess. Call + * g_subprocess_force_exit() if it is desirable. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * Returns: %TRUE on success, %FALSE if @cancellable was cancelled + * Since: 2.40 */ /** - * g_socket_listener_add_any_inet_port: - * @listener: a #GSocketListener - * @source_object: (nullable): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Listens for TCP connections on any available port number for both - * IPv6 and IPv4 (if each is available). + * 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 * - * This is useful if you need to have a socket for incoming connections - * but don't care about the specific port number. + * Wait for the subprocess to terminate. * - * @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. + * This is the asynchronous version of g_subprocess_wait(). * - * Returns: the port number, or 0 in case of failure. - * Since: 2.24 + * Since: 2.40 */ /** - * g_socket_listener_add_inet_port: - * @listener: a #GSocketListener - * @port: an IP port number (non-zero) - * @source_object: (nullable): 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. + * g_subprocess_wait_check: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable + * @error: a #GError * - * @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. + * Combines g_subprocess_wait() with g_spawn_check_exit_status(). * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * Returns: %TRUE on success, %FALSE if process exited abnormally, or + * @cancellable was cancelled + * Since: 2.40 */ /** - * g_socket_listener_add_socket: - * @listener: a #GSocketListener - * @socket: a listening #GSocket - * @source_object: (nullable): Optional #GObject identifying this source - * @error: #GError for error reporting, or %NULL to ignore. - * - * 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. + * 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 * - * @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. + * Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). * - * 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. + * This is the asynchronous version of g_subprocess_wait_check(). * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * Since: 2.40 */ /** - * g_socket_listener_close: - * @listener: a #GSocketListener + * g_subprocess_wait_check_finish: + * @subprocess: a #GSubprocess + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL * - * Closes all the sockets in the listener. + * Collects the result of a previous call to + * g_subprocess_wait_check_async(). * - * Since: 2.22 + * Returns: %TRUE if successful, or %FALSE with @error set + * Since: 2.40 */ /** - * g_socket_listener_new: + * g_subprocess_wait_finish: + * @subprocess: a #GSubprocess + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL * - * 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(). + * Collects the result of a previous call to + * g_subprocess_wait_async(). * - * Returns: a new #GSocketListener. - * Since: 2.22 + * Returns: %TRUE if successful, or %FALSE with @error set + * Since: 2.40 */ /** - * g_socket_listener_set_backlog: - * @listener: a #GSocketListener - * @listen_backlog: an integer + * g_task_attach_source: + * @task: a #GTask + * @source: the source to attach + * @callback: the callback to invoke when @source triggers * - * Sets the listen backlog on the sockets in the listener. + * 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`. * - * See g_socket_set_listen_backlog() for details + * This takes a reference on @task until @source is destroyed. * - * Since: 2.22 + * Since: 2.36 */ /** - * 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. + * g_task_get_cancellable: + * @task: a #GTask * - * 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. + * Gets @task's #GCancellable * - * Returns: a #GSocket or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * Returns: (transfer none): @task's #GCancellable + * Since: 2.36 */ /** - * g_socket_new_from_fd: - * @fd: a native socket file descriptor. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GSocket from a native file descriptor - * or winsock SOCKET handle. - * - * 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. - * - * On success, the returned #GSocket takes ownership of @fd. On failure, the - * caller must close @fd themselves. + * g_task_get_check_cancellable: + * @task: the #GTask * - * Since GLib 2.46, it is no longer a fatal error to call this on a non-socket - * descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED + * Gets @task's check-cancellable flag. See + * g_task_set_check_cancellable() for more details. * - * Returns: a #GSocket or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 + * Since: 2.36 */ /** - * 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: (nullable): 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. - * - * 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. - * - * 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(). - * - * 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. + * g_task_get_completed: + * @task: a #GTask. * - * On error -1 is returned and @error is set accordingly. + * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after + * the task’s callback is invoked, and will return %FALSE if called from inside + * the callback. * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.22 + * Returns: %TRUE if the task has completed, %FALSE otherwise. + * Since: 2.44 */ /** - * g_socket_receive_from: - * @socket: a #GSocket - * @address: (out) (optional): 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Receive data (up to @size bytes) from a socket. + * g_task_get_context: + * @task: a #GTask * - * 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 #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). * - * See g_socket_receive() for additional information. + * This will always return a non-%NULL value, even if the task's + * context is the default #GMainContext. * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.22 + * Returns: (transfer none): @task's #GMainContext + * Since: 2.36 */ /** - * g_socket_receive_message: - * @socket: a #GSocket - * @address: (out) (optional): 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) (out) (optional) (nullable): a pointer - * which may be filled with an array of #GSocketControlMessages, or %NULL - * @num_messages: (out): a pointer which will be filled with the number of - * elements in @messages, or %NULL - * @flags: (inout): a pointer to an int containing #GSocketMsgFlags flags - * @cancellable: a %GCancellable or %NULL - * @error: a #GError pointer, or %NULL - * - * Receive data from a socket. For receiving multiple messages, see - * g_socket_receive_messages(); for easier use, see - * g_socket_receive() and g_socket_receive_from(). - * - * 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. - * - * @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. - * - * 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. - * - * @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. - * - * @num_messages, if non-%NULL, will be set to the number of control - * messages received. - * - * 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). - * Flags passed in to the parameter affect the receive operation; flags returned - * out of it are relevant to the specific returned message. - * - * 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. + * g_task_get_priority: + * @task: a #GTask * - * On error -1 is returned and @error is set accordingly. + * Gets @task's priority * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.22 + * Returns: @task's priority + * Since: 2.36 */ /** - * g_socket_receive_messages: - * @socket: a #GSocket - * @messages: (array length=num_messages): an array of #GInputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags for the overall operation - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore - * - * Receive 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_receive(), g_socket_receive_from(), and g_socket_receive_message(). - * - * @messages must point to an array of #GInputMessage structs and - * @num_messages must be the length of this array. Each #GInputMessage - * contains a pointer to an array of #GInputVector structs describing the - * buffers that the data received in each message will be written to. Using - * multiple #GInputVectors is more memory-efficient than manually copying data - * out of a single buffer to multiple sources, and more system-call-efficient - * than making multiple calls to g_socket_receive(), such as in scenarios where - * a lot of data packets need to be received (e.g. high-bandwidth video - * streaming over RTP/UDP). - * - * @flags modify how all messages are received. 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. These - * flags affect the overall receive operation. Flags affecting individual - * messages are returned in #GInputMessage.flags. - * - * The other members of #GInputMessage are treated as described in its - * documentation. - * - * If #GSocket:blocking is %TRUE the call will block until @num_messages have - * been received, or the end of the stream is reached. + * g_task_get_return_on_cancel: + * @task: the #GTask * - * If #GSocket:blocking is %FALSE the call will return up to @num_messages - * without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the - * operating system to be received. + * Gets @task's return-on-cancel flag. See + * g_task_set_return_on_cancel() for more details. * - * In blocking mode, if #GSocket:timeout is positive and is reached before any - * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to - * @num_messages are returned. (Note: This is effectively the - * behaviour of `MSG_WAITFORONE` with recvmmsg().) + * Since: 2.36 + */ + + +/** + * g_task_get_source_object: + * @task: a #GTask * - * To be notified when messages are available, wait for the - * %G_IO_IN condition. Note though that you may still receive - * %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were - * previously notified of a %G_IO_IN condition. + * Gets the source object from @task. Like + * g_async_result_get_source_object(), but does not ref the object. * - * If the remote peer closes the connection, any messages queued in the - * operating system will be returned, and subsequent calls to - * g_socket_receive_messages() will return 0 (with no error set). + * Returns: (transfer none) (nullable) (type GObject): @task's source object, or %NULL + * Since: 2.36 + */ + + +/** + * g_task_get_source_tag: + * @task: a #GTask * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be received; otherwise the number of - * messages successfully received before the error will be returned. + * Gets @task's source tag. See g_task_set_source_tag(). * - * Returns: number of messages received, or -1 on error. Note that the number - * of messages received may be smaller than @num_messages if in non-blocking - * mode, if the peer closed the connection, or if @num_messages - * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - * to receive the remaining messages. - * Since: 2.48 + * Returns: (transfer none): @task's source tag + * Since: 2.36 */ /** - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_task_get_task_data: + * @task: a #GTask * - * 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. + * Gets @task's `task_data`. * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.26 + * Returns: (transfer none): @task's `task_data`. + * Since: 2.36 */ /** - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_task_had_error: + * @task: a #GTask. * - * 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. + * Tests if @task resulted in an error. * - * 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: %TRUE if the task resulted in an error, %FALSE otherwise. + * Since: 2.36 + */ + + +/** + * g_task_is_valid: + * @result: (type Gio.AsyncResult): A #GAsyncResult + * @source_object: (nullable) (type GObject): the source object + * expected to be associated with the task * - * On error -1 is returned and @error is set accordingly. + * 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: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.22 + * Returns: %TRUE if @result and @source_object are valid, %FALSE + * if not + * Since: 2.36 */ /** - * g_socket_send_message: - * @socket: a #GSocket - * @address: (nullable): 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) (nullable): 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_task_new: + * @source_object: (nullable) (type GObject): the #GObject that owns + * this task, or %NULL. + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. * - * Send data to @address on @socket. For sending multiple messages see - * g_socket_send_messages(); for easier use, see - * g_socket_send() and g_socket_send_to(). + * 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]. * - * If @address is %NULL then the message is sent to the default receiver - * (set by g_socket_connect()). + * 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(). * - * @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(). + * 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. * - * @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 #GTask. + * Since: 2.36 + */ + + +/** + * g_task_propagate_boolean: + * @task: a #GTask. + * @error: return location for a #GError * - * @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 result of @task as a #gboolean. * - * 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.) + * If the task resulted in an error, or was cancelled, then this will + * instead return %FALSE and set @error. * - * On error -1 is returned and @error is set accordingly. + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.22 + * Returns: the task result, or %FALSE on error + * Since: 2.36 */ /** - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Send multiple data messages from @socket in one go. This is the most - * complicated and fully-featured version of this call. For easier use, see - * g_socket_send(), g_socket_send_to(), and g_socket_send_message(). - * - * @messages must point to an array of #GOutputMessage structs and - * @num_messages must be the length of this array. Each #GOutputMessage - * contains an address to send the data to, and a pointer to an array of - * #GOutputVector structs to describe the buffers that the data to be sent - * for each message will be gathered from. Using multiple #GOutputVectors is - * more memory-efficient than manually copying data from multiple sources - * into a single buffer, and more network-efficient than making multiple - * calls to g_socket_send(). Sending multiple messages in one go avoids the - * overhead of making a lot of syscalls in scenarios where a lot of data - * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), - * or where the same data needs to be sent to multiple recipients. + * g_task_propagate_int: + * @task: a #GTask. + * @error: return location for a #GError * - * @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 result of @task as an integer (#gssize). * - * 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.) + * If the task resulted in an error, or was cancelled, then this will + * instead return -1 and set @error. * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be sent; otherwise the number of messages - * successfully sent before the error will be returned. + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. * - * 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 + * Returns: the task result, or -1 on error + * Since: 2.36 */ /** - * g_socket_send_to: - * @socket: a #GSocket - * @address: (nullable): 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_task_propagate_pointer: + * @task: a #GTask + * @error: return location for a #GError * - * 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 the result of @task as a pointer, and transfers ownership + * of that value to the caller. * - * See g_socket_send() for additional information. + * If the task resulted in an error, or was cancelled, then this will + * instead return %NULL and set @error. * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on 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: (transfer full): the task result, or %NULL on error + * Since: 2.36 */ /** - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_task_report_error: + * @source_object: (nullable) (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 * - * 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. + * 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. * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.26 + * See also g_task_report_new_error(). + * + * Since: 2.36 */ /** - * g_socket_service_is_active: - * @service: a #GSocketService + * g_task_report_new_error: + * @source_object: (nullable) (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. * - * 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. + * 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. * - * Returns: %TRUE if the service is active, %FALSE otherwise - * Since: 2.22 + * See also g_task_report_error(). + * + * Since: 2.36 */ /** - * g_socket_service_new: - * - * 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(). + * g_task_return_boolean: + * @task: a #GTask. + * @result: the #gboolean result of a task function. * - * New services are created active, there is no need to call - * g_socket_service_start(), unless g_socket_service_stop() has been - * called before. + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). * - * Returns: a new #GSocketService. - * Since: 2.22 + * Since: 2.36 */ /** - * g_socket_service_start: - * @service: a #GSocketService + * g_task_return_error: + * @task: a #GTask. + * @error: (transfer full): the #GError result of a task function. * - * Restarts the service, i.e. start accepting connections - * from the added sockets when the mainloop runs. This only needs - * to be called after the service has been stopped from - * g_socket_service_stop(). + * 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). * - * This call is thread-safe, so it may be called from a thread - * handling an incoming client request. + * 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. * - * Since: 2.22 + * See also g_task_return_new_error(). + * + * Since: 2.36 */ /** - * g_socket_service_stop: - * @service: a #GSocketService - * - * Stops the service, i.e. stops accepting connections - * from the added sockets when the mainloop runs. - * - * 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.) + * g_task_return_error_if_cancelled: + * @task: a #GTask * - * This must be called before calling g_socket_listener_close() as - * the socket service will start accepting connections immediately - * when a new socket is added. + * Checks if @task's #GCancellable has been cancelled, and if so, sets + * @task's error accordingly and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). * - * Since: 2.22 + * Returns: %TRUE if @task has been cancelled, %FALSE if not + * Since: 2.36 */ /** - * g_socket_set_blocking: - * @socket: a #GSocket. - * @blocking: Whether to use blocking I/O or not. - * - * Sets the blocking mode of the socket. In blocking mode - * all operations (which don’t take an explicit blocking parameter) 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. + * g_task_return_int: + * @task: a #GTask. + * @result: the integer (#gssize) result of a task function. * - * 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. + * 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.22 + * Since: 2.36 */ /** - * g_socket_set_broadcast: - * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to broadcast - * addresses + * g_task_return_new_error: + * @task: a #GTask. + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. * - * Sets whether @socket should allow sending to broadcast addresses. - * This is %FALSE by default. + * 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). * - * Since: 2.32 + * See also g_task_return_error(). + * + * Since: 2.36 */ /** - * g_socket_set_keepalive: - * @socket: a #GSocket. - * @keepalive: Value for the keepalive flag + * g_task_return_pointer: + * @task: a #GTask + * @result: (nullable) (transfer full): the pointer result of a task + * function + * @result_destroy: (nullable): a #GDestroyNotify function. * - * 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. + * 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(). * - * This option is only functional on certain kinds of sockets. (Notably, - * %G_SOCKET_PROTOCOL_TCP sockets.) + * "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. * - * 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. + * 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.22 + * Since: 2.36 */ /** - * g_socket_set_listen_backlog: - * @socket: a #GSocket. - * @backlog: the maximum number of pending connections. + * g_task_run_in_thread: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc * - * 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. + * Runs @task_func in another thread. When @task_func returns, @task's + * #GAsyncReadyCallback will be invoked in @task's #GMainContext. * - * Note that this must be called before g_socket_listen() and has no - * effect if called after that. + * This takes a ref on @task until the task completes. * - * Since: 2.22 + * See #GTaskThreadFunc for more details about how @task_func is handled. + * + * Although GLib currently rate-limits the tasks queued via + * g_task_run_in_thread(), you should not assume that it will always + * do this. If you have a very large number of tasks to run, but don't + * want them to all run at once, you should only queue a limited + * number of them at a time. + * + * Since: 2.36 */ /** - * g_socket_set_multicast_loopback: - * @socket: a #GSocket. - * @loopback: whether @socket should receive messages sent to its - * multicast groups from the local host + * g_task_run_in_thread_sync: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc * - * Sets whether outgoing multicast packets will be received by sockets - * listening on that multicast address on the same host. This is %TRUE - * by default. + * 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. * - * Since: 2.32 + * 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. + * + * Although GLib currently rate-limits the tasks queued via + * g_task_run_in_thread_sync(), you should not assume that it will + * always do this. If you have a very large number of tasks to run, + * but don't want them to all run at once, you should only queue a + * limited number of them at a time. + * + * Since: 2.36 */ /** - * g_socket_set_multicast_ttl: - * @socket: a #GSocket. - * @ttl: the time-to-live value for all multicast datagrams on @socket + * g_task_set_check_cancellable: + * @task: the #GTask + * @check_cancellable: whether #GTask will check the state of + * its #GCancellable for you. * - * 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. + * 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. * - * Since: 2.32 + * 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_socket_set_option: - * @socket: a #GSocket - * @level: the "API level" of the option (eg, `SOL_SOCKET`) - * @optname: the "name" of the option (eg, `SO_BROADCAST`) - * @value: the value to set the option to - * @error: #GError for error reporting, or %NULL to ignore. + * g_task_set_priority: + * @task: the #GTask + * @priority: the [priority][io-priority] of the request * - * 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.) + * Sets @task's priority. If you do not call this, it will default to + * %G_PRIORITY_DEFAULT. * - * The [][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. + * 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(). * - * Returns: success or failure. On failure, @error will be set, and - * the system error value (`errno` or WSAGetLastError()) will still - * be set to the result of the setsockopt() call. * Since: 2.36 */ /** - * g_socket_set_timeout: - * @socket: a #GSocket. - * @timeout: the timeout for @socket, in seconds, or 0 for none + * g_task_set_return_on_cancel: + * @task: the #GTask + * @return_on_cancel: whether the task returns automatically when + * it is cancelled. * - * Sets the time in seconds after which I/O operations on @socket will - * time out if they have not yet completed. + * 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(). * - * 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. + * 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. * - * 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. + * 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. * - * If @timeout is 0 (the default), operations will never time out - * on their own. + * 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. * - * Note that if an I/O operation is interrupted by a signal, this may - * cause the timeout to be reset. + * 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. * - * Since: 2.26 + * 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_socket_set_ttl: - * @socket: a #GSocket. - * @ttl: the time-to-live value for all unicast packets on @socket + * g_task_set_source_tag: + * @task: the #GTask + * @source_tag: an opaque pointer indicating the source of this task * - * Sets the time-to-live for outgoing unicast packets on @socket. - * By default the platform-specific default value is used. + * Sets @task's source tag. You can use this to tag a task return + * value with a particular pointer (usually a pointer to the function + * doing the tagging) and then later check it using + * g_task_get_source_tag() (or g_async_result_is_tagged()) in the + * task's "finish" function, to figure out if the response came from a + * particular place. * - * Since: 2.32 + * 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. - * - * Shut down part or all of a full-duplex connection. - * - * If @shutdown_read is %TRUE then the receiving side of the connection - * is shut down, and further reading is disallowed. + * g_task_set_task_data: + * @task: the #GTask + * @task_data: (nullable): task-specific data + * @task_data_destroy: (nullable): #GDestroyNotify for @task_data * - * If @shutdown_write is %TRUE then the sending side of the connection - * is shut down, and further writing is disallowed. + * Sets @task's task data (freeing the existing task data, if any). * - * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. + * Since: 2.36 + */ + + +/** + * g_tcp_connection_get_graceful_disconnect: + * @connection: a #GTcpConnection * - * One example where it is useful to shut down only one side of a connection 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 graceful disconnects are used. See + * g_tcp_connection_set_graceful_disconnect(). * - * Returns: %TRUE on success, %FALSE on error + * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise * Since: 2.22 */ /** - * g_socket_speaks_ipv4: - * @socket: a #GSocket - * - * Checks if a socket is capable of speaking IPv4. + * g_tcp_connection_set_graceful_disconnect: + * @connection: a #GTcpConnection + * @graceful_disconnect: Whether to do graceful disconnects or not * - * 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. + * 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. * - * No other types of sockets are currently considered as being capable - * of speaking IPv4. + * A graceful disconnect means that we can be sure that we successfully sent + * all the outstanding data to the other end, or get an error reported. + * However, it also means we have to wait for all the data to reach the + * other side and for it to acknowledge this by closing the socket, which may + * take a while. For this reason it is disabled by default. * - * Returns: %TRUE if this socket can be used with IPv4. * Since: 2.22 */ /** - * g_srv_target_copy: - * @target: a #GSrvTarget + * g_tcp_wrapper_connection_get_base_io_stream: + * @conn: a #GTcpWrapperConnection * - * Copies @target + * Get's @conn's base #GIOStream * - * Returns: a copy of @target - * Since: 2.22 + * Returns: (transfer none): @conn's base #GIOStream */ /** - * g_srv_target_free: - * @target: a #GSrvTarget + * g_tcp_wrapper_connection_new: + * @base_io_stream: the #GIOStream to wrap + * @socket: the #GSocket associated with @base_io_stream * - * Frees @target + * Wraps @base_io_stream and @socket together as a #GSocketConnection. * - * Since: 2.22 + * Returns: the new #GSocketConnection. + * Since: 2.28 */ /** - * g_srv_target_get_hostname: - * @target: a #GSrvTarget - * - * Gets @target's hostname (in ASCII form; if you are going to present - * this to the user, you should use g_hostname_is_ascii_encoded() to - * check if it contains encoded Unicode segments, and use - * g_hostname_to_unicode() to convert it if it does.) + * g_test_dbus_add_service_dir: + * @self: a #GTestDBus + * @path: path to a directory containing .service files * - * Returns: @target's hostname - * Since: 2.22 + * Add a path where dbus-daemon will look up .service files. This can't be + * called after g_test_dbus_up(). */ /** - * g_srv_target_get_port: - * @target: a #GSrvTarget + * g_test_dbus_down: + * @self: a #GTestDBus * - * Gets @target's port + * Stop the session bus started by g_test_dbus_up(). * - * Returns: @target's port - * Since: 2.22 + * 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_srv_target_get_priority: - * @target: a #GSrvTarget + * g_test_dbus_get_bus_address: + * @self: a #GTestDBus * - * Gets @target's priority. You should not need to look at this; - * #GResolver already sorts the targets according to the algorithm in - * RFC 2782. + * 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: @target's priority - * Since: 2.22 + * Returns: (nullable): the address of the bus, or %NULL. */ /** - * g_srv_target_get_weight: - * @target: a #GSrvTarget + * g_test_dbus_get_flags: + * @self: a #GTestDBus * - * Gets @target's weight. You should not need to look at this; - * #GResolver already sorts the targets according to the algorithm in - * RFC 2782. + * Get the flags of the #GTestDBus object. * - * Returns: @target's weight - * Since: 2.22 + * Returns: the value of #GTestDBus:flags property */ /** - * g_srv_target_list_sort: (skip) - * @targets: a #GList of #GSrvTarget + * g_test_dbus_new: + * @flags: a #GTestDBusFlags * - * Sorts @targets in place according to the algorithm in RFC 2782. + * Create a new #GTestDBus object. * - * Returns: (transfer full): the head of the sorted list. - * Since: 2.22 + * Returns: (transfer full): a new #GTestDBus. */ /** - * 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_test_dbus_stop: + * @self: a #GTestDBus * - * You should not need to use this; normally #GSrvTargets are - * created by #GResolver. + * Stop the session bus started by g_test_dbus_up(). * - * Returns: a new #GSrvTarget. - * Since: 2.22 + * 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_static_resource_fini: - * @static_resource: pointer to a static #GStaticResource - * - * Finalized a GResource initialized by g_static_resource_init(). + * g_test_dbus_unset: * - * This is normally used by code generated by - * [glib-compile-resources][glib-compile-resources] - * and is not typically used by other code. + * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test + * won't use user's session bus. * - * Since: 2.32 + * 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_static_resource_get_resource: - * @static_resource: pointer to a static #GStaticResource + * g_test_dbus_up: + * @self: a #GTestDBus * - * Gets the GResource that was registered by a call to g_static_resource_init(). + * 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. * - * This is normally used by code generated by - * [glib-compile-resources][glib-compile-resources] - * and is not typically used by other code. + * If this function is called from setup callback of g_test_add(), + * g_test_dbus_down() must be called in its teardown callback. * - * Returns: (transfer none): a #GResource - * Since: 2.32 + * If this function is called from unit test's main(), then g_test_dbus_down() + * must be called after g_test_run(). */ /** - * g_static_resource_init: - * @static_resource: pointer to a static #GStaticResource - * - * Initializes a GResource from static data using a - * GStaticResource. + * g_themed_icon_append_name: + * @icon: a #GThemedIcon + * @iconname: name of icon to append to list of icons from within @icon. * - * This is normally used by code generated by - * [glib-compile-resources][glib-compile-resources] - * and is not typically used by other code. + * Append a name to the list of icons from within @icon. * - * Since: 2.32 + * Note that doing so invalidates the hash computed by prior calls + * to g_icon_hash(). */ /** - * g_subprocess_communicate: - * @subprocess: a #GSubprocess - * @stdin_buf: (nullable): data to send to the stdin of the subprocess, or %NULL - * @cancellable: a #GCancellable - * @stdout_buf: (out): data read from the subprocess stdout - * @stderr_buf: (out): data read from the subprocess stderr - * @error: a pointer to a %NULL #GError pointer, or %NULL - * - * Communicate with the subprocess until it terminates, and all input - * and output has been completed. - * - * If @stdin_buf is given, the subprocess must have been created with - * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the - * stdin of the subprocess and the pipe is closed (ie: EOF). - * - * At the same time (as not to cause blocking when dealing with large - * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or - * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those - * streams. The data that was read is returned in @stdout and/or - * the @stderr. - * - * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, - * @stdout_buf will contain the data read from stdout. Otherwise, for - * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, - * @stdout_buf will be set to %NULL. Similar provisions apply to - * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. - * - * As usual, any output variable may be given as %NULL to ignore it. - * - * If you desire the stdout and stderr data to be interleaved, create - * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and - * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned - * in @stdout_buf and @stderr_buf will be set to %NULL. - * - * In case of any error (including cancellation), %FALSE will be - * returned with @error set. Some or all of the stdin data may have - * been written. Any stdout or stderr data that has been read will be - * discarded. None of the out variables (aside from @error) will have - * been set to anything in particular and should not be inspected. - * - * In the case that %TRUE is returned, the subprocess has exited and the - * exit status inspection APIs (eg: g_subprocess_get_if_exited(), - * g_subprocess_get_exit_status()) may be used. + * g_themed_icon_get_names: + * @icon: a #GThemedIcon. * - * 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). + * Gets the names of icons from within @icon. * - * Returns: %TRUE if successful - * Since: 2.40 + * Returns: (transfer none): a list of icon names. */ /** - * g_subprocess_communicate_async: - * @subprocess: Self - * @stdin_buf: (nullable): Input data, or %NULL - * @cancellable: (nullable): Cancellable - * @callback: Callback - * @user_data: User data + * g_themed_icon_new: + * @iconname: a string containing an icon name. * - * Asynchronous version of g_subprocess_communicate(). Complete - * invocation with g_subprocess_communicate_finish(). - */ - - -/** - * g_subprocess_communicate_finish: - * @subprocess: Self - * @result: Result - * @stdout_buf: (out): Return location for stdout data - * @stderr_buf: (out): Return location for stderr data - * @error: Error + * Creates a new themed icon for @iconname. * - * Complete an invocation of g_subprocess_communicate_async(). + * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon. */ /** - * g_subprocess_communicate_utf8: - * @subprocess: a #GSubprocess - * @stdin_buf: (nullable): 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 + * 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 * - * Like g_subprocess_communicate(), but validates the output of the - * process as UTF-8, and returns it as a regular NUL terminated string. + * Creates a new themed icon for @iconnames. + * + * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon */ /** - * g_subprocess_communicate_utf8_async: - * @subprocess: Self - * @stdin_buf: (nullable): Input data, or %NULL - * @cancellable: Cancellable - * @callback: Callback - * @user_data: User data + * g_themed_icon_new_with_default_fallbacks: + * @iconname: a string containing an icon name * - * Asynchronous version of g_subprocess_communicate_utf8(). Complete - * invocation with g_subprocess_communicate_utf8_finish(). + * Creates a new themed icon for @iconname, and all the names + * that can be created by shortening @iconname at '-' characters. + * + * In the following example, @icon1 and @icon2 are equivalent: + * |[ + * const char *names[] = { + * "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) (type GThemedIcon): a new #GThemedIcon. */ /** - * 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 + * g_themed_icon_prepend_name: + * @icon: a #GThemedIcon + * @iconname: name of icon to prepend to list of icons from within @icon. * - * Complete an invocation of g_subprocess_communicate_utf8_async(). + * Prepend a name to the list of icons from within @icon. + * + * Note that doing so invalidates the hash computed by prior calls + * to g_icon_hash(). + * + * Since: 2.18 */ /** - * g_subprocess_force_exit: - * @subprocess: a #GSubprocess - * - * Use an operating-system specific method to attempt an immediate, - * forceful termination of the process. There is no mechanism to - * determine whether or not the request itself was successful; - * however, you can use g_subprocess_wait() to monitor the status of - * the process after calling this function. + * g_threaded_socket_service_new: + * @max_threads: the maximal number of threads to execute concurrently + * handling incoming clients, -1 means no limit * - * On Unix, this function sends %SIGKILL. + * Creates a new #GThreadedSocketService with no listeners. Listeners + * must be added with one of the #GSocketListener "add" methods. * - * Since: 2.40 + * Returns: a new #GSocketService. + * Since: 2.22 */ /** - * g_subprocess_get_exit_status: - * @subprocess: a #GSubprocess - * - * Check the exit status of the subprocess, given that it exited - * normally. This is the value passed to the exit() system call or the - * return value from main. - * - * This is equivalent to the system WEXITSTATUS macro. + * g_tls_backend_get_certificate_type: + * @backend: the #GTlsBackend * - * It is an error to call this function before g_subprocess_wait() and - * unless g_subprocess_get_if_exited() returned %TRUE. + * Gets the #GType of @backend's #GTlsCertificate implementation. * - * Returns: the exit status - * Since: 2.40 + * Returns: the #GType of @backend's #GTlsCertificate + * implementation. + * Since: 2.28 */ /** - * g_subprocess_get_identifier: - * @subprocess: a #GSubprocess + * g_tls_backend_get_client_connection_type: + * @backend: the #GTlsBackend * - * On UNIX, returns the process ID as a decimal string. - * On Windows, returns the result of GetProcessId() also as a string. + * Gets the #GType of @backend's #GTlsClientConnection implementation. + * + * Returns: the #GType of @backend's #GTlsClientConnection + * implementation. + * Since: 2.28 */ /** - * g_subprocess_get_if_exited: - * @subprocess: a #GSubprocess - * - * Check if the given subprocess exited normally (ie: by way of exit() - * or return from main()). - * - * This is equivalent to the system WIFEXITED macro. + * g_tls_backend_get_default: * - * It is an error to call this function before g_subprocess_wait() has - * returned. + * Gets the default #GTlsBackend for the system. * - * Returns: %TRUE if the case of a normal exit - * Since: 2.40 + * Returns: (transfer none): a #GTlsBackend + * Since: 2.28 */ /** - * g_subprocess_get_if_signaled: - * @subprocess: a #GSubprocess - * - * Check if the given subprocess terminated in response to a signal. - * - * This is equivalent to the system WIFSIGNALED macro. + * g_tls_backend_get_default_database: + * @backend: the #GTlsBackend * - * It is an error to call this function before g_subprocess_wait() has - * returned. + * Gets the default #GTlsDatabase used to verify TLS connections. * - * Returns: %TRUE if the case of termination due to a signal - * Since: 2.40 + * Returns: (transfer full): the default database, which should be + * unreffed when done. + * Since: 2.30 */ /** - * g_subprocess_get_status: - * @subprocess: a #GSubprocess - * - * Gets the raw status code of the process, as from waitpid(). - * - * This value has no particular meaning, but it can be used with the - * macros defined by the system headers such as WIFEXITED. It can also - * be used with g_spawn_check_exit_status(). - * - * It is more likely that you want to use g_subprocess_get_if_exited() - * followed by g_subprocess_get_exit_status(). + * g_tls_backend_get_dtls_client_connection_type: + * @backend: the #GTlsBackend * - * It is an error to call this function before g_subprocess_wait() has - * returned. + * Gets the #GType of @backend’s #GDtlsClientConnection implementation. * - * Returns: the (meaningless) waitpid() exit status from the kernel - * Since: 2.40 + * Returns: the #GType of @backend’s #GDtlsClientConnection + * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. + * Since: 2.48 */ /** - * g_subprocess_get_stderr_pipe: - * @subprocess: a #GSubprocess - * - * Gets the #GInputStream from which to read the stderr output of - * @subprocess. + * g_tls_backend_get_dtls_server_connection_type: + * @backend: the #GTlsBackend * - * The process must have been created with - * %G_SUBPROCESS_FLAGS_STDERR_PIPE. + * Gets the #GType of @backend’s #GDtlsServerConnection implementation. * - * Returns: (transfer none): the stderr pipe - * Since: 2.40 + * Returns: the #GType of @backend’s #GDtlsServerConnection + * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. + * Since: 2.48 */ /** - * g_subprocess_get_stdin_pipe: - * @subprocess: a #GSubprocess - * - * Gets the #GOutputStream that you can write to in order to give data - * to the stdin of @subprocess. + * g_tls_backend_get_file_database_type: + * @backend: the #GTlsBackend * - * The process must have been created with - * %G_SUBPROCESS_FLAGS_STDIN_PIPE. + * Gets the #GType of @backend's #GTlsFileDatabase implementation. * - * Returns: (transfer none): the stdout pipe - * Since: 2.40 + * Returns: the #GType of backend's #GTlsFileDatabase implementation. + * Since: 2.30 */ /** - * g_subprocess_get_stdout_pipe: - * @subprocess: a #GSubprocess - * - * Gets the #GInputStream from which to read the stdout output of - * @subprocess. + * g_tls_backend_get_server_connection_type: + * @backend: the #GTlsBackend * - * The process must have been created with - * %G_SUBPROCESS_FLAGS_STDOUT_PIPE. + * Gets the #GType of @backend's #GTlsServerConnection implementation. * - * Returns: (transfer none): the stdout pipe - * Since: 2.40 + * Returns: the #GType of @backend's #GTlsServerConnection + * implementation. + * Since: 2.28 */ /** - * g_subprocess_get_successful: - * @subprocess: a #GSubprocess - * - * Checks if the process was "successful". A process is considered - * successful if it exited cleanly with an exit status of 0, either by - * way of the exit() system call or return from main(). + * g_tls_backend_supports_dtls: + * @backend: the #GTlsBackend * - * It is an error to call this function before g_subprocess_wait() has - * returned. + * Checks if DTLS is supported. DTLS support may not be available even if TLS + * support is available, and vice-versa. * - * Returns: %TRUE if the process exited cleanly with a exit status of 0 - * Since: 2.40 + * Returns: whether DTLS is supported + * Since: 2.48 */ /** - * g_subprocess_get_term_sig: - * @subprocess: a #GSubprocess - * - * Get the signal number that caused the subprocess to terminate, given - * that it terminated due to a signal. - * - * This is equivalent to the system WTERMSIG macro. + * g_tls_backend_supports_tls: + * @backend: the #GTlsBackend * - * It is an error to call this function before g_subprocess_wait() and - * unless g_subprocess_get_if_signaled() returned %TRUE. + * Checks if TLS is supported; if this returns %FALSE for the default + * #GTlsBackend, it means no "real" TLS backend is available. * - * Returns: the signal causing termination - * Since: 2.40 + * Returns: whether or not TLS is supported + * Since: 2.28 */ /** - * g_subprocess_launcher_getenv: - * @self: a #GSubprocess - * @variable: (type filename): the environment variable to get - * - * Returns the value of the environment variable @variable in the - * environment of processes launched from this launcher. + * g_tls_certificate_get_issuer: + * @cert: a #GTlsCertificate * - * On UNIX, the returned string can be an arbitrary byte string. - * On Windows, it will be UTF-8. + * Gets the #GTlsCertificate representing @cert's issuer, if known * - * Returns: (type filename): the value of the environment variable, - * %NULL if unset - * Since: 2.40 + * Returns: (transfer none): The certificate of @cert's issuer, + * or %NULL if @cert is self-signed or signed with an unknown + * certificate. + * Since: 2.28 */ /** - * g_subprocess_launcher_new: - * @flags: #GSubprocessFlags - * - * Creates a new #GSubprocessLauncher. + * g_tls_certificate_is_same: + * @cert_one: first certificate to compare + * @cert_two: second certificate to compare * - * 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. + * 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. * - * Since: 2.40 + * Returns: whether the same or not + * Since: 2.34 */ /** - * g_subprocess_launcher_set_child_setup: (skip) - * @self: a #GSubprocessLauncher - * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function - * @user_data: user data for @child_setup - * @destroy_notify: a #GDestroyNotify for @user_data - * - * Sets up a child setup function. - * - * The child setup function will be called after fork() but before - * exec() on the child's side. - * - * @destroy_notify will not be automatically called on the child's side - * of the fork(). It will only be called when the last reference on the - * #GSubprocessLauncher is dropped or when a new child setup function is - * given. - * - * %NULL can be given as @child_setup to disable the functionality. + * g_tls_certificate_list_new_from_file: + * @file: (type filename): file containing PEM-encoded certificates to import + * @error: #GError for error reporting, or %NULL to ignore. * - * Child setup functions are only available on UNIX. + * 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. * - * Since: 2.40 + * Returns: (element-type Gio.TlsCertificate) (transfer full): a + * #GList containing #GTlsCertificate objects. You must free the list + * and its contents when you are done with it. + * Since: 2.28 */ /** - * g_subprocess_launcher_set_cwd: - * @self: a #GSubprocess - * @cwd: (type filename): the cwd for launched processes + * g_tls_certificate_new_from_file: + * @file: (type filename): file containing a PEM-encoded certificate to import + * @error: #GError for error reporting, or %NULL to ignore. * - * Sets the current working directory that processes will be launched - * with. + * 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. * - * By default processes are launched with the current working directory - * of the launching process at the time of launch. + * 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(). * - * Since: 2.40 + * Returns: the new certificate, or %NULL on error + * Since: 2.28 */ /** - * g_subprocess_launcher_set_environ: - * @self: a #GSubprocess - * @env: (array zero-terminated=1) (element-type filename) (transfer none): - * the replacement environment - * - * Replace the entire environment of processes launched from this - * launcher with the given 'environ' variable. - * - * Typically you will build this variable by using g_listenv() to copy - * the process 'environ' and using the functions g_environ_setenv(), - * g_environ_unsetenv(), etc. - * - * As an alternative, you can use g_subprocess_launcher_setenv(), - * g_subprocess_launcher_unsetenv(), etc. + * g_tls_certificate_new_from_files: + * @cert_file: (type filename): file containing one or more PEM-encoded + * certificates to import + * @key_file: (type filename): file containing a PEM-encoded private key + * to import + * @error: #GError for error reporting, or %NULL to ignore. * - * Pass an empty array to set an empty environment. Pass %NULL to inherit the - * parent process’ environment. As of GLib 2.54, the parent process’ environment - * will be copied when g_subprocess_launcher_set_environ() is called. - * Previously, it was copied when the subprocess was executed. This means the - * copied environment may now be modified (using g_subprocess_launcher_setenv(), - * etc.) before launching the subprocess. + * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file + * 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. * - * On UNIX, all strings in this array can be arbitrary byte strings. - * On Windows, they should be in UTF-8. + * 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(). * - * Since: 2.40 + * Returns: the new certificate, or %NULL on error + * Since: 2.28 */ /** - * g_subprocess_launcher_set_flags: - * @self: a #GSubprocessLauncher - * @flags: #GSubprocessFlags - * - * Sets the flags on the launcher. - * - * The default flags are %G_SUBPROCESS_FLAGS_NONE. + * g_tls_certificate_new_from_pem: + * @data: PEM-encoded certificate data + * @length: the length of @data, or -1 if it's 0-terminated. + * @error: #GError for error reporting, or %NULL to ignore. * - * 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). + * 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.) * - * 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(). + * 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. * - * Since: 2.40 + * Returns: the new certificate, or %NULL if @data is invalid + * Since: 2.28 */ /** - * g_subprocess_launcher_set_stderr_file_path: - * @self: a #GSubprocessLauncher - * @path: (type filename) (nullable): a filename or %NULL - * - * Sets the file path to use as the stderr for spawned processes. - * - * If @path is %NULL then any previously given path is unset. + * g_tls_certificate_verify: + * @cert: a #GTlsCertificate + * @identity: (nullable): the expected peer identity + * @trusted_ca: (nullable): the certificate of a trusted authority * - * The file will be created or truncated when the process is spawned, as - * would be the case if using '2>' at the shell. + * This verifies @cert and returns a set of #GTlsCertificateFlags + * indicating any problems found with it. This can be used to verify a + * certificate outside the context of making a connection, or to + * check a certificate against a CA that is not part of the system + * CA database. * - * If you want to send both stdout and stderr to the same file then use - * %G_SUBPROCESS_FLAGS_STDERR_MERGE. + * If @identity is not %NULL, @cert's name(s) will be compared against + * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return + * value if it does not match. If @identity is %NULL, that bit will + * never be set in the return value. * - * 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. + * If @trusted_ca is not %NULL, then @cert (or one of the certificates + * in its chain) must be signed by it, or else + * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If + * @trusted_ca is %NULL, that bit will never be set in the return + * value. * - * This feature is only available on UNIX. + * (All other #GTlsCertificateFlags values will always be set or unset + * as appropriate.) * - * Since: 2.40 + * Returns: the appropriate #GTlsCertificateFlags + * Since: 2.28 */ /** - * g_subprocess_launcher_set_stdin_file_path: - * @self: a #GSubprocessLauncher - * @path: - * - * Sets the file path to use as the stdin for spawned processes. - * - * If @path is %NULL then any previously given path is unset. - * - * The file must exist or spawning the process will fail. - * - * You may not set a stdin file path if a stdin fd is already set or if - * the launcher flags contain any flags directing stdin elsewhere. + * g_tls_client_connection_copy_session_state: + * @conn: a #GTlsClientConnection + * @source: a #GTlsClientConnection * - * This feature is only available on UNIX. + * Copies session state from one connection to another. This is + * not normally needed, but may be used when the same session + * needs to be used between different endpoints as is required + * by some protocols such as FTP over TLS. @source should have + * already completed a handshake, and @conn should not have + * completed a handshake. * - * Since: 2.40 + * Since: 2.46 */ /** - * g_subprocess_launcher_set_stdout_file_path: - * @self: a #GSubprocessLauncher - * @path: (type filename) (nullable): a filename or %NULL - * - * Sets the file path to use as the stdout for spawned processes. - * - * If @path is %NULL then any previously given path is unset. - * - * The file will be created or truncated when the process is spawned, as - * would be the case if using '>' at the shell. + * g_tls_client_connection_get_accepted_cas: + * @conn: the #GTlsClientConnection * - * 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. + * Gets the list of distinguished names of the Certificate Authorities + * that the server will accept certificates from. This will be set + * during the TLS handshake if the server requests a certificate. + * Otherwise, it will be %NULL. * - * This feature is only available on UNIX. + * Each item in the list is a #GByteArray which contains the complete + * subject DN of the certificate authority. * - * Since: 2.40 + * Returns: (element-type GByteArray) (transfer full): the list of + * CA DNs. You should unref each element with g_byte_array_unref() and then + * the free the list with g_list_free(). + * Since: 2.28 */ /** - * g_subprocess_launcher_setenv: - * @self: a #GSubprocess - * @variable: (type filename): the environment variable to set, - * must not contain '=' - * @value: (type filename): the new value for the variable - * @overwrite: whether to change the variable if it already exists - * - * Sets the environment variable @variable in the environment of - * processes launched from this launcher. + * g_tls_client_connection_get_server_identity: + * @conn: the #GTlsClientConnection * - * On UNIX, both the variable's name and value can be arbitrary byte - * strings, except that the variable's name cannot contain '='. - * On Windows, they should be in UTF-8. + * Gets @conn's expected server identity * - * Since: 2.40 + * Returns: (transfer none): a #GSocketConnectable describing the + * expected server identity, or %NULL if the expected identity is not + * known. + * Since: 2.28 */ /** - * g_subprocess_launcher_spawn: - * @self: a #GSubprocessLauncher - * @error: Error - * @argv0: Command line arguments - * @...: Continued arguments, %NULL terminated + * g_tls_client_connection_get_use_ssl3: + * @conn: the #GTlsClientConnection * - * Creates a #GSubprocess given a provided varargs list of arguments. + * Gets whether @conn will use SSL 3.0 rather than the + * highest-supported version of TLS; see + * g_tls_client_connection_set_use_ssl3(). * - * Since: 2.40 - * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + * Returns: whether @conn will use SSL 3.0 + * Since: 2.28 */ /** - * g_subprocess_launcher_spawnv: - * @self: a #GSubprocessLauncher - * @argv: (array zero-terminated=1) (element-type filename): Command line arguments - * @error: Error + * g_tls_client_connection_get_validation_flags: + * @conn: the #GTlsClientConnection * - * Creates a #GSubprocess given a provided array of arguments. + * Gets @conn's validation flags * - * Since: 2.40 - * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + * Returns: the validation flags + * Since: 2.28 */ /** - * g_subprocess_launcher_take_fd: - * @self: a #GSubprocessLauncher - * @source_fd: File descriptor in parent process - * @target_fd: Target descriptor for child process + * g_tls_client_connection_new: + * @base_io_stream: the #GIOStream to wrap + * @server_identity: (nullable): the expected identity of the server + * @error: #GError for error reporting, or %NULL to ignore. * - * 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. + * Creates a new #GTlsClientConnection wrapping @base_io_stream (which + * must have pollable input and output streams) which is assumed to + * communicate with the server identified by @server_identity. * - * 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. + * See the documentation for #GTlsConnection:base-io-stream for restrictions + * on when application code can run operations on the @base_io_stream after + * this function has returned. * - * 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. + * Returns: (transfer full) (type GTlsClientConnection): the new + * #GTlsClientConnection, or %NULL on error + * Since: 2.28 */ /** - * g_subprocess_launcher_take_stderr_fd: - * @self: a #GSubprocessLauncher - * @fd: a file descriptor, or -1 - * - * Sets the file descriptor to use as the stderr for spawned processes. - * - * If @fd is -1 then any previously given fd is unset. - * - * Note that the default behaviour is to pass stderr through to the - * stderr of the parent process. - * - * The passed @fd belongs to the #GSubprocessLauncher. It will be - * automatically closed when the launcher is finalized. The file - * descriptor will also be closed on the child side when executing the - * spawned process. - * - * You may not set a stderr fd if a stderr file path is already set or - * if the launcher flags contain any flags directing stderr elsewhere. + * g_tls_client_connection_set_server_identity: + * @conn: the #GTlsClientConnection + * @identity: a #GSocketConnectable describing the expected server identity * - * This feature is only available on UNIX. + * Sets @conn's expected server identity, which is used both to tell + * servers on virtual hosts which certificate to present, and also + * to let @conn know what name to look for in the certificate when + * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. * - * Since: 2.40 + * Since: 2.28 */ /** - * g_subprocess_launcher_take_stdin_fd: - * @self: a #GSubprocessLauncher - * @fd: a file descriptor, or -1 - * - * Sets the file descriptor to use as the stdin for spawned processes. - * - * If @fd is -1 then any previously given fd is unset. - * - * Note that if your intention is to have the stdin of the calling - * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT - * is a better way to go about doing that. - * - * The passed @fd is noted but will not be touched in the current - * process. It is therefore necessary that it be kept open by the - * caller until the subprocess is spawned. The file descriptor will - * also not be explicitly closed on the child side, so it must be marked - * O_CLOEXEC if that's what you want. - * - * You may not set a stdin fd if a stdin file path is already set or if - * the launcher flags contain any flags directing stdin elsewhere. + * g_tls_client_connection_set_use_ssl3: + * @conn: the #GTlsClientConnection + * @use_ssl3: whether to use SSL 3.0 * - * This feature is only available on UNIX. + * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than + * trying to properly negotiate the right version of TLS or SSL to use. + * This can be used when talking to servers that do not implement the + * fallbacks correctly and which will therefore fail to handshake with + * a "modern" TLS handshake attempt. * - * Since: 2.40 + * Since: 2.28 */ /** - * g_subprocess_launcher_take_stdout_fd: - * @self: a #GSubprocessLauncher - * @fd: a file descriptor, or -1 - * - * Sets the file descriptor to use as the stdout for spawned processes. - * - * If @fd is -1 then any previously given fd is unset. - * - * Note that the default behaviour is to pass stdout through to the - * stdout of the parent process. - * - * The passed @fd is noted but will not be touched in the current - * process. It is therefore necessary that it be kept open by the - * caller until the subprocess is spawned. The file descriptor will - * also not be explicitly closed on the child side, so it must be marked - * O_CLOEXEC if that's what you want. - * - * You may not set a stdout fd if a stdout file path is already set or - * if the launcher flags contain any flags directing stdout elsewhere. + * g_tls_client_connection_set_validation_flags: + * @conn: the #GTlsClientConnection + * @flags: the #GTlsCertificateFlags to use * - * This feature is only available on UNIX. + * Sets @conn's validation flags, to override the default set of + * checks performed when validating a server certificate. By default, + * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. * - * Since: 2.40 + * Since: 2.28 */ /** - * g_subprocess_launcher_unsetenv: - * @self: a #GSubprocess - * @variable: (type filename): the environment variable to unset, - * must not contain '=' - * - * Removes the environment variable @variable from the environment of - * processes launched from this launcher. + * g_tls_connection_emit_accept_certificate: + * @conn: a #GTlsConnection + * @peer_cert: the peer's #GTlsCertificate + * @errors: the problems with @peer_cert * - * On UNIX, the variable's name can be an arbitrary byte string not - * containing '='. On Windows, it should be in UTF-8. + * Used by #GTlsConnection implementations to emit the + * #GTlsConnection::accept-certificate signal. * - * Since: 2.40 + * Returns: %TRUE if one of the signal handlers has returned + * %TRUE to accept @peer_cert + * Since: 2.28 */ /** - * g_subprocess_new: (skip) - * @flags: flags that define the behaviour of the subprocess - * @error: (nullable): return location for an error, or %NULL - * @argv0: first commandline argument to pass to the subprocess - * @...: more commandline arguments, followed by %NULL - * - * Create a new process with the given flags and varargs argument - * list. By default, matching the g_spawn_async() defaults, the - * child's stdin will be set to the system null device, and - * stdout/stderr will be inherited from the parent. You can use - * @flags to control this behavior. + * g_tls_connection_get_certificate: + * @conn: a #GTlsConnection * - * The argument list must be terminated with %NULL. + * Gets @conn's certificate, as set by + * g_tls_connection_set_certificate(). * - * Returns: A newly created #GSubprocess, or %NULL on error (and @error - * will be set) - * Since: 2.40 + * Returns: (transfer none): @conn's certificate, or %NULL + * Since: 2.28 */ /** - * g_subprocess_newv: (rename-to g_subprocess_new) - * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess - * @flags: flags that define the behaviour of the subprocess - * @error: (nullable): return location for an error, or %NULL - * - * Create a new process with the given flags and argument list. + * g_tls_connection_get_database: + * @conn: a #GTlsConnection * - * The argument list is expected to be %NULL-terminated. + * Gets the certificate database that @conn uses to verify + * peer certificates. See g_tls_connection_set_database(). * - * Returns: A newly created #GSubprocess, or %NULL on error (and @error - * will be set) - * Since: 2.40 + * Returns: (transfer none): the certificate database that @conn uses or %NULL + * Since: 2.30 */ /** - * g_subprocess_send_signal: - * @subprocess: a #GSubprocess - * @signal_num: the signal number to send + * g_tls_connection_get_interaction: + * @conn: a connection * - * Sends the UNIX signal @signal_num to the subprocess, if it is still - * running. + * Get the object that will be used to interact with the user. It will be used + * for things like prompting the user for passwords. If %NULL is returned, then + * no user interaction will occur for this connection. * - * This API is race-free. If the subprocess has terminated, it will not - * be signalled. + * Returns: (transfer none): The interaction object. + * Since: 2.30 + */ + + +/** + * g_tls_connection_get_peer_certificate: + * @conn: a #GTlsConnection * - * This API is not available on Windows. + * Gets @conn's peer's certificate after the handshake has completed. + * (It is not set during the emission of + * #GTlsConnection::accept-certificate.) * - * Since: 2.40 + * Returns: (transfer none): @conn's peer's certificate, or %NULL + * Since: 2.28 */ /** - * g_subprocess_wait: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable - * @error: a #GError - * - * Synchronously wait for the subprocess to terminate. + * g_tls_connection_get_peer_certificate_errors: + * @conn: a #GTlsConnection * - * 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(). + * Gets the errors associated with validating @conn's peer's + * certificate, after the handshake has completed. (It is not set + * during the emission of #GTlsConnection::accept-certificate.) * - * This function does not fail in the case of the subprocess having - * abnormal termination. See g_subprocess_wait_check() for that. + * Returns: @conn's peer's certificate errors + * Since: 2.28 + */ + + +/** + * g_tls_connection_get_rehandshake_mode: + * @conn: a #GTlsConnection * - * Cancelling @cancellable doesn't kill the subprocess. Call - * g_subprocess_force_exit() if it is desirable. + * Gets @conn rehandshaking mode. See + * g_tls_connection_set_rehandshake_mode() for details. * - * Returns: %TRUE on success, %FALSE if @cancellable was cancelled - * Since: 2.40 + * Returns: @conn's rehandshaking mode + * Since: 2.28 */ /** - * g_subprocess_wait_async: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable, or %NULL - * @callback: a #GAsyncReadyCallback to call when the operation is complete - * @user_data: user_data for @callback - * - * Wait for the subprocess to terminate. + * g_tls_connection_get_require_close_notify: + * @conn: a #GTlsConnection * - * This is the asynchronous version of g_subprocess_wait(). + * Tests whether or not @conn expects a proper TLS close notification + * when the connection is closed. See + * g_tls_connection_set_require_close_notify() for details. * - * Since: 2.40 + * Returns: %TRUE if @conn requires a proper TLS close + * notification. + * Since: 2.28 */ /** - * g_subprocess_wait_check: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable - * @error: a #GError + * g_tls_connection_get_use_system_certdb: + * @conn: a #GTlsConnection * - * Combines g_subprocess_wait() with g_spawn_check_exit_status(). + * Gets whether @conn uses the system certificate database to verify + * peer certificates. See g_tls_connection_set_use_system_certdb(). * - * Returns: %TRUE on success, %FALSE if process exited abnormally, or - * @cancellable was cancelled - * Since: 2.40 + * Returns: whether @conn uses the system certificate database + * Deprecated: 2.30: Use g_tls_connection_get_database() instead */ /** - * 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 + * g_tls_connection_handshake: + * @conn: a #GTlsConnection + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: a #GError, or %NULL + * + * Attempts a TLS handshake on @conn. + * + * On the client side, it is never necessary to call this method; + * although the connection needs to perform a handshake after + * connecting (or after sending a "STARTTLS"-type command) and may + * need to rehandshake later if the server requests it, + * #GTlsConnection will handle this for you automatically when you try + * to send or receive data on the connection. However, you can call + * g_tls_connection_handshake() manually if you want to know for sure + * whether the initial handshake succeeded or failed (as opposed to + * just immediately trying to write to @conn's output stream, in which + * case if it fails, it may not be possible to tell if it failed + * before or after completing the handshake). * - * Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). + * Likewise, on the server side, although a handshake is necessary at + * the beginning of the communication, you do not need to call this + * function explicitly unless you want clearer error reporting. + * However, you may call g_tls_connection_handshake() later on to + * renegotiate parameters (encryption methods, etc) with the client. * - * This is the asynchronous version of g_subprocess_wait_check(). + * #GTlsConnection::accept_certificate may be emitted during the + * handshake. * - * Since: 2.40 + * Returns: success or failure + * Since: 2.28 */ /** - * g_subprocess_wait_check_finish: - * @subprocess: a #GSubprocess - * @result: the #GAsyncResult passed to your #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL + * g_tls_connection_handshake_async: + * @conn: a #GTlsConnection + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the handshake is complete + * @user_data: the data to pass to the callback function * - * Collects the result of a previous call to - * g_subprocess_wait_check_async(). + * Asynchronously performs a TLS handshake on @conn. See + * g_tls_connection_handshake() for more information. * - * Returns: %TRUE if successful, or %FALSE with @error set - * Since: 2.40 + * Since: 2.28 */ /** - * g_subprocess_wait_finish: - * @subprocess: a #GSubprocess - * @result: the #GAsyncResult passed to your #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL + * g_tls_connection_handshake_finish: + * @conn: a #GTlsConnection + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * Collects the result of a previous call to - * g_subprocess_wait_async(). + * Finish an asynchronous TLS handshake operation. See + * g_tls_connection_handshake() for more information. * - * Returns: %TRUE if successful, or %FALSE with @error set - * Since: 2.40 + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set. + * Since: 2.28 */ /** - * g_task_attach_source: - * @task: a #GTask - * @source: the source to attach - * @callback: the callback to invoke when @source triggers + * g_tls_connection_set_certificate: + * @conn: a #GTlsConnection + * @certificate: the certificate to use for @conn * - * A utility function for dealing with async operations where you need - * to wait for a #GSource to trigger. Attaches @source to @task's - * #GMainContext with @task's [priority][io-priority], and sets @source's - * callback to @callback, with @task as the callback's `user_data`. + * This sets the certificate that @conn will present to its peer + * during the TLS handshake. For a #GTlsServerConnection, it is + * mandatory to set this, and that will normally be done at construct + * time. * - * This takes a reference on @task until @source is destroyed. + * For a #GTlsClientConnection, this is optional. If a handshake fails + * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server + * requires a certificate, and if you try connecting again, you should + * call this method first. You can call + * g_tls_client_connection_get_accepted_cas() on the failed connection + * to get a list of Certificate Authorities that the server will + * accept certificates from. * - * Since: 2.36 + * (It is also possible that a server will allow the connection with + * or without a certificate; in that case, if you don't provide a + * certificate, you can tell that the server requested one by the fact + * that g_tls_client_connection_get_accepted_cas() will return + * non-%NULL.) + * + * Since: 2.28 */ /** - * g_task_get_cancellable: - * @task: a #GTask + * g_tls_connection_set_database: + * @conn: a #GTlsConnection + * @database: a #GTlsDatabase * - * Gets @task's #GCancellable + * Sets the certificate database that is used to verify peer certificates. + * This is set to the default database by default. See + * g_tls_backend_get_default_database(). If set to %NULL, then + * peer certificate validation will always set the + * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning + * #GTlsConnection::accept-certificate will always be emitted on + * client-side connections, unless that bit is not set in + * #GTlsClientConnection:validation-flags). * - * Returns: (transfer none): @task's #GCancellable - * Since: 2.36 + * Since: 2.30 */ /** - * g_task_get_check_cancellable: - * @task: the #GTask + * g_tls_connection_set_interaction: + * @conn: a connection + * @interaction: (nullable): an interaction object, or %NULL * - * Gets @task's check-cancellable flag. See - * g_task_set_check_cancellable() for more details. + * Set the object that will be used to interact with the user. It will be used + * for things like prompting the user for passwords. * - * Since: 2.36 + * The @interaction argument will normally be a derived subclass of + * #GTlsInteraction. %NULL can also be provided if no user interaction + * should occur for this connection. + * + * Since: 2.30 */ /** - * g_task_get_completed: - * @task: a #GTask. + * g_tls_connection_set_rehandshake_mode: + * @conn: a #GTlsConnection + * @mode: the rehandshaking mode * - * 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. + * Sets how @conn behaves with respect to rehandshaking requests. * - * Returns: %TRUE if the task has completed, %FALSE otherwise. - * Since: 2.44 - */ - - -/** - * g_task_get_context: - * @task: a #GTask + * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to + * rehandshake after the initial handshake is complete. (For a client, + * this means it will refuse rehandshake requests from the server, and + * for a server, this means it will close the connection with an error + * if the client attempts to rehandshake.) * - * 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). + * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a + * rehandshake only if the other end of the connection supports the + * 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. * - * This will always return a non-%NULL value, even if the task's - * context is the default #GMainContext. + * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow + * 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. * - * Returns: (transfer none): @task's #GMainContext - * Since: 2.36 + * Since: 2.28 */ /** - * g_task_get_priority: - * @task: a #GTask + * g_tls_connection_set_require_close_notify: + * @conn: a #GTlsConnection + * @require_close_notify: whether or not to require close notification * - * Gets @task's priority + * Sets whether or not @conn expects a proper TLS close notification + * before the connection is closed. If this is %TRUE (the default), + * then @conn will expect to receive a TLS close notification from its + * peer before the connection is closed, and will return a + * %G_TLS_ERROR_EOF error if the connection is closed without proper + * notification (since this may indicate a network error, or + * man-in-the-middle attack). * - * Returns: @task's priority - * Since: 2.36 - */ - - -/** - * g_task_get_return_on_cancel: - * @task: the #GTask + * In some protocols, the application will know whether or not the + * connection was closed cleanly based on application-level data + * (because the application-level data includes a length field, or is + * somehow self-delimiting); in this case, the close notify is + * redundant and sometimes omitted. (TLS 1.1 explicitly allows this; + * in TLS 1.0 it is technically an error, but often done anyway.) You + * can use g_tls_connection_set_require_close_notify() to tell @conn + * to allow an "unannounced" connection close, in which case the close + * will show up as a 0-length read, as in a non-TLS + * #GSocketConnection, and it is up to the application to check that + * the data has been fully received. * - * Gets @task's return-on-cancel flag. See - * g_task_set_return_on_cancel() for more details. + * Note that this only affects the behavior when the peer closes the + * connection; when the application calls g_io_stream_close() itself + * on @conn, this will send a close notification regardless of the + * setting of this property. If you explicitly want to do an unclean + * close, you can close @conn's #GTlsConnection:base-io-stream rather + * than closing @conn itself, but note that this may only be done when no other + * operations are pending on @conn or the base I/O stream. * - * Since: 2.36 + * Since: 2.28 */ /** - * g_task_get_source_object: - * @task: a #GTask + * g_tls_connection_set_use_system_certdb: + * @conn: a #GTlsConnection + * @use_system_certdb: whether to use the system certificate database * - * Gets the source object from @task. Like - * g_async_result_get_source_object(), but does not ref the object. + * Sets whether @conn uses the system certificate database to verify + * peer certificates. This is %TRUE by default. If set to %FALSE, then + * peer certificate validation will always set the + * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning + * #GTlsConnection::accept-certificate will always be emitted on + * client-side connections, unless that bit is not set in + * #GTlsClientConnection:validation-flags). * - * Returns: (transfer none) (nullable) (type GObject): @task's source object, or %NULL - * Since: 2.36 + * Deprecated: 2.30: Use g_tls_connection_set_database() instead */ /** - * g_task_get_source_tag: - * @task: a #GTask + * g_tls_database_create_certificate_handle: + * @self: a #GTlsDatabase + * @certificate: certificate for which to create a handle. * - * Gets @task's source tag. See g_task_set_source_tag(). + * Create a handle string for the certificate. The database will only be able + * to create a handle for certificates that originate from the database. In + * cases where the database cannot create a handle for a certificate, %NULL + * will be returned. * - * Returns: (transfer none): @task's source tag - * Since: 2.36 + * This handle should be stable across various instances of the application, + * 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: (nullable): a newly allocated string containing the + * handle. + * Since: 2.30 */ /** - * g_task_get_task_data: - * @task: a #GTask + * g_tls_database_lookup_certificate_for_handle: + * @self: a #GTlsDatabase + * @handle: a certificate handle + * @interaction: (nullable): used to interact with the user if necessary + * @flags: Flags which affect the lookup. + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (nullable): a #GError, or %NULL * - * Gets @task's `task_data`. + * Lookup a certificate by its handle. * - * Returns: (transfer none): @task's `task_data`. - * Since: 2.36 + * 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. + * + * Returns: (transfer full) (nullable): a newly allocated + * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Since: 2.30 */ /** - * g_task_had_error: - * @task: a #GTask. + * g_tls_database_lookup_certificate_for_handle_async: + * @self: a #GTlsDatabase + * @handle: a certificate handle + * @interaction: (nullable): used to interact with the user if necessary + * @flags: Flags which affect the lookup. + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the operation completes + * @user_data: the data to pass to the callback function * - * Tests if @task resulted in an error. + * Asynchronously lookup a certificate by its handle in the database. See + * g_tls_database_lookup_certificate_for_handle() for more information. * - * Returns: %TRUE if the task resulted in an error, %FALSE otherwise. - * Since: 2.36 + * Since: 2.30 */ /** - * g_task_is_valid: - * @result: (type Gio.AsyncResult): A #GAsyncResult - * @source_object: (nullable) (type GObject): the source object - * expected to be associated with the task + * g_tls_database_lookup_certificate_for_handle_finish: + * @self: a #GTlsDatabase + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * 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. + * Finish an asynchronous lookup of a certificate by its handle. See + * g_tls_database_lookup_certificate_by_handle() for more information. * - * Returns: %TRUE if @result and @source_object are valid, %FALSE - * if not - * Since: 2.36 + * If the handle is no longer valid, or does not point to a certificate in + * this database, then %NULL will be returned. + * + * Returns: (transfer full): a newly allocated #GTlsCertificate object. + * Use g_object_unref() to release the certificate. + * Since: 2.30 */ /** - * g_task_new: - * @source_object: (nullable) (type GObject): the #GObject that owns - * this task, or %NULL. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @callback_data: (closure): user data passed to @callback. + * g_tls_database_lookup_certificate_issuer: + * @self: a #GTlsDatabase + * @certificate: a #GTlsCertificate + * @interaction: (nullable): used to interact with the user if necessary + * @flags: flags which affect the lookup operation + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (nullable): a #GError, or %NULL * - * 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]. + * Lookup the issuer of @certificate in the database. * - * 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(). + * The %issuer property + * of @certificate is not modified, and the two certificates are not hooked + * into a chain. * - * 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. + * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform + * the lookup operation asynchronously. * - * Returns: a #GTask. - * Since: 2.36 + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. + * Since: 2.30 */ /** - * g_task_propagate_boolean: - * @task: a #GTask. - * @error: return location for a #GError - * - * Gets the result of @task as a #gboolean. - * - * If the task resulted in an error, or was cancelled, then this will - * instead return %FALSE and set @error. + * g_tls_database_lookup_certificate_issuer_async: + * @self: a #GTlsDatabase + * @certificate: a #GTlsCertificate + * @interaction: (nullable): used to interact with the user if necessary + * @flags: flags which affect the lookup operation + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the operation completes + * @user_data: the data to pass to the callback function * - * Since this method transfers ownership of the return value (or - * error) to the caller, you may only call it once. + * Asynchronously lookup the issuer of @certificate in the database. See + * g_tls_database_lookup_certificate_issuer() for more information. * - * Returns: the task result, or %FALSE on error - * Since: 2.36 + * Since: 2.30 */ /** - * g_task_propagate_int: - * @task: a #GTask. - * @error: return location for a #GError - * - * Gets the result of @task as an integer (#gssize). - * - * If the task resulted in an error, or was cancelled, then this will - * instead return -1 and set @error. + * g_tls_database_lookup_certificate_issuer_finish: + * @self: a #GTlsDatabase + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * Since this method transfers ownership of the return value (or - * error) to the caller, you may only call it once. + * Finish an asynchronous lookup issuer operation. See + * g_tls_database_lookup_certificate_issuer() for more information. * - * Returns: the task result, or -1 on error - * Since: 2.36 + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. + * Since: 2.30 */ /** - * g_task_propagate_pointer: - * @task: a #GTask - * @error: return location for a #GError - * - * Gets the result of @task as a pointer, and transfers ownership - * of that value to the caller. + * g_tls_database_lookup_certificates_issued_by: + * @self: a #GTlsDatabase + * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN. + * @interaction: (nullable): used to interact with the user if necessary + * @flags: Flags which affect the lookup operation. + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (nullable): a #GError, or %NULL * - * If the task resulted in an error, or was cancelled, then this will - * instead return %NULL and set @error. + * Lookup certificates issued by this issuer in the database. * - * Since this method transfers ownership of the return value (or - * error) to the caller, you may only call it once. + * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform + * the lookup operation asynchronously. * - * Returns: (transfer full): the task result, or %NULL on error - * Since: 2.36 + * 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 */ /** - * g_task_report_error: - * @source_object: (nullable) (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 + * g_tls_database_lookup_certificates_issued_by_async: + * @self: a #GTlsDatabase + * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN. + * @interaction: (nullable): used to interact with the user if necessary + * @flags: Flags which affect the lookup operation. + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the operation completes + * @user_data: the data to pass to the callback function * - * 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. + * Asynchronously lookup certificates issued by this issuer in the database. See + * g_tls_database_lookup_certificates_issued_by() for more information. * - * See also g_task_report_new_error(). + * The database may choose to hold a reference to the issuer byte array for the duration + * of of this asynchronous operation. The byte array should not be modified during + * this time. * - * Since: 2.36 + * Since: 2.30 */ /** - * g_task_report_new_error: - * @source_object: (nullable) (type GObject): the #GObject that owns - * this task, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @callback_data: (closure): user data passed to @callback. - * @source_tag: an opaque pointer indicating the source of this task - * @domain: a #GQuark. - * @code: an error code. - * @format: a string with format characters. - * @...: a list of values to insert into @format. - * - * Creates a #GTask and then immediately calls - * g_task_return_new_error() on it. Use this in the wrapper function - * of an asynchronous method when you want to avoid even calling the - * virtual method. You can then use g_async_result_is_tagged() in the - * finish method wrapper to check if the result there is tagged as - * having been created by the wrapper method, and deal with it - * appropriately if so. + * g_tls_database_lookup_certificates_issued_by_finish: + * @self: a #GTlsDatabase + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * See also g_task_report_error(). + * Finish an asynchronous lookup of certificates. See + * g_tls_database_lookup_certificates_issued_by() for more information. * - * Since: 2.36 + * 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 */ /** - * g_task_return_boolean: - * @task: a #GTask. - * @result: the #gboolean result of a task function. + * g_tls_database_verify_chain: + * @self: a #GTlsDatabase + * @chain: a #GTlsCertificate chain + * @purpose: the purpose that this certificate chain will be used for. + * @identity: (nullable): the expected peer identity + * @interaction: (nullable): used to interact with the user if necessary + * @flags: additional verify flags + * @cancellable: (nullable): a #GCancellable, or %NULL + * @error: (nullable): a #GError, or %NULL * - * Sets @task's result to @result and completes the task (see - * g_task_return_pointer() for more discussion of exactly what this - * means). + * Determines the validity of a certificate chain after looking up and + * adding any missing certificates to the chain. + * + * @chain is a chain of #GTlsCertificate objects each pointing to the next + * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially + * consist of one or more certificates. After the verification process is + * complete, @chain may be modified by adding missing certificates, or removing + * extra certificates. If a certificate anchor was found, then it is added to + * the @chain. + * + * @purpose describes the purpose (or usage) for which the certificate + * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER + * which means that the certificate is being used to authenticate a server + * (and we are acting as the client). + * + * The @identity is used to check for pinned certificates (trust exceptions) + * in the database. These will override the normal verification process on a + * host by host basis. + * + * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be + * used. + * + * If @chain is found to be valid, then the return value will be 0. If + * @chain is found to be invalid, then the return value will indicate + * the problems found. If the function is unable to determine whether + * @chain is valid or not (eg, because @cancellable is triggered + * before it completes) then the return value will be + * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set + * accordingly. @error is not set when @chain is successfully analyzed + * but found to be invalid. + * + * This function can block, use g_tls_database_verify_chain_async() to perform + * the verification operation asynchronously. * - * Since: 2.36 + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. + * Since: 2.30 */ /** - * g_task_return_error: - * @task: a #GTask. - * @error: (transfer full): the #GError result of a task function. - * - * Sets @task's result to @error (which @task assumes ownership of) - * and completes the task (see g_task_return_pointer() for more - * discussion of exactly what this means). - * - * Note that since the task takes ownership of @error, and since the - * task may be completed before returning from g_task_return_error(), - * you cannot assume that @error is still valid after calling this. - * Call g_error_copy() on the error if you need to keep a local copy - * as well. + * g_tls_database_verify_chain_async: + * @self: a #GTlsDatabase + * @chain: a #GTlsCertificate chain + * @purpose: the purpose that this certificate chain will be used for. + * @identity: (nullable): the expected peer identity + * @interaction: (nullable): used to interact with the user if necessary + * @flags: additional verify flags + * @cancellable: (nullable): a #GCancellable, or %NULL + * @callback: callback to call when the operation completes + * @user_data: the data to pass to the callback function * - * See also g_task_return_new_error(). + * Asynchronously determines the validity of a certificate chain after + * looking up and adding any missing certificates to the chain. See + * g_tls_database_verify_chain() for more information. * - * Since: 2.36 + * Since: 2.30 */ /** - * g_task_return_error_if_cancelled: - * @task: a #GTask + * g_tls_database_verify_chain_finish: + * @self: a #GTlsDatabase + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * 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). + * Finish an asynchronous verify chain operation. See + * g_tls_database_verify_chain() for more information. * - * Returns: %TRUE if @task has been cancelled, %FALSE if not - * Since: 2.36 + * If @chain is found to be valid, then the return value will be 0. If + * @chain is found to be invalid, then the return value will indicate + * the problems found. If the function is unable to determine whether + * @chain is valid or not (eg, because @cancellable is triggered + * before it completes) then the return value will be + * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set + * accordingly. @error is not set when @chain is successfully analyzed + * but found to be invalid. + * + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. + * Since: 2.30 */ /** - * g_task_return_int: - * @task: a #GTask. - * @result: the integer (#gssize) result of a task function. + * g_tls_error_quark: * - * Sets @task's result to @result and completes the task (see - * g_task_return_pointer() for more discussion of exactly what this - * means). + * Gets the TLS error quark. * - * Since: 2.36 + * Returns: a #GQuark. + * Since: 2.28 */ /** - * 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. + * g_tls_file_database_new: + * @anchors: (type filename): filename of anchor certificate authorities. + * @error: #GError for error reporting, or %NULL to ignore. * - * 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). + * Creates a new #GTlsFileDatabase which uses anchor certificate authorities + * in @anchors to verify certificate chains. * - * See also g_task_return_error(). + * The certificates in @anchors must be PEM encoded. * - * Since: 2.36 + * Returns: (transfer full) (type GTlsFileDatabase): the new + * #GTlsFileDatabase, or %NULL on error + * Since: 2.30 */ /** - * g_task_return_pointer: - * @task: a #GTask - * @result: (nullable) (transfer full): the pointer result of a task - * function - * @result_destroy: (nullable): a #GDestroyNotify function. + * g_tls_interaction_ask_password: + * @interaction: a #GTlsInteraction object + * @password: a #GTlsPassword object + * @cancellable: an optional #GCancellable cancellation object + * @error: an optional location to place an error on failure * - * 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(). + * Run synchronous interaction to ask the user for a password. In general, + * g_tls_interaction_invoke_ask_password() should be used instead of this + * function. * - * "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. + * 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. * - * 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. + * 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. * - * Since: 2.36 + * Returns: The status of the ask password interaction. + * Since: 2.30 */ /** - * g_task_run_in_thread: - * @task: a #GTask - * @task_func: a #GTaskThreadFunc + * g_tls_interaction_ask_password_async: + * @interaction: a #GTlsInteraction object + * @password: a #GTlsPassword object + * @cancellable: an optional #GCancellable cancellation object + * @callback: (nullable): will be called when the interaction completes + * @user_data: (nullable): data to pass to the @callback * - * Runs @task_func in another thread. When @task_func returns, @task's - * #GAsyncReadyCallback will be invoked in @task's #GMainContext. + * Run asynchronous interaction to ask the user for a password. In general, + * g_tls_interaction_invoke_ask_password() should be used instead of this + * function. * - * This takes a ref on @task until the task completes. + * 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. * - * See #GTaskThreadFunc for more details about how @task_func is handled. + * 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. * - * Although GLib currently rate-limits the tasks queued via - * g_task_run_in_thread(), you should not assume that it will always - * do this. If you have a very large number of tasks to run, but don't - * want them to all run at once, you should only queue a limited - * number of them at a time. + * Certain implementations may not support immediate cancellation. * - * Since: 2.36 + * Since: 2.30 */ /** - * g_task_run_in_thread_sync: - * @task: a #GTask - * @task_func: a #GTaskThreadFunc - * - * Runs @task_func in another thread, and waits for it to return or be - * cancelled. You can use g_task_propagate_pointer(), etc, afterward - * to get the result of @task_func. + * g_tls_interaction_ask_password_finish: + * @interaction: a #GTlsInteraction object + * @result: the result passed to the callback + * @error: an optional location to place an error on failure * - * See #GTaskThreadFunc for more details about how @task_func is handled. + * Complete an ask password user interaction request. This should be once + * the g_tls_interaction_ask_password_async() completion callback is called. * - * 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. + * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed + * to g_tls_interaction_ask_password() will have its password filled in. * - * Although GLib currently rate-limits the tasks queued via - * g_task_run_in_thread_sync(), you should not assume that it will - * always do this. If you have a very large number of tasks to run, - * but don't want them to all run at once, you should only queue a - * limited number of them at a time. + * 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. * - * Since: 2.36 + * Returns: The status of the ask password interaction. + * Since: 2.30 */ /** - * g_task_set_check_cancellable: - * @task: the #GTask - * @check_cancellable: whether #GTask will check the state of - * its #GCancellable for you. + * g_tls_interaction_invoke_ask_password: + * @interaction: a #GTlsInteraction object + * @password: a #GTlsPassword object + * @cancellable: an optional #GCancellable cancellation object + * @error: an optional location to place an error on failure * - * 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. + * Invoke the interaction to ask the user for a password. 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 or #GTlsDatabase to ask the user + * for a password. * - * 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()). + * 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. * - * If you are using g_task_set_return_on_cancel() as well, then - * you must leave check-cancellable set %TRUE. + * 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. * - * Since: 2.36 + * 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_task_set_priority: - * @task: the #GTask - * @priority: the [priority][io-priority] of the request + * 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 * - * Sets @task's priority. If you do not call this, it will default to - * %G_PRIORITY_DEFAULT. + * 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. * - * 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(). + * 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. * - * Since: 2.36 + * 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_task_set_return_on_cancel: - * @task: the #GTask - * @return_on_cancel: whether the task returns automatically when - * it is cancelled. - * - * Sets or clears @task's return-on-cancel flag. This is only - * meaningful for tasks run via g_task_run_in_thread() or - * g_task_run_in_thread_sync(). + * 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 * - * 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. + * 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. * - * 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. + * 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. * - * 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 %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 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. + * 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: %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 + * Returns: The status of the request certificate interaction. + * Since: 2.40 */ /** - * g_task_set_source_tag: - * @task: the #GTask - * @source_tag: an opaque pointer indicating the source of this task + * 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: (nullable): will be called when the interaction completes + * @user_data: (nullable): data to pass to the @callback * - * 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. + * 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. * - * Since: 2.36 + * 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_task_set_task_data: - * @task: the #GTask - * @task_data: (nullable): task-specific data - * @task_data_destroy: (nullable): #GDestroyNotify for @task_data + * 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 * - * Sets @task's task data (freeing the existing task data, if any). + * Complete an request certificate user interaction request. This should be once + * the g_tls_interaction_request_certificate_async() completion callback is called. * - * Since: 2.36 - */ - - -/** - * g_tcp_connection_get_graceful_disconnect: - * @connection: a #GTcpConnection + * 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. * - * Checks if graceful disconnects are used. See - * g_tcp_connection_set_graceful_disconnect(). + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. * - * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise - * Since: 2.22 + * Returns: The status of the request certificate interaction. + * Since: 2.40 */ /** - * g_tcp_connection_set_graceful_disconnect: - * @connection: a #GTcpConnection - * @graceful_disconnect: Whether to do graceful disconnects or not - * - * 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_tls_password_get_description: + * @password: a #GTlsPassword object * - * A graceful disconnect means that we can be sure that we successfully sent - * all the outstanding data to the other end, or get an error reported. - * However, it also means we have to wait for all the data to reach the - * other side and for it to acknowledge this by closing the socket, which may - * take a while. For this reason it is disabled by default. + * Get a description string about what the password will be used for. * - * Since: 2.22 + * Returns: The description of the password. + * Since: 2.30 */ /** - * g_tcp_wrapper_connection_get_base_io_stream: - * @conn: a #GTcpWrapperConnection + * g_tls_password_get_flags: + * @password: a #GTlsPassword object * - * Get's @conn's base #GIOStream + * Get flags about the password. * - * Returns: (transfer none): @conn's base #GIOStream + * Returns: The flags about the password. + * Since: 2.30 */ /** - * g_tcp_wrapper_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @socket: the #GSocket associated with @base_io_stream + * g_tls_password_get_value: + * @password: a #GTlsPassword object + * @length: (nullable): location to place the length of the password. * - * Wraps @base_io_stream and @socket together as a #GSocketConnection. + * 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 new #GSocketConnection. - * Since: 2.28 + * Returns: The password value (owned by the password object). + * Since: 2.30 */ /** - * g_test_dbus_add_service_dir: - * @self: a #GTestDBus - * @path: path to a directory containing .service files + * g_tls_password_get_warning: + * @password: a #GTlsPassword object * - * Add a path where dbus-daemon will look up .service files. This can't be - * called after g_test_dbus_up(). + * Get a user readable translated warning. Usually this warning is a + * representation of the password flags returned from + * g_tls_password_get_flags(). + * + * Returns: The warning. + * Since: 2.30 */ /** - * g_test_dbus_down: - * @self: a #GTestDBus + * g_tls_password_new: + * @flags: the password flags + * @description: description of what the password is for * - * Stop the session bus started by g_test_dbus_up(). + * Create a new #GTlsPassword object. * - * 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. + * Returns: (transfer full): The newly allocated password object */ /** - * g_test_dbus_get_bus_address: - * @self: a #GTestDBus + * g_tls_password_set_description: + * @password: a #GTlsPassword object + * @description: The description of the password * - * 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(). + * Set a description string about what the password will be used for. * - * Returns: (nullable): the address of the bus, or %NULL. + * Since: 2.30 */ /** - * g_test_dbus_get_flags: - * @self: a #GTestDBus + * g_tls_password_set_flags: + * @password: a #GTlsPassword object + * @flags: The flags about the password * - * Get the flags of the #GTestDBus object. + * Set flags about the password. * - * Returns: the value of #GTestDBus:flags property + * Since: 2.30 */ /** - * g_test_dbus_new: - * @flags: a #GTestDBusFlags + * g_tls_password_set_value: + * @password: a #GTlsPassword object + * @value: (array length=length): the new password value + * @length: the length of the password, or -1 * - * Create a new #GTestDBus object. + * Set the value for this password. The @value will be copied by the password + * object. * - * Returns: (transfer full): a new #GTestDBus. + * 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_test_dbus_stop: - * @self: a #GTestDBus + * g_tls_password_set_value_full: (virtual set_value) + * @password: a #GTlsPassword object + * @value: (array length=length): the value for the password + * @length: the length of the password, or -1 + * @destroy: (nullable): a function to use to free the password. * - * Stop the session bus started by g_test_dbus_up(). + * Provide the value for this password. * - * 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. + * The @value will be owned by the password object, and later freed using + * the @destroy function callback. + * + * 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_test_dbus_unset: + * g_tls_password_set_warning: + * @password: a #GTlsPassword object + * @warning: The user readable warning * - * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test - * won't use user's session bus. + * Set a user readable translated warning. Usually this warning is a + * representation of the password flags returned from + * g_tls_password_get_flags(). * - * 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. + * Since: 2.30 */ /** - * g_test_dbus_up: - * @self: a #GTestDBus + * g_tls_server_connection_new: + * @base_io_stream: the #GIOStream to wrap + * @certificate: (nullable): the default server certificate, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * 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. + * Creates a new #GTlsServerConnection wrapping @base_io_stream (which + * must have pollable input and output streams). * - * If this function is called from setup callback of g_test_add(), - * g_test_dbus_down() must be called in its teardown callback. + * See the documentation for #GTlsConnection:base-io-stream for restrictions + * on when application code can run operations on the @base_io_stream after + * this function has returned. * - * If this function is called from unit test's main(), then g_test_dbus_down() - * must be called after g_test_run(). + * Returns: (transfer full) (type GTlsServerConnection): the new + * #GTlsServerConnection, or %NULL on error + * Since: 2.28 */ /** - * g_themed_icon_append_name: - * @icon: a #GThemedIcon - * @iconname: name of icon to append to list of icons from within @icon. + * g_unix_connection_receive_credentials: + * @connection: A #GUnixConnection. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Append a name to the list of icons from within @icon. + * Receives credentials from the sending end of the connection. The + * sending end has to call g_unix_connection_send_credentials() (or + * similar) for this to work. * - * Note that doing so invalidates the hash computed by prior calls - * to g_icon_hash(). + * As well as reading the credentials this also reads (and discards) a + * single byte from the stream, as this is required for credentials + * passing to work on some implementations. + * + * Other ways to exchange credentials with a foreign peer includes the + * #GUnixCredentialsMessage type and g_socket_get_credentials() function. + * + * Returns: (transfer full): Received credentials on success (free with + * g_object_unref()), %NULL if @error is set. + * Since: 2.26 */ /** - * g_themed_icon_get_names: - * @icon: a #GThemedIcon. + * g_unix_connection_receive_credentials_async: + * @connection: A #GUnixConnection. + * @cancellable: (nullable): 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 names of icons from within @icon. + * Asynchronously receive credentials. * - * Returns: (transfer none): a list of icon names. + * 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_themed_icon_new: - * @iconname: a string containing an icon name. + * g_unix_connection_receive_credentials_finish: + * @connection: A #GUnixConnection. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Creates a new themed icon for @iconname. + * Finishes an asynchronous receive credentials operation started with + * g_unix_connection_receive_credentials_async(). * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon. + * Returns: (transfer full): a #GCredentials, or %NULL on error. + * Free the returned object with g_object_unref(). + * Since: 2.32 */ /** - * 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 + * g_unix_connection_receive_fd: + * @connection: a #GUnixConnection + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @error: (nullable): #GError for error reporting, or %NULL to ignore * - * Creates a new themed icon for @iconnames. + * Receives a file descriptor from the sending end of the connection. + * The sending end has to call g_unix_connection_send_fd() for this + * to work. * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon + * As well as reading the fd this also reads a single byte from the + * stream, as this is required for fd passing to work on some + * implementations. + * + * Returns: a file descriptor on success, -1 on error. + * Since: 2.22 */ /** - * g_themed_icon_new_with_default_fallbacks: - * @iconname: a string containing an icon name + * g_unix_connection_send_credentials: + * @connection: A #GUnixConnection. + * @cancellable: (nullable): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Creates a new themed icon for @iconname, and all the names - * that can be created by shortening @iconname at '-' characters. + * Passes the credentials of the current user the receiving side + * of the connection. The receiving end has to call + * g_unix_connection_receive_credentials() (or similar) to accept the + * credentials. * - * In the following example, @icon1 and @icon2 are equivalent: - * |[ - * const char *names[] = { - * "gnome-dev-cdrom-audio", - * "gnome-dev-cdrom", - * "gnome-dev", - * "gnome" - * }; + * As well as sending the credentials this also writes a single NUL + * byte to the stream, as this is required for credentials passing to + * work on some implementations. * - * icon1 = g_themed_icon_new_from_names (names, 4); - * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); - * ]| + * Other ways to exchange credentials with a foreign peer includes the + * #GUnixCredentialsMessage type and g_socket_get_credentials() function. * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon. + * Returns: %TRUE on success, %FALSE if @error is set. + * Since: 2.26 */ /** - * g_themed_icon_prepend_name: - * @icon: a #GThemedIcon - * @iconname: name of icon to prepend to list of icons from within @icon. + * g_unix_connection_send_credentials_async: + * @connection: A #GUnixConnection. + * @cancellable: (nullable): 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 * - * Prepend a name to the list of icons from within @icon. + * Asynchronously send credentials. * - * Note that doing so invalidates the hash computed by prior calls - * to g_icon_hash(). + * For more details, see g_unix_connection_send_credentials() which is + * the synchronous version of this call. * - * Since: 2.18 + * 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_threaded_socket_service_new: - * @max_threads: the maximal number of threads to execute concurrently - * handling incoming clients, -1 means no limit + * g_unix_connection_send_credentials_finish: + * @connection: A #GUnixConnection. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Creates a new #GThreadedSocketService with no listeners. Listeners - * must be added with one of the #GSocketListener "add" methods. + * Finishes an asynchronous send credentials operation started with + * g_unix_connection_send_credentials_async(). * - * Returns: a new #GSocketService. - * Since: 2.22 + * Returns: %TRUE if the operation was successful, otherwise %FALSE. + * Since: 2.32 */ /** - * g_tls_backend_get_certificate_type: - * @backend: the #GTlsBackend + * g_unix_connection_send_fd: + * @connection: a #GUnixConnection + * @fd: a file descriptor + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. + * @error: (nullable): #GError for error reporting, or %NULL to ignore. * - * Gets the #GType of @backend's #GTlsCertificate implementation. + * Passes a file descriptor to the receiving side of the + * connection. The receiving end has to call g_unix_connection_receive_fd() + * to accept the file descriptor. * - * Returns: the #GType of @backend's #GTlsCertificate - * implementation. - * Since: 2.28 + * As well as sending the fd this also writes a single byte to the + * stream, as this is required for fd passing to work on some + * implementations. + * + * Returns: a %TRUE on success, %NULL on error. + * Since: 2.22 */ /** - * g_tls_backend_get_client_connection_type: - * @backend: the #GTlsBackend + * g_unix_credentials_message_get_credentials: + * @message: A #GUnixCredentialsMessage. * - * Gets the #GType of @backend's #GTlsClientConnection implementation. + * Gets the credentials stored in @message. * - * Returns: the #GType of @backend's #GTlsClientConnection - * implementation. - * Since: 2.28 + * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message. + * Since: 2.26 */ /** - * g_tls_backend_get_default: + * g_unix_credentials_message_is_supported: * - * Gets the default #GTlsBackend for the system. + * Checks if passing #GCredentials on a #GSocket is supported on this platform. * - * Returns: (transfer none): a #GTlsBackend - * Since: 2.28 + * Returns: %TRUE if supported, %FALSE otherwise + * Since: 2.26 */ /** - * g_tls_backend_get_default_database: - * @backend: the #GTlsBackend + * g_unix_credentials_message_new: * - * Gets the default #GTlsDatabase used to verify TLS connections. + * Creates a new #GUnixCredentialsMessage with credentials matching the current processes. * - * Returns: (transfer full): the default database, which should be - * unreffed when done. - * Since: 2.30 + * Returns: a new #GUnixCredentialsMessage + * Since: 2.26 */ /** - * g_tls_backend_get_dtls_client_connection_type: - * @backend: the #GTlsBackend + * g_unix_credentials_message_new_with_credentials: + * @credentials: A #GCredentials object. * - * Gets the #GType of @backend’s #GDtlsClientConnection implementation. + * Creates a new #GUnixCredentialsMessage holding @credentials. * - * Returns: the #GType of @backend’s #GDtlsClientConnection - * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. - * Since: 2.48 + * Returns: a new #GUnixCredentialsMessage + * Since: 2.26 */ /** - * g_tls_backend_get_dtls_server_connection_type: - * @backend: the #GTlsBackend + * g_unix_fd_list_append: + * @list: a #GUnixFDList + * @fd: a valid open file descriptor + * @error: a #GError pointer * - * Gets the #GType of @backend’s #GDtlsServerConnection implementation. + * Adds a file descriptor to @list. * - * Returns: the #GType of @backend’s #GDtlsServerConnection - * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. - * Since: 2.48 + * The file descriptor is duplicated using dup(). You keep your copy + * of the descriptor and the copy contained in @list will be closed + * when @list is finalized. + * + * A possible cause of failure is exceeding the per-process or + * system-wide file descriptor limit. + * + * The index of the file descriptor in the list is returned. If you use + * this index with g_unix_fd_list_get() then you will receive back a + * duplicated copy of the same file descriptor. + * + * Returns: the index of the appended fd in case of success, else -1 + * (and @error is set) + * Since: 2.24 */ /** - * g_tls_backend_get_file_database_type: - * @backend: the #GTlsBackend + * g_unix_fd_list_get: + * @list: a #GUnixFDList + * @index_: the index into the list + * @error: a #GError pointer * - * Gets the #GType of @backend's #GTlsFileDatabase implementation. + * Gets a file descriptor out of @list. * - * Returns: the #GType of backend's #GTlsFileDatabase implementation. - * Since: 2.30 + * @index_ specifies the index of the file descriptor to get. It is a + * programmer error for @index_ to be out of range; see + * g_unix_fd_list_get_length(). + * + * The file descriptor is duplicated using dup() and set as + * close-on-exec before being returned. You must call close() on it + * when you are done. + * + * A possible cause of failure is exceeding the per-process or + * system-wide file descriptor limit. + * + * Returns: the file descriptor, or -1 in case of error + * Since: 2.24 */ /** - * g_tls_backend_get_server_connection_type: - * @backend: the #GTlsBackend + * g_unix_fd_list_get_length: + * @list: a #GUnixFDList * - * Gets the #GType of @backend's #GTlsServerConnection implementation. + * Gets the length of @list (ie: the number of file descriptors + * contained within). * - * Returns: the #GType of @backend's #GTlsServerConnection - * implementation. - * Since: 2.28 + * Returns: the length of @list + * Since: 2.24 */ /** - * g_tls_backend_supports_dtls: - * @backend: the #GTlsBackend + * g_unix_fd_list_new: * - * Checks if DTLS is supported. DTLS support may not be available even if TLS - * support is available, and vice-versa. + * Creates a new #GUnixFDList containing no file descriptors. * - * Returns: whether DTLS is supported - * Since: 2.48 + * Returns: a new #GUnixFDList + * Since: 2.24 */ /** - * g_tls_backend_supports_tls: - * @backend: the #GTlsBackend + * g_unix_fd_list_new_from_array: + * @fds: (array length=n_fds): the initial list of file descriptors + * @n_fds: the length of #fds, or -1 * - * Checks if TLS is supported; if this returns %FALSE for the default - * #GTlsBackend, it means no "real" TLS backend is available. + * Creates a new #GUnixFDList containing the file descriptors given in + * @fds. The file descriptors become the property of the new list and + * may no longer be used by the caller. The array itself is owned by + * the caller. * - * Returns: whether or not TLS is supported - * Since: 2.28 + * Each file descriptor in the array should be set to close-on-exec. + * + * If @n_fds is -1 then @fds must be terminated with -1. + * + * Returns: a new #GUnixFDList + * Since: 2.24 */ /** - * g_tls_certificate_get_issuer: - * @cert: a #GTlsCertificate + * g_unix_fd_list_peek_fds: + * @list: a #GUnixFDList + * @length: (out) (optional): pointer to the length of the returned + * array, or %NULL * - * Gets the #GTlsCertificate representing @cert's issuer, if known + * Returns the array of file descriptors that is contained in this + * object. * - * Returns: (transfer none): The certificate of @cert's issuer, - * or %NULL if @cert is self-signed or signed with an unknown - * certificate. - * Since: 2.28 + * After this call, the descriptors remain the property of @list. The + * caller must not close them and must not free the array. The array is + * valid only until @list is changed in any way. + * + * If @length is non-%NULL then it is set to the number of file + * descriptors in the returned array. The returned array is also + * terminated with -1. + * + * This function never returns %NULL. In case there are no file + * descriptors contained in @list, an empty array is returned. + * + * Returns: (array length=length) (transfer none): an array of file + * descriptors + * Since: 2.24 */ /** - * g_tls_certificate_is_same: - * @cert_one: first certificate to compare - * @cert_two: second certificate to compare + * g_unix_fd_list_steal_fds: + * @list: a #GUnixFDList + * @length: (out) (optional): pointer to the length of the returned + * array, or %NULL * - * 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 the array of file descriptors that is contained in this + * object. * - * Returns: whether the same or not - * Since: 2.34 + * After this call, the descriptors are no longer contained in + * @list. Further calls will return an empty list (unless more + * descriptors have been added). + * + * The return result of this function must be freed with g_free(). + * The caller is also responsible for closing all of the file + * descriptors. The file descriptors in the array are set to + * close-on-exec. + * + * If @length is non-%NULL then it is set to the number of file + * descriptors in the returned array. The returned array is also + * terminated with -1. + * + * This function never returns %NULL. In case there are no file + * descriptors contained in @list, an empty array is returned. + * + * Returns: (array length=length) (transfer full): an array of file + * descriptors + * Since: 2.24 */ /** - * g_tls_certificate_list_new_from_file: - * @file: (type filename): file containing PEM-encoded certificates to import - * @error: #GError for error reporting, or %NULL to ignore. + * g_unix_fd_message_append_fd: + * @message: a #GUnixFDMessage + * @fd: a valid open file descriptor + * @error: a #GError pointer * - * 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. + * Adds a file descriptor to @message. * - * Returns: (element-type Gio.TlsCertificate) (transfer full): a - * #GList containing #GTlsCertificate objects. You must free the list - * and its contents when you are done with it. - * Since: 2.28 + * The file descriptor is duplicated using dup(). You keep your copy + * of the descriptor and the copy contained in @message will be closed + * when @message is finalized. + * + * A possible cause of failure is exceeding the per-process or + * system-wide file descriptor limit. + * + * Returns: %TRUE in case of success, else %FALSE (and @error is set) + * Since: 2.22 */ /** - * g_tls_certificate_new_from_file: - * @file: (type filename): 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. 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. + * g_unix_fd_message_get_fd_list: + * @message: a #GUnixFDMessage * - * 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(). + * Gets the #GUnixFDList contained in @message. This function does not + * return a reference to the caller, but the returned list is valid for + * the lifetime of @message. * - * Returns: the new certificate, or %NULL on error - * Since: 2.28 + * Returns: (transfer none): the #GUnixFDList from @message + * Since: 2.24 */ /** - * g_tls_certificate_new_from_files: - * @cert_file: (type filename): file containing one or more PEM-encoded - * certificates to import - * @key_file: (type filename): 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. 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. + * g_unix_fd_message_new: * - * 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(). + * Creates a new #GUnixFDMessage containing an empty file descriptor + * list. * - * Returns: the new certificate, or %NULL on error - * Since: 2.28 + * Returns: a new #GUnixFDMessage + * Since: 2.22 */ /** - * g_tls_certificate_new_from_pem: - * @data: PEM-encoded certificate data - * @length: the length of @data, or -1 if it's 0-terminated. - * @error: #GError for error reporting, or %NULL to ignore. - * - * 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.) + * g_unix_fd_message_new_with_fd_list: + * @fd_list: a #GUnixFDList * - * 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. + * Creates a new #GUnixFDMessage containing @list. * - * Returns: the new certificate, or %NULL if @data is invalid - * Since: 2.28 + * Returns: a new #GUnixFDMessage + * Since: 2.24 */ /** - * g_tls_certificate_verify: - * @cert: a #GTlsCertificate - * @identity: (nullable): the expected peer identity - * @trusted_ca: (nullable): the certificate of a trusted authority + * g_unix_fd_message_steal_fds: + * @message: a #GUnixFDMessage + * @length: (out) (optional): pointer to the length of the returned + * array, or %NULL * - * This verifies @cert and returns a set of #GTlsCertificateFlags - * indicating any problems found with it. This can be used to verify a - * certificate outside the context of making a connection, or to - * check a certificate against a CA that is not part of the system - * CA database. + * Returns the array of file descriptors that is contained in this + * object. * - * If @identity is not %NULL, @cert's name(s) will be compared against - * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return - * value if it does not match. If @identity is %NULL, that bit will - * never be set in the return value. + * After this call, the descriptors are no longer contained in + * @message. Further calls will return an empty list (unless more + * descriptors have been added). * - * If @trusted_ca is not %NULL, then @cert (or one of the certificates - * in its chain) must be signed by it, or else - * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If - * @trusted_ca is %NULL, that bit will never be set in the return - * value. + * The return result of this function must be freed with g_free(). + * The caller is also responsible for closing all of the file + * descriptors. + * + * If @length is non-%NULL then it is set to the number of file + * descriptors in the returned array. The returned array is also + * terminated with -1. * - * (All other #GTlsCertificateFlags values will always be set or unset - * as appropriate.) + * This function never returns %NULL. In case there are no file + * descriptors contained in @message, an empty array is returned. * - * Returns: the appropriate #GTlsCertificateFlags - * Since: 2.28 + * Returns: (array length=length) (transfer full): an array of file + * descriptors + * Since: 2.22 */ /** - * g_tls_client_connection_copy_session_state: - * @conn: a #GTlsClientConnection - * @source: a #GTlsClientConnection + * g_unix_input_stream_get_close_fd: + * @stream: a #GUnixInputStream * - * Copies session state from one connection to another. This is - * not normally needed, but may be used when the same session - * needs to be used between different endpoints as is required - * by some protocols such as FTP over TLS. @source should have - * already completed a handshake, and @conn should not have - * completed a handshake. + * Returns whether the file descriptor of @stream will be + * closed when the stream is closed. * - * Since: 2.46 + * Returns: %TRUE if the file descriptor is closed when done + * Since: 2.20 */ /** - * g_tls_client_connection_get_accepted_cas: - * @conn: the #GTlsClientConnection - * - * Gets the list of distinguished names of the Certificate Authorities - * that the server will accept certificates from. This will be set - * during the TLS handshake if the server requests a certificate. - * Otherwise, it will be %NULL. + * g_unix_input_stream_get_fd: + * @stream: a #GUnixInputStream * - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. + * Return the UNIX file descriptor that the stream reads from. * - * Returns: (element-type GByteArray) (transfer full): the list of - * CA DNs. You should unref each element with g_byte_array_unref() and then - * the free the list with g_list_free(). - * Since: 2.28 + * Returns: The file descriptor of @stream + * Since: 2.20 */ /** - * g_tls_client_connection_get_server_identity: - * @conn: the #GTlsClientConnection + * g_unix_input_stream_new: + * @fd: a UNIX file descriptor + * @close_fd: %TRUE to close the file descriptor when done * - * Gets @conn's expected server identity + * Creates a new #GUnixInputStream for the given @fd. * - * Returns: (transfer none): a #GSocketConnectable describing the - * expected server identity, or %NULL if the expected identity is not - * known. - * Since: 2.28 + * If @close_fd is %TRUE, the file descriptor will be closed + * when the stream is closed. + * + * Returns: a new #GUnixInputStream */ /** - * g_tls_client_connection_get_use_ssl3: - * @conn: the #GTlsClientConnection + * g_unix_input_stream_set_close_fd: + * @stream: a #GUnixInputStream + * @close_fd: %TRUE to close the file descriptor when done * - * Gets whether @conn will force the lowest-supported TLS protocol - * version rather than attempt to negotiate the highest mutually- - * supported version of TLS; see g_tls_client_connection_set_use_ssl3(). + * Sets whether the file descriptor of @stream shall be closed + * when the stream is closed. * - * Returns: whether @conn will use the lowest-supported TLS protocol version - * Since: 2.28 - * Deprecated: 2.56: SSL 3.0 is insecure, and this function does not - * actually indicate whether it is enabled. + * Since: 2.20 */ /** - * g_tls_client_connection_get_validation_flags: - * @conn: the #GTlsClientConnection + * g_unix_is_mount_path_system_internal: + * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr` * - * Gets @conn's validation flags + * Determines if @mount_path is considered an implementation of the + * OS. This is primarily used for hiding mountable and mounted volumes + * that only are used in the OS and has little to no relevance to the + * casual user. * - * Returns: the validation flags - * Since: 2.28 + * Returns: %TRUE if @mount_path is considered an implementation detail + * of the OS. */ /** - * g_tls_client_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @server_identity: (nullable): the expected identity of the server - * @error: #GError for error reporting, or %NULL to ignore. + * g_unix_is_system_device_path: + * @device_path: a device path, e.g. `/dev/loop0` or `nfsd` * - * Creates a new #GTlsClientConnection wrapping @base_io_stream (which - * must have pollable input and output streams) which is assumed to - * communicate with the server identified by @server_identity. + * Determines if @device_path is considered a block device path which is only + * used in implementation of the OS. This is primarily used for hiding + * mounted volumes that are intended as APIs for programs to read, and system + * administrators at a shell; rather than something that should, for example, + * appear in a GUI. For example, the Linux `/proc` filesystem. * - * See the documentation for #GTlsConnection:base-io-stream for restrictions - * on when application code can run operations on the @base_io_stream after - * this function has returned. + * The list of device paths considered ‘system’ ones may change over time. * - * Returns: (transfer full) (type GTlsClientConnection): the new - * #GTlsClientConnection, or %NULL on error - * Since: 2.28 + * Returns: %TRUE if @device_path is considered an implementation detail of + * the OS. + * Since: 2.56 */ /** - * g_tls_client_connection_set_server_identity: - * @conn: the #GTlsClientConnection - * @identity: a #GSocketConnectable describing the expected server identity + * g_unix_is_system_fs_type: + * @fs_type: a file system type, e.g. `procfs` or `tmpfs` * - * Sets @conn's expected server identity, which is used both to tell - * servers on virtual hosts which certificate to present, and also - * to let @conn know what name to look for in the certificate when - * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. + * Determines if @fs_type is considered a type of file system which is only + * used in implementation of the OS. This is primarily used for hiding + * mounted volumes that are intended as APIs for programs to read, and system + * administrators at a shell; rather than something that should, for example, + * appear in a GUI. For example, the Linux `/proc` filesystem. * - * Since: 2.28 + * The list of file system types considered ‘system’ ones may change over time. + * + * Returns: %TRUE if @fs_type is considered an implementation detail of the OS. + * Since: 2.56 */ /** - * g_tls_client_connection_set_use_ssl3: - * @conn: the #GTlsClientConnection - * @use_ssl3: whether to use the lowest-supported protocol version - * - * If @use_ssl3 is %TRUE, this forces @conn to use the lowest-supported - * TLS protocol version rather than trying to properly negotiate the - * highest mutually-supported protocol version with the peer. This can - * be used when talking to broken TLS servers that exhibit protocol - * version intolerance. + * g_unix_mount_at: + * @mount_path: (type filename): path for a possible unix mount. + * @time_read: (out) (optional): guint64 to contain a timestamp. * - * Be aware that SSL 3.0 is generally disabled by the #GTlsBackend, so - * the lowest-supported protocol version is probably not SSL 3.0. + * Gets a #GUnixMountEntry for a given mount path. If @time_read + * is set, it will be filled with a unix timestamp for checking + * if the mounts have changed since with g_unix_mounts_changed_since(). * - * Since: 2.28 - * Deprecated: 2.56: SSL 3.0 is insecure, and this function does not - * generally enable or disable it, despite its name. + * Returns: (transfer full): a #GUnixMountEntry. */ /** - * g_tls_client_connection_set_validation_flags: - * @conn: the #GTlsClientConnection - * @flags: the #GTlsCertificateFlags to use + * g_unix_mount_compare: + * @mount1: first #GUnixMountEntry to compare. + * @mount2: second #GUnixMountEntry to compare. * - * Sets @conn's validation flags, to override the default set of - * checks performed when validating a server certificate. By default, - * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. + * Compares two unix mounts. * - * Since: 2.28 + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ /** - * g_tls_connection_emit_accept_certificate: - * @conn: a #GTlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert + * g_unix_mount_copy: + * @mount_entry: a #GUnixMountEntry. * - * Used by #GTlsConnection implementations to emit the - * #GTlsConnection::accept-certificate signal. + * Makes a copy of @mount_entry. * - * Returns: %TRUE if one of the signal handlers has returned - * %TRUE to accept @peer_cert - * Since: 2.28 + * Returns: (transfer full): a new #GUnixMountEntry + * Since: 2.54 */ /** - * g_tls_connection_get_certificate: - * @conn: a #GTlsConnection + * g_unix_mount_for: + * @file_path: (type filename): file path on some unix mount. + * @time_read: (out) (optional): guint64 to contain a timestamp. * - * Gets @conn's certificate, as set by - * g_tls_connection_set_certificate(). + * Gets a #GUnixMountEntry for a given file path. If @time_read + * is set, it will be filled with a unix timestamp for checking + * if the mounts have changed since with g_unix_mounts_changed_since(). * - * Returns: (transfer none): @conn's certificate, or %NULL - * Since: 2.28 + * Returns: (transfer full): a #GUnixMountEntry. + * Since: 2.52 */ /** - * g_tls_connection_get_database: - * @conn: a #GTlsConnection - * - * Gets the certificate database that @conn uses to verify - * peer certificates. See g_tls_connection_set_database(). + * g_unix_mount_free: + * @mount_entry: a #GUnixMountEntry. * - * Returns: (transfer none): the certificate database that @conn uses or %NULL - * Since: 2.30 + * Frees a unix mount. */ /** - * g_tls_connection_get_interaction: - * @conn: a connection + * g_unix_mount_get_device_path: + * @mount_entry: a #GUnixMount. * - * Get the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. If %NULL is returned, then - * no user interaction will occur for this connection. + * Gets the device path for a unix mount. * - * Returns: (transfer none): The interaction object. - * Since: 2.30 + * Returns: (type filename): a string containing the device path. */ /** - * g_tls_connection_get_peer_certificate: - * @conn: a #GTlsConnection + * g_unix_mount_get_fs_type: + * @mount_entry: a #GUnixMount. * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of - * #GTlsConnection::accept-certificate.) + * Gets the filesystem type for the unix mount. * - * Returns: (transfer none): @conn's peer's certificate, or %NULL - * Since: 2.28 + * Returns: a string containing the file system type. */ /** - * g_tls_connection_get_peer_certificate_errors: - * @conn: a #GTlsConnection + * g_unix_mount_get_mount_path: + * @mount_entry: input #GUnixMountEntry to get the mount path for. * - * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GTlsConnection::accept-certificate.) + * Gets the mount path for a unix mount. * - * Returns: @conn's peer's certificate errors - * Since: 2.28 + * Returns: (type filename): the mount path for @mount_entry. */ /** - * g_tls_connection_get_rehandshake_mode: - * @conn: a #GTlsConnection + * g_unix_mount_guess_can_eject: + * @mount_entry: a #GUnixMountEntry * - * Gets @conn rehandshaking mode. See - * g_tls_connection_set_rehandshake_mode() for details. + * Guesses whether a Unix mount can be ejected. * - * Returns: @conn's rehandshaking mode - * Since: 2.28 + * Returns: %TRUE if @mount_entry is deemed to be ejectable. */ /** - * g_tls_connection_get_require_close_notify: - * @conn: a #GTlsConnection + * g_unix_mount_guess_icon: + * @mount_entry: a #GUnixMountEntry * - * Tests whether or not @conn expects a proper TLS close notification - * when the connection is closed. See - * g_tls_connection_set_require_close_notify() for details. + * Guesses the icon of a Unix mount. * - * Returns: %TRUE if @conn requires a proper TLS close - * notification. - * Since: 2.28 + * Returns: (transfer full): a #GIcon */ /** - * g_tls_connection_get_use_system_certdb: - * @conn: a #GTlsConnection + * g_unix_mount_guess_name: + * @mount_entry: a #GUnixMountEntry * - * Gets whether @conn uses the system certificate database to verify - * peer certificates. See g_tls_connection_set_use_system_certdb(). + * Guesses the name of a Unix mount. + * The result is a translated string. * - * Returns: whether @conn uses the system certificate database - * Deprecated: 2.30: Use g_tls_connection_get_database() instead + * Returns: A newly allocated string that must + * be freed with g_free() */ /** - * g_tls_connection_handshake: - * @conn: a #GTlsConnection - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Attempts a TLS handshake on @conn. - * - * On the client side, it is never necessary to call this method; - * although the connection needs to perform a handshake after - * connecting (or after sending a "STARTTLS"-type command) and may - * need to rehandshake later if the server requests it, - * #GTlsConnection will handle this for you automatically when you try - * to send or receive data on the connection. However, you can call - * g_tls_connection_handshake() manually if you want to know for sure - * whether the initial handshake succeeded or failed (as opposed to - * just immediately trying to write to @conn's output stream, in which - * case if it fails, it may not be possible to tell if it failed - * before or after completing the handshake). - * - * Likewise, on the server side, although a handshake is necessary at - * the beginning of the communication, you do not need to call this - * function explicitly unless you want clearer error reporting. - * However, you may call g_tls_connection_handshake() later on to - * renegotiate parameters (encryption methods, etc) with the client. + * g_unix_mount_guess_should_display: + * @mount_entry: a #GUnixMountEntry * - * #GTlsConnection::accept_certificate may be emitted during the - * handshake. + * Guesses whether a Unix mount should be displayed in the UI. * - * Returns: success or failure - * Since: 2.28 + * Returns: %TRUE if @mount_entry is deemed to be displayable. */ /** - * g_tls_connection_handshake_async: - * @conn: a #GTlsConnection - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the handshake is complete - * @user_data: the data to pass to the callback function + * g_unix_mount_guess_symbolic_icon: + * @mount_entry: a #GUnixMountEntry * - * Asynchronously performs a TLS handshake on @conn. See - * g_tls_connection_handshake() for more information. + * Guesses the symbolic icon of a Unix mount. * - * Since: 2.28 + * Returns: (transfer full): a #GIcon + * Since: 2.34 */ /** - * g_tls_connection_handshake_finish: - * @conn: a #GTlsConnection - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL + * g_unix_mount_guess_type: + * @mount_entry: a #GUnixMount. * - * Finish an asynchronous TLS handshake operation. See - * g_tls_connection_handshake() for more information. + * Guesses the type of a unix mount. If the mount type cannot be + * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set. - * Since: 2.28 + * Returns: a #GUnixMountType. */ /** - * g_tls_connection_set_certificate: - * @conn: a #GTlsConnection - * @certificate: the certificate to use for @conn - * - * This sets the certificate that @conn will present to its peer - * during the TLS handshake. For a #GTlsServerConnection, it is - * mandatory to set this, and that will normally be done at construct - * time. - * - * For a #GTlsClientConnection, this is optional. If a handshake fails - * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server - * requires a certificate, and if you try connecting again, you should - * call this method first. You can call - * g_tls_client_connection_get_accepted_cas() on the failed connection - * to get a list of Certificate Authorities that the server will - * accept certificates from. + * g_unix_mount_is_readonly: + * @mount_entry: a #GUnixMount. * - * (It is also possible that a server will allow the connection with - * or without a certificate; in that case, if you don't provide a - * certificate, you can tell that the server requested one by the fact - * that g_tls_client_connection_get_accepted_cas() will return - * non-%NULL.) + * Checks if a unix mount is mounted read only. * - * Since: 2.28 + * Returns: %TRUE if @mount_entry is read only. */ /** - * g_tls_connection_set_database: - * @conn: a #GTlsConnection - * @database: a #GTlsDatabase + * g_unix_mount_is_system_internal: + * @mount_entry: a #GUnixMount. * - * Sets the certificate database that is used to verify peer certificates. - * This is set to the default database by default. See - * g_tls_backend_get_default_database(). If set to %NULL, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GTlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GTlsClientConnection:validation-flags). + * Checks if a Unix mount is a system mount. This is the Boolean OR of + * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and + * g_unix_is_mount_path_system_internal() on @mount_entry’s properties. * - * Since: 2.30 + * The definition of what a ‘system’ mount entry is may change over time as new + * file system types and device paths are ignored. + * + * Returns: %TRUE if the unix mount is for a system path. */ /** - * g_tls_connection_set_interaction: - * @conn: a connection - * @interaction: (nullable): an interaction object, or %NULL + * g_unix_mount_monitor_get: * - * Set the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. + * Gets the #GUnixMountMonitor for the current thread-default main + * context. * - * The @interaction argument will normally be a derived subclass of - * #GTlsInteraction. %NULL can also be provided if no user interaction - * should occur for this connection. + * 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). * - * Since: 2.30 + * 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_tls_connection_set_rehandshake_mode: - * @conn: a #GTlsConnection - * @mode: the rehandshaking mode - * - * Sets how @conn behaves with respect to rehandshaking requests. - * - * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to - * rehandshake after the initial handshake is complete. (For a client, - * this means it will refuse rehandshake requests from the server, and - * for a server, this means it will close the connection with an error - * if the client attempts to rehandshake.) + * g_unix_mount_monitor_new: * - * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a - * rehandshake only if the other end of the connection supports the - * 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. + * Deprecated alias for g_unix_mount_monitor_get(). * - * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow - * 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. + * This function was never a true constructor, which is why it was + * renamed. * - * Since: 2.28 + * Returns: a #GUnixMountMonitor. + * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead. */ /** - * g_tls_connection_set_require_close_notify: - * @conn: a #GTlsConnection - * @require_close_notify: whether or not to require close notification - * - * Sets whether or not @conn expects a proper TLS close notification - * before the connection is closed. If this is %TRUE (the default), - * then @conn will expect to receive a TLS close notification from its - * peer before the connection is closed, and will return a - * %G_TLS_ERROR_EOF error if the connection is closed without proper - * notification (since this may indicate a network error, or - * man-in-the-middle attack). + * g_unix_mount_monitor_set_rate_limit: + * @mount_monitor: a #GUnixMountMonitor + * @limit_msec: a integer with the limit in milliseconds to + * poll for changes. * - * In some protocols, the application will know whether or not the - * connection was closed cleanly based on application-level data - * (because the application-level data includes a length field, or is - * somehow self-delimiting); in this case, the close notify is - * redundant and sometimes omitted. (TLS 1.1 explicitly allows this; - * in TLS 1.0 it is technically an error, but often done anyway.) You - * can use g_tls_connection_set_require_close_notify() to tell @conn - * to allow an "unannounced" connection close, in which case the close - * will show up as a 0-length read, as in a non-TLS - * #GSocketConnection, and it is up to the application to check that - * the data has been fully received. + * This function does nothing. * - * Note that this only affects the behavior when the peer closes the - * connection; when the application calls g_io_stream_close() itself - * on @conn, this will send a close notification regardless of the - * setting of this property. If you explicitly want to do an unclean - * close, you can close @conn's #GTlsConnection:base-io-stream rather - * than closing @conn itself, but note that this may only be done when no other - * operations are pending on @conn or the base I/O stream. + * 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.28 + * Since: 2.18 + * Deprecated: 2.44: This function does nothing. Don't call it. */ /** - * g_tls_connection_set_use_system_certdb: - * @conn: a #GTlsConnection - * @use_system_certdb: whether to use the system certificate database + * g_unix_mount_point_compare: + * @mount1: a #GUnixMount. + * @mount2: a #GUnixMount. * - * Sets whether @conn uses the system certificate database to verify - * peer certificates. This is %TRUE by default. If set to %FALSE, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GTlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GTlsClientConnection:validation-flags). + * Compares two unix mount points. * - * Deprecated: 2.30: Use g_tls_connection_set_database() instead + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ /** - * g_tls_database_create_certificate_handle: - * @self: a #GTlsDatabase - * @certificate: certificate for which to create a handle. - * - * Create a handle string for the certificate. The database will only be able - * to create a handle for certificates that originate from the database. In - * cases where the database cannot create a handle for a certificate, %NULL - * will be returned. + * g_unix_mount_point_copy: + * @mount_point: a #GUnixMountPoint. * - * This handle should be stable across various instances of the application, - * 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. + * Makes a copy of @mount_point. * - * Returns: (nullable): a newly allocated string containing the - * handle. - * Since: 2.30 + * Returns: (transfer full): a new #GUnixMountPoint + * Since: 2.54 */ /** - * g_tls_database_lookup_certificate_for_handle: - * @self: a #GTlsDatabase - * @handle: a certificate handle - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL - * - * Lookup a certificate by its handle. - * - * 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. + * g_unix_mount_point_free: + * @mount_point: unix mount point to free. * - * If the handle is no longer valid, or does not point to a certificate in - * this database, then %NULL will be returned. + * Frees a unix mount point. + */ + + +/** + * g_unix_mount_point_get_device_path: + * @mount_point: a #GUnixMountPoint. * - * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform - * the lookup operation asynchronously. + * Gets the device path for a unix mount point. * - * Returns: (transfer full) (nullable): a newly allocated - * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. - * Since: 2.30 + * Returns: (type filename): a string containing the device path. */ /** - * g_tls_database_lookup_certificate_for_handle_async: - * @self: a #GTlsDatabase - * @handle: a certificate handle - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function + * g_unix_mount_point_get_fs_type: + * @mount_point: a #GUnixMountPoint. * - * Asynchronously lookup a certificate by its handle in the database. See - * g_tls_database_lookup_certificate_for_handle() for more information. + * Gets the file system type for the mount point. * - * Since: 2.30 + * Returns: a string containing the file system type. */ /** - * g_tls_database_lookup_certificate_for_handle_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous lookup of a certificate by its handle. See - * g_tls_database_lookup_certificate_by_handle() for more information. + * g_unix_mount_point_get_mount_path: + * @mount_point: a #GUnixMountPoint. * - * If the handle is no longer valid, or does not point to a certificate in - * this database, then %NULL will be returned. + * Gets the mount path for a unix mount point. * - * Returns: (transfer full): a newly allocated #GTlsCertificate object. - * Use g_object_unref() to release the certificate. - * Since: 2.30 + * Returns: (type filename): a string containing the mount path. */ /** - * g_tls_database_lookup_certificate_issuer: - * @self: a #GTlsDatabase - * @certificate: a #GTlsCertificate - * @interaction: (nullable): used to interact with the user if necessary - * @flags: flags which affect the lookup operation - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL + * g_unix_mount_point_get_options: + * @mount_point: a #GUnixMountPoint. * - * Lookup the issuer of @certificate in the database. + * Gets the options for the mount point. * - * The %issuer property - * of @certificate is not modified, and the two certificates are not hooked - * into a chain. + * Returns: a string containing the options. + * Since: 2.32 + */ + + +/** + * g_unix_mount_point_guess_can_eject: + * @mount_point: a #GUnixMountPoint * - * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform - * the lookup operation asynchronously. + * Guesses whether a Unix mount point can be ejected. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, - * or %NULL. Use g_object_unref() to release the certificate. - * Since: 2.30 + * Returns: %TRUE if @mount_point is deemed to be ejectable. */ /** - * g_tls_database_lookup_certificate_issuer_async: - * @self: a #GTlsDatabase - * @certificate: a #GTlsCertificate - * @interaction: (nullable): used to interact with the user if necessary - * @flags: flags which affect the lookup operation - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function + * g_unix_mount_point_guess_icon: + * @mount_point: a #GUnixMountPoint * - * Asynchronously lookup the issuer of @certificate in the database. See - * g_tls_database_lookup_certificate_issuer() for more information. + * Guesses the icon of a Unix mount point. * - * Since: 2.30 + * Returns: (transfer full): a #GIcon */ /** - * g_tls_database_lookup_certificate_issuer_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL + * g_unix_mount_point_guess_name: + * @mount_point: a #GUnixMountPoint * - * Finish an asynchronous lookup issuer operation. See - * g_tls_database_lookup_certificate_issuer() for more information. + * Guesses the name of a Unix mount point. + * The result is a translated string. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, - * or %NULL. Use g_object_unref() to release the certificate. - * Since: 2.30 + * Returns: A newly allocated string that must + * be freed with g_free() */ /** - * g_tls_database_lookup_certificates_issued_by: - * @self: a #GTlsDatabase - * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN. - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup operation. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL - * - * Lookup certificates issued by this issuer in the database. + * g_unix_mount_point_guess_symbolic_icon: + * @mount_point: a #GUnixMountPoint * - * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform - * the lookup operation asynchronously. + * Guesses the symbolic icon of a Unix mount point. * - * 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 + * Returns: (transfer full): a #GIcon + * Since: 2.34 */ /** - * g_tls_database_lookup_certificates_issued_by_async: - * @self: a #GTlsDatabase - * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN. - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup operation. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function - * - * Asynchronously lookup certificates issued by this issuer in the database. See - * g_tls_database_lookup_certificates_issued_by() for more information. + * g_unix_mount_point_guess_type: + * @mount_point: a #GUnixMountPoint. * - * The database may choose to hold a reference to the issuer byte array for the duration - * of of this asynchronous operation. The byte array should not be modified during - * this time. + * Guesses the type of a unix mount point. + * If the mount type cannot be determined, + * returns %G_UNIX_MOUNT_TYPE_UNKNOWN. * - * Since: 2.30 + * Returns: a #GUnixMountType. */ /** - * g_tls_database_lookup_certificates_issued_by_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL + * g_unix_mount_point_is_loopback: + * @mount_point: a #GUnixMountPoint. * - * Finish an asynchronous lookup of certificates. See - * g_tls_database_lookup_certificates_issued_by() for more information. + * Checks if a unix mount point is a loopback device. * - * 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 + * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. */ /** - * g_tls_database_verify_chain: - * @self: a #GTlsDatabase - * @chain: a #GTlsCertificate chain - * @purpose: the purpose that this certificate chain will be used for. - * @identity: (nullable): the expected peer identity - * @interaction: (nullable): used to interact with the user if necessary - * @flags: additional verify flags - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL + * g_unix_mount_point_is_readonly: + * @mount_point: a #GUnixMountPoint. * - * Determines the validity of a certificate chain after looking up and - * adding any missing certificates to the chain. + * Checks if a unix mount point is read only. * - * @chain is a chain of #GTlsCertificate objects each pointing to the next - * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially - * consist of one or more certificates. After the verification process is - * complete, @chain may be modified by adding missing certificates, or removing - * extra certificates. If a certificate anchor was found, then it is added to - * the @chain. + * Returns: %TRUE if a mount point is read only. + */ + + +/** + * g_unix_mount_point_is_user_mountable: + * @mount_point: a #GUnixMountPoint. * - * @purpose describes the purpose (or usage) for which the certificate - * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER - * which means that the certificate is being used to authenticate a server - * (and we are acting as the client). + * Checks if a unix mount point is mountable by the user. * - * The @identity is used to check for pinned certificates (trust exceptions) - * in the database. These will override the normal verification process on a - * host by host basis. + * Returns: %TRUE if the mount point is user mountable. + */ + + +/** + * g_unix_mount_points_changed_since: + * @time: guint64 to contain a timestamp. * - * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be - * used. + * Checks if the unix mount points have changed since a given unix time. * - * If @chain is found to be valid, then the return value will be 0. If - * @chain is found to be invalid, then the return value will indicate - * the problems found. If the function is unable to determine whether - * @chain is valid or not (eg, because @cancellable is triggered - * before it completes) then the return value will be - * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set - * accordingly. @error is not set when @chain is successfully analyzed - * but found to be invalid. + * Returns: %TRUE if the mount points have changed since @time. + */ + + +/** + * g_unix_mount_points_get: + * @time_read: (out) (optional): guint64 to contain a timestamp. * - * This function can block, use g_tls_database_verify_chain_async() to perform - * the verification operation asynchronously. + * Gets a #GList of #GUnixMountPoint containing the unix mount points. + * If @time_read is set, it will be filled with the mount timestamp, + * allowing for checking if the mounts have changed with + * g_unix_mount_points_changed_since(). * - * Returns: the appropriate #GTlsCertificateFlags which represents the - * result of verification. - * Since: 2.30 + * Returns: (element-type GUnixMountPoint) (transfer full): + * a #GList of the UNIX mountpoints. */ /** - * g_tls_database_verify_chain_async: - * @self: a #GTlsDatabase - * @chain: a #GTlsCertificate chain - * @purpose: the purpose that this certificate chain will be used for. - * @identity: (nullable): the expected peer identity - * @interaction: (nullable): used to interact with the user if necessary - * @flags: additional verify flags - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function + * g_unix_mounts_changed_since: + * @time: guint64 to contain a timestamp. * - * Asynchronously determines the validity of a certificate chain after - * looking up and adding any missing certificates to the chain. See - * g_tls_database_verify_chain() for more information. + * Checks if the unix mounts have changed since a given unix time. * - * Since: 2.30 + * Returns: %TRUE if the mounts have changed since @time. */ /** - * g_tls_database_verify_chain_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous verify chain operation. See - * g_tls_database_verify_chain() for more information. + * g_unix_mounts_get: + * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL * - * If @chain is found to be valid, then the return value will be 0. If - * @chain is found to be invalid, then the return value will indicate - * the problems found. If the function is unable to determine whether - * @chain is valid or not (eg, because @cancellable is triggered - * before it completes) then the return value will be - * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set - * accordingly. @error is not set when @chain is successfully analyzed - * but found to be invalid. + * Gets a #GList of #GUnixMountEntry containing the unix mounts. + * If @time_read is set, it will be filled with the mount + * timestamp, allowing for checking if the mounts have changed + * with g_unix_mounts_changed_since(). * - * Returns: the appropriate #GTlsCertificateFlags which represents the - * result of verification. - * Since: 2.30 + * Returns: (element-type GUnixMountEntry) (transfer full): + * a #GList of the UNIX mounts. */ /** - * g_tls_error_quark: + * g_unix_output_stream_get_close_fd: + * @stream: a #GUnixOutputStream * - * Gets the TLS error quark. + * Returns whether the file descriptor of @stream will be + * closed when the stream is closed. * - * Returns: a #GQuark. - * Since: 2.28 + * Returns: %TRUE if the file descriptor is closed when done + * Since: 2.20 */ /** - * g_tls_file_database_new: - * @anchors: (type filename): filename of anchor certificate authorities. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GTlsFileDatabase which uses anchor certificate authorities - * in @anchors to verify certificate chains. + * g_unix_output_stream_get_fd: + * @stream: a #GUnixOutputStream * - * The certificates in @anchors must be PEM encoded. + * Return the UNIX file descriptor that the stream writes to. * - * Returns: (transfer full) (type GTlsFileDatabase): the new - * #GTlsFileDatabase, or %NULL on error - * Since: 2.30 + * Returns: The file descriptor of @stream + * Since: 2.20 */ /** - * g_tls_interaction_ask_password: - * @interaction: a #GTlsInteraction object - * @password: a #GTlsPassword object - * @cancellable: an optional #GCancellable cancellation object - * @error: an optional location to place an error on failure - * - * Run synchronous interaction to ask the user for a password. In general, - * g_tls_interaction_invoke_ask_password() should be used instead of this - * function. + * g_unix_output_stream_new: + * @fd: a UNIX file descriptor + * @close_fd: %TRUE to close the file descriptor when done * - * 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. + * Creates a new #GUnixOutputStream for the given @fd. * - * 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. + * If @close_fd, is %TRUE, the file descriptor will be closed when + * the output stream is destroyed. * - * Returns: The status of the ask password interaction. - * Since: 2.30 + * Returns: a new #GOutputStream */ /** - * g_tls_interaction_ask_password_async: - * @interaction: a #GTlsInteraction object - * @password: a #GTlsPassword object - * @cancellable: an optional #GCancellable cancellation object - * @callback: (nullable): will be called when the interaction completes - * @user_data: (nullable): data to pass to the @callback - * - * Run asynchronous interaction to ask the user for a password. In general, - * g_tls_interaction_invoke_ask_password() should be used instead of this - * function. + * g_unix_output_stream_set_close_fd: + * @stream: a #GUnixOutputStream + * @close_fd: %TRUE to close the file descriptor when done * - * 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. + * Sets whether the file descriptor of @stream shall be closed + * when the stream is closed. * - * 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. + * Since: 2.20 + */ + + +/** + * g_unix_socket_address_abstract_names_supported: * - * Certain implementations may not support immediate cancellation. + * Checks if abstract UNIX domain socket names are supported. * - * Since: 2.30 + * Returns: %TRUE if supported, %FALSE otherwise + * Since: 2.22 */ /** - * g_tls_interaction_ask_password_finish: - * @interaction: a #GTlsInteraction object - * @result: the result passed to the callback - * @error: an optional location to place an error on failure + * g_unix_socket_address_get_address_type: + * @address: a #GInetSocketAddress * - * Complete an ask password user interaction request. This should be once - * the g_tls_interaction_ask_password_async() completion callback is called. + * Gets @address's type. * - * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed - * to g_tls_interaction_ask_password() will have its password filled in. + * Returns: a #GUnixSocketAddressType + * Since: 2.26 + */ + + +/** + * g_unix_socket_address_get_is_abstract: + * @address: a #GInetSocketAddress * - * 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. + * Tests if @address is abstract. * - * Returns: The status of the ask password interaction. - * Since: 2.30 + * Returns: %TRUE if the address is abstract, %FALSE otherwise + * Since: 2.22 + * Deprecated: Use g_unix_socket_address_get_address_type() */ /** - * g_tls_interaction_invoke_ask_password: - * @interaction: a #GTlsInteraction object - * @password: a #GTlsPassword object - * @cancellable: an optional #GCancellable cancellation object - * @error: an optional location to place an error on failure + * g_unix_socket_address_get_path: + * @address: a #GInetSocketAddress * - * Invoke the interaction to ask the user for a password. 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 or #GTlsDatabase to ask the user - * for a password. + * Gets @address's path, or for abstract sockets the "name". * - * 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. + * Guaranteed to be zero-terminated, but an abstract socket + * may contain embedded zeros, and thus you should use + * g_unix_socket_address_get_path_len() to get the true length + * of this string. * - * 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. + * Returns: the path for @address + * Since: 2.22 + */ + + +/** + * g_unix_socket_address_get_path_len: + * @address: a #GInetSocketAddress * - * 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. + * Gets the length of @address's path. * - * Returns: The status of the ask password interaction. - * Since: 2.30 + * For details, see g_unix_socket_address_get_path(). + * + * Returns: the length of the path + * Since: 2.22 */ /** - * 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 + * g_unix_socket_address_new: + * @path: the socket path * - * 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. + * Creates a new #GUnixSocketAddress for @path. * - * 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. + * To create abstract socket addresses, on systems that support that, + * use g_unix_socket_address_new_abstract(). * - * 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. + * Returns: a new #GUnixSocketAddress + * Since: 2.22 + */ + + +/** + * g_unix_socket_address_new_abstract: + * @path: (array length=path_len) (element-type gchar): the abstract name + * @path_len: the length of @path, or -1 * - * 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. + * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED + * #GUnixSocketAddress for @path. * - * Returns: The status of the certificate request interaction. - * Since: 2.40 + * Returns: a new #GUnixSocketAddress + * Deprecated: Use g_unix_socket_address_new_with_type(). */ /** - * 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 + * g_unix_socket_address_new_with_type: + * @path: (array length=path_len) (element-type gchar): the name + * @path_len: the length of @path, or -1 + * @type: a #GUnixSocketAddressType * - * 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. + * Creates a new #GUnixSocketAddress of type @type with name @path. * - * 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 @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to + * calling g_unix_socket_address_new(). * - * 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 @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be + * ignored. * - * 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. + * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len + * bytes of @path will be copied to the socket's path, and only those + * bytes will be considered part of the name. (If @path_len is -1, + * then @path is assumed to be NUL-terminated.) For example, if @path + * was "test", then calling g_socket_address_get_native_size() on the + * returned socket would return 7 (2 bytes of overhead, 1 byte for the + * abstract-socket indicator byte, and 4 bytes for the name "test"). + * + * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then + * @path_len bytes of @path will be copied to the socket's path, the + * rest of the path will be padded with 0 bytes, and the entire + * 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 `struct sockaddr_un`, although + * g_unix_socket_address_get_path_len() will still return just the + * length of @path. + * + * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over + * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, + * when connecting to a server created by another process, you must + * use the appropriate type corresponding to how that process created + * its listening socket. * - * Returns: The status of the request certificate interaction. - * Since: 2.40 + * Returns: a new #GUnixSocketAddress + * Since: 2.26 */ /** - * 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: (nullable): will be called when the interaction completes - * @user_data: (nullable): 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. + * g_vfs_get_default: * - * 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. + * Gets the default #GVfs for the system. * - * Since: 2.40 + * Returns: (transfer none): a #GVfs. */ /** - * g_tls_interaction_request_certificate_finish: - * @interaction: a #GTlsInteraction object - * @result: the result passed to the callback - * @error: an optional location to place an error on failure - * - * Complete an request certificate user interaction request. This should be once - * the g_tls_interaction_request_certificate_async() completion callback is called. - * - * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection - * passed to g_tls_interaction_request_certificate_async() will have had its - * #GTlsConnection:certificate filled in. + * g_vfs_get_file_for_path: + * @vfs: a #GVfs. + * @path: a string containing a VFS path. * - * 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. + * Gets a #GFile for @path. * - * Returns: The status of the request certificate interaction. - * Since: 2.40 + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ /** - * g_tls_password_get_description: - * @password: a #GTlsPassword object + * g_vfs_get_file_for_uri: + * @vfs: a#GVfs. + * @uri: a string containing a URI * - * Get a description string about what the password will be used for. + * Gets a #GFile for @uri. * - * Returns: The description of the password. - * Since: 2.30 + * This operation never fails, but the returned object + * might not support any I/O operation if the URI + * is malformed or if the URI scheme is not supported. + * + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ /** - * g_tls_password_get_flags: - * @password: a #GTlsPassword object + * g_vfs_get_local: * - * Get flags about the password. + * Gets the local #GVfs for the system. * - * Returns: The flags about the password. - * Since: 2.30 + * Returns: (transfer none): a #GVfs. */ /** - * g_tls_password_get_value: - * @password: a #GTlsPassword object - * @length: (nullable): location to place the length of the password. + * g_vfs_get_supported_uri_schemes: + * @vfs: a #GVfs. * - * 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.) + * Gets a list of URI schemes supported by @vfs. * - * Returns: The password value (owned by the password object). - * Since: 2.30 + * Returns: (transfer none): a %NULL-terminated array of strings. + * The returned array belongs to GIO and must + * not be freed or modified. */ /** - * g_tls_password_get_warning: - * @password: a #GTlsPassword object + * g_vfs_is_active: + * @vfs: a #GVfs. * - * Get a user readable translated warning. Usually this warning is a - * representation of the password flags returned from - * g_tls_password_get_flags(). + * Checks if the VFS is active. * - * Returns: The warning. - * Since: 2.30 + * Returns: %TRUE if construction of the @vfs was successful + * and it is now active. */ /** - * g_tls_password_new: - * @flags: the password flags - * @description: description of what the password is for + * g_vfs_parse_name: + * @vfs: a #GVfs. + * @parse_name: a string to be parsed by the VFS module. * - * Create a new #GTlsPassword object. + * This operation never fails, but the returned object might + * not support any I/O operations if the @parse_name cannot + * be parsed by the #GVfs module. * - * Returns: (transfer full): The newly allocated password object + * Returns: (transfer full): a #GFile for the given @parse_name. + * Free the returned object with g_object_unref(). */ /** - * g_tls_password_set_description: - * @password: a #GTlsPassword object - * @description: The description of the password + * g_vfs_register_uri_scheme: + * @vfs: a #GVfs + * @scheme: an URI scheme, e.g. "http" + * @uri_func: (scope notified) (nullable): a #GVfsFileLookupFunc + * @uri_data: (nullable): custom data passed to be passed to @uri_func, or %NULL + * @uri_destroy: (nullable): function to be called when unregistering the + * URI scheme, or when @vfs is disposed, to free the resources used + * by the URI lookup function + * @parse_name_func: (scope notified) (nullable): a #GVfsFileLookupFunc + * @parse_name_data: (nullable): custom data passed to be passed to + * @parse_name_func, or %NULL + * @parse_name_destroy: (nullable): function to be called when unregistering the + * URI scheme, or when @vfs is disposed, to free the resources used + * by the parse name lookup function * - * Set a description string about what the password will be used for. + * Registers @uri_func and @parse_name_func as the #GFile URI and parse name + * lookup functions for URIs with a scheme matching @scheme. + * Note that @scheme is registered only within the running application, as + * opposed to desktop-wide as it happens with GVfs backends. * - * Since: 2.30 + * When a #GFile is requested with an URI containing @scheme (e.g. through + * g_file_new_for_uri()), @uri_func will be called to allow a custom + * constructor. The implementation of @uri_func should not be blocking, and + * must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). + * + * When g_file_parse_name() is called with a parse name obtained from such file, + * @parse_name_func will be called to allow the #GFile to be created again. In + * that case, it's responsibility of @parse_name_func to make sure the parse + * name matches what the custom #GFile implementation returned when + * g_file_get_parse_name() was previously called. The implementation of + * @parse_name_func should not be blocking, and must not call + * g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). + * + * It's an error to call this function twice with the same scheme. To unregister + * a custom URI scheme, use g_vfs_unregister_uri_scheme(). + * + * Returns: %TRUE if @scheme was successfully registered, or %FALSE if a handler + * for @scheme already exists. + * Since: 2.50 */ /** - * g_tls_password_set_flags: - * @password: a #GTlsPassword object - * @flags: The flags about the password + * g_vfs_unregister_uri_scheme: + * @vfs: a #GVfs + * @scheme: an URI scheme, e.g. "http" * - * Set flags about the password. + * Unregisters the URI handler for @scheme previously registered with + * g_vfs_register_uri_scheme(). * - * Since: 2.30 + * Returns: %TRUE if @scheme was successfully unregistered, or %FALSE if a + * handler for @scheme does not exist. + * Since: 2.50 */ /** - * g_tls_password_set_value: - * @password: a #GTlsPassword object - * @value: (array length=length): the new password value - * @length: the length of the password, or -1 - * - * Set the value for this password. The @value will be copied by the password - * object. + * g_volume_can_eject: + * @volume: a #GVolume * - * 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.) + * Checks if a volume can be ejected. * - * Since: 2.30 + * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise */ /** - * g_tls_password_set_value_full: (virtual set_value) - * @password: a #GTlsPassword object - * @value: (array length=length): the value for the password - * @length: the length of the password, or -1 - * @destroy: (nullable): a function to use to free the password. - * - * Provide the value for this password. - * - * The @value will be owned by the password object, and later freed using - * the @destroy function callback. + * g_volume_can_mount: + * @volume: a #GVolume * - * 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.) + * Checks if a volume can be mounted. * - * Since: 2.30 + * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise */ /** - * g_tls_password_set_warning: - * @password: a #GTlsPassword object - * @warning: The user readable warning + * g_volume_eject: + * @volume: a #GVolume + * @flags: flags affecting the unmount if required for eject + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL + * @user_data: user data that gets passed to @callback * - * Set a user readable translated warning. Usually this warning is a - * representation of the password flags returned from - * g_tls_password_get_flags(). + * Ejects a volume. This is an asynchronous operation, and is + * finished by calling g_volume_eject_finish() with the @volume + * and #GAsyncResult returned in the @callback. * - * Since: 2.30 + * Deprecated: 2.22: Use g_volume_eject_with_operation() instead. */ /** - * g_tls_server_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @certificate: (nullable): the default server certificate, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GTlsServerConnection wrapping @base_io_stream (which - * must have pollable input and output streams). + * g_volume_eject_finish: + * @volume: pointer to a #GVolume + * @result: a #GAsyncResult + * @error: a #GError location to store an error, or %NULL to ignore * - * See the documentation for #GTlsConnection:base-io-stream for restrictions - * on when application code can run operations on the @base_io_stream after - * this function has returned. + * 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: (transfer full) (type GTlsServerConnection): the new - * #GTlsServerConnection, or %NULL on error - * Since: 2.28 + * Returns: %TRUE, %FALSE if operation failed + * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. */ /** - * g_unix_connection_receive_credentials: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Receives credentials from the sending end of the connection. The - * sending end has to call g_unix_connection_send_credentials() (or - * similar) for this to work. - * - * As well as reading the credentials this also reads (and discards) a - * single byte from the stream, as this is required for credentials - * passing to work on some implementations. + * g_volume_eject_with_operation: + * @volume: a #GVolume + * @flags: flags affecting the unmount if required for eject + * @mount_operation: (nullable): a #GMountOperation or %NULL to + * avoid user interaction + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL + * @user_data: user data passed to @callback * - * Other ways to exchange credentials with a foreign peer includes the - * #GUnixCredentialsMessage type and g_socket_get_credentials() function. + * Ejects a volume. This is an asynchronous operation, and is + * finished by calling g_volume_eject_with_operation_finish() with the @volume + * and #GAsyncResult data returned in the @callback. * - * Returns: (transfer full): Received credentials on success (free with - * g_object_unref()), %NULL if @error is set. - * Since: 2.26 + * Since: 2.22 */ /** - * g_unix_connection_receive_credentials_async: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): 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. + * g_volume_eject_with_operation_finish: + * @volume: a #GVolume + * @result: a #GAsyncResult + * @error: a #GError location to store the error occurring, or %NULL * - * 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. + * Finishes ejecting a volume. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * Since: 2.32 + * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise + * Since: 2.22 */ /** - * g_unix_connection_receive_credentials_finish: - * @connection: A #GUnixConnection. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_volume_enumerate_identifiers: + * @volume: a #GVolume * - * Finishes an asynchronous receive credentials operation started with - * g_unix_connection_receive_credentials_async(). + * Gets the kinds of [identifiers][volume-identifier] that @volume has. + * Use g_volume_get_identifier() to obtain the identifiers themselves. * - * Returns: (transfer full): a #GCredentials, or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.32 + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array + * of strings containing kinds of identifiers. Use g_strfreev() to free. */ /** - * g_unix_connection_receive_fd: - * @connection: a #GUnixConnection - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: (nullable): #GError for error reporting, or %NULL to ignore + * g_volume_get_activation_root: + * @volume: a #GVolume * - * Receives a file descriptor from the sending end of the connection. - * The sending end has to call g_unix_connection_send_fd() for this - * to work. + * Gets the activation root for a #GVolume if it is known ahead of + * mount time. Returns %NULL otherwise. If not %NULL and if @volume + * is mounted, then the result of g_mount_get_root() on the + * #GMount object obtained from g_volume_get_mount() will always + * either be equal or a prefix of what this function returns. In + * other words, in code * - * As well as reading the fd this also reads a single byte from the - * stream, as this is required for fd passing to work on some - * implementations. + * |[ + * GMount *mount; + * GFile *mount_root + * GFile *volume_activation_root; * - * Returns: a file descriptor on success, -1 on error. - * Since: 2.22 + * 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 + * |[ + * (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. + * + * Returns: (nullable) (transfer full): the activation root of @volume + * or %NULL. Use g_object_unref() to free. + * Since: 2.18 */ /** - * g_unix_connection_send_credentials: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Passes the credentials of the current user the receiving side - * of the connection. The receiving end has to call - * g_unix_connection_receive_credentials() (or similar) to accept the - * credentials. - * - * As well as sending the credentials this also writes a single NUL - * byte to the stream, as this is required for credentials passing to - * work on some implementations. + * g_volume_get_drive: + * @volume: a #GVolume * - * Other ways to exchange credentials with a foreign peer includes the - * #GUnixCredentialsMessage type and g_socket_get_credentials() function. + * Gets the drive for the @volume. * - * Returns: %TRUE on success, %FALSE if @error is set. - * Since: 2.26 + * 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_unix_connection_send_credentials_async: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): 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. + * g_volume_get_icon: + * @volume: a #GVolume * - * 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. + * Gets the icon for @volume. * - * Since: 2.32 + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ /** - * g_unix_connection_send_credentials_finish: - * @connection: A #GUnixConnection. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_volume_get_identifier: + * @volume: a #GVolume + * @kind: the kind of identifier to return * - * Finishes an asynchronous send credentials operation started with - * g_unix_connection_send_credentials_async(). + * Gets the identifier of the given kind for @volume. + * See the [introduction][volume-identifier] for more + * information about volume identifiers. * - * Returns: %TRUE if the operation was successful, otherwise %FALSE. - * Since: 2.32 + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GVolume + * doesn't have this kind of identifier */ /** - * g_unix_connection_send_fd: - * @connection: a #GUnixConnection - * @fd: a file descriptor - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: (nullable): #GError for error reporting, or %NULL to ignore. - * - * Passes a file descriptor to the receiving side of the - * connection. The receiving end has to call g_unix_connection_receive_fd() - * to accept the file descriptor. + * g_volume_get_mount: + * @volume: a #GVolume * - * As well as sending the fd this also writes a single byte to the - * stream, as this is required for fd passing to work on some - * implementations. + * Gets the mount for the @volume. * - * Returns: a %TRUE on success, %NULL on error. - * Since: 2.22 + * 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_unix_credentials_message_get_credentials: - * @message: A #GUnixCredentialsMessage. + * g_volume_get_name: + * @volume: a #GVolume * - * Gets the credentials stored in @message. + * Gets the name of @volume. * - * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message. - * Since: 2.26 + * Returns: the name for the given @volume. The returned string should + * be freed with g_free() when no longer needed. */ /** - * g_unix_credentials_message_is_supported: + * g_volume_get_sort_key: + * @volume: a #GVolume * - * Checks if passing #GCredentials on a #GSocket is supported on this platform. + * Gets the sort key for @volume, if any. * - * Returns: %TRUE if supported, %FALSE otherwise - * Since: 2.26 + * Returns: Sorting key for @volume or %NULL if no such key is available + * Since: 2.32 */ /** - * g_unix_credentials_message_new: + * g_volume_get_symbolic_icon: + * @volume: a #GVolume * - * Creates a new #GUnixCredentialsMessage with credentials matching the current processes. + * Gets the symbolic icon for @volume. * - * Returns: a new #GUnixCredentialsMessage - * Since: 2.26 + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. + * Since: 2.34 */ /** - * g_unix_credentials_message_new_with_credentials: - * @credentials: A #GCredentials object. + * g_volume_get_uuid: + * @volume: a #GVolume * - * Creates a new #GUnixCredentialsMessage holding @credentials. + * Gets the UUID for the @volume. The reference is typically based on + * the file system UUID for the volume in question and should be + * considered an opaque string. Returns %NULL if there is no UUID + * available. * - * Returns: a new #GUnixCredentialsMessage - * Since: 2.26 + * 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. */ /** - * g_unix_fd_list_append: - * @list: a #GUnixFDList - * @fd: a valid open file descriptor - * @error: a #GError pointer + * g_volume_monitor_adopt_orphan_mount: + * @mount: a #GMount object to find a parent for * - * Adds a file descriptor to @list. + * This function should be called by any #GVolumeMonitor + * implementation when a new #GMount object is created that is not + * associated with a #GVolume object. It must be called just before + * emitting the @mount_added signal. * - * The file descriptor is duplicated using dup(). You keep your copy - * of the descriptor and the copy contained in @list will be closed - * when @list is finalized. + * If the return value is not %NULL, the caller must associate the + * returned #GVolume object with the #GMount. This involves returning + * it in its g_mount_get_volume() implementation. The caller must + * also listen for the "removed" signal on the returned object + * and give up its reference when handling that signal * - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. + * Similary, if implementing g_volume_monitor_adopt_orphan_mount(), + * the implementor must take a reference to @mount and return it in + * its g_volume_get_mount() implemented. Also, the implementor must + * listen for the "unmounted" signal on @mount and give up its + * reference upon handling that signal. * - * The index of the file descriptor in the list is returned. If you use - * this index with g_unix_fd_list_get() then you will receive back a - * duplicated copy of the same file descriptor. + * There are two main use cases for this function. * - * Returns: the index of the appended fd in case of success, else -1 - * (and @error is set) - * Since: 2.24 + * One is when implementing a user space file system driver that reads + * blocks of a block device that is already represented by the native + * volume monitor (for example a CD Audio file system driver). Such + * a driver will generate its own #GMount object that needs to be + * associated with the #GVolume object that represents the volume. + * + * The other is for implementing a #GVolumeMonitor whose sole purpose + * 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. */ /** - * g_unix_fd_list_get: - * @list: a #GUnixFDList - * @index_: the index into the list - * @error: a #GError pointer - * - * Gets a file descriptor out of @list. - * - * @index_ specifies the index of the file descriptor to get. It is a - * programmer error for @index_ to be out of range; see - * g_unix_fd_list_get_length(). - * - * The file descriptor is duplicated using dup() and set as - * close-on-exec before being returned. You must call close() on it - * when you are done. + * g_volume_monitor_get: * - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. + * Gets the volume monitor used by gio. * - * Returns: the file descriptor, or -1 in case of error - * Since: 2.24 + * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call + * g_object_unref() when done with it. */ /** - * g_unix_fd_list_get_length: - * @list: a #GUnixFDList + * g_volume_monitor_get_connected_drives: + * @volume_monitor: a #GVolumeMonitor. * - * Gets the length of @list (ie: the number of file descriptors - * contained within). + * Gets a list of drives connected to the system. * - * Returns: the length of @list - * Since: 2.24 + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). + * + * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects. */ /** - * g_unix_fd_list_new: + * g_volume_monitor_get_mount_for_uuid: + * @volume_monitor: a #GVolumeMonitor. + * @uuid: the UUID to look for * - * Creates a new #GUnixFDList containing no file descriptors. + * Finds a #GMount object by its UUID (see g_mount_get_uuid()) * - * Returns: a new #GUnixFDList - * Since: 2.24 + * Returns: (transfer full): a #GMount or %NULL if no such mount is available. + * Free the returned object with g_object_unref(). */ /** - * g_unix_fd_list_new_from_array: - * @fds: (array length=n_fds): the initial list of file descriptors - * @n_fds: the length of #fds, or -1 - * - * Creates a new #GUnixFDList containing the file descriptors given in - * @fds. The file descriptors become the property of the new list and - * may no longer be used by the caller. The array itself is owned by - * the caller. + * g_volume_monitor_get_mounts: + * @volume_monitor: a #GVolumeMonitor. * - * Each file descriptor in the array should be set to close-on-exec. + * Gets a list of the mounts on the system. * - * If @n_fds is -1 then @fds must be terminated with -1. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). * - * Returns: a new #GUnixFDList - * Since: 2.24 + * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects. */ /** - * g_unix_fd_list_peek_fds: - * @list: a #GUnixFDList - * @length: (out) (optional): pointer to the length of the returned - * array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * - * After this call, the descriptors remain the property of @list. The - * caller must not close them and must not free the array. The array is - * valid only until @list is changed in any way. - * - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. + * g_volume_monitor_get_volume_for_uuid: + * @volume_monitor: a #GVolumeMonitor. + * @uuid: the UUID to look for * - * This function never returns %NULL. In case there are no file - * descriptors contained in @list, an empty array is returned. + * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) * - * Returns: (array length=length) (transfer none): an array of file - * descriptors - * Since: 2.24 + * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. + * Free the returned object with g_object_unref(). */ /** - * g_unix_fd_list_steal_fds: - * @list: a #GUnixFDList - * @length: (out) (optional): pointer to the length of the returned - * array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * - * After this call, the descriptors are no longer contained in - * @list. Further calls will return an empty list (unless more - * descriptors have been added). - * - * The return result of this function must be freed with g_free(). - * The caller is also responsible for closing all of the file - * descriptors. The file descriptors in the array are set to - * close-on-exec. + * g_volume_monitor_get_volumes: + * @volume_monitor: a #GVolumeMonitor. * - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. + * Gets a list of the volumes on the system. * - * This function never returns %NULL. In case there are no file - * descriptors contained in @list, an empty array is returned. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). * - * Returns: (array length=length) (transfer full): an array of file - * descriptors - * Since: 2.24 + * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects. */ /** - * g_unix_fd_message_append_fd: - * @message: a #GUnixFDMessage - * @fd: a valid open file descriptor - * @error: a #GError pointer + * g_volume_mount: (virtual mount_fn) + * @volume: a #GVolume + * @flags: flags affecting the operation + * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid user interaction + * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore + * @callback: (nullable): a #GAsyncReadyCallback, or %NULL + * @user_data: user data that gets passed to @callback * - * Adds a file descriptor to @message. + * 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. + */ + + +/** + * g_volume_mount_finish: + * @volume: a #GVolume + * @result: a #GAsyncResult + * @error: a #GError location to store an error, or %NULL to ignore * - * The file descriptor is duplicated using dup(). You keep your copy - * of the descriptor and the copy contained in @message will be closed - * when @message is finalized. + * Finishes mounting a volume. If any errors occurred during the operation, + * @error will be set to contain the errors and %FALSE will be returned. * - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. + * If the mount operation succeeded, g_volume_get_mount() on @volume + * is guaranteed to return the mount right after calling this + * function; there's no need to listen for the 'mount-added' signal on + * #GVolumeMonitor. * - * Returns: %TRUE in case of success, else %FALSE (and @error is set) - * Since: 2.22 + * Returns: %TRUE, %FALSE if operation failed */ /** - * g_unix_fd_message_get_fd_list: - * @message: a #GUnixFDMessage + * g_volume_should_automount: + * @volume: a #GVolume * - * Gets the #GUnixFDList contained in @message. This function does not - * return a reference to the caller, but the returned list is valid for - * the lifetime of @message. + * Returns whether the volume should be automatically mounted. * - * Returns: (transfer none): the #GUnixFDList from @message - * Since: 2.24 + * Returns: %TRUE if the volume should be automatically mounted */ /** - * g_unix_fd_message_new: + * g_win32_input_stream_get_close_handle: + * @stream: a #GWin32InputStream * - * Creates a new #GUnixFDMessage containing an empty file descriptor - * list. + * Returns whether the handle of @stream will be + * closed when the stream is closed. * - * Returns: a new #GUnixFDMessage - * Since: 2.22 + * Returns: %TRUE if the handle is closed when done + * Since: 2.26 */ /** - * g_unix_fd_message_new_with_fd_list: - * @fd_list: a #GUnixFDList + * g_win32_input_stream_get_handle: + * @stream: a #GWin32InputStream * - * Creates a new #GUnixFDMessage containing @list. + * Return the Windows file handle that the stream reads from. * - * Returns: a new #GUnixFDMessage - * Since: 2.24 + * Returns: The file handle of @stream + * Since: 2.26 */ /** - * g_unix_fd_message_steal_fds: - * @message: a #GUnixFDMessage - * @length: (out) (optional): pointer to the length of the returned - * array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * - * After this call, the descriptors are no longer contained in - * @message. Further calls will return an empty list (unless more - * descriptors have been added). + * g_win32_input_stream_new: + * @handle: a Win32 file handle + * @close_handle: %TRUE to close the handle when done * - * The return result of this function must be freed with g_free(). - * The caller is also responsible for closing all of the file - * descriptors. + * Creates a new #GWin32InputStream for the given @handle. * - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. + * If @close_handle is %TRUE, the handle will be closed + * when the stream is closed. * - * This function never returns %NULL. In case there are no file - * descriptors contained in @message, an empty array is returned. + * Note that "handle" here means a Win32 HANDLE, not a "file descriptor" + * as used in the Windows C libraries. * - * Returns: (array length=length) (transfer full): an array of file - * descriptors - * Since: 2.22 + * Returns: a new #GWin32InputStream */ /** - * g_unix_input_stream_get_close_fd: - * @stream: a #GUnixInputStream + * g_win32_input_stream_set_close_handle: + * @stream: a #GWin32InputStream + * @close_handle: %TRUE to close the handle when done * - * Returns whether the file descriptor of @stream will be - * closed when the stream is closed. + * Sets whether the handle of @stream shall be closed + * when the stream is closed. * - * Returns: %TRUE if the file descriptor is closed when done - * Since: 2.20 + * Since: 2.26 */ /** - * g_unix_input_stream_get_fd: - * @stream: a #GUnixInputStream + * g_win32_output_stream_get_close_handle: + * @stream: a #GWin32OutputStream * - * Return the UNIX file descriptor that the stream reads from. + * Returns whether the handle of @stream will be closed when the + * stream is closed. * - * Returns: The file descriptor of @stream - * Since: 2.20 + * Returns: %TRUE if the handle is closed when done + * Since: 2.26 */ /** - * g_unix_input_stream_new: - * @fd: a UNIX file descriptor - * @close_fd: %TRUE to close the file descriptor when done - * - * Creates a new #GUnixInputStream for the given @fd. + * g_win32_output_stream_get_handle: + * @stream: a #GWin32OutputStream * - * If @close_fd is %TRUE, the file descriptor will be closed - * when the stream is closed. + * Return the Windows handle that the stream writes to. * - * Returns: a new #GUnixInputStream + * Returns: The handle descriptor of @stream + * Since: 2.26 */ /** - * g_unix_input_stream_set_close_fd: - * @stream: a #GUnixInputStream - * @close_fd: %TRUE to close the file descriptor when done + * g_win32_output_stream_new: + * @handle: a Win32 file handle + * @close_handle: %TRUE to close the handle when done * - * Sets whether the file descriptor of @stream shall be closed - * when the stream is closed. + * Creates a new #GWin32OutputStream for the given @handle. * - * Since: 2.20 + * If @close_handle, is %TRUE, the handle will be closed when the + * output stream is destroyed. + * + * Returns: a new #GOutputStream + * Since: 2.26 */ /** - * g_unix_is_mount_path_system_internal: - * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr` + * g_win32_output_stream_set_close_handle: + * @stream: a #GWin32OutputStream + * @close_handle: %TRUE to close the handle when done * - * 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. + * Sets whether the handle of @stream shall be closed when the stream + * is closed. * - * Returns: %TRUE if @mount_path is considered an implementation detail - * of the OS. + * Since: 2.26 */ /** - * g_unix_is_system_device_path: - * @device_path: a device path, e.g. `/dev/loop0` or `nfsd` + * g_win32_registry_key_erase_change_indicator: + * @key: (in) (transfer none): a #GWin32RegistryKey * - * Determines if @device_path is considered a block device path which is only - * used in implementation of the OS. This is primarily used for hiding - * mounted volumes that are intended as APIs for programs to read, and system - * administrators at a shell; rather than something that should, for example, - * appear in a GUI. For example, the Linux `/proc` filesystem. + * Erases change indicator of the @key. * - * The list of device paths considered ‘system’ ones may change over time. + * Subsequent calls to g_win32_registry_key_has_changed() will return %FALSE + * until the key is put on watch again by calling + * g_win32_registry_key_watch() again. * - * Returns: %TRUE if @device_path is considered an implementation detail of - * the OS. - * Since: 2.56 + * Since: 2.46 */ /** - * g_unix_is_system_fs_type: - * @fs_type: a file system type, e.g. `procfs` or `tmpfs` - * - * Determines if @fs_type is considered a type of file system which is only - * used in implementation of the OS. This is primarily used for hiding - * mounted volumes that are intended as APIs for programs to read, and system - * administrators at a shell; rather than something that should, for example, - * appear in a GUI. For example, the Linux `/proc` filesystem. + * g_win32_registry_key_get_child: + * @key: (in) (transfer none): a parent #GWin32RegistryKey + * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key + * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL * - * The list of file system types considered ‘system’ ones may change over time. + * Opens a @subkey of the @key. * - * Returns: %TRUE if @fs_type is considered an implementation detail of the OS. - * Since: 2.56 + * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free + * with g_object_unref(). */ /** - * g_unix_mount_at: - * @mount_path: (type filename): path for a possible unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * g_win32_registry_key_get_child_w: + * @key: (in) (transfer none): a parent #GWin32RegistryKey + * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key + * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL * - * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a unix timestamp for checking - * if the mounts have changed since with g_unix_mounts_changed_since(). + * Opens a @subkey of the @key. * - * Returns: (transfer full): a #GUnixMountEntry. + * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free + * with g_object_unref(). */ /** - * g_unix_mount_compare: - * @mount1: first #GUnixMountEntry to compare. - * @mount2: second #GUnixMountEntry to compare. + * g_win32_registry_key_get_path: + * @key: (in) (transfer none): a #GWin32RegistryKey * - * Compares two unix mounts. + * Get full path to the key * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. + * Returns: (transfer none): a full path to the key (in UTF-8), + * or %NULL if it can't be converted to UTF-8. + * Since: 2.46 */ /** - * g_unix_mount_copy: - * @mount_entry: a #GUnixMountEntry. + * g_win32_registry_key_get_path_w: + * @key: (in) (transfer none): a #GWin32RegistryKey * - * Makes a copy of @mount_entry. + * Get full path to the key * - * Returns: (transfer full): a new #GUnixMountEntry - * Since: 2.54 + * Returns: (transfer none): a full path to the key (in UTF-16) + * Since: 2.46 */ /** - * g_unix_mount_for: - * @file_path: (type filename): file path on some unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. + * g_win32_registry_key_get_value: + * @key: (in) (transfer none): a #GWin32RegistryKey + * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR + * to G_WIN32_REGISTRY_VALUE_STR. + * @value_name: (in) (transfer none): name of the value to get (in UTF-8). + * Empty string means the '(Default)' value. + * @value_type: (out) (optional): type of the value retrieved. + * @value_data: (out callee-allocates) (optional): contents of the value. + * @value_data_size: (out) (optional): size of the buffer pointed + * by @value_data. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Gets a #GUnixMountEntry for a given file path. If @time_read - * is set, it will be filled with a unix timestamp for checking - * if the mounts have changed since with g_unix_mounts_changed_since(). + * Get data from a value of a key. String data is guaranteed to be + * appropriately terminated and will be in UTF-8. * - * Returns: (transfer full): a #GUnixMountEntry. - * Since: 2.52 + * Returns: %TRUE on success, %FALSE on failure. + * Since: 2.46 */ /** - * g_unix_mount_free: - * @mount_entry: a #GUnixMountEntry. + * g_win32_registry_key_get_value_w: + * @key: (in) (transfer none): a #GWin32RegistryKey + * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR + * to G_WIN32_REGISTRY_VALUE_STR. + * @value_name: (in) (transfer none): name of the value to get (in UTF-16). + * Empty string means the '(Default)' value. + * @value_type: (out) (optional): type of the value retrieved. + * @value_data: (out callee-allocates) (optional): contents of the value. + * @value_data_size: (out) (optional): size of the buffer pointed + * by @value_data. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Frees a unix mount. + * Get data from a value of a key. + * + * Get data from a value of a key. String data is guaranteed to be + * appropriately terminated and will be in UTF-16. + * + * When calling with value_data == NULL (to get data size without getting + * the data itself) remember that returned size corresponds to possibly + * unterminated string data (if value is some kind of string), because + * termination cannot be checked and fixed unless the data is retreived + * too. + * + * Returns: %TRUE on success, %FALSE on failure. + * Since: 2.46 */ /** - * g_unix_mount_get_device_path: - * @mount_entry: a #GUnixMount. + * g_win32_registry_key_has_changed: + * @key: (in) (transfer none): a #GWin32RegistryKey * - * Gets the device path for a unix mount. + * Check the @key's status indicator. * - * Returns: (type filename): a string containing the device path. + * Returns: %TRUE if the @key was put under watch at some point and has changed + * since then, %FALSE if it either wasn't changed or wasn't watched at all. + * Since: 2.46 */ /** - * g_unix_mount_get_fs_type: - * @mount_entry: a #GUnixMount. + * g_win32_registry_key_new: + * @path: absolute full name of a key to open (in UTF-8) + * @error: (nullable): a pointer to a %NULL #GError, or %NULL * - * Gets the filesystem type for the unix mount. + * Creates an object that represents a registry key specified by @path. + * @path must start with one of the following pre-defined names: + * - HKEY_CLASSES_ROOT + * - HKEY_CURRENT_CONFIG + * - HKEY_CURRENT_USER + * - HKEY_CURRENT_USER_LOCAL_SETTINGS + * - HKEY_LOCAL_MACHINE + * - HKEY_PERFORMANCE_DATA + * - HKEY_PERFORMANCE_NLSTEXT + * - HKEY_PERFORMANCE_TEXT + * - HKEY_USERS + * @path must not end with '\\'. * - * Returns: a string containing the file system type. + * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't + * be opened. Free with g_object_unref(). */ /** - * g_unix_mount_get_mount_path: - * @mount_entry: input #GUnixMountEntry to get the mount path for. + * g_win32_registry_key_new_w: + * @path: (in) (transfer none): absolute full name of a key to open (in UTF-16) + * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL * - * Gets the mount path for a unix mount. + * Creates an object that represents a registry key specified by @path. + * @path must start with one of the following pre-defined names: + * - HKEY_CLASSES_ROOT + * - HKEY_CURRENT_CONFIG + * - HKEY_CURRENT_USER + * - HKEY_CURRENT_USER_LOCAL_SETTINGS + * - HKEY_LOCAL_MACHINE + * - HKEY_PERFORMANCE_DATA + * - HKEY_PERFORMANCE_NLSTEXT + * - HKEY_PERFORMANCE_TEXT + * - HKEY_USERS + * @path must not end with L'\\'. * - * Returns: (type filename): the mount path for @mount_entry. + * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't + * be opened. Free with g_object_unref(). */ /** - * g_unix_mount_guess_can_eject: - * @mount_entry: a #GUnixMountEntry + * g_win32_registry_key_watch: + * @key: (in) (transfer none): a #GWin32RegistryKey + * @watch_children: (in): %TRUE also watch the children of the @key, %FALSE + * to watch the key only. + * @watch_flags: (in): specifies the types of changes to watch for. + * @callback: (in) (nullable): a function to invoke when a change occurs. + * @user_data: (in) (nullable): a pointer to pass to @callback on invocation. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Guesses whether a Unix mount can be ejected. + * Puts @key under a watch. * - * Returns: %TRUE if @mount_entry is deemed to be ejectable. + * When the key changes, an APC will be queued in the current thread. The APC + * will run when the current thread enters alertable state (GLib main loop + * should do that; if you are not using it, see MSDN documentation for W32API + * calls that put thread into alertable state). When it runs, it will + * atomically switch an indicator in the @key. If a callback was specified, + * it is invoked at that point. Subsequent calls to + * g_win32_registry_key_has_changed() will return %TRUE, and the callback (if + * it was specified) will not be invoked anymore. + * Calling g_win32_registry_key_erase_change_indicator() will reset the indicator, + * and g_win32_registry_key_has_changed() will start returning %FALSE. + * To resume the watch, call g_win32_registry_key_watch_for_changes() again. + * + * Calling g_win32_registry_key_watch_for_changes() for a key that is already + * being watched is allowed and affects nothing. + * + * The fact that the key is being watched will be used internally to update + * key path (if it changes). + * + * Returns: %TRUE on success, %FALSE on failure. + * Since: 2.46 */ /** - * g_unix_mount_guess_icon: - * @mount_entry: a #GUnixMountEntry + * g_win32_registry_subkey_iter_assign: + * @iter: a #GWin32RegistrySubkeyIter + * @other: another #GWin32RegistrySubkeyIter * - * Guesses the icon of a Unix mount. + * Assigns the value of @other to @iter. This function + * is not useful in applications, because iterators can be assigned + * with `GWin32RegistrySubkeyIter i = j;`. The + * function is used by language bindings. * - * Returns: (transfer full): a #GIcon + * Since: 2.46 */ /** - * g_unix_mount_guess_name: - * @mount_entry: a #GUnixMountEntry + * g_win32_registry_subkey_iter_clear: + * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter * - * Guesses the name of a Unix mount. - * The result is a translated string. + * Frees internal buffers of a #GWin32RegistrySubkeyIter. * - * Returns: A newly allocated string that must - * be freed with g_free() + * Since: 2.46 */ /** - * g_unix_mount_guess_should_display: - * @mount_entry: a #GUnixMountEntry + * g_win32_registry_subkey_iter_copy: + * @iter: an iterator * - * Guesses whether a Unix mount should be displayed in the UI. + * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated + * state of the iterator is duplicated too. * - * Returns: %TRUE if @mount_entry is deemed to be displayable. + * Returns: (transfer full): a copy of the @iter, + * free with g_win32_registry_subkey_iter_free () + * Since: 2.46 */ /** - * g_unix_mount_guess_symbolic_icon: - * @mount_entry: a #GUnixMountEntry + * g_win32_registry_subkey_iter_free: + * @iter: a dynamically-allocated iterator * - * Guesses the symbolic icon of a Unix mount. + * Free an iterator allocated on the heap. For iterators that are allocated + * on the stack use g_win32_registry_subkey_iter_clear () instead. * - * Returns: (transfer full): a #GIcon - * Since: 2.34 + * Since: 2.46 */ /** - * g_unix_mount_guess_type: - * @mount_entry: a #GUnixMount. + * g_win32_registry_subkey_iter_get_name: + * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter + * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location + * to store the name of a subkey (in UTF-8). Free with g_free(). + * @subkey_name_len: (out) (optional): Pointer to a location to store the + * length of @subkey_name, in gchars, excluding NUL-terminator. + * %NULL if length is not needed. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Guesses the type of a unix mount. If the mount type cannot be - * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. + * Gets the name of the subkey at the @iter potision. * - * Returns: a #GUnixMountType. + * Returns: %TRUE if the name was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_is_readonly: - * @mount_entry: a #GUnixMount. + * g_win32_registry_subkey_iter_get_name_w: + * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter + * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location + * to store the name of a subkey (in UTF-16). + * @subkey_name_len: (out) (optional) (transfer none): Pointer to a location + * to store the length of @subkey_name, in gunichar2s, excluding + * NUL-terminator. + * %NULL if length is not needed. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Checks if a unix mount is mounted read only. + * Same as g_win32_registry_subkey_iter_get_next(), but outputs UTF-16-encoded + * data, without converting it to UTF-8 first. * - * Returns: %TRUE if @mount_entry is read only. + * Returns: %TRUE if the name was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_is_system_internal: - * @mount_entry: a #GUnixMount. + * g_win32_registry_subkey_iter_init: + * @iter: (in) (transfer none): a pointer to a #GWin32RegistrySubkeyIter + * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over + * @error: (inout) (optional) (nullable): a pointer to %NULL #GError, or %NULL * - * Checks if a Unix mount is a system mount. This is the Boolean OR of - * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and - * g_unix_is_mount_path_system_internal() on @mount_entry’s properties. + * Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be + * completely uninitialised prior to this call; its old value is + * ignored. * - * The definition of what a ‘system’ mount entry is may change over time as new - * file system types and device paths are ignored. + * The iterator remains valid for as long as @key exists. + * Clean up its internal buffers with a call to + * g_win32_registry_subkey_iter_clear() when done. * - * Returns: %TRUE if the unix mount is for a system path. + * Returns: %TRUE if iterator was initialized successfully, %FALSE on error. + * Since: 2.46 */ /** - * g_unix_mount_monitor_get: - * - * Gets the #GUnixMountMonitor for the current thread-default main - * context. + * g_win32_registry_subkey_iter_n_subkeys: + * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter * - * 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). + * Queries the number of subkeys items in the key that we are + * iterating over. This is the total number of subkeys -- not the number + * of items remaining. * - * You must only call g_object_unref() on the return value from under - * the same main context as you called this function. + * This information is accurate at the point of iterator initialization, + * and may go out of sync with reality even while subkeys are enumerated. * - * Returns: (transfer full): the #GUnixMountMonitor. - * Since: 2.44 + * Returns: the number of subkeys in the key + * Since: 2.46 */ /** - * g_unix_mount_monitor_new: + * g_win32_registry_subkey_iter_next: + * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter + * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as + * the actual number of subkeys being less than expected) and + * proceed forward + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Deprecated alias for g_unix_mount_monitor_get(). + * Moves iterator to the next subkey. + * Enumeration errors can be ignored if @skip_errors is %TRUE * - * This function was never a true constructor, which is why it was - * renamed. + * Here is an example for iterating with g_win32_registry_subkey_iter_next(): + * |[ + * // recursively iterate a key + * void + * iterate_key_recursive (GWin32RegistryKey *key) + * { + * GWin32RegistrySubkeyIter iter; + * gchar *name; + * GWin32RegistryKey *child; * - * Returns: a #GUnixMountMonitor. - * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead. + * if (!g_win32_registry_subkey_iter_init (&iter, key, NULL)) + * return; + * + * while (g_win32_registry_subkey_iter_next (&iter, TRUE, NULL)) + * { + * if (!g_win32_registry_subkey_iter_get_name (&iter, &name, NULL, NULL)) + * continue; + * + * g_print ("subkey '%s'\n", name); + * child = g_win32_registry_key_get_child (key, name, NULL); + * + * if (child) + * iterate_key_recursive (child); + * } + * + * g_win32_registry_subkey_iter_clear (&iter); + * } + * ]| + * + * Returns: %TRUE if next subkey info was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_monitor_set_rate_limit: - * @mount_monitor: a #GUnixMountMonitor - * @limit_msec: a integer with the limit in milliseconds to - * poll for changes. - * - * This function does nothing. + * g_win32_registry_value_iter_assign: + * @iter: a #GWin32RegistryValueIter + * @other: another #GWin32RegistryValueIter * - * 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. + * Assigns the value of @other to @iter. This function + * is not useful in applications, because iterators can be assigned + * with `GWin32RegistryValueIter i = j;`. The + * function is used by language bindings. * - * Since: 2.18 - * Deprecated: 2.44: This function does nothing. Don't call it. + * Since: 2.46 */ /** - * g_unix_mount_point_compare: - * @mount1: a #GUnixMount. - * @mount2: a #GUnixMount. + * g_win32_registry_value_iter_clear: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter * - * Compares two unix mount points. + * Frees internal buffers of a #GWin32RegistryValueIter. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. + * Since: 2.46 */ /** - * g_unix_mount_point_copy: - * @mount_point: a #GUnixMountPoint. + * g_win32_registry_value_iter_copy: + * @iter: an iterator * - * Makes a copy of @mount_point. + * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated + * state of the iterator is duplicated too. * - * Returns: (transfer full): a new #GUnixMountPoint - * Since: 2.54 + * Returns: (transfer full): a copy of the @iter, + * free with g_win32_registry_value_iter_free (). + * Since: 2.46 */ /** - * g_unix_mount_point_free: - * @mount_point: unix mount point to free. + * g_win32_registry_value_iter_free: + * @iter: a dynamically-allocated iterator * - * Frees a unix mount point. + * Free an iterator allocated on the heap. For iterators that are allocated + * on the stack use g_win32_registry_value_iter_clear () instead. + * + * Since: 2.46 */ /** - * g_unix_mount_point_get_device_path: - * @mount_point: a #GUnixMountPoint. + * g_win32_registry_value_iter_get_data: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to + * G_WIN32_REGISTRY_VALUE_STR + * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a + * location to store the data of the value (in UTF-8, if it's a string) + * @value_data_size: (out) (optional): Pointer to a location to store the length + * of @value_data, in bytes (including any NUL-terminators, if it's a string). + * %NULL if length is not needed + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Gets the device path for a unix mount point. + * Stores the data of the value currently being iterated over in @value_data, + * and its length - in @value_data_len (if not %NULL). * - * Returns: (type filename): a string containing the device path. + * Returns: %TRUE if value data was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_point_get_fs_type: - * @mount_point: a #GUnixMountPoint. + * g_win32_registry_value_iter_get_data_w: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to + * G_WIN32_REGISTRY_VALUE_STR + * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a + * location to store the data of the value (in UTF-16, if it's a string) + * @value_data_size: (out) (optional): Pointer to a location to store the size + * of @value_data, in bytes (including any NUL-terminators, if it's a string). + * %NULL if length is not needed. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Gets the file system type for the mount point. + * Stores the data of the value currently being iterated over in @value_data, + * and its length - in @value_data_len (if not %NULL). * - * Returns: a string containing the file system type. + * Returns: %TRUE if value data was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_point_get_mount_path: - * @mount_point: a #GUnixMountPoint. + * g_win32_registry_value_iter_get_name: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * @value_name: (out callee-allocates) (transfer none): Pointer to a location + * to store the name of a value (in UTF-8). + * @value_name_len: (out) (optional): Pointer to a location to store the length + * of @value_name, in gchars, excluding NUL-terminator. + * %NULL if length is not needed. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Gets the mount path for a unix mount point. + * Stores the name of the value currently being iterated over in @value_name, + * and its length - in @value_name_len (if not %NULL). * - * Returns: (type filename): a string containing the mount path. + * Returns: %TRUE if value name was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_point_get_options: - * @mount_point: a #GUnixMountPoint. + * g_win32_registry_value_iter_get_name_w: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * @value_name: (out callee-allocates) (transfer none): Pointer to a location + * to store the name of a value (in UTF-16). + * @value_name_len: (out) (optional): Pointer to a location to store the length + * of @value_name, in gunichar2s, excluding NUL-terminator. + * %NULL if length is not needed. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Gets the options for the mount point. + * Stores the name of the value currently being iterated over in @value_name, + * and its length - in @value_name (if not %NULL). * - * Returns: a string containing the options. - * Since: 2.32 + * Returns: %TRUE if value name was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_point_guess_can_eject: - * @mount_point: a #GUnixMountPoint + * g_win32_registry_value_iter_get_value_type: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * @value_type: (out): Pointer to a location to store the type of + * the value. + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Guesses whether a Unix mount point can be ejected. + * Stores the type of the value currently being iterated over in @value_type. * - * Returns: %TRUE if @mount_point is deemed to be ejectable. + * Returns: %TRUE if value type was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_point_guess_icon: - * @mount_point: a #GUnixMountPoint + * g_win32_registry_value_iter_init: + * @iter: (in) (transfer none): a pointer to a #GWin32RegistryValueIter + * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Guesses the icon of a Unix mount point. + * Initialises (without allocating) a #GWin32RegistryValueIter. @iter may be + * completely uninitialised prior to this call; its old value is + * ignored. * - * Returns: (transfer full): a #GIcon + * The iterator remains valid for as long as @key exists. + * Clean up its internal buffers with a call to + * g_win32_registry_value_iter_clear() when done. + * + * Returns: %TRUE if iterator was initialized successfully, %FALSE on error. + * Since: 2.46 */ /** - * g_unix_mount_point_guess_name: - * @mount_point: a #GUnixMountPoint + * g_win32_registry_value_iter_n_values: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter * - * Guesses the name of a Unix mount point. - * The result is a translated string. + * Queries the number of values items in the key that we are + * iterating over. This is the total number of values -- not the number + * of items remaining. * - * Returns: A newly allocated string that must - * be freed with g_free() + * This information is accurate at the point of iterator initialization, + * and may go out of sync with reality even while values are enumerated. + * + * Returns: the number of values in the key + * Since: 2.46 */ /** - * g_unix_mount_point_guess_symbolic_icon: - * @mount_point: a #GUnixMountPoint + * g_win32_registry_value_iter_next: + * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as + * the actual number of values being less than expected) and + * proceed forward + * @error: (nullable): a pointer to %NULL #GError, or %NULL * - * Guesses the symbolic icon of a Unix mount point. + * Advances iterator to the next value in the key. If no more values remain then + * FALSE is returned. + * Enumeration errors can be ignored if @skip_errors is %TRUE * - * Returns: (transfer full): a #GIcon - * Since: 2.34 + * Here is an example for iterating with g_win32_registry_value_iter_next(): + * |[ + * // iterate values of a key + * void + * iterate_values_recursive (GWin32RegistryKey *key) + * { + * GWin32RegistryValueIter iter; + * gchar *name; + * GWin32RegistryValueType val_type; + * gchar *val_data; + * + * if (!g_win32_registry_value_iter_init (&iter, key, NULL)) + * return; + * + * while (g_win32_registry_value_iter_next (&iter, TRUE, NULL)) + * { + * if ((!g_win32_registry_value_iter_get_value_type (&iter, &value)) || + * ((val_type != G_WIN32_REGISTRY_VALUE_STR) && + * (val_type != G_WIN32_REGISTRY_VALUE_EXPAND_STR))) + * continue; + * + * if (g_win32_registry_value_iter_get_value (&iter, TRUE, &name, NULL, + * &val_data, NULL, NULL)) + * g_print ("value '%s' = '%s'\n", name, val_data); + * } + * + * g_win32_registry_value_iter_clear (&iter); + * } + * ]| + * + * Returns: %TRUE if next value info was retrieved, %FALSE otherwise. + * Since: 2.46 */ /** - * g_unix_mount_point_guess_type: - * @mount_point: a #GUnixMountPoint. + * g_zlib_compressor_get_file_info: + * @compressor: a #GZlibCompressor * - * Guesses the type of a unix mount point. - * If the mount type cannot be determined, - * returns %G_UNIX_MOUNT_TYPE_UNKNOWN. + * Returns the #GZlibCompressor:file-info property. * - * Returns: a #GUnixMountType. + * Returns: (transfer none): a #GFileInfo, or %NULL + * Since: 2.26 */ /** - * g_unix_mount_point_is_loopback: - * @mount_point: a #GUnixMountPoint. + * g_zlib_compressor_new: + * @format: The format to use for the compressed data + * @level: compression level (0-9), -1 for default * - * Checks if a unix mount point is a loopback device. + * Creates a new #GZlibCompressor. * - * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. + * Returns: a new #GZlibCompressor + * Since: 2.24 */ /** - * g_unix_mount_point_is_readonly: - * @mount_point: a #GUnixMountPoint. + * g_zlib_compressor_set_file_info: + * @compressor: a #GZlibCompressor + * @file_info: (nullable): a #GFileInfo * - * Checks if a unix mount point is read only. + * Sets @file_info in @compressor. If non-%NULL, and @compressor's + * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, + * it will be used to set the file name and modification time in + * the GZIP header of the compressed data. * - * Returns: %TRUE if a mount point is read only. + * Note: it is an error to call this function while a compression is in + * progress; it may only be called immediately after creation of @compressor, + * or after resetting it with g_converter_reset(). + * + * Since: 2.26 */ /** - * g_unix_mount_point_is_user_mountable: - * @mount_point: a #GUnixMountPoint. + * g_zlib_decompressor_get_file_info: + * @decompressor: a #GZlibDecompressor * - * Checks if a unix mount point is mountable by the user. + * Retrieves the #GFileInfo constructed from the GZIP header data + * of compressed data processed by @compressor, or %NULL if @decompressor's + * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, + * or the header data was not fully processed yet, or it not present in the + * data stream at all. * - * Returns: %TRUE if the mount point is user mountable. + * Returns: (transfer none): a #GFileInfo, or %NULL + * Since: 2.26 */ /** - * g_unix_mount_points_changed_since: - * @time: guint64 to contain a timestamp. + * g_zlib_decompressor_new: + * @format: The format to use for the compressed data * - * Checks if the unix mount points have changed since a given unix time. + * Creates a new #GZlibDecompressor. * - * Returns: %TRUE if the mount points have changed since @time. + * Returns: a new #GZlibDecompressor + * Since: 2.24 */ /** - * g_unix_mount_points_get: - * @time_read: (out) (optional): guint64 to contain a timestamp. + * get_viewable_logical_drives: * - * Gets a #GList of #GUnixMountPoint containing the unix mount points. - * If @time_read is set, it will be filled with the mount timestamp, - * allowing for checking if the mounts have changed with - * g_unix_mount_points_changed_since(). + * 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. * - * Returns: (element-type GUnixMountPoint) (transfer full): - * a #GList of the UNIX mountpoints. + * Returns: bitmask with same meaning as returned by GetLogicalDrives() */ /** - * g_unix_mounts_changed_since: - * @time: guint64 to contain a timestamp. + * gxdp_documents_call_add: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_fd: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @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 if the unix mounts have changed since a given unix time. + * Asynchronously invokes the Add() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_add_finish() to get the result of the operation. * - * Returns: %TRUE if the mounts have changed since @time. + * See gxdp_documents_call_add_sync() for the synchronous, blocking version of this method. */ /** - * g_unix_mounts_get: - * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL + * gxdp_documents_call_add_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add(). + * @error: Return location for error or %NULL. * - * Gets a #GList of #GUnixMountEntry containing the unix mounts. - * If @time_read is set, it will be filled with the mount - * timestamp, allowing for checking if the mounts have changed - * with g_unix_mounts_changed_since(). + * Finishes an operation started with gxdp_documents_call_add(). * - * Returns: (element-type GUnixMountEntry) (transfer full): - * a #GList of the UNIX mounts. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_output_stream_get_close_fd: - * @stream: a #GUnixOutputStream + * gxdp_documents_call_add_full: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_fds: Argument to pass with the method invocation. + * @arg_flags: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @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. * - * Returns whether the file descriptor of @stream will be - * closed when the stream is closed. + * Asynchronously invokes the AddFull() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_add_full_finish() to get the result of the operation. * - * Returns: %TRUE if the file descriptor is closed when done - * Since: 2.20 + * See gxdp_documents_call_add_full_sync() for the synchronous, blocking version of this method. */ /** - * g_unix_output_stream_get_fd: - * @stream: a #GUnixOutputStream + * gxdp_documents_call_add_full_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_ids: (out): Return location for return parameter or %NULL to ignore. + * @out_extra_out: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add_full(). + * @error: Return location for error or %NULL. * - * Return the UNIX file descriptor that the stream writes to. + * Finishes an operation started with gxdp_documents_call_add_full(). * - * Returns: The file descriptor of @stream - * Since: 2.20 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_output_stream_new: - * @fd: a UNIX file descriptor - * @close_fd: %TRUE to close the file descriptor when done + * gxdp_documents_call_add_full_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_fds: Argument to pass with the method invocation. + * @arg_flags: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @out_doc_ids: (out): Return location for return parameter or %NULL to ignore. + * @out_extra_out: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Creates a new #GUnixOutputStream for the given @fd. + * Synchronously invokes the AddFull() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * If @close_fd, is %TRUE, the file descriptor will be closed when - * the output stream is destroyed. + * See gxdp_documents_call_add_full() for the asynchronous version of this method. * - * Returns: a new #GOutputStream + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_output_stream_set_close_fd: - * @stream: a #GUnixOutputStream - * @close_fd: %TRUE to close the file descriptor when done + * gxdp_documents_call_add_named: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_parent_fd: Argument to pass with the method invocation. + * @arg_filename: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @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. * - * Sets whether the file descriptor of @stream shall be closed - * when the stream is closed. + * Asynchronously invokes the AddNamed() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_add_named_finish() to get the result of the operation. * - * Since: 2.20 + * See gxdp_documents_call_add_named_sync() for the synchronous, blocking version of this method. */ /** - * g_unix_socket_address_abstract_names_supported: + * gxdp_documents_call_add_named_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_add_named(). + * @error: Return location for error or %NULL. * - * Checks if abstract UNIX domain socket names are supported. + * Finishes an operation started with gxdp_documents_call_add_named(). * - * Returns: %TRUE if supported, %FALSE otherwise - * Since: 2.22 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_socket_address_get_address_type: - * @address: a #GInetSocketAddress + * gxdp_documents_call_add_named_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_parent_fd: Argument to pass with the method invocation. + * @arg_filename: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Gets @address's type. + * Synchronously invokes the AddNamed() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: a #GUnixSocketAddressType - * Since: 2.26 + * See gxdp_documents_call_add_named() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_socket_address_get_is_abstract: - * @address: a #GInetSocketAddress + * gxdp_documents_call_add_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_o_path_fd: Argument to pass with the method invocation. + * @arg_reuse_existing: Argument to pass with the method invocation. + * @arg_persistent: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Tests if @address is abstract. + * Synchronously invokes the Add() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: %TRUE if the address is abstract, %FALSE otherwise - * Since: 2.22 - * Deprecated: Use g_unix_socket_address_get_address_type() + * See gxdp_documents_call_add() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_socket_address_get_path: - * @address: a #GInetSocketAddress + * gxdp_documents_call_delete: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: 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. * - * Gets @address's path, or for abstract sockets the "name". + * Asynchronously invokes the Delete() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_delete_finish() to get the result of the operation. * - * Guaranteed to be zero-terminated, but an abstract socket - * may contain embedded zeros, and thus you should use - * g_unix_socket_address_get_path_len() to get the true length - * of this string. + * See gxdp_documents_call_delete_sync() for the synchronous, blocking version of this method. + */ + + +/** + * gxdp_documents_call_delete_finish: + * @proxy: A #GXdpDocumentsProxy. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_delete(). + * @error: Return location for error or %NULL. * - * Returns: the path for @address - * Since: 2.22 + * Finishes an operation started with gxdp_documents_call_delete(). + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_socket_address_get_path_len: - * @address: a #GInetSocketAddress + * gxdp_documents_call_delete_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Gets the length of @address's path. + * Synchronously invokes the Delete() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * For details, see g_unix_socket_address_get_path(). + * See gxdp_documents_call_delete() for the asynchronous version of this method. * - * Returns: the length of the path - * Since: 2.22 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_socket_address_new: - * @path: the socket path - * - * Creates a new #GUnixSocketAddress for @path. + * gxdp_documents_call_get_mount_point: + * @proxy: A #GXdpDocumentsProxy. + * @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. * - * To create abstract socket addresses, on systems that support that, - * use g_unix_socket_address_new_abstract(). + * Asynchronously invokes the GetMountPoint() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_get_mount_point_finish() to get the result of the operation. * - * Returns: a new #GUnixSocketAddress - * Since: 2.22 + * See gxdp_documents_call_get_mount_point_sync() for the synchronous, blocking version of this method. */ /** - * g_unix_socket_address_new_abstract: - * @path: (array length=path_len) (element-type gchar): the abstract name - * @path_len: the length of @path, or -1 + * gxdp_documents_call_get_mount_point_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_get_mount_point(). + * @error: Return location for error or %NULL. * - * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED - * #GUnixSocketAddress for @path. + * Finishes an operation started with gxdp_documents_call_get_mount_point(). * - * Returns: a new #GUnixSocketAddress - * Deprecated: Use g_unix_socket_address_new_with_type(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_unix_socket_address_new_with_type: - * @path: (array length=path_len) (element-type gchar): the name - * @path_len: the length of @path, or -1 - * @type: a #GUnixSocketAddressType - * - * Creates a new #GUnixSocketAddress of type @type with name @path. - * - * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to - * calling g_unix_socket_address_new(). - * - * If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be - * ignored. - * - * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len - * bytes of @path will be copied to the socket's path, and only those - * bytes will be considered part of the name. (If @path_len is -1, - * then @path is assumed to be NUL-terminated.) For example, if @path - * was "test", then calling g_socket_address_get_native_size() on the - * returned socket would return 7 (2 bytes of overhead, 1 byte for the - * abstract-socket indicator byte, and 4 bytes for the name "test"). + * gxdp_documents_call_get_mount_point_sync: + * @proxy: A #GXdpDocumentsProxy. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then - * @path_len bytes of @path will be copied to the socket's path, the - * rest of the path will be padded with 0 bytes, and the entire - * 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 `struct sockaddr_un`, although - * g_unix_socket_address_get_path_len() will still return just the - * length of @path. + * Synchronously invokes the GetMountPoint() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, - * when connecting to a server created by another process, you must - * use the appropriate type corresponding to how that process created - * its listening socket. + * See gxdp_documents_call_get_mount_point() for the asynchronous version of this method. * - * Returns: a new #GUnixSocketAddress - * Since: 2.26 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_vfs_get_default: + * gxdp_documents_call_grant_permissions: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: 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. * - * Gets the default #GVfs for the system. + * Asynchronously invokes the GrantPermissions() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_grant_permissions_finish() to get the result of the operation. * - * Returns: (transfer none): a #GVfs. + * See gxdp_documents_call_grant_permissions_sync() for the synchronous, blocking version of this method. */ /** - * g_vfs_get_file_for_path: - * @vfs: a #GVfs. - * @path: a string containing a VFS path. + * gxdp_documents_call_grant_permissions_finish: + * @proxy: A #GXdpDocumentsProxy. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_grant_permissions(). + * @error: Return location for error or %NULL. * - * Gets a #GFile for @path. + * Finishes an operation started with gxdp_documents_call_grant_permissions(). * - * Returns: (transfer full): a #GFile. - * Free the returned object with g_object_unref(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_vfs_get_file_for_uri: - * @vfs: a#GVfs. - * @uri: a string containing a URI + * gxdp_documents_call_grant_permissions_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Gets a #GFile for @uri. + * Synchronously invokes the GrantPermissions() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * This operation never fails, but the returned object - * might not support any I/O operation if the URI - * is malformed or if the URI scheme is not supported. + * See gxdp_documents_call_grant_permissions() for the asynchronous version of this method. * - * Returns: (transfer full): a #GFile. - * Free the returned object with g_object_unref(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_vfs_get_local: + * gxdp_documents_call_info: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: 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. * - * Gets the local #GVfs for the system. + * Asynchronously invokes the Info() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_info_finish() to get the result of the operation. * - * Returns: (transfer none): a #GVfs. + * See gxdp_documents_call_info_sync() for the synchronous, blocking version of this method. */ /** - * g_vfs_get_supported_uri_schemes: - * @vfs: a #GVfs. + * gxdp_documents_call_info_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @out_apps: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_info(). + * @error: Return location for error or %NULL. * - * Gets a list of URI schemes supported by @vfs. + * Finishes an operation started with gxdp_documents_call_info(). * - * Returns: (transfer none): a %NULL-terminated array of strings. - * The returned array belongs to GIO and must - * not be freed or modified. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_vfs_is_active: - * @vfs: a #GVfs. + * gxdp_documents_call_info_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @out_path: (out): Return location for return parameter or %NULL to ignore. + * @out_apps: (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 the VFS is active. + * Synchronously invokes the Info() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: %TRUE if construction of the @vfs was successful - * and it is now active. + * See gxdp_documents_call_info() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_vfs_parse_name: - * @vfs: a #GVfs. - * @parse_name: a string to be parsed by the VFS module. + * gxdp_documents_call_list: + * @proxy: A #GXdpDocumentsProxy. + * @arg_app_id: 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. * - * This operation never fails, but the returned object might - * not support any I/O operations if the @parse_name cannot - * be parsed by the #GVfs module. + * Asynchronously invokes the List() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_list_finish() to get the result of the operation. * - * Returns: (transfer full): a #GFile for the given @parse_name. - * Free the returned object with g_object_unref(). + * See gxdp_documents_call_list_sync() for the synchronous, blocking version of this method. */ /** - * g_vfs_register_uri_scheme: - * @vfs: a #GVfs - * @scheme: an URI scheme, e.g. "http" - * @uri_func: (scope notified) (nullable): a #GVfsFileLookupFunc - * @uri_data: (nullable): custom data passed to be passed to @uri_func, or %NULL - * @uri_destroy: (nullable): function to be called when unregistering the - * URI scheme, or when @vfs is disposed, to free the resources used - * by the URI lookup function - * @parse_name_func: (scope notified) (nullable): a #GVfsFileLookupFunc - * @parse_name_data: (nullable): custom data passed to be passed to - * @parse_name_func, or %NULL - * @parse_name_destroy: (nullable): function to be called when unregistering the - * URI scheme, or when @vfs is disposed, to free the resources used - * by the parse name lookup function + * gxdp_documents_call_list_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_docs: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_list(). + * @error: Return location for error or %NULL. * - * Registers @uri_func and @parse_name_func as the #GFile URI and parse name - * lookup functions for URIs with a scheme matching @scheme. - * Note that @scheme is registered only within the running application, as - * opposed to desktop-wide as it happens with GVfs backends. + * Finishes an operation started with gxdp_documents_call_list(). * - * When a #GFile is requested with an URI containing @scheme (e.g. through - * g_file_new_for_uri()), @uri_func will be called to allow a custom - * constructor. The implementation of @uri_func should not be blocking, and - * must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. + */ + + +/** + * gxdp_documents_call_list_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_app_id: Argument to pass with the method invocation. + * @out_docs: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * When g_file_parse_name() is called with a parse name obtained from such file, - * @parse_name_func will be called to allow the #GFile to be created again. In - * that case, it's responsibility of @parse_name_func to make sure the parse - * name matches what the custom #GFile implementation returned when - * g_file_get_parse_name() was previously called. The implementation of - * @parse_name_func should not be blocking, and must not call - * g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). + * Synchronously invokes the List() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * It's an error to call this function twice with the same scheme. To unregister - * a custom URI scheme, use g_vfs_unregister_uri_scheme(). + * See gxdp_documents_call_list() for the asynchronous version of this method. * - * Returns: %TRUE if @scheme was successfully registered, or %FALSE if a handler - * for @scheme already exists. - * Since: 2.50 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_vfs_unregister_uri_scheme: - * @vfs: a #GVfs - * @scheme: an URI scheme, e.g. "http" + * gxdp_documents_call_lookup: + * @proxy: A #GXdpDocumentsProxy. + * @arg_filename: 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. * - * Unregisters the URI handler for @scheme previously registered with - * g_vfs_register_uri_scheme(). + * Asynchronously invokes the Lookup() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_lookup_finish() to get the result of the operation. * - * Returns: %TRUE if @scheme was successfully unregistered, or %FALSE if a - * handler for @scheme does not exist. - * Since: 2.50 + * See gxdp_documents_call_lookup_sync() for the synchronous, blocking version of this method. */ /** - * g_volume_can_eject: - * @volume: a #GVolume + * gxdp_documents_call_lookup_finish: + * @proxy: A #GXdpDocumentsProxy. + * @out_doc_id: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_lookup(). + * @error: Return location for error or %NULL. * - * Checks if a volume can be ejected. + * Finishes an operation started with gxdp_documents_call_lookup(). * - * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_volume_can_mount: - * @volume: a #GVolume + * gxdp_documents_call_lookup_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_filename: Argument to pass with the method invocation. + * @out_doc_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 if a volume can be mounted. + * Synchronously invokes the Lookup() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise + * See gxdp_documents_call_lookup() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_volume_eject: - * @volume: a #GVolume - * @flags: flags affecting the unmount if required for eject - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL - * @user_data: user data that gets passed to @callback + * gxdp_documents_call_revoke_permissions: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: 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. * - * Ejects a volume. This is an asynchronous operation, and is - * finished by calling g_volume_eject_finish() with the @volume - * and #GAsyncResult returned in the @callback. + * Asynchronously invokes the RevokePermissions() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_call_revoke_permissions_finish() to get the result of the operation. * - * Deprecated: 2.22: Use g_volume_eject_with_operation() instead. + * See gxdp_documents_call_revoke_permissions_sync() for the synchronous, blocking version of this method. */ /** - * g_volume_eject_finish: - * @volume: pointer to a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store an error, or %NULL to ignore + * gxdp_documents_call_revoke_permissions_finish: + * @proxy: A #GXdpDocumentsProxy. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_call_revoke_permissions(). + * @error: Return location for error 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. + * Finishes an operation started with gxdp_documents_call_revoke_permissions(). * - * Returns: %TRUE, %FALSE if operation failed - * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_volume_eject_with_operation: - * @volume: a #GVolume - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (nullable): a #GMountOperation or %NULL to - * avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL - * @user_data: user data passed to @callback + * gxdp_documents_call_revoke_permissions_sync: + * @proxy: A #GXdpDocumentsProxy. + * @arg_doc_id: Argument to pass with the method invocation. + * @arg_app_id: Argument to pass with the method invocation. + * @arg_permissions: Argument to pass with the method invocation. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Ejects a volume. This is an asynchronous operation, and is - * finished by calling g_volume_eject_with_operation_finish() with the @volume - * and #GAsyncResult data returned in the @callback. + * Synchronously invokes the RevokePermissions() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Since: 2.22 + * See gxdp_documents_call_revoke_permissions() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_volume_eject_with_operation_finish: - * @volume: a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL + * gxdp_documents_complete_add: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @doc_id: Parameter to return. * - * Finishes ejecting a volume. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. + * Helper function used in service implementations to finish handling invocations of the Add() 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. * - * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise - * Since: 2.22 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_enumerate_identifiers: - * @volume: a #GVolume + * gxdp_documents_complete_add_full: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @doc_ids: Parameter to return. + * @extra_out: Parameter to return. * - * Gets the kinds of [identifiers][volume-identifier] that @volume has. - * Use g_volume_get_identifier() to obtain the identifiers themselves. + * Helper function used in service implementations to finish handling invocations of the AddFull() 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. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array - * of strings containing kinds of identifiers. Use g_strfreev() to free. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_activation_root: - * @volume: a #GVolume - * - * Gets the activation root for a #GVolume if it is known ahead of - * mount time. Returns %NULL otherwise. If not %NULL and if @volume - * is mounted, then the result of g_mount_get_root() on the - * #GMount object obtained from g_volume_get_mount() will always - * either be equal or a prefix of what this function returns. In - * other words, in code - * - * |[ - * 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 - * |[ - * (g_file_has_prefix (volume_activation_root, mount_root) || - * g_file_equal (volume_activation_root, mount_root)) - * ]| - * will always be %TRUE. + * gxdp_documents_complete_add_named: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @doc_id: Parameter to return. * - * Activation roots are typically used in #GVolumeMonitor - * implementations to find the underlying mount to shadow, see - * g_mount_is_shadowed() for more details. + * Helper function used in service implementations to finish handling invocations of the AddNamed() 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. * - * Returns: (nullable) (transfer full): the activation root of @volume - * or %NULL. Use g_object_unref() to free. - * Since: 2.18 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_drive: - * @volume: a #GVolume + * gxdp_documents_complete_delete: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Gets the drive for the @volume. + * Helper function used in service implementations to finish handling invocations of the Delete() 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. * - * 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. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_icon: - * @volume: a #GVolume + * gxdp_documents_complete_get_mount_point: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @path: Parameter to return. * - * Gets the icon for @volume. + * Helper function used in service implementations to finish handling invocations of the GetMountPoint() 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. * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_identifier: - * @volume: a #GVolume - * @kind: the kind of identifier to return + * gxdp_documents_complete_grant_permissions: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Gets the identifier of the given kind for @volume. - * See the [introduction][volume-identifier] for more - * information about volume identifiers. + * Helper function used in service implementations to finish handling invocations of the GrantPermissions() 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. * - * Returns: a newly allocated string containing the - * requested identfier, or %NULL if the #GVolume - * doesn't have this kind of identifier + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_mount: - * @volume: a #GVolume + * gxdp_documents_complete_info: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @path: Parameter to return. + * @apps: Parameter to return. * - * Gets the mount for the @volume. + * Helper function used in service implementations to finish handling invocations of the Info() 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. * - * 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. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_name: - * @volume: a #GVolume + * gxdp_documents_complete_list: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @docs: Parameter to return. * - * Gets the name of @volume. + * Helper function used in service implementations to finish handling invocations of the List() 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. * - * Returns: the name for the given @volume. The returned string should - * be freed with g_free() when no longer needed. + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_sort_key: - * @volume: a #GVolume + * gxdp_documents_complete_lookup: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @doc_id: Parameter to return. * - * Gets the sort key for @volume, if any. + * Helper function used in service implementations to finish handling invocations of the Lookup() 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. * - * Returns: Sorting key for @volume or %NULL if no such key is available - * Since: 2.32 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_symbolic_icon: - * @volume: a #GVolume + * gxdp_documents_complete_revoke_permissions: + * @object: A #GXdpDocuments. + * @invocation: (transfer full): A #GDBusMethodInvocation. * - * Gets the symbolic icon for @volume. + * Helper function used in service implementations to finish handling invocations of the RevokePermissions() 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. * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. - * Since: 2.34 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_volume_get_uuid: - * @volume: a #GVolume + * gxdp_documents_get_version: (skip) + * @object: A #GXdpDocuments. * - * 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. + * Gets the value of the "version" D-Bus property. * - * 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. + * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side. + * + * Returns: The property value. */ /** - * g_volume_monitor_adopt_orphan_mount: - * @mount: a #GMount object to find a parent for + * gxdp_documents_interface_info: * - * This function should be called by any #GVolumeMonitor - * implementation when a new #GMount object is created that is not - * associated with a #GVolume object. It must be called just before - * emitting the @mount_added signal. + * Gets a machine-readable description of the org.freedesktop.portal.Documents D-Bus interface. * - * If the return value is not %NULL, the caller must associate the - * returned #GVolume object with the #GMount. This involves returning - * it in its g_mount_get_volume() implementation. The caller must - * also listen for the "removed" signal on the returned object - * and give up its reference when handling that signal + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. + */ + + +/** + * gxdp_documents_override_properties: + * @klass: The class structure for a #GObject-derived class. + * @property_id_begin: The property id to assign to the first overridden property. * - * Similary, if implementing g_volume_monitor_adopt_orphan_mount(), - * the implementor must take a reference to @mount and return it in - * its g_volume_get_mount() implemented. Also, the implementor must - * listen for the "unmounted" signal on @mount and give up its - * reference upon handling that signal. + * Overrides all #GObject properties in the #GXdpDocuments interface for a concrete class. + * The properties are overridden in the order they are defined. * - * There are two main use cases for this function. + * Returns: The last property id. + */ + + +/** + * gxdp_documents_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. * - * One is when implementing a user space file system driver that reads - * blocks of a block device that is already represented by the native - * volume monitor (for example a CD Audio file system driver). Such - * a driver will generate its own #GMount object that needs to be - * associated with the #GVolume object that represents the volume. + * Asynchronously creates a proxy for the D-Bus interface org.freedesktop.portal.Documents. See g_dbus_proxy_new() for more details. * - * The other is for implementing a #GVolumeMonitor whose sole purpose - * is to return #GVolume objects representing entries in the users - * "favorite servers" list or similar. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_proxy_new_finish() to get the result of the operation. * - * 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. + * See gxdp_documents_proxy_new_sync() for the synchronous, blocking version of this constructor. */ /** - * g_volume_monitor_get: + * gxdp_documents_proxy_new_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_proxy_new(). + * @error: Return location for error or %NULL * - * Gets the volume monitor used by gio. + * Finishes an operation started with gxdp_documents_proxy_new(). * - * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call - * g_object_unref() when done with it. + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_volume_monitor_get_connected_drives: - * @volume_monitor: a #GVolumeMonitor. + * gxdp_documents_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. * - * Gets a list of drives connected to the system. + * Like gxdp_documents_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_documents_proxy_new_for_bus_finish() to get the result of the operation. * - * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects. + * See gxdp_documents_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor. */ /** - * g_volume_monitor_get_mount_for_uuid: - * @volume_monitor: a #GVolumeMonitor. - * @uuid: the UUID to look for + * gxdp_documents_proxy_new_for_bus_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_documents_proxy_new_for_bus(). + * @error: Return location for error or %NULL * - * Finds a #GMount object by its UUID (see g_mount_get_uuid()) + * Finishes an operation started with gxdp_documents_proxy_new_for_bus(). * - * Returns: (transfer full): a #GMount or %NULL if no such mount is available. - * Free the returned object with g_object_unref(). + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_volume_monitor_get_mounts: - * @volume_monitor: a #GVolumeMonitor. + * gxdp_documents_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 * - * Gets a list of the mounts on the system. + * Like gxdp_documents_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * The calling thread is blocked until a reply is received. * - * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects. + * See gxdp_documents_proxy_new_for_bus() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_volume_monitor_get_volume_for_uuid: - * @volume_monitor: a #GVolumeMonitor. - * @uuid: the UUID to look for + * gxdp_documents_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 * - * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) + * Synchronously creates a proxy for the D-Bus interface org.freedesktop.portal.Documents. See g_dbus_proxy_new_sync() for more details. * - * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. - * Free the returned object with g_object_unref(). + * The calling thread is blocked until a reply is received. + * + * See gxdp_documents_proxy_new() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpDocumentsProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_volume_monitor_get_volumes: - * @volume_monitor: a #GVolumeMonitor. + * gxdp_documents_set_version: (skip) + * @object: A #GXdpDocuments. + * @value: The value to set. * - * Gets a list of the volumes on the system. + * Sets the "version" D-Bus property to @value. * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side. + */ + + +/** + * gxdp_documents_skeleton_new: * - * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects. + * Creates a skeleton object for the D-Bus interface org.freedesktop.portal.Documents. + * + * Returns: (transfer full) (type GXdpDocumentsSkeleton): The skeleton object. */ /** - * g_volume_mount: (virtual mount_fn) - * @volume: a #GVolume - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL - * @user_data: user data that gets passed to @callback + * gxdp_network_monitor_emit_changed: + * @object: A #GXdpNetworkMonitor. + * @arg_available: Argument to pass with the signal. * - * 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. + * Emits the "changed" D-Bus signal. */ /** - * g_volume_mount_finish: - * @volume: a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store an error, or %NULL to ignore + * gxdp_network_monitor_get_available: (skip) + * @object: A #GXdpNetworkMonitor. * - * Finishes mounting a volume. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. + * Gets the value of the "available" D-Bus property. * - * If the mount operation succeeded, g_volume_get_mount() on @volume - * is guaranteed to return the mount right after calling this - * function; there's no need to listen for the 'mount-added' signal on - * #GVolumeMonitor. + * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side. * - * Returns: %TRUE, %FALSE if operation failed + * Returns: The property value. */ /** - * g_volume_should_automount: - * @volume: a #GVolume + * gxdp_network_monitor_get_connectivity: (skip) + * @object: A #GXdpNetworkMonitor. * - * Returns whether the volume should be automatically mounted. + * Gets the value of the "connectivity" D-Bus property. * - * Returns: %TRUE if the volume should be automatically mounted + * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side. + * + * Returns: The property value. */ /** - * g_win32_input_stream_get_close_handle: - * @stream: a #GWin32InputStream + * gxdp_network_monitor_get_metered: (skip) + * @object: A #GXdpNetworkMonitor. * - * Returns whether the handle of @stream will be - * closed when the stream is closed. + * Gets the value of the "metered" D-Bus property. * - * Returns: %TRUE if the handle is closed when done - * Since: 2.26 + * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side. + * + * Returns: The property value. */ /** - * g_win32_input_stream_get_handle: - * @stream: a #GWin32InputStream + * gxdp_network_monitor_interface_info: * - * Return the Windows file handle that the stream reads from. + * Gets a machine-readable description of the org.freedesktop.portal.NetworkMonitor D-Bus interface. * - * Returns: The file handle of @stream - * Since: 2.26 + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. */ /** - * g_win32_input_stream_new: - * @handle: a Win32 file handle - * @close_handle: %TRUE to close the handle when done + * gxdp_network_monitor_override_properties: + * @klass: The class structure for a #GObject-derived class. + * @property_id_begin: The property id to assign to the first overridden property. * - * Creates a new #GWin32InputStream for the given @handle. - * - * If @close_handle is %TRUE, the handle will be closed - * when the stream is closed. + * Overrides all #GObject properties in the #GXdpNetworkMonitor interface for a concrete class. + * The properties are overridden in the order they are defined. * - * Note that "handle" here means a Win32 HANDLE, not a "file descriptor" - * as used in the Windows C libraries. - * - * Returns: a new #GWin32InputStream + * Returns: The last property id. */ /** - * g_win32_input_stream_set_close_handle: - * @stream: a #GWin32InputStream - * @close_handle: %TRUE to close the handle when done + * gxdp_network_monitor_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. * - * Sets whether the handle of @stream shall be closed - * when the stream is closed. + * Asynchronously creates a proxy for the D-Bus interface org.freedesktop.portal.NetworkMonitor. See g_dbus_proxy_new() for more details. * - * Since: 2.26 + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_network_monitor_proxy_new_finish() to get the result of the operation. + * + * See gxdp_network_monitor_proxy_new_sync() for the synchronous, blocking version of this constructor. */ /** - * g_win32_output_stream_get_close_handle: - * @stream: a #GWin32OutputStream + * gxdp_network_monitor_proxy_new_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_network_monitor_proxy_new(). + * @error: Return location for error or %NULL * - * Returns whether the handle of @stream will be closed when the - * stream is closed. + * Finishes an operation started with gxdp_network_monitor_proxy_new(). * - * Returns: %TRUE if the handle is closed when done - * Since: 2.26 + * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_output_stream_get_handle: - * @stream: a #GWin32OutputStream + * gxdp_network_monitor_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. * - * Return the Windows handle that the stream writes to. + * Like gxdp_network_monitor_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * Returns: The handle descriptor of @stream - * Since: 2.26 + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_network_monitor_proxy_new_for_bus_finish() to get the result of the operation. + * + * See gxdp_network_monitor_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor. */ /** - * g_win32_output_stream_new: - * @handle: a Win32 file handle - * @close_handle: %TRUE to close the handle when done - * - * Creates a new #GWin32OutputStream for the given @handle. + * gxdp_network_monitor_proxy_new_for_bus_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_network_monitor_proxy_new_for_bus(). + * @error: Return location for error or %NULL * - * If @close_handle, is %TRUE, the handle will be closed when the - * output stream is destroyed. + * Finishes an operation started with gxdp_network_monitor_proxy_new_for_bus(). * - * Returns: a new #GOutputStream - * Since: 2.26 + * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_output_stream_set_close_handle: - * @stream: a #GWin32OutputStream - * @close_handle: %TRUE to close the handle when done + * gxdp_network_monitor_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 + * + * Like gxdp_network_monitor_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. + * + * The calling thread is blocked until a reply is received. * - * Sets whether the handle of @stream shall be closed when the stream - * is closed. + * See gxdp_network_monitor_proxy_new_for_bus() for the asynchronous version of this constructor. * - * Since: 2.26 + * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_registry_key_erase_change_indicator: - * @key: (in) (transfer none): a #GWin32RegistryKey + * gxdp_network_monitor_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 * - * Erases change indicator of the @key. + * Synchronously creates a proxy for the D-Bus interface org.freedesktop.portal.NetworkMonitor. See g_dbus_proxy_new_sync() for more details. * - * Subsequent calls to g_win32_registry_key_has_changed() will return %FALSE - * until the key is put on watch again by calling - * g_win32_registry_key_watch() again. + * The calling thread is blocked until a reply is received. * - * Since: 2.46 + * See gxdp_network_monitor_proxy_new() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpNetworkMonitorProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_registry_key_get_child: - * @key: (in) (transfer none): a parent #GWin32RegistryKey - * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key - * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL + * gxdp_network_monitor_set_available: (skip) + * @object: A #GXdpNetworkMonitor. + * @value: The value to set. * - * Opens a @subkey of the @key. + * Sets the "available" D-Bus property to @value. * - * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free - * with g_object_unref(). + * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side. */ /** - * g_win32_registry_key_get_child_w: - * @key: (in) (transfer none): a parent #GWin32RegistryKey - * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key - * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL + * gxdp_network_monitor_set_connectivity: (skip) + * @object: A #GXdpNetworkMonitor. + * @value: The value to set. * - * Opens a @subkey of the @key. + * Sets the "connectivity" D-Bus property to @value. * - * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free - * with g_object_unref(). + * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side. */ /** - * g_win32_registry_key_get_path: - * @key: (in) (transfer none): a #GWin32RegistryKey + * gxdp_network_monitor_set_metered: (skip) + * @object: A #GXdpNetworkMonitor. + * @value: The value to set. * - * Get full path to the key + * Sets the "metered" D-Bus property to @value. * - * Returns: (transfer none): a full path to the key (in UTF-8), - * or %NULL if it can't be converted to UTF-8. - * Since: 2.46 + * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side. */ /** - * g_win32_registry_key_get_path_w: - * @key: (in) (transfer none): a #GWin32RegistryKey + * gxdp_network_monitor_skeleton_new: * - * Get full path to the key + * Creates a skeleton object for the D-Bus interface org.freedesktop.portal.NetworkMonitor. * - * Returns: (transfer none): a full path to the key (in UTF-16) - * Since: 2.46 + * Returns: (transfer full) (type GXdpNetworkMonitorSkeleton): The skeleton object. */ /** - * g_win32_registry_key_get_value: - * @key: (in) (transfer none): a #GWin32RegistryKey - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR - * to G_WIN32_REGISTRY_VALUE_STR. - * @value_name: (in) (transfer none): name of the value to get (in UTF-8). - * Empty string means the '(Default)' value. - * @value_type: (out) (optional): type of the value retrieved. - * @value_data: (out callee-allocates) (optional): contents of the value. - * @value_data_size: (out) (optional): size of the buffer pointed - * by @value_data. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_open_uri_call_open_file: + * @proxy: A #GXdpOpenURIProxy. + * @arg_parent_window: Argument to pass with the method invocation. + * @arg_fd: Argument to pass with the method invocation. + * @arg_options: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @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. * - * Get data from a value of a key. String data is guaranteed to be - * appropriately terminated and will be in UTF-8. + * Asynchronously invokes the OpenFile() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_open_uri_call_open_file_finish() to get the result of the operation. * - * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.46 + * See gxdp_open_uri_call_open_file_sync() for the synchronous, blocking version of this method. */ /** - * g_win32_registry_key_get_value_w: - * @key: (in) (transfer none): a #GWin32RegistryKey - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR - * to G_WIN32_REGISTRY_VALUE_STR. - * @value_name: (in) (transfer none): name of the value to get (in UTF-16). - * Empty string means the '(Default)' value. - * @value_type: (out) (optional): type of the value retrieved. - * @value_data: (out callee-allocates) (optional): contents of the value. - * @value_data_size: (out) (optional): size of the buffer pointed - * by @value_data. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Get data from a value of a key. - * - * Get data from a value of a key. String data is guaranteed to be - * appropriately terminated and will be in UTF-16. + * gxdp_open_uri_call_open_file_finish: + * @proxy: A #GXdpOpenURIProxy. + * @out_handle: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_open_uri_call_open_file(). + * @error: Return location for error or %NULL. * - * When calling with value_data == NULL (to get data size without getting - * the data itself) remember that returned size corresponds to possibly - * unterminated string data (if value is some kind of string), because - * termination cannot be checked and fixed unless the data is retreived - * too. + * Finishes an operation started with gxdp_open_uri_call_open_file(). * - * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.46 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_win32_registry_key_has_changed: - * @key: (in) (transfer none): a #GWin32RegistryKey + * gxdp_open_uri_call_open_file_sync: + * @proxy: A #GXdpOpenURIProxy. + * @arg_parent_window: Argument to pass with the method invocation. + * @arg_fd: Argument to pass with the method invocation. + * @arg_options: Argument to pass with the method invocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @out_handle: (out): Return location for return parameter or %NULL to ignore. + * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Check the @key's status indicator. + * Synchronously invokes the OpenFile() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: %TRUE if the @key was put under watch at some point and has changed - * since then, %FALSE if it either wasn't changed or wasn't watched at all. - * Since: 2.46 + * See gxdp_open_uri_call_open_file() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_win32_registry_key_new: - * @path: absolute full name of a key to open (in UTF-8) - * @error: (nullable): a pointer to a %NULL #GError, or %NULL + * gxdp_open_uri_call_open_uri: + * @proxy: A #GXdpOpenURIProxy. + * @arg_parent_window: Argument to pass with the method invocation. + * @arg_uri: Argument to pass with the method invocation. + * @arg_options: 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. * - * Creates an object that represents a registry key specified by @path. - * @path must start with one of the following pre-defined names: - * - HKEY_CLASSES_ROOT - * - HKEY_CURRENT_CONFIG - * - HKEY_CURRENT_USER - * - HKEY_CURRENT_USER_LOCAL_SETTINGS - * - HKEY_LOCAL_MACHINE - * - HKEY_PERFORMANCE_DATA - * - HKEY_PERFORMANCE_NLSTEXT - * - HKEY_PERFORMANCE_TEXT - * - HKEY_USERS - * @path must not end with '\\'. + * Asynchronously invokes the OpenURI() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_open_uri_call_open_uri_finish() to get the result of the operation. * - * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't - * be opened. Free with g_object_unref(). + * See gxdp_open_uri_call_open_uri_sync() for the synchronous, blocking version of this method. */ /** - * g_win32_registry_key_new_w: - * @path: (in) (transfer none): absolute full name of a key to open (in UTF-16) - * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL + * gxdp_open_uri_call_open_uri_finish: + * @proxy: A #GXdpOpenURIProxy. + * @out_handle: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_open_uri_call_open_uri(). + * @error: Return location for error or %NULL. * - * Creates an object that represents a registry key specified by @path. - * @path must start with one of the following pre-defined names: - * - HKEY_CLASSES_ROOT - * - HKEY_CURRENT_CONFIG - * - HKEY_CURRENT_USER - * - HKEY_CURRENT_USER_LOCAL_SETTINGS - * - HKEY_LOCAL_MACHINE - * - HKEY_PERFORMANCE_DATA - * - HKEY_PERFORMANCE_NLSTEXT - * - HKEY_PERFORMANCE_TEXT - * - HKEY_USERS - * @path must not end with L'\\'. + * Finishes an operation started with gxdp_open_uri_call_open_uri(). * - * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't - * be opened. Free with g_object_unref(). + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_win32_registry_key_watch: - * @key: (in) (transfer none): a #GWin32RegistryKey - * @watch_children: (in): %TRUE also watch the children of the @key, %FALSE - * to watch the key only. - * @watch_flags: (in): specifies the types of changes to watch for. - * @callback: (in) (nullable): a function to invoke when a change occurs. - * @user_data: (in) (nullable): a pointer to pass to @callback on invocation. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Puts @key under a watch. - * - * When the key changes, an APC will be queued in the current thread. The APC - * will run when the current thread enters alertable state (GLib main loop - * should do that; if you are not using it, see MSDN documentation for W32API - * calls that put thread into alertable state). When it runs, it will - * atomically switch an indicator in the @key. If a callback was specified, - * it is invoked at that point. Subsequent calls to - * g_win32_registry_key_has_changed() will return %TRUE, and the callback (if - * it was specified) will not be invoked anymore. - * Calling g_win32_registry_key_erase_change_indicator() will reset the indicator, - * and g_win32_registry_key_has_changed() will start returning %FALSE. - * To resume the watch, call g_win32_registry_key_watch_for_changes() again. + * gxdp_open_uri_call_open_uri_sync: + * @proxy: A #GXdpOpenURIProxy. + * @arg_parent_window: Argument to pass with the method invocation. + * @arg_uri: Argument to pass with the method invocation. + * @arg_options: Argument to pass with the method invocation. + * @out_handle: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Calling g_win32_registry_key_watch_for_changes() for a key that is already - * being watched is allowed and affects nothing. + * Synchronously invokes the OpenURI() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * The fact that the key is being watched will be used internally to update - * key path (if it changes). + * See gxdp_open_uri_call_open_uri() for the asynchronous version of this method. * - * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.46 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_win32_registry_subkey_iter_assign: - * @iter: a #GWin32RegistrySubkeyIter - * @other: another #GWin32RegistrySubkeyIter + * gxdp_open_uri_complete_open_file: + * @object: A #GXdpOpenURI. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * @handle: Parameter to return. * - * Assigns the value of @other to @iter. This function - * is not useful in applications, because iterators can be assigned - * with `GWin32RegistrySubkeyIter i = j;`. The - * function is used by language bindings. + * Helper function used in service implementations to finish handling invocations of the OpenFile() 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.46 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_win32_registry_subkey_iter_clear: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter + * gxdp_open_uri_complete_open_uri: + * @object: A #GXdpOpenURI. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @handle: Parameter to return. * - * Frees internal buffers of a #GWin32RegistrySubkeyIter. + * Helper function used in service implementations to finish handling invocations of the OpenURI() 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.46 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_win32_registry_subkey_iter_copy: - * @iter: an iterator + * gxdp_open_uri_get_version: (skip) + * @object: A #GXdpOpenURI. * - * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated - * state of the iterator is duplicated too. + * Gets the value of the "version" D-Bus property. * - * Returns: (transfer full): a copy of the @iter, - * free with g_win32_registry_subkey_iter_free () - * Since: 2.46 + * Since this D-Bus property is readable, it is meaningful to use this function on both the client- and service-side. + * + * Returns: The property value. */ /** - * g_win32_registry_subkey_iter_free: - * @iter: a dynamically-allocated iterator + * gxdp_open_uri_interface_info: * - * Free an iterator allocated on the heap. For iterators that are allocated - * on the stack use g_win32_registry_subkey_iter_clear () instead. + * Gets a machine-readable description of the org.freedesktop.portal.OpenURI D-Bus interface. * - * Since: 2.46 + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. */ /** - * g_win32_registry_subkey_iter_get_name: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a subkey (in UTF-8). Free with g_free(). - * @subkey_name_len: (out) (optional): Pointer to a location to store the - * length of @subkey_name, in gchars, excluding NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_open_uri_override_properties: + * @klass: The class structure for a #GObject-derived class. + * @property_id_begin: The property id to assign to the first overridden property. * - * Gets the name of the subkey at the @iter potision. + * Overrides all #GObject properties in the #GXdpOpenURI interface for a concrete class. + * The properties are overridden in the order they are defined. * - * Returns: %TRUE if the name was retrieved, %FALSE otherwise. - * Since: 2.46 + * Returns: The last property id. */ /** - * g_win32_registry_subkey_iter_get_name_w: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a subkey (in UTF-16). - * @subkey_name_len: (out) (optional) (transfer none): Pointer to a location - * to store the length of @subkey_name, in gunichar2s, excluding - * NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_open_uri_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. * - * Same as g_win32_registry_subkey_iter_get_next(), but outputs UTF-16-encoded - * data, without converting it to UTF-8 first. + * Asynchronously creates a proxy for the D-Bus interface org.freedesktop.portal.OpenURI. See g_dbus_proxy_new() for more details. * - * Returns: %TRUE if the name was retrieved, %FALSE otherwise. - * Since: 2.46 + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_open_uri_proxy_new_finish() to get the result of the operation. + * + * See gxdp_open_uri_proxy_new_sync() for the synchronous, blocking version of this constructor. */ /** - * g_win32_registry_subkey_iter_init: - * @iter: (in) (transfer none): a pointer to a #GWin32RegistrySubkeyIter - * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over - * @error: (inout) (optional) (nullable): a pointer to %NULL #GError, or %NULL - * - * Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be - * completely uninitialised prior to this call; its old value is - * ignored. + * gxdp_open_uri_proxy_new_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_open_uri_proxy_new(). + * @error: Return location for error or %NULL * - * The iterator remains valid for as long as @key exists. - * Clean up its internal buffers with a call to - * g_win32_registry_subkey_iter_clear() when done. + * Finishes an operation started with gxdp_open_uri_proxy_new(). * - * Returns: %TRUE if iterator was initialized successfully, %FALSE on error. - * Since: 2.46 + * Returns: (transfer full) (type GXdpOpenURIProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_registry_subkey_iter_n_subkeys: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter + * gxdp_open_uri_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. * - * Queries the number of subkeys items in the key that we are - * iterating over. This is the total number of subkeys -- not the number - * of items remaining. + * Like gxdp_open_uri_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * This information is accurate at the point of iterator initialization, - * and may go out of sync with reality even while subkeys are enumerated. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_open_uri_proxy_new_for_bus_finish() to get the result of the operation. * - * Returns: the number of subkeys in the key - * Since: 2.46 + * See gxdp_open_uri_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor. */ /** - * g_win32_registry_subkey_iter_next: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as - * the actual number of subkeys being less than expected) and - * proceed forward - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Moves iterator to the next subkey. - * Enumeration errors can be ignored if @skip_errors is %TRUE - * - * Here is an example for iterating with g_win32_registry_subkey_iter_next(): - * |[ - * // recursively iterate a key - * void - * iterate_key_recursive (GWin32RegistryKey *key) - * { - * GWin32RegistrySubkeyIter iter; - * gchar *name; - * GWin32RegistryKey *child; - * - * if (!g_win32_registry_subkey_iter_init (&iter, key, NULL)) - * return; - * - * while (g_win32_registry_subkey_iter_next (&iter, TRUE, NULL)) - * { - * if (!g_win32_registry_subkey_iter_get_name (&iter, &name, NULL, NULL)) - * continue; - * - * g_print ("subkey '%s'\n", name); - * child = g_win32_registry_key_get_child (key, name, NULL); - * - * if (child) - * iterate_key_recursive (child); - * } + * gxdp_open_uri_proxy_new_for_bus_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_open_uri_proxy_new_for_bus(). + * @error: Return location for error or %NULL * - * g_win32_registry_subkey_iter_clear (&iter); - * } - * ]| + * Finishes an operation started with gxdp_open_uri_proxy_new_for_bus(). * - * Returns: %TRUE if next subkey info was retrieved, %FALSE otherwise. - * Since: 2.46 + * Returns: (transfer full) (type GXdpOpenURIProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_registry_value_iter_assign: - * @iter: a #GWin32RegistryValueIter - * @other: another #GWin32RegistryValueIter + * gxdp_open_uri_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 * - * Assigns the value of @other to @iter. This function - * is not useful in applications, because iterators can be assigned - * with `GWin32RegistryValueIter i = j;`. The - * function is used by language bindings. + * Like gxdp_open_uri_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * Since: 2.46 + * The calling thread is blocked until a reply is received. + * + * See gxdp_open_uri_proxy_new_for_bus() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpOpenURIProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_registry_value_iter_clear: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * gxdp_open_uri_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 * - * Frees internal buffers of a #GWin32RegistryValueIter. + * Synchronously creates a proxy for the D-Bus interface org.freedesktop.portal.OpenURI. See g_dbus_proxy_new_sync() for more details. * - * Since: 2.46 + * The calling thread is blocked until a reply is received. + * + * See gxdp_open_uri_proxy_new() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpOpenURIProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_win32_registry_value_iter_copy: - * @iter: an iterator + * gxdp_open_uri_set_version: (skip) + * @object: A #GXdpOpenURI. + * @value: The value to set. * - * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated - * state of the iterator is duplicated too. + * Sets the "version" D-Bus property to @value. * - * Returns: (transfer full): a copy of the @iter, - * free with g_win32_registry_value_iter_free (). - * Since: 2.46 + * Since this D-Bus property is not writable, it is only meaningful to use this function on the service-side. */ /** - * g_win32_registry_value_iter_free: - * @iter: a dynamically-allocated iterator + * gxdp_open_uri_skeleton_new: * - * Free an iterator allocated on the heap. For iterators that are allocated - * on the stack use g_win32_registry_value_iter_clear () instead. + * Creates a skeleton object for the D-Bus interface org.freedesktop.portal.OpenURI. * - * Since: 2.46 + * Returns: (transfer full) (type GXdpOpenURISkeleton): The skeleton object. */ /** - * g_win32_registry_value_iter_get_data: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to - * G_WIN32_REGISTRY_VALUE_STR - * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a - * location to store the data of the value (in UTF-8, if it's a string) - * @value_data_size: (out) (optional): Pointer to a location to store the length - * of @value_data, in bytes (including any NUL-terminators, if it's a string). - * %NULL if length is not needed - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_proxy_resolver_call_lookup: + * @proxy: A #GXdpProxyResolverProxy. + * @arg_uri: 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. * - * Stores the data of the value currently being iterated over in @value_data, - * and its length - in @value_data_len (if not %NULL). + * Asynchronously invokes the Lookup() D-Bus method on @proxy. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_proxy_resolver_call_lookup_finish() to get the result of the operation. * - * Returns: %TRUE if value data was retrieved, %FALSE otherwise. - * Since: 2.46 + * See gxdp_proxy_resolver_call_lookup_sync() for the synchronous, blocking version of this method. */ /** - * g_win32_registry_value_iter_get_data_w: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to - * G_WIN32_REGISTRY_VALUE_STR - * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a - * location to store the data of the value (in UTF-16, if it's a string) - * @value_data_size: (out) (optional): Pointer to a location to store the size - * of @value_data, in bytes (including any NUL-terminators, if it's a string). - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_proxy_resolver_call_lookup_finish: + * @proxy: A #GXdpProxyResolverProxy. + * @out_proxies: (out): Return location for return parameter or %NULL to ignore. + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_proxy_resolver_call_lookup(). + * @error: Return location for error or %NULL. * - * Stores the data of the value currently being iterated over in @value_data, - * and its length - in @value_data_len (if not %NULL). + * Finishes an operation started with gxdp_proxy_resolver_call_lookup(). * - * Returns: %TRUE if value data was retrieved, %FALSE otherwise. - * Since: 2.46 + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_win32_registry_value_iter_get_name: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @value_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a value (in UTF-8). - * @value_name_len: (out) (optional): Pointer to a location to store the length - * of @value_name, in gchars, excluding NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_proxy_resolver_call_lookup_sync: + * @proxy: A #GXdpProxyResolverProxy. + * @arg_uri: Argument to pass with the method invocation. + * @out_proxies: (out): Return location for return parameter or %NULL to ignore. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Stores the name of the value currently being iterated over in @value_name, - * and its length - in @value_name_len (if not %NULL). + * Synchronously invokes the Lookup() D-Bus method on @proxy. The calling thread is blocked until a reply is received. * - * Returns: %TRUE if value name was retrieved, %FALSE otherwise. - * Since: 2.46 + * See gxdp_proxy_resolver_call_lookup() for the asynchronous version of this method. + * + * Returns: (skip): %TRUE if the call succeded, %FALSE if @error is set. */ /** - * g_win32_registry_value_iter_get_name_w: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @value_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a value (in UTF-16). - * @value_name_len: (out) (optional): Pointer to a location to store the length - * of @value_name, in gunichar2s, excluding NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_proxy_resolver_complete_lookup: + * @object: A #GXdpProxyResolver. + * @invocation: (transfer full): A #GDBusMethodInvocation. + * @proxies: Parameter to return. * - * Stores the name of the value currently being iterated over in @value_name, - * and its length - in @value_name (if not %NULL). + * Helper function used in service implementations to finish handling invocations of the Lookup() 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. * - * Returns: %TRUE if value name was retrieved, %FALSE otherwise. - * Since: 2.46 + * This method will free @invocation, you cannot use it afterwards. */ /** - * g_win32_registry_value_iter_get_value_type: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @value_type: (out): Pointer to a location to store the type of - * the value. - * @error: (nullable): a pointer to %NULL #GError, or %NULL + * gxdp_proxy_resolver_interface_info: * - * Stores the type of the value currently being iterated over in @value_type. + * Gets a machine-readable description of the org.freedesktop.portal.ProxyResolver D-Bus interface. * - * Returns: %TRUE if value type was retrieved, %FALSE otherwise. - * Since: 2.46 + * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. */ /** - * g_win32_registry_value_iter_init: - * @iter: (in) (transfer none): a pointer to a #GWin32RegistryValueIter - * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Initialises (without allocating) a #GWin32RegistryValueIter. @iter may be - * completely uninitialised prior to this call; its old value is - * ignored. + * gxdp_proxy_resolver_override_properties: + * @klass: The class structure for a #GObject-derived class. + * @property_id_begin: The property id to assign to the first overridden property. * - * The iterator remains valid for as long as @key exists. - * Clean up its internal buffers with a call to - * g_win32_registry_value_iter_clear() when done. + * Overrides all #GObject properties in the #GXdpProxyResolver interface for a concrete class. + * The properties are overridden in the order they are defined. * - * Returns: %TRUE if iterator was initialized successfully, %FALSE on error. - * Since: 2.46 + * Returns: The last property id. */ /** - * g_win32_registry_value_iter_n_values: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter + * gxdp_proxy_resolver_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. * - * Queries the number of values items in the key that we are - * iterating over. This is the total number of values -- not the number - * of items remaining. + * Asynchronously creates a proxy for the D-Bus interface org.freedesktop.portal.ProxyResolver. See g_dbus_proxy_new() for more details. * - * This information is accurate at the point of iterator initialization, - * and may go out of sync with reality even while values are enumerated. + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_proxy_resolver_proxy_new_finish() to get the result of the operation. * - * Returns: the number of values in the key - * Since: 2.46 + * See gxdp_proxy_resolver_proxy_new_sync() for the synchronous, blocking version of this constructor. */ /** - * g_win32_registry_value_iter_next: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as - * the actual number of values being less than expected) and - * proceed forward - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Advances iterator to the next value in the key. If no more values remain then - * FALSE is returned. - * Enumeration errors can be ignored if @skip_errors is %TRUE - * - * Here is an example for iterating with g_win32_registry_value_iter_next(): - * |[ - * // iterate values of a key - * void - * iterate_values_recursive (GWin32RegistryKey *key) - * { - * GWin32RegistryValueIter iter; - * gchar *name; - * GWin32RegistryValueType val_type; - * gchar *val_data; - * - * if (!g_win32_registry_value_iter_init (&iter, key, NULL)) - * return; - * - * while (g_win32_registry_value_iter_next (&iter, TRUE, NULL)) - * { - * if ((!g_win32_registry_value_iter_get_value_type (&iter, &value)) || - * ((val_type != G_WIN32_REGISTRY_VALUE_STR) && - * (val_type != G_WIN32_REGISTRY_VALUE_EXPAND_STR))) - * continue; - * - * if (g_win32_registry_value_iter_get_value (&iter, TRUE, &name, NULL, - * &val_data, NULL, NULL)) - * g_print ("value '%s' = '%s'\n", name, val_data); - * } + * gxdp_proxy_resolver_proxy_new_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_proxy_resolver_proxy_new(). + * @error: Return location for error or %NULL * - * g_win32_registry_value_iter_clear (&iter); - * } - * ]| + * Finishes an operation started with gxdp_proxy_resolver_proxy_new(). * - * Returns: %TRUE if next value info was retrieved, %FALSE otherwise. - * Since: 2.46 + * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_zlib_compressor_get_file_info: - * @compressor: a #GZlibCompressor + * gxdp_proxy_resolver_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. * - * Returns the #GZlibCompressor:file-info property. + * Like gxdp_proxy_resolver_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * Returns: (transfer none): a #GFileInfo, or %NULL - * Since: 2.26 + * When the operation is finished, @callback will be invoked in the thread-default main loop of the thread you are calling this method from. + * You can then call gxdp_proxy_resolver_proxy_new_for_bus_finish() to get the result of the operation. + * + * See gxdp_proxy_resolver_proxy_new_for_bus_sync() for the synchronous, blocking version of this constructor. */ /** - * g_zlib_compressor_new: - * @format: The format to use for the compressed data - * @level: compression level (0-9), -1 for default + * gxdp_proxy_resolver_proxy_new_for_bus_finish: + * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to gxdp_proxy_resolver_proxy_new_for_bus(). + * @error: Return location for error or %NULL * - * Creates a new #GZlibCompressor. + * Finishes an operation started with gxdp_proxy_resolver_proxy_new_for_bus(). * - * Returns: a new #GZlibCompressor - * Since: 2.24 + * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_zlib_compressor_set_file_info: - * @compressor: a #GZlibCompressor - * @file_info: (nullable): a #GFileInfo + * gxdp_proxy_resolver_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 * - * Sets @file_info in @compressor. If non-%NULL, and @compressor's - * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, - * it will be used to set the file name and modification time in - * the GZIP header of the compressed data. + * Like gxdp_proxy_resolver_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * Note: it is an error to call this function while a compression is in - * progress; it may only be called immediately after creation of @compressor, - * or after resetting it with g_converter_reset(). + * The calling thread is blocked until a reply is received. * - * Since: 2.26 + * See gxdp_proxy_resolver_proxy_new_for_bus() for the asynchronous version of this constructor. + * + * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set. */ /** - * g_zlib_decompressor_get_file_info: - * @decompressor: a #GZlibDecompressor + * gxdp_proxy_resolver_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 * - * Retrieves the #GFileInfo constructed from the GZIP header data - * of compressed data processed by @compressor, or %NULL if @decompressor's - * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, - * or the header data was not fully processed yet, or it not present in the - * data stream at all. + * Synchronously creates a proxy for the D-Bus interface org.freedesktop.portal.ProxyResolver. See g_dbus_proxy_new_sync() for more details. * - * Returns: (transfer none): a #GFileInfo, or %NULL - * Since: 2.26 - */ - - -/** - * g_zlib_decompressor_new: - * @format: The format to use for the compressed data + * The calling thread is blocked until a reply is received. * - * Creates a new #GZlibDecompressor. + * See gxdp_proxy_resolver_proxy_new() for the asynchronous version of this constructor. * - * Returns: a new #GZlibDecompressor - * Since: 2.24 + * Returns: (transfer full) (type GXdpProxyResolverProxy): The constructed proxy object or %NULL if @error is set. */ /** - * get_viewable_logical_drives: + * gxdp_proxy_resolver_skeleton_new: * - * 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. + * Creates a skeleton object for the D-Bus interface org.freedesktop.portal.ProxyResolver. * - * Returns: bitmask with same meaning as returned by GetLogicalDrives() + * Returns: (transfer full) (type GXdpProxyResolverSkeleton): The skeleton object. */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 8fcf8fe5..854cee12 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -593,7 +593,7 @@ * g_direct_hash() is also the appropriate hash function for keys * of the form `GINT_TO_POINTER (n)` (or similar macros). * - * A good hash functions should produce + * A good hash functions should produce * hash values that are evenly distributed over a fairly large range. * The modulus is taken with the hash table size (a prime number) to * find the 'bucket' to place each key into. The function should also @@ -5443,7 +5443,7 @@ * in it ("/"). However, displaying file names may require conversion: * from the character set in which they were created, to the character * set in which the application operates. Consider the Spanish file name - * "Presentación.sxi". If the application which created it uses + * "Presentación.sxi". If the application which created it uses * ISO-8859-1 for its encoding, * |[ * Character: P r e s e n t a c i ó n . s x i @@ -5456,31 +5456,31 @@ * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 * ]| * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use - * GLib do the same thing. If you get a file name from the file system, + * Glib do the same thing. If you get a file name from the file system, * for example, from readdir() or from g_dir_read_name(), and you wish * to display the file name to the user, you will need to convert it * into UTF-8. The opposite case is when the user types the name of a - * file they wish to save: the toolkit will give you that string in + * file he wishes to save: the toolkit will give you that string in * UTF-8 encoding, and you will need to convert it to the character * set used for file names before you can create the file with open() * or fopen(). * - * By default, GLib assumes that file names on disk are in UTF-8 + * By default, Glib assumes that file names on disk are in UTF-8 * encoding. This is a valid assumption for file systems which * were created relatively recently: most applications use UTF-8 * encoding for their strings, and that is also what they use for * the file names they create. However, older file systems may * still contain file names created in "older" encodings, such as * ISO-8859-1. In this case, for compatibility reasons, you may want - * to instruct GLib to use that particular encoding for file names + * to instruct Glib to use that particular encoding for file names * rather than UTF-8. You can do this by specifying the encoding for * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] * environment variable. For example, if your installation uses - * ISO-8859-1 for file names, you can put this in your `~/.profile`: + * ISO-8859-1 for file names, you can put this in your `~/.profile` * |[ * export G_FILENAME_ENCODING=ISO-8859-1 * ]| - * GLib provides the functions g_filename_to_utf8() and + * Glib provides the functions g_filename_to_utf8() and * g_filename_from_utf8() to perform the necessary conversions. * These functions convert file names from the encoding specified * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This @@ -7235,13 +7235,8 @@ * * These functions provide support for allocating and freeing memory. * - * If any call to allocate memory using functions g_new(), g_new0(), g_renew(), - * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() - * fails, the application is terminated. This also means that there is no - * need to check if the call succeeded. On the other hand, g_try_...() family - * of functions returns %NULL on failure that can be used as a check - * for unsuccessful memory allocation. The application is not terminated - * in this case. + * If any call to allocate memory fails, the application is terminated. + * This also means that there is no need to check if the call succeeded. * * It's important to match g_malloc() (and wrappers such as g_new()) with * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with @@ -7841,12 +7836,6 @@ * g_sequence_move_range() will not invalidate the iterators pointing * to it. The only operation that will invalidate an iterator is when * the element it points to is removed from any sequence. - * - * To sort the data, either use g_sequence_insert_sorted() or - * g_sequence_insert_sorted_iter() to add data to the #GSequence or, if - * you want to add a large amount of data, it is more efficient to call - * g_sequence_sort() or g_sequence_sort_iter() after doing unsorted - * insertions. */ @@ -10617,9 +10606,9 @@ * * membuf = g_malloc (8192); * - * // Some computation on membuf + * /* Some computation on membuf */ * - * // membuf will be automatically freed here + * /* membuf will be automatically freed here */ * return TRUE; * } * ]| @@ -12107,12 +12096,6 @@ * A reference to @bytes will be held by the newly created #GBytes until * the byte data is no longer needed. * - * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then - * @bytes will be returned with the reference count incremented by 1. If @bytes - * is a slice of another #GBytes, then the resulting #GBytes will reference - * the same #GBytes instead of @bytes. This allows consumers to simplify the - * usage of #GBytes when asynchronously writing to streams. - * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ @@ -12853,7 +12836,7 @@ * Converts a string from one character set to another. * * Note that you should use g_iconv() for streaming conversions. - * Despite the fact that @bytes_read can return information about partial + * Despite the fact that @byes_read can return information about partial * characters, the g_convert_... functions are not generally suitable * for streaming. If the underlying converter maintains internal state, * then this won't be preserved across successive calls to g_convert(), @@ -12880,7 +12863,7 @@ * for the @len parameter is unsafe) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. - * @fallback: UTF-8 string to use in place of characters not + * @fallback: UTF-8 string to use in place of character not * present in the target encoding. (The string must be * representable in the target encoding). * If %NULL, characters not in the target encoding will @@ -12904,7 +12887,7 @@ * in which case GLib will simply return that approximate conversion. * * Note that you should use g_iconv() for streaming conversions. - * Despite the fact that @bytes_read can return information about partial + * Despite the fact that @byes_read can return information about partial * characters, the g_convert_... functions are not generally suitable * for streaming. If the underlying converter maintains internal state, * then this won't be preserved across successive calls to g_convert(), @@ -12943,7 +12926,7 @@ * Converts a string from one character set to another. * * Note that you should use g_iconv() for streaming conversions. - * Despite the fact that @bytes_read can return information about partial + * Despite the fact that @byes_read can return information about partial * characters, the g_convert_... functions are not generally suitable * for streaming. If the underlying converter maintains internal state, * then this won't be preserved across successive calls to g_convert(), @@ -12952,14 +12935,6 @@ * character until it knows that the next character is not a mark that * could combine with the base character.) * - * Characters which are valid in the input character set, but which have no - * representation in the output character set will result in a - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv() - * specification, which leaves this behaviour implementation defined. Note that - * this is the same error code as is returned for an invalid byte sequence in - * the input character set. To get defined behaviour for conversion of - * unrepresentable characters, use g_convert_with_fallback(). - * * Returns: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with * g_free(). Otherwise %NULL and @error will be set. @@ -13169,7 +13144,7 @@ * * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including - * the registered destroy notify for it (passed out in @old_destroy). + * the registred destroy notify for it (passed out in @old_destroy). * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. @@ -15701,7 +15676,7 @@ * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: (out): the number of bytes stored in the output buffer (not @@ -15714,11 +15689,6 @@ * on other platforms, this function indirectly depends on the * [current locale][setlocale]. * - * The input string shall not contain nul characters even if the @len - * argument is positive. A nul character found inside the string will result - * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Note that nul bytes are - * prohibited in all filename encodings that GLib is known to work with. - * * Returns: (array length=bytes_written) (element-type guint8) (transfer full): * The converted string, or %NULL on an error. */ @@ -15753,7 +15723,7 @@ * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: (out) (optional): the number of bytes stored in the output @@ -15766,14 +15736,6 @@ * for filenames; on other platforms, this function indirectly depends on * the [current locale][setlocale]. * - * The input string shall not contain nul characters even if the @len - * argument is positive. A nul character found inside the string will result - * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. - * If the source encoding is not UTF-8 and the conversion output contains a - * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the - * function returns %NULL. Use g_convert() to produce output that - * may contain embedded nul characters. - * * Returns: The converted string, or %NULL on an error. */ @@ -15967,10 +15929,6 @@ * handle file names. It might be different from the character set * used by the C library's current locale. * - * On Linux, the character set is found by consulting nl_langinfo() if - * available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG` - * and `CHARSET` are queried in order. - * * The return value is %TRUE if the locale's encoding is UTF-8, in that * case you can perhaps avoid calling g_convert(). * @@ -17534,13 +17492,6 @@ * GLib provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * - * Note that the behaviour of iconv() for characters which are valid in the - * input character set, but which have no representation in the output character - * set, is implementation defined. This function may return success (with a - * positive number of non-reversible conversions as replacement characters were - * used), or it may return -1 and set an error such as %EILSEQ, in such a - * situation. - * * Returns: count of non-reversible conversions, or -1 on error */ @@ -18651,29 +18602,6 @@ */ -/** - * g_key_file_get_locale_for_key: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @locale: (nullable): a locale identifier or %NULL - * - * Returns the actual locale which the result of - * g_key_file_get_locale_string() or g_key_file_get_locale_string_list() - * came from. - * - * If calling g_key_file_get_locale_string() or - * g_key_file_get_locale_string_list() with exactly the same @key_file, - * @group_name, @key and @locale, the result of those functions will - * have originally been tagged with the locale that is the result of - * this function. - * - * Returns: (nullable): the locale from the file, or %NULL if the key was not - * found or the entry in the file was was untranslated - * Since: 2.56 - */ - - /** * g_key_file_get_locale_string: * @key_file: a #GKeyFile @@ -19860,13 +19788,15 @@ * g_locale_from_utf8: * @utf8string: a UTF-8 encoded string * @len: the length of the string, or -1 if the string is - * nul-terminated. + * nul-terminated (Note that some encodings may allow nul + * bytes to occur inside strings. In that case, using -1 + * for the @len parameter is unsafe) * @bytes_read: (out) (optional): location to store the number of bytes in the * input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: (out) (optional): the number of bytes stored in the output @@ -19879,11 +19809,6 @@ * system) in the [current locale][setlocale]. On Windows this means * the system codepage. * - * The input string shall not contain nul characters even if the @len - * argument is positive. A nul character found inside the string will result - * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert - * input that may contain embedded nul characters. - * * Returns: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. */ @@ -19902,7 +19827,7 @@ * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: (out) (optional): the number of bytes stored in the output @@ -19914,14 +19839,6 @@ * the C runtime (usually the same as that used by the operating * system) in the [current locale][setlocale] into a UTF-8 string. * - * If the source encoding is not UTF-8 and the conversion output contains a - * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the - * function returns %NULL. - * If the source encoding is UTF-8, an embedded nul character is treated with - * the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with - * earlier versions of this library. Use g_convert() to produce output that - * may contain embedded nul characters. - * * Returns: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. */ @@ -26407,10 +26324,6 @@ * if the first item comes before the second, and a positive value * if the second item comes before the first. * - * Note that when adding a large amount of data to a #GSequence, - * it is more efficient to do unsorted insertions and then call - * g_sequence_sort() or g_sequence_sort_iter(). - * * Returns: (transfer none): a #GSequenceIter pointing to the new item. * Since: 2.14 */ @@ -26437,10 +26350,6 @@ * first iterator comes before the second, and a positive value * if the second iterator comes before the first. * - * Note that when adding a large amount of data to a #GSequence, - * it is more efficient to do unsorted insertions and then call - * g_sequence_sort() or g_sequence_sort_iter(). - * * Returns: (transfer none): a #GSequenceIter pointing to the new item * Since: 2.14 */ @@ -26581,7 +26490,10 @@ * the second item comes before the first. * * This function will fail if the data contained in the sequence is - * unsorted. + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. * * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of the * first item found equal to @data according to @cmp_func and @@ -26606,7 +26518,10 @@ * value if the second iterator comes before the first. * * This function will fail if the data contained in the sequence is - * unsorted. + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. * * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of * the first item found equal to @data according to @cmp_func @@ -26739,7 +26654,10 @@ * consider using g_sequence_lookup(). * * This function will fail if the data contained in the sequence is - * unsorted. + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. * * Returns: (transfer none): an #GSequenceIter pointing to the position where @data * would have been inserted according to @cmp_func and @cmp_data @@ -26766,7 +26684,10 @@ * consider using g_sequence_lookup_iter(). * * This function will fail if the data contained in the sequence is - * unsorted. + * unsorted. Use g_sequence_insert_sorted() or + * g_sequence_insert_sorted_iter() to add data to your sequence or, if + * you want to add a large amount of data, call g_sequence_sort() after + * doing unsorted insertions. * * Returns: (transfer none): a #GSequenceIter pointing to the position in @seq * where @data would have been inserted according to @iter_cmp @@ -34148,9 +34069,6 @@ * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all * text before trying to use UTF-8 utility functions with it.) * - * Note you must ensure @dest is at least 4 * @n to fit the - * largest possible UTF-8 characters - * * Returns: @dest */ @@ -36121,7 +36039,7 @@ * GVariant *new_variant; * * new_variant = g_variant_new ("(t^as)", - * // This cast is required. + * /* This cast is required. */ * (guint64) some_flags, * some_strings); * ]| @@ -38172,9 +38090,7 @@ * goffset: * * A signed integer type that is used for file offsets, - * corresponding to the POSIX type `off_t` as if compiling with - * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on - * 32-bit architectures. + * corresponding to the C99 type off64_t. * Values of this type can range from #G_MINOFFSET to * #G_MAXOFFSET. * diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 5e6f3bc9..f52cc7ca 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -902,17 +902,22 @@ /** * g_cclosure_marshal_BOOLEAN__FLAGS: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue which can store the returned #gboolean - * @n_param_values: 2 - * @param_values: a #GValue array holding instance and arg1 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter - * denotes a flags type. + * A #GClosureMarshal function for use with signals with handlers that + * take a flags type as an argument and return a boolean. If you have + * such a signal, you will probably also need to use an accumulator, + * such as g_signal_accumulator_true_handled(). */ @@ -972,23 +977,39 @@ /** * g_cclosure_marshal_BOOL__FLAGS: + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). + * An old alias for g_cclosure_marshal_BOOLEAN__FLAGS(). */ /** * g_cclosure_marshal_STRING__OBJECT_POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue, which can store the returned string - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with handlers that + * take a #GObject and a pointer and produce a string. It is highly + * unlikely that your signal handler fits this description. */ @@ -1013,16 +1034,20 @@ /** * g_cclosure_marshal_VOID__BOOLEAN: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gboolean parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * boolean argument. */ @@ -1047,16 +1072,20 @@ /** * g_cclosure_marshal_VOID__BOXED: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GBoxed* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * argument which is any boxed pointer type. */ @@ -1081,16 +1110,20 @@ /** * g_cclosure_marshal_VOID__CHAR: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * character argument. */ @@ -1115,16 +1148,20 @@ /** * g_cclosure_marshal_VOID__DOUBLE: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gdouble parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with one + * double-precision floating point argument. */ @@ -1149,16 +1186,20 @@ /** * g_cclosure_marshal_VOID__ENUM: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the enumeration parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + * A #GClosureMarshal function for use with signals with a single + * argument with an enumerated type. */ @@ -1183,16 +1224,20 @@ /** * g_cclosure_marshal_VOID__FLAGS: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the flags parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + * A #GClosureMarshal function for use with signals with a single + * argument with a flags types. */ @@ -1217,16 +1262,20 @@ /** * g_cclosure_marshal_VOID__FLOAT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gfloat parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with one + * single-precision floating point argument. */ @@ -1251,16 +1300,20 @@ /** * g_cclosure_marshal_VOID__INT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gint parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * integer argument. */ @@ -1285,16 +1338,20 @@ /** * g_cclosure_marshal_VOID__LONG: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #glong parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with with a single + * long integer argument. */ @@ -1319,16 +1376,20 @@ /** * g_cclosure_marshal_VOID__OBJECT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GObject* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * #GObject argument. */ @@ -1353,16 +1414,20 @@ /** * g_cclosure_marshal_VOID__PARAM: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * argument of type #GParamSpec. */ @@ -1387,16 +1452,24 @@ /** * g_cclosure_marshal_VOID__POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gpointer parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single raw + * pointer argument type. + * + * If it is possible, it is better to use one of the more specific + * functions such as g_cclosure_marshal_VOID__OBJECT() or + * g_cclosure_marshal_VOID__OBJECT(). */ @@ -1421,16 +1494,20 @@ /** * g_cclosure_marshal_VOID__STRING: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single string + * argument. */ @@ -1455,16 +1532,20 @@ /** * g_cclosure_marshal_VOID__UCHAR: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guchar parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * unsigned character argument. */ @@ -1489,31 +1570,39 @@ /** * g_cclosure_marshal_VOID__UINT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guint parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with with a single + * unsigned integer argument. */ /** * g_cclosure_marshal_VOID__UINT_POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a unsigned int + * and a pointer as arguments. */ @@ -1557,16 +1646,20 @@ /** * g_cclosure_marshal_VOID__ULONG: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gulong parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * unsigned long integer argument. */ @@ -1591,18 +1684,20 @@ /** * g_cclosure_marshal_VOID__VARIANT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GVariant* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * Since: 2.26 + * A #GClosureMarshal function for use with signals with a single + * #GVariant argument. */ @@ -1627,16 +1722,19 @@ /** * g_cclosure_marshal_VOID__VOID: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 1 - * @param_values: a #GValue array holding only the instance - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: 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: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with no arguments. */ @@ -3104,7 +3202,7 @@ * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including * the registered destroy notify for it (passed out in @old_destroy). - * It’s up to the caller to free this as needed, which may + * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * @@ -3133,7 +3231,7 @@ * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including * the registered destroy notify for it (passed out in @old_destroy). - * It’s up to the caller to free this as needed, which may + * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * -- cgit v1.2.1