If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. Since: 2.28 The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GActionGroup. It is immutable. Since: 2.28 The type of the parameter that must be given when activating the action. This is immutable, and may be %NULL if no parameter is needed when activating the action. Since: 2.28 The state of the action, or %NULL if the action is stateless. Since: 2.28 The #GVariantType of the state that the action has, or %NULL if the action is stateless. This is immutable. Since: 2.28 Signals that a new action was just added to the group. This signal is emitted after the action has been added and is now visible. Since: 2.28 the #GActionGroup that changed the name of the action in @action_group Signals that the enabled status of the named action has changed. Since: 2.28 the #GActionGroup that changed the name of the action in @action_group whether the action is enabled or not Signals that an action is just about to be removed from the group. This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler. Since: 2.28 the #GActionGroup that changed the name of the action in @action_group Signals that the state of the named action has changed. Since: 2.28 the #GActionGroup that changed the name of the action in @action_group the new value of the state Flags used when creating a #GAppInfo. No flags. Application opens in a terminal window. Application supports URI arguments. Application supports startup notification. Since 2.26 Signal emitted when the app info database for changes (ie: newly installed or removed applications). The #GAppLaunchContext::launch-failed signal is emitted when a #GAppInfo launch fails. The startup notification id is provided, so that the launcher can cancel the startup notification. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance. Since: 2.36 the object emitting the signal the startup notification id for the failed launch The #GAppLaunchContext::launch-started signal is emitted when a #GAppInfo is about to be launched. If non-null the @platform_data is an GVariant dictionary mapping strings to variants (ie `a{sv}`), which contains additional, platform-specific data about this launch. On UNIX, at least the `startup-notification-id` keys will be present. The value of the `startup-notification-id` key (type `s`) is a startup notification ID corresponding to the format from the [startup-notification specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt). It allows tracking the progress of the launchee through startup. It is guaranteed that this signal is followed by either a #GAppLaunchContext::launched or #GAppLaunchContext::launch-failed signal. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance. Since: 2.72 the object emitting the signal the #GAppInfo that is about to be launched additional platform-specific data for this launch The #GAppLaunchContext::launched signal is emitted when a #GAppInfo is successfully launched. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one time for each spawned instance. The @platform_data is an GVariant dictionary mapping strings to variants (ie `a{sv}`), which contains additional, platform-specific data about this launch. On UNIX, at least the `pid` and `startup-notification-id` keys will be present. Since 2.72 the `pid` may be 0 if the process id wasn't known (for example if the process was launched via D-Bus). The `pid` may not be set at all in subsequent releases. On Windows, `pid` is guaranteed to be valid only for the duration of the #GAppLaunchContext::launched signal emission; after the signal is emitted, GLib will call g_spawn_close_pid(). If you need to keep the #GPid after the signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. Since: 2.36 the object emitting the signal the #GAppInfo that was just launched additional platform-specific data for this launch The ::activate signal is emitted on the primary instance when an activation occurs. See g_application_activate(). the application The ::command-line signal is emitted on the primary instance when a commandline is not handled locally. See g_application_run() and the #GApplicationCommandLine documentation for more information. the application a #GApplicationCommandLine representing the passed commandline An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status(). The ::handle-local-options signal is emitted on the local instance after the parsing of the commandline options has occurred. You can add options to be recognised during commandline option parsing using g_application_add_main_option_entries() and g_application_add_option_group(). Signal handlers can inspect @options (along with values pointed to from the @arg_data of an installed #GOptionEntrys) in order to decide to perform certain actions, including direct local handling (which may be useful for options like --version). In the event that the application is marked %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will send the @options dictionary to the primary instance where it can be read with g_application_command_line_get_options_dict(). The signal handler can modify the dictionary before returning, and the modified dictionary will be sent. In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set, "normal processing" will treat the remaining uncollected command line arguments as filenames or URIs. If there are no arguments, the application is activated by g_application_activate(). One or more arguments results in a call to g_application_open(). If you want to handle the local commandline arguments for yourself by converting them to calls to g_application_open() or g_action_group_activate_action() then you must be sure to register the application first. You should probably not call g_application_activate() for yourself, however: just return -1 and allow the default handler to do it for you. This will ensure that the `--gapplication-service` switch works properly (i.e. no activation in that case). Note that this signal is emitted from the default implementation of local_command_line(). If you override that function and don't chain up then this signal will never be emitted. You can override local_command_line() if you need more powerful capabilities than what is provided here, but this should not normally be required. Since: 2.40 the application the options dictionary an exit code. If you have handled your options and want to exit the process, return a non-negative option, 0 for success, and a positive value for failure. To continue, return -1 to let the default option processing continue. The ::name-lost signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the %G_APPLICATION_ALLOW_REPLACEMENT flag. The default handler for this signal calls g_application_quit(). Since: 2.60 the application %TRUE if the signal has been handled The ::open signal is emitted on the primary instance when there are files to open. See g_application_open() for more information. the application an array of #GFiles the length of @files a hint provided by the calling instance The ::shutdown signal is emitted only on the registered primary instance immediately after the main loop terminates. the application The ::startup signal is emitted on the primary instance immediately after registration. See g_application_register(). the application Whether the application is currently marked as busy through g_application_mark_busy() or g_application_bind_busy_property(). Since: 2.44 Flags used to define the behaviour of a #GApplication. Since: 2.28 Default. Deprecated in 2.74, use %G_APPLICATION_DEFAULT_FLAGS instead Default flags. Since: 2.74 Run as a service. In this mode, registration fails if the service is already running, and the application will initially wait up to 10 seconds for an initial activation message to arrive. Don't try to become the primary instance. This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for details. This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details. Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected to use the `GIT_COMMITTER_NAME` environment variable when editing a git commit message. The environment is available to the #GApplication::command-line signal handler, via g_application_command_line_getenv(). Make no attempts to do any of the typical single-instance application negotiation, even if the application ID is given. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process. Since: 2.30. Allow users to override the application ID from the command line with `--gapplication-app-id`. Since: 2.48 Allow another instance to take over the bus name. Since: 2.60 Take over from another instance. This flag is usually set by passing `--gapplication-replace` on the commandline. Since: 2.60 #GAskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation. operation requires a password. operation requires a username. operation requires a domain. operation supports saving settings. operation supports anonymous users. operation takes TCRYPT parameters (Since: 2.58) Flags used in g_bus_own_name(). Since: 2.26 No flags set. Allow another message bus connection to claim the name. If another message bus connection owns the name and have specified %G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. If another message bus connection owns the name, immediately return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54) Flags used in g_bus_watch_name(). Since: 2.26 No flags set. If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name. An enumeration for well-known message buses. Since: 2.26 An alias for the message bus that activated the process, if any. Not a message bus. The system-wide message bus. The login session message bus. The bytes containing the icon. Emitted when the operation has been cancelled. Can be used by implementations of cancellable operations. If the operation is cancelled from another thread, the signal will be emitted in the thread that cancelled the operation, not the thread that is running the operation. Note that disconnecting from this signal (or any signal) in a multi-threaded program is prone to race conditions. For instance it is possible that a signal handler may be invoked even after a call to g_signal_handler_disconnect() for that handler has already returned. There is also a problem when cancellation happens right before connecting to the signal. If this happens the signal will unexpectedly not be emitted, and checking before connecting to the signal leaves a race condition where this is still happening. In order to make it safe and easy to connect handlers there are two helper functions: g_cancellable_connect() and g_cancellable_disconnect() which protect against problems like this. An example of how to us this: |[<!-- language="C" --> // Make sure we don't do unnecessary work if already cancelled if (g_cancellable_set_error_if_cancelled (cancellable, error)) return; // Set up all the data needed to be able to handle cancellation // of the operation my_data = my_data_new (...); id = 0; if (cancellable) id = g_cancellable_connect (cancellable, G_CALLBACK (cancelled_handler) data, NULL); // cancellable operation here... g_cancellable_disconnect (cancellable, id); // cancelled_handler is never called after this, it is now safe // to free the data my_data_free (my_data); ]| Note that the cancelled signal is emitted in the thread that the user cancelled from, which may be the main thread. So, the cancellable signal should not do something that can block. a #GCancellable. Flags used when calling a g_converter_convert(). Since: 2.24 No flags. At end of input data Flush data Results returned from g_converter_convert(). Since: 2.24 There was an error during conversion. Some data was consumed or produced The conversion is finished Flushing is finished Enumeration describing different kinds of native credential types. Since: 2.26 Indicates an invalid native credential type. The native credentials type is a `struct ucred`. The native credentials type is a `struct cmsgcred`. The native credentials type is a `struct sockpeercred`. Added in 2.30. The native credentials type is a `ucred_t`. Added in 2.40. The native credentials type is a `struct unpcbid`. Added in 2.42. The native credentials type is a `struct xucred`. Added in 2.66. The native credentials type is a PID `DWORD`. Added in 2.72. If authenticating as a server, this property contains the received credentials, if any. If authenticating as a client, the property contains the credentials that were sent, if any. Emitted to check if @mechanism is allowed to be used. Since: 2.34 The #GDBusAuthObserver emitting the signal. The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. Emitted to check if a peer that is successfully authenticated is authorized. Since: 2.26 The #GDBusAuthObserver emitting the signal. A #GIOStream for the #GDBusConnection. Credentials received from the peer or %NULL. %TRUE if the peer is authorized, %FALSE if not. Flags used in g_dbus_connection_call() and similar APIs. Since: 2.26 No flags set. The bus must not launch an owner for the destination name in response to this method invocation. the caller is prepared to wait for interactive authorization. Since 2.46. Capabilities negotiated with the remote peer. Since: 2.26 No flags set. The connection supports exchanging UNIX file descriptors with the remote peer. Emitted when the connection is closed. The cause of this event can be - If g_dbus_connection_close() is called. In this case @remote_peer_vanished is set to %FALSE and @error is %NULL. - If the remote peer closes the connection. In this case @remote_peer_vanished is set to %TRUE and @error is set. - If the remote peer sends invalid or malformed data. In this case @remote_peer_vanished is set to %FALSE and @error is set. Upon receiving this signal, you should give up your reference to @connection. You are guaranteed that this signal is emitted only once. Since: 2.26 the #GDBusConnection emitting the signal %TRUE if @connection is closed because the remote peer closed its end of the connection a #GError with more details about the event or %NULL A D-Bus address specifying potential endpoints that can be used when establishing the connection. Since: 2.26 A #GDBusAuthObserver object to assist in the authentication process or %NULL. Since: 2.26 Flags from the #GDBusCapabilityFlags enumeration representing connection features negotiated with the other peer. Since: 2.26 A boolean specifying whether the connection has been closed. Since: 2.26 A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer. Note that #GDBusConnection objects returned by g_bus_get_finish() and g_bus_get_sync() will (usually) have this property set to %TRUE. Since: 2.26 Flags from the #GDBusConnectionFlags enumeration. Since: 2.26 The GUID of the peer performing the role of server when authenticating. If you are constructing a #GDBusConnection and pass %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the #GDBusConnection:flags property then you **must** also set this property to a valid guid. If you are constructing a #GDBusConnection and pass %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the #GDBusConnection:flags property you will be able to read the GUID of the other peer here after the connection has been successfully initialized. Note that the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the term ‘GUID’ for historical reasons. Despite its name, the format of #GDBusConnection:guid does not follow [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft GUID format. Since: 2.26 A boolean specifying whether the message is locked. Since: 2.26 The underlying #GIOStream used for I/O. If this is passed on construction and is a #GSocketConnection, then the corresponding #GSocket will be put into non-blocking mode. While the #GDBusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly. Since: 2.26 The unique name as assigned by the message bus or %NULL if the connection is not open or not a message bus connection. Since: 2.26 Flags used when creating a new #GDBusConnection. Since: 2.26 No flags set. Perform authentication against server. Perform authentication against client. When authenticating as a server, allow the anonymous authentication method. Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup. If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called. When authenticating as a server, require the UID of the peer to be the same as the UID of the server. (Since: 2.68) When authenticating, try to use protocols that work across a Linux user namespace boundary, even if this reduces interoperability with older D-Bus implementations. This currently affects client-side `EXTERNAL` authentication, for which this flag makes connections to a server in another user namespace succeed, but causes a deadlock when connecting to a GDBus server older than 2.73.3. Since: 2.74 Error codes for the %G_DBUS_ERROR error domain. Since: 2.26 A generic error; "something went wrong" - see the error message for more. There was not enough memory to complete an operation. The bus doesn't know how to launch a service to supply the bus name you wanted. The bus name you referenced doesn't exist (i.e. no application owns it). No reply to a message expecting one, usually means a timeout occurred. Something went wrong reading or writing to a socket, for example. A D-Bus bus address was malformed. Requested operation isn't supported (like ENOSYS on UNIX). Some limited resource is exhausted. Security restrictions don't allow doing what you're trying to do. Authentication didn't work. Unable to connect to server (probably caused by ECONNREFUSED on a socket). Certain timeout errors, possibly ETIMEDOUT on a socket. Note that %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also exists. We can't fix it for compatibility reasons so just be careful. No network access (probably ENETUNREACH on a socket). Can't bind a socket since its address is in use (i.e. EADDRINUSE). The connection is disconnected and you're trying to use it. Invalid arguments passed to a method call. Missing file. Existing file and the operation you're using does not silently overwrite. Method name you invoked isn't known by the object you invoked it on. Object you invoked a method on isn't known. Since 2.42 Interface you invoked a method on isn't known by the object. Since 2.42 Property you tried to access isn't known by the object. Since 2.42 Property you tried to set is read-only. Since 2.42 Certain timeout errors, e.g. while starting a service. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We can't fix it for compatibility reasons so just be careful. Tried to remove or modify a match rule that didn't exist. The match rule isn't syntactically valid. While starting a new process, the exec() call failed. While starting a new process, the fork() call failed. While starting a new process, the child exited with a status code. While starting a new process, the child exited on a signal. While starting a new process, something went wrong. We failed to setup the environment correctly. We failed to setup the config parser correctly. Bus name was not valid. Service file not found in system-services directory. Permissions are incorrect on the setuid helper. Service file invalid (Name, User or Exec missing). Tried to get a UNIX process ID and it wasn't available. Tried to get a UNIX process ID and it wasn't available. A type signature is not valid. A file contains invalid syntax or is otherwise broken. Asked for SELinux security context and it wasn't available. Asked for ADT audit data and it wasn't available. There's already an object with the requested object path. Emitted when a method is invoked by a remote caller and used to determine if the method call is authorized. Note that this signal is emitted in a thread dedicated to handling the method call so handlers are allowed to perform blocking IO. This means that it is appropriate to call e.g. [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync) with the [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS) flag set. If %FALSE is returned then no further handlers are run and the signal handler must take a reference to @invocation and finish handling the call (e.g. return an error via g_dbus_method_invocation_return_error()). Otherwise, if %TRUE is returned, signal emission continues. If no handlers return %FALSE, then the method is dispatched. If @interface has an enclosing #GDBusObjectSkeleton, then the #GDBusObjectSkeleton::authorize-method signal handlers run before the handlers for this signal. The default class handler just returns %TRUE. Please note that the common case is optimized: if no signals handlers are connected and the default class handler isn't overridden (for both @interface and the enclosing #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does not have the %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD flags set, no dedicated thread is ever used and the call will be handled in the same thread as the object that @interface belongs to was exported in. Since: 2.30 The #GDBusInterfaceSkeleton emitting the signal. A #GDBusMethodInvocation. %TRUE if the call is authorized, %FALSE otherwise. Flags from the #GDBusInterfaceSkeletonFlags enumeration. Since: 2.30 Flags describing the behavior of a #GDBusInterfaceSkeleton instance. Since: 2.30 No flags set. Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must use locking to access data structures used by other threads. Enumeration used to describe the byte order of a D-Bus message. Since: 2.26 The byte order is big endian. The byte order is little endian. Message flags used in #GDBusMessage. Since: 2.26 No flags set. A reply is not expected. The bus must not launch an owner for the destination name in response to this message. If set on a method call, this flag means that the caller is prepared to wait for interactive authorization. Since 2.46. Header fields used in #GDBusMessage. Since: 2.26 Not a valid header field. The object path. The interface name. The method or signal name. The name of the error that occurred. The serial number the message is a reply to. The name the message is intended for. Unique name of the sender of the message (filled in by the bus). The signature of the message body. The number of UNIX file descriptors that accompany the message. Message types used in #GDBusMessage. Since: 2.26 Message is of invalid type. Method call. Method reply. Error reply. Signal emission. Emitted when @interface is added to @object. Since: 2.30 The #GDBusObject emitting the signal. The #GDBusInterface that was added. Emitted when @interface is removed from @object. Since: 2.30 The #GDBusObject emitting the signal. The #GDBusInterface that was removed. Emitted when @interface is added to @object. This signal exists purely as a convenience to avoid having to connect signals to all objects managed by @manager. Since: 2.30 The #GDBusObjectManager emitting the signal. The #GDBusObject on which an interface was added. The #GDBusInterface that was added. Emitted when @interface has been removed from @object. This signal exists purely as a convenience to avoid having to connect signals to all objects managed by @manager. Since: 2.30 The #GDBusObjectManager emitting the signal. The #GDBusObject on which an interface was removed. The #GDBusInterface that was removed. Emitted when @object is added to @manager. Since: 2.30 The #GDBusObjectManager emitting the signal. The #GDBusObject that was added. Emitted when @object is removed from @manager. Since: 2.30 The #GDBusObjectManager emitting the signal. The #GDBusObject that was removed. Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both @changed_properties and @invalidated_properties are guaranteed to never be %NULL (either may be empty though). This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by @manager. This signal is emitted in the [thread-default main context][g-main-context-push-thread-default] that @manager was constructed in. Since: 2.30 The #GDBusObjectManagerClient emitting the signal. The #GDBusObjectProxy on which an interface has properties that are changing. The #GDBusProxy that has properties that are changing. A #GVariant containing the properties that changed (type: `a{sv}`). A %NULL terminated array of properties that were invalidated. Emitted when a D-Bus signal is received on @interface_proxy. This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by @manager. This signal is emitted in the [thread-default main context][g-main-context-push-thread-default] that @manager was constructed in. Since: 2.30 The #GDBusObjectManagerClient emitting the signal. The #GDBusObjectProxy on which an interface is emitting a D-Bus signal. The #GDBusProxy that is emitting a D-Bus signal. The sender of the signal or NULL if the connection is not a bus connection. The signal name. A #GVariant tuple with parameters for the signal. If this property is not %G_BUS_TYPE_NONE, then #GDBusObjectManagerClient:connection must be %NULL and will be set to the #GDBusConnection obtained by calling g_bus_get() with the value of this property. Since: 2.30 The #GDBusConnection to use. Since: 2.30 Flags from the #GDBusObjectManagerClientFlags enumeration. Since: 2.30 A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data. Since: 2.30 The #GDBusProxyTypeFunc to use when determining what #GType to use for interface proxies or %NULL. Since: 2.30 The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. Since: 2.30 The well-known name or unique name that the manager is for. Since: 2.30 The unique name that owns #GDBusObjectManagerClient:name or %NULL if no-one is currently owning the name. Connect to the #GObject::notify signal to track changes to this property. Since: 2.30 The object path the manager is for. Since: 2.30 Flags used when constructing a #GDBusObjectManagerClient. Since: 2.30 No flags set. If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in managers for well-known names. The #GDBusConnection to export objects on. Since: 2.30 The object path to register the manager object at. Since: 2.30 The connection of the proxy. Since: 2.30 The object path of the proxy. Since: 2.30 Emitted when a method is invoked by a remote caller and used to determine if the method call is authorized. This signal is like #GDBusInterfaceSkeleton's #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is for the enclosing object. The default class handler just returns %TRUE. Since: 2.30 The #GDBusObjectSkeleton emitting the signal. The #GDBusInterfaceSkeleton that @invocation is for. A #GDBusMethodInvocation. %TRUE if the call is authorized, %FALSE otherwise. The object path where the object is exported. Since: 2.30 Flags describing the access control of a D-Bus property. Since: 2.26 No flags set. Property is readable. Property is writable. Emitted when one or more D-Bus properties on @proxy changes. The local cache has already been updated when this signal fires. Note that both @changed_properties and @invalidated_properties are guaranteed to never be %NULL (either may be empty though). If the proxy has the flag %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then @invalidated_properties will always be empty. This signal corresponds to the `PropertiesChanged` D-Bus signal on the `org.freedesktop.DBus.Properties` interface. Since: 2.26 The #GDBusProxy emitting the signal. A #GVariant containing the properties that changed (type: `a{sv}`) A %NULL terminated array of properties that was invalidated Emitted when a signal from the remote object and interface that @proxy is for, has been received. Since 2.72 this signal supports detailed connections. You can connect to the detailed signal `g-signal::x` in order to receive callbacks only when signal `x` is received from the remote object. Since: 2.26 The #GDBusProxy emitting the signal. The sender of the signal or %NULL if the connection is not a bus connection. The name of the signal. A #GVariant tuple with parameters for the signal. If this property is not %G_BUS_TYPE_NONE, then #GDBusProxy:g-connection must be %NULL and will be set to the #GDBusConnection obtained by calling g_bus_get() with the value of this property. Since: 2.26 The #GDBusConnection the proxy is for. Since: 2.26 The timeout to use if -1 (specifying default timeout) is passed as @timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions. This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to %G_MAXINT, then no timeout is used. Since: 2.26 Flags from the #GDBusProxyFlags enumeration. Since: 2.26 Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given #GDBusInterfaceInfo is said to be the "expected interface". The checks performed are: - When completing a method call, if the type signature of the reply message isn't what's expected, the reply is discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - Received signals that have a type signature mismatch are dropped and a warning is logged via g_warning(). - Properties received via the initial `GetAll()` call or via the `::PropertiesChanged` signal (on the [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) interface) or set using g_dbus_proxy_set_cached_property() with a type signature mismatch are ignored and a warning is logged via g_warning(). Note that these checks are never done on methods, signals and properties that are not referenced in the given #GDBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break. Since: 2.26 The D-Bus interface name the proxy is for. Since: 2.26 The well-known or unique name that the proxy is for. Since: 2.26 The unique name that owns #GDBusProxy:g-name or %NULL if no-one currently owns that name. You may connect to #GObject::notify signal to track changes to this property. Since: 2.26 The object path the proxy is for. Since: 2.26 Flags used when constructing an instance of a #GDBusProxy derived class. Since: 2.26 No flags set. Don't load properties. Don't connect to signals on the remote object. If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization or a method call. This flag is only meaningful in proxies for well-known names. If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32. If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization, but allow it to be autostarted by a method call. This flag is only meaningful in proxies for well-known names, and only if %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified. Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). (Since: 2.72) Flags used when sending #GDBusMessages on a #GDBusConnection. Since: 2.26 No flags set. Do not automatically assign a serial number from the #GDBusConnection object when sending a message. Emitted when a new authenticated connection has been made. Use g_dbus_connection_get_peer_credentials() to figure out what identity (if any), was authenticated. If you want to accept the connection, take a reference to the @connection object and return %TRUE. When you are done with the connection call g_dbus_connection_close() and give up your reference. Note that the other peer may disconnect at any time - a typical thing to do when accepting a connection is to listen to the #GDBusConnection::closed signal. If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD then the signal is emitted in a new thread dedicated to the connection. Otherwise the signal is emitted in the [thread-default main context][g-main-context-push-thread-default] of the thread that @server was constructed in. You are guaranteed that signal handlers for this signal runs before incoming messages on @connection are processed. This means that it's suitable to call g_dbus_connection_register_object() or similar from the signal handler. Since: 2.26 The #GDBusServer emitting the signal. A #GDBusConnection for the new connection. %TRUE to claim @connection, %FALSE to let other handlers run. Whether the server is currently active. Since: 2.26 The D-Bus address to listen on. Since: 2.26 A #GDBusAuthObserver object to assist in the authentication process or %NULL. Since: 2.26 The D-Bus address that clients can use. Since: 2.26 Flags from the #GDBusServerFlags enumeration. Since: 2.26 The GUID of the server. See #GDBusConnection:guid for more details. Since: 2.26 Flags used when creating a #GDBusServer. Since: 2.26 No flags set. All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details). Allow the anonymous authentication method. Require the UID of the peer to be the same as the UID of the server when authenticating. (Since: 2.68) Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). Since: 2.26 No flags set. Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). Match first arguments that contain a bus or interface name with the given namespace. Match first arguments that contain an object path that is either equivalent to the given path, or one of the paths is a subpath of the other. Flags passed to g_dbus_connection_register_subtree(). Since: 2.26 No flags set. Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. The :byte-order property determines the byte ordering that is used when reading multi-byte entities (such as integers) from the stream. The :newline-type property determines what is considered as a line ending when reading complete lines from the stream. Determines the byte ordering that is used when writing multi-byte entities (such as integers) to the stream. #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures. Selects Big Endian byte order. Selects Little Endian byte order. Selects endianness based on host machine's architecture. #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. Selects "LF" line endings, common on most modern UNIX platforms. Selects "CR" line endings. Selects "CR, LF" line ending, common on Microsoft Windows. Automatically try to handle any line ending type. %TRUE if debug output should be exposed (for example by forwarding it to the journal), %FALSE otherwise. Since: 2.72 Emitted when a D-Bus peer is trying to change the debug settings and used to determine if that is authorized. This signal is emitted in a dedicated worker thread, so handlers are allowed to perform blocking I/O. This means that, for example, it is appropriate to call `polkit_authority_check_authorization_sync()` to check authorization using polkit. If %FALSE is returned then no further handlers are run and the request to change the debug settings is rejected. Otherwise, if %TRUE is returned, signal emission continues. If no handlers return %FALSE, then the debug settings are allowed to be changed. Signal handlers must not modify @invocation, or cause it to return a value. The default class handler just returns %TRUE. Since: 2.72 The #GDebugControllerDBus emitting the signal. A #GDBusMethodInvocation. %TRUE if the call is authorized, %FALSE otherwise. The D-Bus connection to expose the debugging interface on. Typically this will be the same connection (to the system or session bus) which the rest of the application or service’s D-Bus objects are registered on. Since: 2.72 The origin filename of this #GDesktopAppInfo Emitted when the drive's state has changed. a #GDrive. This signal is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. a #GDrive. Emitted when the physical eject button (if any) of a drive has been pressed. a #GDrive. Emitted when the physical stop button (if any) of a drive has been pressed. Since: 2.22 a #GDrive. Flags used when starting a drive. Since: 2.22 No flags set. Enumeration describing how a drive can be started/stopped. Since: 2.22 Unknown or drive doesn't support start/stop. The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. The start/stop methods are used for connecting/disconnect to the drive over the network. The start/stop methods will assemble/disassemble a virtual drive from several physical drives. The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command) A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. Since: 2.48 A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in #GDtlsClientConnection:validation-flags, this object will be used to determine the expected identify of the remote end of the connection; if #GDtlsClientConnection:server-identity is not set, or does not match the identity presented by the server, then the %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts. Since: 2.48 What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GDtlsConnection::accept-certificate. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to #GDtlsConnection::accept-certificate. Since: 2.48 Deprecated: 2.74: Do not attempt to ignore validation errors. Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert's certification path by calling g_tls_certificate_get_issuer() on it. For a client-side connection, @peer_cert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to @conn's #GDtlsClientConnection:validation_flags. If you would like the certificate to be accepted despite @errors, return %TRUE from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in @errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. For a server-side connection, @peer_cert is the certificate presented by the client, if this was requested via the server's #GDtlsServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns %TRUE. Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return %FALSE from the signal handler on the first attempt, and then after the connection attempt returns a %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return %TRUE from the signal handler the next time. If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. Since: 2.48 a #GDtlsConnection the peer's #GTlsCertificate the problems with @peer_cert. %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. The list of application-layer protocols that the connection advertises that it is willing to speak. See g_dtls_connection_set_advertised_protocols(). Since: 2.60 The #GDatagramBased that the connection wraps. Note that this may be any implementation of #GDatagramBased, not just a #GSocket. Since: 2.48 The connection's certificate; see g_dtls_connection_set_certificate(). Since: 2.48 The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). Since: 2.70 The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). When using a non-default database, #GDtlsConnection must fall back to using the #GTlsDatabase to perform certificate verification using g_tls_database_verify_chain(), which means certificate verification will not be able to make use of TLS session context. This may be less secure. For example, if you create your own #GTlsDatabase that just wraps the default #GTlsDatabase, you might expect that you have not changed anything, but this is not true because you may have altered the behavior of #GDtlsConnection by causing it to use g_tls_database_verify_chain(). See the documentation of g_tls_database_verify_chain() for more details on specific security checks that may not be performed. Accordingly, setting a non-default database is discouraged except for specialty applications with unusual security requirements. Since: 2.48 A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. Since: 2.48 The application-layer protocol negotiated during the TLS handshake. See g_dtls_connection_get_negotiated_protocol(). Since: 2.60 The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GDtlsConnection::accept-certificate. (You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.) Since: 2.48 The errors noticed while verifying #GDtlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GDtlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if #GDtlsConnection::accept-certificate overrode the default behavior. GLib guarantees that if certificate verification fails, at least one error will be set, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Since: 2.48 The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). Since: 2.70 The rehandshaking mode. See g_dtls_connection_set_rehandshake_mode(). Since: 2.48 Deprecated: 2.60: The rehandshake mode is ignored. Whether or not proper TLS close notification is required. See g_dtls_connection_set_require_close_notify(). Since: 2.48 The #GTlsAuthenticationMode for the server. This can be changed before calling g_dtls_connection_handshake() if you want to rehandshake with a different mode from the initial handshake. Since: 2.48 GEmblemOrigin is used to add information about the origin of the emblem to #GEmblem. Since: 2.18 Emblem of unknown origin Emblem adds device-specific information Emblem depicts live metadata, such as "readonly" Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) Flags specifying the behaviour of an attribute. no flags set. copy the attribute values when the file is copied. copy the attribute values when the file is moved. Used by g_file_set_attributes_from_info() when setting file attributes. Attribute value is unset (empty). Attribute value is set. Indicates an error in setting the value. The data types for file attributes. indicates an invalid or uninitialized type. a null terminated UTF8 string. a zero terminated string of non-zero bytes. a boolean value. an unsigned 4-byte/32-bit integer. a signed 4-byte/32-bit integer. an unsigned 8-byte/64-bit integer. a signed 8-byte/64-bit integer. a #GObject. a %NULL terminated char **. Since 2.22 Flags used when copying or moving files. No flags set. Overwrite any existing files Make a backup of any existing files. Don't follow symlinks. Copy all file metadata instead of just default set used for copy (see #GFileInfo). Don't use copy and delete fallback if native move not supported. Leaves target file with default perms, instead of setting the source file perms. Flags used when an operation may create a file. No flags set. Create a file that can only be accessed by the current user. Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. This flag can only be used with g_file_replace() and its variants, including g_file_replace_contents(). Since 2.20 The file containing the icon. Flags that can be used with g_file_measure_disk_usage(). Since: 2.38 No flags set. Report any error encountered while traversing the directory tree. Normally errors are only reported for the toplevel file. Tally usage based on apparent file sizes. Normally, the block-size is used, if available, as this is a more accurate representation of disk space used. Compare with `du --apparent-size`. Do not cross mount point boundaries. Compare with `du -x`. Emitted when @file has been changed. If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and the information is available (and if supported by the backend), @event_type may be %G_FILE_MONITOR_EVENT_RENAMED, %G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT. In all cases @file will be a child of the monitored directory. For renames, @file will be the old name and @other_file is the new name. For "moved in" events, @file is the name of the file that appeared and @other_file is the old name that it was moved from (in another directory). For "moved out" events, @file is the name of the file that used to be in this directory and @other_file is the name of the file at its new location. It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as equivalent to %G_FILE_MONITOR_EVENT_CREATED and %G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to %G_FILE_MONITOR_EVENT_DELETED, with extra information. %G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create pair. This is exactly how the events will be reported in the case that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use. If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is %G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the old path, and @other_file will be set to a #GFile containing the new path. In all the other cases, @other_file will be set to #NULL. a #GFileMonitor. a #GFile. a #GFile or #NULL. a #GFileMonitorEvent. Specifies what type of event a monitor event is. a file changed. a hint that this was probably the last change in a set of changes. a file was deleted. a file was created. a file attribute was changed. the file location will soon be unmounted. the file location was unmounted. the file was moved -- only sent if the (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set the file was renamed within the current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. the file was moved into the monitored directory from another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. the file was moved out of the monitored directory to another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46 Flags used to set what a #GFileMonitor will watch for. No flags set. Watch for mount events. Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events). Deprecated since 2.46: use %G_FILE_MONITOR_WATCH_MOVES instead. Watch for changes to the file made via another hard link. Since 2.36. Watch for rename operations on a monitored directory. This causes %G_FILE_MONITOR_EVENT_RENAMED, %G_FILE_MONITOR_EVENT_MOVED_IN and %G_FILE_MONITOR_EVENT_MOVED_OUT events to be emitted when possible. Since: 2.46. Flags used when querying a #GFileInfo. No flags set. Don't follow symlinks. Indicates the file's on-disk type. On Windows systems a file will never have %G_FILE_TYPE_SYMBOLIC_LINK type; use #GFileInfo and %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK to determine whether a file is a symlink or not. This is due to the fact that NTFS does not have a single filesystem object type for symbolic links - it has files that symlink to files, and directories that symlink to directories. #GFileType enumeration cannot precisely represent this important distinction, which is why all Windows symlinks will continue to be reported as %G_FILE_TYPE_REGULAR or %G_FILE_TYPE_DIRECTORY. File's type is unknown. File handle represents a regular file. File handle represents a directory. File handle represents a symbolic link (Unix systems). File is a "special" file, such as a socket, fifo, block device, or character device. File is a shortcut (Windows systems). File is a mountable location. Emitted when the file name completion information comes available. Indicates a hint from the file system whether files should be previewed in a file manager. Returned as the value of the key %G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. Only preview files if user has explicitly requested it. Preview files if user has requested preview of "local" files. Never preview files. Error codes returned by GIO functions. Note that this domain may be extended in future GLib releases. In general, new error codes either only apply to new APIs, or else replace %G_IO_ERROR_FAILED in cases that were not explicitly distinguished before. You should therefore avoid writing code like |[<!-- language="C" --> if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED)) { // Assume that this is EPRINTERONFIRE ... } ]| but should instead treat all unrecognized error codes the same as %G_IO_ERROR_FAILED. See also #GPollableReturn for a cheaper way of returning %G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError. Generic error condition for when an operation fails and no more specific #GIOErrorEnum value is defined. File not found. File already exists. File is a directory. File is not a directory. File is a directory that isn't empty. File is not a regular file. File is not a symbolic link. File cannot be mounted. Filename is too many characters. Filename is invalid or contains invalid characters. File contains too many symbolic links. No space left on drive. Invalid argument. Permission denied. Operation (or one of its parameters) not supported File isn't mounted. File is already mounted. File was closed. Operation was cancelled. See #GCancellable. Operations are still pending. File is read only. Backup couldn't be created. File's Entity Tag was incorrect. Operation timed out. Operation would be recursive. File is busy. Operation would block. Host couldn't be found (remote operations). Operation would merge files. Operation failed and a helper program has already interacted with the user. Do not display any error dialog. The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 The object has not been initialized. Since 2.22 The requested address is already in use. Since 2.22 Need more input to finish operation. Since 2.24 The input data was invalid. Since 2.24 A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26. Host unreachable. Since 2.26 Network unreachable. Since 2.26 Connection refused. Since 2.26 Connection to proxy server failed. Since 2.26 Proxy authentication failed. Since 2.26 Proxy server needs authentication. Since 2.26 Proxy connection is not allowed by ruleset. Since 2.26 Broken pipe. Since 2.36 Connection closed by peer. Note that this is the same code as %G_IO_ERROR_BROKEN_PIPE; before 2.44 some "connection closed" errors returned %G_IO_ERROR_BROKEN_PIPE, but others returned %G_IO_ERROR_FAILED. Now they should all return the same value, which has this more logical name. Since 2.44. Transport endpoint is not connected. Since 2.44 Message too large. Since 2.48. No such device found. Since 2.74 Flags for use with g_io_module_scope_new(). Since: 2.30 No module scan flags When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module. GIOStreamSpliceFlags determine how streams should be spliced. Since: 2.28 Do not close either stream. Close the first stream after the splice. Close the second stream after the splice. Wait for both splice operations to finish before calling the callback. Whether this is the "any" address for its family. See g_inet_address_get_is_any(). Since: 2.22 Whether this is a link-local address. See g_inet_address_get_is_link_local(). Since: 2.22 Whether this is the loopback address for its family. See g_inet_address_get_is_loopback(). Since: 2.22 Whether this is a global multicast address. See g_inet_address_get_is_mc_global(). Since: 2.22 Whether this is a link-local multicast address. See g_inet_address_get_is_mc_link_local(). Since: 2.22 Whether this is a node-local multicast address. See g_inet_address_get_is_mc_node_local(). Since: 2.22 Whether this is an organization-local multicast address. See g_inet_address_get_is_mc_org_local(). Since: 2.22 Whether this is a site-local multicast address. See g_inet_address_get_is_mc_site_local(). Since: 2.22 Whether this is a multicast address. See g_inet_address_get_is_multicast(). Since: 2.22 Whether this is a site-local address. See g_inet_address_get_is_loopback(). Since: 2.22 The `sin6_flowinfo` field, for IPv6 addresses. Since: 2.32 The directory where the system defaults and locks are located. Defaults to `/etc/glib-2.0/settings`. The location where the settings are stored on disk. Defaults to `$XDG_CONFIG_HOME/glib-2.0/settings/keyfile`. If @root_group is non-%NULL then it specifies the name of the keyfile group used for keys that are written directly below the root path. Defaults to NULL. 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 "/". Defaults to "/". This signal is emitted whenever items were added to or removed from @list. At @position, @removed items were removed and @added items were added in their place. Note: If `removed != added`, the positions of all later items in the model change. Since: 2.44 the #GListModel that changed the position at which @list changed the number of items removed the number of items added The type of items contained in this list store. Items must be subclasses of #GObject. Since: 2.44 The number of items contained in this list store. Since: 2.74 Emitted when the system is running low on free memory. The signal handler should then take the appropriate action depending on the warning level. See the #GMemoryMonitorWarningLevel documentation for details. Since: 2.64 a #GMemoryMonitor the #GMemoryMonitorWarningLevel warning level Memory availability warning levels. Note that because new values might be added, it is recommended that applications check #GMemoryMonitorWarningLevel as ranges, for example: |[<!-- language="C" --> if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) drop_caches (); ]| Since: 2.64 Memory on the device is low, processes should free up unneeded resources (for example, in-memory caches) so they can be used elsewhere. Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW but the device has even less free memory, so processes should try harder to free up unneeded resources. If your process does not need to stay running, it is a good time for it to quit. The system will soon start terminating processes to reclaim memory, including background processes. Pointer to buffer where data will be written. Since: 2.24 Size of data written to the buffer. Since: 2.24 Function called with the buffer as argument when the stream is destroyed. Since: 2.24 Function with realloc semantics called to enlarge the buffer. Since: 2.24 Current size of the data buffer. Since: 2.24 Emitted when a change has occurred to the menu. The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added back in the same location). This signal is capable of describing both of those changes (at the same time). The signal means that starting at the index @position, @removed items were removed and @added items were added in their place. If @removed is zero then only items were added. If @added is zero then only items were removed. As an example, if the menu contains items a, b, c, d (in that order) and the signal (2, 1, 3) occurs then the new composition of the menu will be a, b, _, _, _, d (with each _ representing some new item). Signal handlers may query the model (particularly the added items) and expect to see the results of the modification that is being reported. The signal is emitted after the modification. the #GMenuModel that is changing the position of the change the number of items removed the number of items added Emitted when the mount has been changed. the object on which the signal is emitted This signal may be emitted when the #GMount is about to be unmounted. This signal depends on the backend and is only emitted if GIO was used to unmount. Since: 2.22 the object on which the signal is emitted This signal is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. the object on which the signal is emitted Flags used when mounting a mount. No flags set. Emitted by the backend when e.g. a device becomes unavailable while a mount operation is in progress. Implementations of GMountOperation should handle this signal by dismissing open password dialogs. Since: 2.20 Emitted when a mount operation asks the user for a password. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. a #GMountOperation requesting a password. string containing a message to display to the user. string containing the default user name. string containing the default domain. a set of #GAskPasswordFlags. Emitted when asking the user a question and gives a list of choices for the user to choose from. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. a #GMountOperation asking a question. string containing a message to display to the user. an array of strings for each possible choice. Emitted when the user has replied to the mount operation. a #GMountOperation. a #GMountOperationResult indicating how the request was handled Emitted when one or more processes are blocking an operation e.g. unmounting/ejecting a #GMount or stopping a #GDrive. Note that this signal may be emitted several times to update the list of blocking processes as processes close files. The application should only respond with g_mount_operation_reply() to the latest signal (setting #GMountOperation:choice to the choice the user made). If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. Since: 2.22 a #GMountOperation. string containing a message to display to the user. an array of #GPid for processes blocking the operation. an array of strings for each possible choice. Emitted when an unmount operation has been busy for more than some time (typically 1.5 seconds). When unmounting or ejecting a volume, the kernel might need to flush pending data in its buffers to the volume stable storage, and this operation can take a considerable amount of time. This signal may be emitted several times as long as the unmount operation is outstanding, and then one last time when the operation is completed, with @bytes_left set to zero. Implementations of GMountOperation should handle this signal by showing an UI notification, and then dismiss it, or show another notification of completion, when @bytes_left reaches zero. If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a #GtkMessageDialog. Since: 2.34 a #GMountOperation: string containing a message to display to the user the estimated time left before the operation completes, in microseconds, or -1 the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed Whether to use an anonymous user when authenticating. The index of the user's choice when a question is asked during the mount operation. See the #GMountOperation::ask-question signal. The domain to use for the mount operation. Whether the device to be unlocked is a TCRYPT hidden volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html). Since: 2.58 Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see [the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html). Since: 2.58 The password that is used for authentication when carrying out the mount operation. Determines if and how the password information should be saved. The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html). Since: 2.58 The user name that is used for authentication when carrying out the mount operation. #GMountOperationResult is returned as a result when a request for information is send by the mounting operation. The request was fulfilled and the user specified data is now available The user requested the mount operation to be aborted The request was unhandled (i.e. not implemented) Flags used when an unmounting a mount. No flags set. Unmount even if there are outstanding file operations on the mount. The host's network connectivity state, as reported by #GNetworkMonitor. Since: 2.44 The host is not configured with a route to the Internet; it may or may not be connected to a local network. The host is connected to a network, but does not appear to be able to reach the full Internet, perhaps due to upstream network problems. The host is behind a captive portal and cannot reach the full Internet. The host is connected to a network, and appears to be able to reach the full Internet. Emitted when the network configuration changes. Since: 2.32 a #GNetworkMonitor the current value of #GNetworkMonitor:network-available More detailed information about the host's network connectivity. See g_network_monitor_get_connectivity() and #GNetworkConnectivity for more details. Since: 2.44 Whether the network is considered available. That is, whether the system has a default route for at least one of IPv4 or IPv6. Real-world networks are of course much more complicated than this; the machine may be connected to a wifi hotspot that requires payment before allowing traffic through, or may be connected to a functioning router that has lost its own upstream connectivity. Some hosts might only be accessible when a VPN is active. Other hosts might only be accessible when the VPN is not active. Thus, it is best to use g_network_monitor_can_reach() or g_network_monitor_can_reach_async() to test for reachability on a host-by-host basis. (On the other hand, when the property is %FALSE, the application can reasonably expect that no remote hosts at all are reachable, and should indicate this to the user in its UI.) See also #GNetworkMonitor::network-changed. Since: 2.32 Whether the network is considered metered. That is, whether the system has traffic flowing through the default connection that is subject to limitations set by service providers. For example, traffic might be billed by the amount of data transmitted, or there might be a quota on the amount of traffic per month. This is typical with tethered connections (3G and 4G) and in such situations, bandwidth intensive applications may wish to avoid network activity where possible if it will cost the user money or use up their limited quota. If more information is required about specific devices then the system network management API should be used instead (for example, NetworkManager or ConnMan). If this information is not available then no networks will be marked as metered. See also #GNetworkMonitor:network-available. Since: 2.46 Priority levels for #GNotifications. Since: 2.42 for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) GOutputStreamSpliceFlags determine how streams should be spliced. Do not close either stream. Close the source stream after the splice. Close the target stream after the splice. #GPasswordSave is used to indicate the lifespan of a saved password. #Gvfs stores passwords in the Gnome keyring when this flag allows it to, and later retrieves it again from there. never save a password. save a password for the session. save a password permanently. %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. %TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). %TRUE if it is generally possible to release the permission by calling g_permission_release(). Return value for various IO operations that signal errors via the return value and not necessarily via a #GError. This enum exists to be able to return errors to callers without having to allocate a #GError. Allocating #GErrors can be quite expensive for regularly happening errors like %G_IO_ERROR_WOULD_BLOCK. In case of %G_POLLABLE_RETURN_FAILED a #GError should be set for the operation to give details about the error that happened. Since: 2.60 Generic error condition for when an operation fails. The operation was successfully finished. The operation would block. Whether “Power Saver” mode is enabled on the system. Since: 2.70 If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. Since: 2.38 If %TRUE, the state of the action will be the negation of the property value, provided the property is boolean. Since: 2.46 The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GActionMap. Since: 2.38 The object to wrap a property on. The object must be a non-%NULL #GObject with properties. Since: 2.38 The type of the parameter that must be given when activating the action. Since: 2.38 The name of the property to wrap on the object. The property must exist on the passed-in object and it must be readable and writable (and not construct-only). Since: 2.38 The state of the action, or %NULL if the action is stateless. Since: 2.38 The #GVariantType of the state that the action has, or %NULL if the action is stateless. Since: 2.38 The protocol being spoke to the destination host, or %NULL if the #GProxyAddress doesn't know. Since: 2.34 The URI string that the proxy was constructed from (or %NULL if the creator didn't specify this). Since: 2.34 The default port to use if #GProxyAddressEnumerator:uri does not specify one. Since: 2.38 The proxy resolver to use. Since: 2.36 Emitted when the resolver notices that the system resolver configuration has changed. a #GResolver An error code used with %G_RESOLVER_ERROR in a #GError returned from a #GResolver routine. Since: 2.22 the requested name/address/service was not found the requested information could not be looked up due to a network error or similar problem unknown error Flags to modify lookup behavior. Since: 2.60 default behavior (same as g_resolver_lookup_by_name()) only resolve ipv4 addresses only resolve ipv6 addresses The type of record that g_resolver_lookup_records() or g_resolver_lookup_records_async() should retrieve. The records are returned as lists of #GVariant tuples. Each record type has different values in the variant tuples returned. %G_RESOLVER_RECORD_SRV records are returned as variants with the signature `(qqqs)`, containing a `guint16` with the priority, a `guint16` with the weight, a `guint16` with the port, and a string of the hostname. %G_RESOLVER_RECORD_MX records are returned as variants with the signature `(qs)`, representing a `guint16` with the preference, and a string containing the mail exchanger hostname. %G_RESOLVER_RECORD_TXT records are returned as variants with the signature `(as)`, representing an array of the strings in the text record. Note: Most TXT records only contain a single string, but [RFC 1035](https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a record to contain multiple strings. The RFC which defines the interpretation of a specific TXT record will likely require concatenation of multiple strings if they are present, as with [RFC 7208](https://tools.ietf.org/html/rfc7208#section-3.3). %G_RESOLVER_RECORD_SOA records are returned as variants with the signature `(ssuuuuu)`, representing a string containing the primary name server, a string containing the administrator, the serial as a `guint32`, the refresh interval as a `guint32`, the retry interval as a `guint32`, the expire timeout as a `guint32`, and the TTL as a `guint32`. %G_RESOLVER_RECORD_NS records are returned as variants with the signature `(s)`, representing a string of the hostname of the name server. Since: 2.34 look up DNS SRV records for a domain look up DNS MX records for a domain look up DNS TXT records for a name look up DNS SOA records for a zone look up DNS NS records for a domain An error code used with %G_RESOURCE_ERROR in a #GError returned from a #GResource routine. Since: 2.32 no file was found at the requested path unknown error GResourceFlags give information about a particular file inside a resource bundle. Since: 2.32 No flags set. The file is compressed. GResourceLookupFlags determine how resource path lookups are handled. Since: 2.32 No flags set. The "change-event" signal is emitted once per change event that affects this settings object. You should connect to this signal only if you are interested in viewing groups of changes before they are split out into multiple emissions of the "changed" signal. For most use cases it is more appropriate to use the "changed" signal. In the event that the change event applies to one or more specified keys, @keys will be an array of #GQuark of length @n_keys. In the event that the change event applies to the #GSettings object as a whole (ie: potentially every key has been changed) then @keys will be %NULL and @n_keys will be 0. The default handler for this signal invokes the "changed" signal for each affected key. If any other connected handler returns %TRUE then this default functionality will be suppressed. the object on which the signal was emitted an array of #GQuarks for the changed keys, or %NULL the length of the @keys array, or 0 %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. The "changed" signal is emitted when a key has potentially changed. You should call one of the g_settings_get() calls to check the new value. This signal supports detailed connections. You can connect to the detailed signal "changed::x" in order to only receive callbacks when key "x" changes. Note that @settings only emits this signal if you have read @key at least once while a signal handler was already connected for @key. the object on which the signal was emitted the name of the key that changed The "writable-change-event" signal is emitted once per writability change event that affects this settings object. You should connect to this signal if you are interested in viewing groups of changes before they are split out into multiple emissions of the "writable-changed" signal. For most use cases it is more appropriate to use the "writable-changed" signal. In the event that the writability change applies only to a single key, @key will be set to the #GQuark for that key. In the event that the writability change affects the entire settings object, @key will be 0. The default handler for this signal invokes the "writable-changed" and "changed" signals for each affected key. This is done because changes in writability might also imply changes in value (if for example, a new mandatory setting is introduced). If any other connected handler returns %TRUE then this default functionality will be suppressed. the object on which the signal was emitted the quark of the key, or 0 %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. The "writable-changed" signal is emitted when the writability of a key has potentially changed. You should call g_settings_is_writable() in order to determine the new status. This signal supports detailed connections. You can connect to the detailed signal "writable-changed::x" in order to only receive callbacks when the writability of "x" changes. the object on which the signal was emitted the key The name of the context that the settings are stored in. Whether the #GSettings object is in 'delay-apply' mode. See g_settings_delay() for details. Since: 2.28 If this property is %TRUE, the #GSettings object has outstanding changes that will be applied when g_settings_apply() is called. The path within the backend where the settings are stored. The name of the schema that describes the types of keys for this #GSettings object. The type of this property is *not* #GSettingsSchema. #GSettingsSchema has only existed since version 2.32 and unfortunately this name was used in previous versions to refer to the schema ID rather than the schema itself. Take care to use the 'settings-schema' property if you wish to pass in a #GSettingsSchema. Deprecated:2.32:Use the 'schema-id' property instead. In a future version, this property may instead refer to a #GSettingsSchema. The name of the schema that describes the types of keys for this #GSettings object. The #GSettingsSchema describing the types of keys for this #GSettings object. Ideally, this property would be called 'schema'. #GSettingsSchema has only existed since version 2.32, however, and before then the 'schema' property was used to refer to the ID of the schema rather than the schema itself. Take care. Flags used when creating a binding. These flags determine in which direction the binding works. The default is to synchronize in both directions. Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET` Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable. Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable. Do not try to bind a "sensitivity" property to the writability of the setting When set in addition to %G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to g_settings_bind_with_mapping(). Indicates that the action was just activated. @parameter will always be of the expected type, i.e. the parameter type specified when the action was created. If an incorrect type is given when activating the action, this signal is not emitted. Since GLib 2.40, if no handler is connected to this signal then the default behaviour for boolean-stated actions with a %NULL parameter type is to toggle them via the #GSimpleAction::change-state signal. For stateful actions where the state type is equal to the parameter type, the default is to forward them directly to #GSimpleAction::change-state. This should allow almost all users of #GSimpleAction to connect only one handler or the other. Since: 2.28 the #GSimpleAction the parameter to the activation, or %NULL if it has no parameter Indicates that the action just received a request to change its state. @value will always be of the correct state type, i.e. the type of the initial state passed to g_simple_action_new_stateful(). If an incorrect type is given when requesting to change the state, this signal is not emitted. If no handler is connected to this signal then the default behaviour is to call g_simple_action_set_state() to set the state to the requested value. If you connect a signal handler then no default action is taken. If the state should change then you must call g_simple_action_set_state() from the handler. An example of a 'change-state' handler: |[<!-- language="C" --> static void change_volume_state (GSimpleAction *action, GVariant *value, gpointer user_data) { gint requested; requested = g_variant_get_int32 (value); // Volume only goes from 0 to 10 if (0 <= requested && requested <= 10) g_simple_action_set_state (action, value); } ]| The handler need not set the state to the requested value. It could set it to any value at all, or take some other action. Since: 2.30 the #GSimpleAction the requested value for the state If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. Since: 2.28 The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GSimpleActionGroup. Since: 2.28 The type of the parameter that must be given when activating the action. Since: 2.28 The state of the action, or %NULL if the action is stateless. Since: 2.28 The #GVariantType of the state that the action has, or %NULL if the action is stateless. Since: 2.28 Since: 2.44 Since: 2.44 The default proxy URI that will be used for any URI that doesn't match #GSimpleProxyResolver:ignore-hosts, and doesn't match any of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). Note that as a special case, if this URI starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. A list of hostnames and IP addresses that the resolver should allow direct connections to. Entries can be in one of 4 formats: - A hostname, such as "example.com", ".example.com", or "*.example.com", any of which match "example.com" or any subdomain of it. - An IPv4 or IPv6 address, such as "192.168.1.1", which matches only that address. - A hostname or IP address followed by a port, such as "example.com:80", which matches whatever the hostname or IP address would match, but only for URLs with the (explicitly) indicated port. In the case of an IPv6 address, the address part must appear in brackets: "[::1]:443" - An IP address range, given by a base address and prefix length, such as "fe80::/10", which matches any address in that range. Note that when dealing with Unicode hostnames, the matching is done against the ASCII form of the name. Also note that hostname exclusions apply only to connections made to hosts identified by name, and IP address exclusions apply only to connections made to hosts identified by address. That is, if example.com has an address of 192.168.1.1, and the :ignore-hosts list contains only "192.168.1.1", then a connection to "example.com" (eg, via a #GNetworkAddress) will use the proxy, and a connection to "192.168.1.1" (eg, via a #GInetSocketAddress) will not. These rules match the "ignore-hosts"/"noproxy" rules most commonly used by other applications. Whether the socket should allow sending to broadcast addresses. Since: 2.32 Whether outgoing multicast packets loop back to the local host. Since: 2.32 Time-to-live out outgoing multicast packets Since: 2.32 The timeout in seconds on socket I/O Since: 2.26 Time-to-live for outgoing unicast packets Since: 2.32 Emitted when @client's activity on @connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different @event values are as follows: - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable in DNS. @connection will be %NULL. - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved @connectable in DNS. @connection will be %NULL. - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection to a remote host; either a proxy server or the destination server itself. @connection is the #GSocketConnection, which is not yet connected. Since GLib 2.40, you can access the remote address via g_socket_connection_get_remote_address(). - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected to a remote host. @connection is the connected #GSocketConnection. - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate with a proxy to get it to connect to @connectable. @connection is the #GSocketConnection to the proxy server. - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a connection to @connectable through a proxy server. @connection is the stream returned from g_proxy_connect(), which may or may not be a #GSocketConnection. - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS handshake. @connection is a #GTlsClientConnection. - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed the TLS handshake. @connection is a #GTlsClientConnection. - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected to @connectable (in which case @connection is the #GSocketConnection that it will be returning to the caller) or has failed (in which case @connection is %NULL and the client is about to return an error). Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted multiple times (or not at all) for a given connectable (in particular, if @client ends up attempting to connect to more than one address). However, if @client emits the #GSocketClient::event signal at all for a given connectable, then it will always emit it with %G_SOCKET_CLIENT_COMPLETE when it is done. Note that there may be additional #GSocketClientEvent values in the future; unrecognized @event values should be ignored. Since: 2.32 the #GSocketClient the event that is occurring the #GSocketConnectable that @event is occurring on the current representation of the connection The proxy resolver to use Since: 2.36 The TLS validation flags used when creating TLS connections. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to the #GSocketClient::event signal, wait for it to be emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, and use that to connect to #GTlsConnection::accept-certificate. Deprecated: 2.72: Do not attempt to ignore validation errors. Describes an event occurring on a #GSocketClient. See the #GSocketClient::event signal for more details. Additional values may be added to this type in the future. Since: 2.32 The client is doing a DNS lookup. The client has completed a DNS lookup. The client is connecting to a remote host (either a proxy or the destination server). The client has connected to a remote host. The client is negotiating with a proxy to connect to the destination server. The client has negotiated with the proxy server. The client is performing a TLS handshake. The client has performed a TLS handshake. The client is done with a particular #GSocketConnectable. The protocol family of a #GSocketAddress. (These values are identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, if available.) Since: 2.22 no address family the IPv4 family the IPv6 family the UNIX domain family Emitted when @listener's activity on @socket changes state. Note that when @listener is used to listen on both IPv4 and IPv6, a separate set of signals will be emitted for each, and the order they happen in is undefined. Since: 2.46 the #GSocketListener the event that is occurring the #GSocket the event is occurring on Describes an event occurring on a #GSocketListener. See the #GSocketListener::event signal for more details. Additional values may be added to this type in the future. Since: 2.46 The listener is about to bind a socket. The listener has bound a socket. The listener is about to start listening on this socket. The listener is now listening on this socket. Flags used in g_socket_receive_message() and g_socket_send_message(). The flags listed in the enum are some commonly available flags, but the values used for them are the same as on the platform, and any other flags are passed in/out as is. So to use a platform specific flag, just include the right system header and pass in the flag. Since: 2.22 No flags. Request to send/receive out of band data. Read data from the socket without removing it from the queue. Don't use a gateway to send out the packet, only send to hosts on directly connected networks. A protocol identifier is specified when creating a #GSocket, which is a family/type specific identifier, where 0 means the default protocol for the particular family/type. This enum contains a set of commonly available and used protocols. You can also pass any other identifiers handled by the platform in order to use protocols not listed here. Since: 2.22 The protocol type is unknown The default protocol for the family/type TCP over IP UDP over IP SCTP over IP The ::incoming signal is emitted when a new incoming connection to @service needs to be handled. The handler must initiate the handling of @connection, but may not block; in essence, asynchronous operations must be used. @connection will be unreffed once the signal handler returns, so you need to ref it yourself if you are planning to use it. Since: 2.22 the #GSocketService a new #GSocketConnection object the source_object passed to g_socket_listener_add_address() %TRUE to stop other handlers from being called Whether the service is currently accepting connections. Since: 2.46 Flags used when creating a #GSocket. Some protocols may not implement all the socket types. Since: 2.22 Type unknown or wrong Reliable connection-based byte streams (e.g. TCP). Connectionless, unreliable datagram passing. (e.g. UDP) Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). Flags to define the behaviour of a #GSubprocess. Note that the default for stdin is to redirect from `/dev/null`. For stdout and stderr the default are for them to inherit the corresponding descriptor from the calling process. Note that it is a programmer error to mix 'incompatible' flags. For example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and %G_SUBPROCESS_FLAGS_STDOUT_SILENCE. Since: 2.40 No flags. create a pipe for the stdin of the spawned process that can be accessed with g_subprocess_get_stdin_pipe(). stdin is inherited from the calling process. create a pipe for the stdout of the spawned process that can be accessed with g_subprocess_get_stdout_pipe(). silence the stdout of the spawned process (ie: redirect to `/dev/null`). create a pipe for the stderr of the spawned process that can be accessed with g_subprocess_get_stderr_pipe(). silence the stderr of the spawned process (ie: redirect to `/dev/null`). merge the stderr of the spawned process with whatever the stdout happens to be. This is a good way of directing both streams to a common log file, for example. spawned processes will inherit the file descriptors of their parent, unless those descriptors have been explicitly marked as close-on-exec. This flag has no effect over the "standard" file descriptors (stdin, stdout, stderr). if path searching is needed when spawning the subprocess, use the `PATH` in the launcher environment. (Since: 2.72) Whether the task has completed, meaning its callback (if set) has been invoked. This can only happen after g_task_return_pointer(), g_task_return_error() or one of the other return functions have been called on the task. This property is guaranteed to change from %FALSE to %TRUE exactly once. The #GObject::notify signal for this change is emitted in the same main context as the task’s callback, immediately after that callback is invoked. Since: 2.44 #GTestDBusFlags specifying the behaviour of the D-Bus session. Since: 2.34 Flags to define future #GTestDBus behaviour. Since: 2.34 No flags. The icon name. A %NULL-terminated array of icon names. Whether to use the default fallbacks found by shortening the icon name at '-' characters. If the "names" array has more than one element, ignores any past the first. For example, if the icon name was "gnome-dev-cdrom-audio", the array would become |[<!-- language="C" --> { "gnome-dev-cdrom-audio", "gnome-dev-cdrom", "gnome-dev", "gnome", NULL }; ]| The ::run signal is emitted in a worker thread in response to an incoming connection. This thread is dedicated to handling @connection and may perform blocking IO. The signal handler need not return until the connection is closed. the #GThreadedSocketService. a new #GSocketConnection object. the source_object passed to g_socket_listener_add_address(). %TRUE to stop further signal handlers from being called The client authentication mode for a #GTlsServerConnection. Since: 2.28 client authentication not required client authentication is requested client authentication is required The DER (binary) encoded representation of the certificate. This property and the #GTlsCertificate:certificate-pem property represent the same data, just in different forms. Since: 2.28 The PEM (ASCII) encoded representation of the certificate. This property and the #GTlsCertificate:certificate property represent the same data, just in different forms. Since: 2.28 The DNS names from the certificate's Subject Alternative Names (SANs), %NULL if unavailable. Since: 2.70 The IP addresses from the certificate's Subject Alternative Names (SANs), %NULL if unavailable. Since: 2.70 A #GTlsCertificate representing the entity that issued this certificate. If %NULL, this means that the certificate is either self-signed, or else the certificate of the issuer is not available. Beware the issuer certificate may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used. Accordingly, this property cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. Since: 2.28 The issuer from the certificate, %NULL if unavailable. Since: 2.70 The time at which this cert is no longer valid, %NULL if unavailable. Since: 2.70 The time at which this cert is considered to be valid, %NULL if unavailable. Since: 2.70 An optional password used when constructed with GTlsCertificate:pkcs12-data. Since: 2.72 A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) objects containing an X.509 certificate and optionally a private key. If %NULL, the certificate is either not backed by PKCS \#11 or the #GTlsBackend does not support PKCS \#11. Since: 2.68 The PKCS #12 formatted data used to construct the object. See also: g_tls_certificate_new_from_pkcs12() Since: 2.72 The DER (binary) encoded representation of the certificate's private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208) PKCS \#8 format is supported since 2.32; earlier releases only support PKCS \#1. You can use the `openssl rsa` tool to convert PKCS \#8 keys to PKCS \#1. This property (or the #GTlsCertificate:private-key-pem property) can be set when constructing a key (for example, from a file). Since GLib 2.70, it is now also readable; however, be aware that if the private key is backed by a PKCS \#11 URI – for example, if it is stored on a smartcard – then this property will be %NULL. If so, the private key must be referenced via its PKCS \#11 URI, #GTlsCertificate:private-key-pkcs11-uri. You must check both properties to see if the certificate really has a private key. When this property is read, the output format will be unencrypted PKCS \#8. Since: 2.28 The PEM (ASCII) encoded representation of the certificate's private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) ("`BEGIN RSA PRIVATE KEY`") or unencrypted [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208) ("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32; earlier releases only support PKCS \#1. You can use the `openssl rsa` tool to convert PKCS \#8 keys to PKCS \#1. This property (or the #GTlsCertificate:private-key property) can be set when constructing a key (for example, from a file). Since GLib 2.70, it is now also readable; however, be aware that if the private key is backed by a PKCS \#11 URI - for example, if it is stored on a smartcard - then this property will be %NULL. If so, the private key must be referenced via its PKCS \#11 URI, #GTlsCertificate:private-key-pkcs11-uri. You must check both properties to see if the certificate really has a private key. When this property is read, the output format will be unencrypted PKCS \#8. Since: 2.28 A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) object containing a private key. Since: 2.68 The subject from the cert, %NULL if unavailable. Since: 2.70 A set of flags describing TLS certification validation. This can be used to describe why a particular certificate was rejected (for example, in #GTlsConnection::accept-certificate). GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Since: 2.28 No flags set. Since: 2.74 The signing certificate authority is not known. The certificate does not match the expected identity of the site that it was retrieved from. The certificate's activation time is still in the future The certificate has expired The certificate has been revoked according to the #GTlsConnection's certificate revocation list. The certificate's algorithm is considered insecure. Some other error occurred validating the certificate the combination of all of the above flags Flags for g_tls_interaction_request_certificate(), g_tls_interaction_request_certificate_async(), and g_tls_interaction_invoke_request_certificate(). Since: 2.40 No flags An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to indicate a TLS channel binding retrieval error. Since: 2.66 Either entire binding retrieval facility or specific binding type is not implemented in the TLS backend. The handshake is not yet complete on the connection which is a strong requirement for any existing binding type. Handshake is complete but binding data is not available. That normally indicates the TLS implementation failed to provide the binding data. For example, some implementations do not provide a peer certificate for resumed connections. Binding type is not supported on the current connection. This error could be triggered when requesting `tls-server-end-point` binding data for a certificate which has no hash function or uses multiple hash functions. Any other backend error preventing binding data retrieval. The type of TLS channel binding data to retrieve from #GTlsConnection or #GDtlsConnection, as documented by RFC 5929 or RFC 9266. The [`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5) binding type is not currently implemented. Since: 2.66 [`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding type [`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) binding type [`tls-exporter`](https://www.rfc-editor.org/rfc/rfc9266.html) binding type. Since: 2.74 A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. Since: 2.28 A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in #GTlsClientConnection:validation-flags, this object will be used to determine the expected identify of the remote end of the connection; if #GTlsClientConnection:server-identity is not set, or does not match the identity presented by the server, then the %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts. Since: 2.28 SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. Since: 2.28 Deprecated: 2.56: SSL 3.0 is insecure. What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GTlsConnection::accept-certificate. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to #GTlsConnection::accept-certificate. Since: 2.28 Deprecated: 2.72: Do not attempt to ignore validation errors. Emitted during the TLS handshake after the peer certificate has been received. You can examine @peer_cert's certification path by calling g_tls_certificate_get_issuer() on it. For a client-side connection, @peer_cert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to @conn's #GTlsClientConnection:validation_flags. If you would like the certificate to be accepted despite @errors, return %TRUE from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in @errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. For a server-side connection, @peer_cert is the certificate presented by the client, if this was requested via the server's #GTlsServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns %TRUE. Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return %FALSE from the signal handler on the first attempt, and then after the connection attempt returns a %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return %TRUE from the signal handler the next time. If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer. Since: 2.28 a #GTlsConnection the peer's #GTlsCertificate the problems with @peer_cert. %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. The list of application-layer protocols that the connection advertises that it is willing to speak. See g_tls_connection_set_advertised_protocols(). Since: 2.60 The #GIOStream that the connection wraps. The connection holds a reference to this stream, and may run operations on the stream from other threads throughout its lifetime. Consequently, after the #GIOStream has been constructed, application code may only run its own operations on this stream when no #GIOStream operations are running. Since: 2.28 The connection's certificate; see g_tls_connection_set_certificate(). Since: 2.28 The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). Since: 2.70 The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). When using a non-default database, #GTlsConnection must fall back to using the #GTlsDatabase to perform certificate verification using g_tls_database_verify_chain(), which means certificate verification will not be able to make use of TLS session context. This may be less secure. For example, if you create your own #GTlsDatabase that just wraps the default #GTlsDatabase, you might expect that you have not changed anything, but this is not true because you may have altered the behavior of #GTlsConnection by causing it to use g_tls_database_verify_chain(). See the documentation of g_tls_database_verify_chain() for more details on specific security checks that may not be performed. Accordingly, setting a non-default database is discouraged except for specialty applications with unusual security requirements. Since: 2.30 A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. Since: 2.30 The application-layer protocol negotiated during the TLS handshake. See g_tls_connection_get_negotiated_protocol(). Since: 2.60 The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GTlsConnection::accept-certificate. (You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.) Since: 2.28 The errors noticed while verifying #GTlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GTlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if #GTlsConnection::accept-certificate overrode the default behavior. GLib guarantees that if certificate verification fails, at least one error will be set, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Since: 2.28 The TLS protocol version in use. See g_tls_connection_get_protocol_version(). Since: 2.70 The rehandshaking mode. See g_tls_connection_set_rehandshake_mode(). Since: 2.28 Deprecated: 2.60: The rehandshake mode is ignored. Whether or not proper TLS close notification is required. See g_tls_connection_set_require_close_notify(). Since: 2.28 Whether or not the system certificate database will be used to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Deprecated: 2.30: Use GTlsConnection:database instead Flags for g_tls_database_lookup_certificate_for_handle(), g_tls_database_lookup_certificate_issuer(), and g_tls_database_lookup_certificates_issued_by(). Since: 2.30 No lookup flags Restrict lookup to certificates that have a private key. Flags for g_tls_database_verify_chain(). Since: 2.30 No verification flags An error code used with %G_TLS_ERROR in a #GError returned from a TLS-related routine. Since: 2.28 No TLS provider is available Miscellaneous TLS error The certificate presented could not be parsed or failed validation. The TLS handshake failed because the peer does not seem to be a TLS server. The TLS handshake failed because the peer's certificate was not acceptable. The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate(). The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify(). The TLS handshake failed because the client sent the fallback SCSV, indicating a protocol downgrade attack. Since: 2.60 The certificate failed to load because a password was incorrect. Since: 2.72 The path to a file containing PEM encoded certificate authority root anchors. The certificates in this file will be treated as root authorities for the purpose of verifying other certificates via the g_tls_database_verify_chain() operation. Since: 2.30 #GTlsInteractionResult is returned by various functions in #GTlsInteraction when finishing an interaction request. Since: 2.30 The interaction was unhandled (i.e. not implemented). The interaction completed, and resulting data is available. The interaction has failed, or was cancelled. and the operation should be aborted. Various flags for the password. Since: 2.30 No flags The password was wrong, and the user should retry. Hint to the user that the password has been wrong many times, and the user may not have many chances left. Hint to the user that this is the last try to get this password right. For PKCS #11, the user PIN is required. Since: 2.70. For PKCS #11, the security officer PIN is required. Since: 2.70. For PKCS #11, the context-specific PIN is required. Since: 2.70. The TLS or DTLS protocol version used by a #GTlsConnection or #GDtlsConnection. The integer values of these versions are sequential to ensure newer known protocol versions compare greater than older known versions. Any known DTLS protocol version will compare greater than any SSL or TLS protocol version. The protocol version may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the TLS backend supports a newer protocol version that GLib does not yet know about. This means that it's possible for an unknown DTLS protocol version to compare less than the TLS protocol versions. Since: 2.70 No protocol version or unknown protocol version SSL 3.0, which is insecure and should not be used TLS 1.0, which is insecure and should not be used TLS 1.1, which is insecure and should not be used TLS 1.2, defined by [RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) TLS 1.3, defined by [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) DTLS 1.0, which is insecure and should not be used DTLS 1.2, defined by [RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347) When to allow rehandshaking. See g_tls_connection_set_rehandshake_mode(). Since: 2.28 Deprecated: 2.60. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. Never allow rehandshaking Allow safe rehandshaking only Allow unsafe rehandshaking The #GTlsAuthenticationMode for the server. This can be changed before calling g_tls_connection_handshake() if you want to rehandshake with a different mode from the initial handshake. Since: 2.28 The credentials stored in the message. Since: 2.26 Whether to close the file descriptor when the stream is closed. Since: 2.20 The file descriptor that the stream reads from. Since: 2.20 Emitted when the unix mount points have changed. the object on which the signal is emitted Emitted when the unix mounts have changed. the object on which the signal is emitted Types of UNIX mounts. Unknown UNIX mount type. Floppy disk UNIX mount type. CDROM UNIX mount type. Network File System (NFS) UNIX mount type. ZIP UNIX mount type. JAZZ UNIX mount type. Memory Stick UNIX mount type. Compact Flash UNIX mount type. Smart Media UNIX mount type. SD/MMC UNIX mount type. iPod UNIX mount type. Digital camera UNIX mount type. Hard drive UNIX mount type. Whether to close the file descriptor when the stream is closed. Since: 2.20 The file descriptor that the stream writes to. Since: 2.20 Whether or not this is an abstract address Deprecated: Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses. The type of name used by a #GUnixSocketAddress. %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS indicates a socket not bound to any name (eg, a client-side socket, or a socket created with socketpair()). For abstract sockets, there are two incompatible ways of naming them; the man pages suggest using the entire `struct sockaddr_un` as the name, padding the unused parts of the %sun_path field with zeroes; this corresponds to %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs instead just use a portion of %sun_path, and pass an appropriate smaller length to bind() or connect(). This is %G_UNIX_SOCKET_ADDRESS_ABSTRACT. Since: 2.26 invalid anonymous a filesystem path an abstract name an abstract name, 0-padded to the full length of a unix socket name Emitted when the volume has been changed. This signal is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized. Emitted when a drive changes. The volume monitor emitting the signal. the drive that changed Emitted when a drive is connected to the system. The volume monitor emitting the signal. a #GDrive that was connected. Emitted when a drive is disconnected from the system. The volume monitor emitting the signal. a #GDrive that was disconnected. Emitted when the eject button is pressed on @drive. Since: 2.18 The volume monitor emitting the signal. the drive where the eject button was pressed Emitted when the stop button is pressed on @drive. Since: 2.22 The volume monitor emitting the signal. the drive where the stop button was pressed Emitted when a mount is added. The volume monitor emitting the signal. a #GMount that was added. Emitted when a mount changes. The volume monitor emitting the signal. a #GMount that changed. May be emitted when a mount is about to be removed. This signal depends on the backend and is only emitted if GIO was used to unmount. The volume monitor emitting the signal. a #GMount that is being unmounted. Emitted when a mount is removed. The volume monitor emitting the signal. a #GMount that was removed. Emitted when a mountable volume is added to the system. The volume monitor emitting the signal. a #GVolume that was added. Emitted when mountable volume is changed. The volume monitor emitting the signal. a #GVolume that changed. Emitted when a mountable volume is removed from the system. The volume monitor emitting the signal. a #GVolume that was removed. Whether to close the file handle when the stream is closed. Since: 2.26 The handle that the stream reads from. Since: 2.26 Whether to close the file handle when the stream is closed. Since: 2.26 The file handle that the stream writes to. Since: 2.26 A path to the key in the registry, in UTF-8. Since: 2.46 A path to the key in the registry, in UTF-16. Since: 2.46 If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name and modification time from the file info to the GZIP header. Since: 2.26 Used to select the type of data format to use for #GZlibDecompressor and #GZlibCompressor. Since: 2.24 deflate compression with zlib header gzip file format deflate compression with no header A #GFileInfo containing the information found in the GZIP header of the data stream processed, or %NULL if the header was not yet fully processed, is not present at all, or the compressor's #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. Since: 2.26 Activates the action. @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. If the @parameter GVariant is floating, it is consumed. Since: 2.28 a #GAction the parameter to the activation Request for the state of @action to be changed to @value. The action must be stateful and @value must be of the correct type. See g_action_get_state_type(). This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See g_action_get_state_hint(). If the @value GVariant is floating, it is consumed. Since: 2.30 a #GAction the new state Checks if @action is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. Since: 2.28 a #GAction whether the action is enabled Queries the name of @action. Since: 2.28 a #GAction the name of the action Queries the type of the parameter that must be given when activating @action. When activating the action using g_action_activate(), the #GVariant given to that function must be of the type returned by this function. In the case that this function returns %NULL, you must not give any #GVariant, but %NULL instead. Since: 2.28 a #GAction the parameter type Queries the current state of @action. If the action is not stateful then %NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_get_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required. Since: 2.28 a #GAction the current state of the action Requests a hint about the valid range of values for the state of @action. 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. Since: 2.28 a #GAction the state range hint Queries the type of the state of @action. If the action is stateful (e.g. created with g_simple_action_new_stateful()) then this function returns the #GVariantType of the state. This is the type of the initial value given as the state. All calls to g_action_change_state() must give a #GVariant of this type and g_action_get_state() will return a #GVariant of the same type. If the action is not stateful (e.g. created with g_simple_action_new()) then this function will return %NULL. In that case, g_action_get_state() will return %NULL and you must not call g_action_change_state(). Since: 2.28 a #GAction the state type, if the action is stateful Emits the #GActionGroup::action-added signal on @action_group. This function should only be called by #GActionGroup implementations. Since: 2.28 a #GActionGroup the name of an action in the group Emits the #GActionGroup::action-enabled-changed signal on @action_group. This function should only be called by #GActionGroup implementations. Since: 2.28 a #GActionGroup the name of an action in the group whether or not the action is now enabled Emits the #GActionGroup::action-removed signal on @action_group. This function should only be called by #GActionGroup implementations. Since: 2.28 a #GActionGroup the name of an action in the group Emits the #GActionGroup::action-state-changed signal on @action_group. This function should only be called by #GActionGroup implementations. Since: 2.28 a #GActionGroup the name of an action in the group the new state of the named action Activate the named action within @action_group. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no parameters then @parameter must be %NULL. See g_action_group_get_action_parameter_type(). If the #GActionGroup implementation supports asynchronous remote activation over D-Bus, this call may return before the relevant D-Bus traffic has been sent, or any replies have been received. In order to block on such asynchronous activation calls, g_dbus_connection_flush() should be called prior to the code, which depends on the result of the action activation. Without flushing the D-Bus connection, there is no guarantee that the action would have been activated. The following code which runs in a remote app instance, shows an example of a "quit" action being activated on the primary app instance over D-Bus. Here g_dbus_connection_flush() is called before `exit()`. Without g_dbus_connection_flush(), the "quit" action may fail to be activated on the primary instance. |[<!-- language="C" --> // call "quit" action on primary instance g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); // make sure the action is activated now g_dbus_connection_flush (...); g_debug ("application has been terminated. exiting."); exit (0); ]| Since: 2.28 a #GActionGroup the name of the action to activate parameters to the activation Request for the state of the named action within @action_group to be changed to @value. The action must be stateful and @value must be of the correct type. See g_action_group_get_action_state_type(). This call merely requests a change. The action may refuse to change its state or may change its state to something other than @value. See g_action_group_get_action_state_hint(). If the @value GVariant is floating, it is consumed. Since: 2.28 a #GActionGroup the name of the action to request the change on the new state Checks if the named action within @action_group is currently enabled. An action must be enabled in order to be activated or in order to have its state changed from outside callers. Since: 2.28 a #GActionGroup the name of the action to query whether or not the action is currently enabled Queries the type of the parameter that must be given when activating the named action within @action_group. When activating the action using g_action_group_activate_action(), the #GVariant given to that function must be of the type returned by this function. In the case that this function returns %NULL, you must not give any #GVariant, but %NULL instead. 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. Since: 2.28 a #GActionGroup the name of the action to query the parameter type Queries the current state of the named action within @action_group. If the action is not stateful then %NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_group_get_action_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required. Since: 2.28 a #GActionGroup the name of the action to query the current state of the action Requests a hint about the valid range of values for the state of the named action within @action_group. If %NULL is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action. If a #GVariant array is returned then each item in the array is a possible value for the state. If a #GVariant pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state. In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail. The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required. Since: 2.28 a #GActionGroup the name of the action to query the state range hint Queries the type of the state of the named action within @action_group. 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. 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(). 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. Since: 2.28 a #GActionGroup the name of the action to query the state type, if the action is stateful Checks if the named action exists within @action_group. Since: 2.28 a #GActionGroup the name of the action to check for whether the named action exists Lists the actions contained within @action_group. The caller is responsible for freeing the list with g_strfreev() when it is no longer required. Since: 2.28 a #GActionGroup a %NULL-terminated array of the names of the actions in the group Queries all aspects of the named action within an @action_group. This function acquires the information available from g_action_group_has_action(), g_action_group_get_action_enabled(), g_action_group_get_action_parameter_type(), g_action_group_get_action_state_type(), g_action_group_get_action_state_hint() and g_action_group_get_action_state() with a single function call. This provides two main benefits. The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing #GActionGroup can now be done by only overriding this one virtual function. The interface provides a default implementation of this function that calls the individual functions, as required, to fetch the information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others. If the action exists, %TRUE is returned and any of the requested fields (as indicated by having a non-%NULL reference passed in) are filled. If the action doesn't exist, %FALSE is returned and the fields may or may not have been modified. Since: 2.32 a #GActionGroup the name of an action in the group if the action is presently enabled the parameter type, or %NULL if none needed the state type, or %NULL if stateless the state hint, or %NULL if none the current state, or %NULL if stateless %TRUE if the action exists, else %FALSE Adds an action to the @action_map. If the action map already contains an action with the same name as @action then the old action is dropped from the action map. The action map takes its own reference on @action. Since: 2.32 a #GActionMap a #GAction A convenience function for creating multiple #GSimpleAction instances and adding them to a #GActionMap. Each action is constructed as per one #GActionEntry. |[<!-- language="C" --> static void activate_quit (GSimpleAction *simple, GVariant *parameter, gpointer user_data) { exit (0); } static void activate_print_string (GSimpleAction *simple, GVariant *parameter, gpointer user_data) { g_print ("%s\n", g_variant_get_string (parameter, NULL)); } static GActionGroup * create_action_group (void) { const GActionEntry entries[] = { { "quit", activate_quit }, { "print-string", activate_print_string, "s" } }; GSimpleActionGroup *group; group = g_simple_action_group_new (); g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); return G_ACTION_GROUP (group); } ]| Since: 2.32 a #GActionMap a pointer to the first item in an array of #GActionEntry structs the length of @entries, or -1 if @entries is %NULL-terminated the user data for signal connections Looks up the action with the name @action_name in @action_map. If no such action exists, returns %NULL. Since: 2.32 a #GActionMap the name of an action a #GAction, or %NULL Removes the named action from the action map. If no action of this name is in the map then nothing happens. Since: 2.32 a #GActionMap the name of the action Checks if @action_name is valid. @action_name is valid if it consists only of alphanumeric characters, plus '-' and '.'. The empty string is not a valid action name. It is an error to call this function with a non-utf8 @action_name. @action_name must not be %NULL. Since: 2.38 a potential action name %TRUE if @action_name is valid Parses a detailed action name into its separate name and target components. Detailed action names can have three formats. The first format is used to represent an action name with no target value and consists of just an action name containing no whitespace nor the characters `:`, `(` or `)`. For example: `app.action`. The second format is used to represent an action with a target value that is a non-empty string consisting only of alphanumerics, plus `-` and `.`. In that case, the action name and target value are separated by a double colon (`::`). For example: `app.action::target`. The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: `app.action(42)`. The target value is parsed using g_variant_parse(). If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: `app.action((1,2,3))`. A string target can be specified this way as well: `app.action('target')`. For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, `-` and `.`. If this function returns %TRUE, a non-%NULL value is guaranteed to be returned in @action_name (if a pointer is passed in). A %NULL value may still be returned in @target_value, as the @detailed_name may not contain a target. If returned, the #GVariant in @target_value is guaranteed to not be floating. Since: 2.38 a detailed action name the action name the target value, or %NULL for no target a pointer to a %NULL #GError, or %NULL %TRUE if successful, else %FALSE with @error set Formats a detailed action name from @action_name and @target_value. It is an error to call this function with an invalid action name. This function is the opposite of g_action_parse_detailed_name(). It will produce a string that can be parsed back to the @action_name and @target_value by that function. See that function for the types of strings that will be printed by this function. Since: 2.38 a valid action name a #GVariant target value, or %NULL a detailed format string Adds a content type to the application information to indicate the application is capable of opening files with the given content type. a #GAppInfo. a string. a #GError. %TRUE on success, %FALSE on error. Obtains the information whether the #GAppInfo can be deleted. See g_app_info_delete(). Since: 2.20 a #GAppInfo %TRUE if @appinfo can be deleted Checks if a supported content type can be removed from an application. a #GAppInfo. %TRUE if it is possible to remove supported content types from a given @appinfo, %FALSE if not. Creates a new #GAppInfo from the given information. Note that for @commandline, the quoting rules of the Exec key of the [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. the commandline to use the application name, or %NULL to use @commandline flags that can specify details of the created #GAppInfo a #GError location to store the error occurring, %NULL to ignore. new #GAppInfo for given command. Tries to delete a #GAppInfo. On some platforms, there may be a difference between user-defined #GAppInfos which can be deleted, and system-wide ones which cannot. See g_app_info_can_delete(). Virtual: do_delete Since: 2.20 a #GAppInfo %TRUE if @appinfo has been deleted Creates a duplicate of a #GAppInfo. a #GAppInfo. a duplicate of @appinfo. Checks if two #GAppInfos are equal. 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. the first #GAppInfo. the second #GAppInfo. %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. Gets a list of all of the applications currently registered on this system. For desktop files, this includes applications that have `NoDisplay=true` set or are excluded from display by means of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). The returned list does not include applications which have the `Hidden` key set. a newly allocated #GList of references to #GAppInfos. 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(). the content type to find a #GAppInfo for #GList of #GAppInfos for given @content_type or %NULL on error. Gets the commandline with which the application will be started. Since: 2.20 a #GAppInfo a string containing the @appinfo's commandline, or %NULL if this information is not available Gets the default #GAppInfo for a given content type. the content type to find a #GAppInfo for if %TRUE, the #GAppInfo is expected to support URIs #GAppInfo for given @content_type or %NULL on error. Asynchronously gets the default #GAppInfo for a given content type. Since: 2.74 the content type to find a #GAppInfo for if %TRUE, the #GAppInfo is expected to support URIs optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a default #GAppInfo lookup started by g_app_info_get_default_for_type_async(). If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. Since: 2.74 a #GAsyncResult a #GError #GAppInfo for given @content_type or %NULL on error. 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". a string containing a URI scheme. #GAppInfo for given @uri_scheme or %NULL on error. Asynchronously 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.74 a string containing a URI scheme. optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a default #GAppInfo lookup started by g_app_info_get_default_for_uri_scheme_async(). If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. Since: 2.74 a #GAsyncResult a #GError #GAppInfo for given @uri_scheme or %NULL on error. Gets a human-readable description of an installed application. a #GAppInfo. a string containing a description of the application @appinfo, or %NULL if none. Gets the display name of the application. The display name is often more descriptive to the user than the name itself. Since: 2.24 a #GAppInfo. the display name of the application for @appinfo, or the name if no display name is available. Gets the executable's name for the installed application. a #GAppInfo a string containing the @appinfo's application binaries name 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. Since: 2.28 the content type to find a #GAppInfo for #GList of #GAppInfos for given @content_type or %NULL on error. Gets the icon for the application. a #GAppInfo. the default #GIcon for @appinfo or %NULL if there is no default icon. 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. Note that the returned ID may be %NULL, depending on how the @appinfo has been constructed. a #GAppInfo. a string containing the application's ID. Gets the installed name of the application. a #GAppInfo. the name of the application for @appinfo. 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.28 the content type to find a #GAppInfo for #GList of #GAppInfos for given @content_type or %NULL on error. 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.34 a #GAppInfo that can handle files a list of content types. 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. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using g_app_info_launch_uris() instead. The launched application inherits the environment of the launching process, but it can be modified with g_app_launch_context_setenv() and g_app_launch_context_unsetenv(). On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. a #GAppInfo a #GList of #GFile objects a #GAppLaunchContext or %NULL a #GError %TRUE on successful launch, %FALSE otherwise. Utility function that launches the default application registered to handle the specified uri. Synchronous I/O is done on the uri to detect the type of the file if required. The D-Bus–activated applications don't have to be started if your application terminates too soon after this function. To prevent this, use g_app_info_launch_default_for_uri_async() instead. the uri to show an optional #GAppLaunchContext return location for an error, or %NULL %TRUE on success, %FALSE on error. Async version of g_app_info_launch_default_for_uri(). 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. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation. Since: 2.50 the uri to show an optional #GAppLaunchContext a #GCancellable a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes an asynchronous launch-default-for-uri operation. Since: 2.50 a #GAsyncResult return location for an error, or %NULL %TRUE if the launch was successful, %FALSE if @error is set 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. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. To launch the application without arguments pass a %NULL @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. a #GAppInfo a #GList containing URIs to launch. a #GAppLaunchContext or %NULL a #GError %TRUE on successful launch, %FALSE otherwise. Async version of g_app_info_launch_uris(). The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for g_app_info_launch_default_for_uri_async(). Since: 2.60 a #GAppInfo a #GList containing URIs to launch. a #GAppLaunchContext or %NULL a #GCancellable a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a g_app_info_launch_uris_async() operation. Since: 2.60 a #GAppInfo a #GAsyncResult a #GError %TRUE on successful launch, %FALSE otherwise. Gets the #GAppInfoMonitor for the current thread-default main context. The #GAppInfoMonitor will emit a "changed" signal in the thread-default main context whenever the list of installed applications (as reported by g_app_info_get_all()) may have changed. You must only call g_object_unref() on the return value from under the same main context as you created it. Since: 2.40 a reference to a #GAppInfoMonitor Removes a supported type from an application, if possible. a #GAppInfo. a string. a #GError. %TRUE on success, %FALSE on error. 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.20 a content type Sets the application as the default handler for the given file extension. a #GAppInfo. a string containing the file extension (without the dot). a #GError. %TRUE on success, %FALSE on error. Sets the application as the default handler for a given type. a #GAppInfo. the content type. a #GError. %TRUE on success, %FALSE on error. 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. a #GAppInfo. the content type. a #GError. %TRUE on success, %FALSE on error. Checks if the application info should be shown in menus that list available applications. a #GAppInfo. %TRUE if the @appinfo should be shown, %FALSE otherwise. Checks if the application accepts files as arguments. a #GAppInfo. %TRUE if the @appinfo supports files. Checks if the application supports reading files and directories from URIs. a #GAppInfo. %TRUE if the @appinfo supports URIs. 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. a #GAppLaunchContext a #GAppInfo a #GList of #GFile objects a display string for the display. Gets the complete environment variable list to be passed to the child process when @context is used to launch an application. This is a %NULL-terminated array of strings, where each string has the form `KEY=VALUE`. Since: 2.32 a #GAppLaunchContext the child's environment Initiates startup notification for the application and returns the `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation, if supported. The returned token may be referred to equivalently as an ‘activation token’ (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology). The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst). Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1), and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). Support for the XDG Activation Protocol was added in GLib 2.76. a #GAppLaunchContext a #GAppInfo a #GList of of #GFile objects a startup notification ID for the application, or %NULL if not supported. 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(). a #GAppLaunchContext. the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). Creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as #GdkAppLaunchContext. a #GAppLaunchContext. Arranges for @variable to be set to @value in the child's environment when @context is used to launch an application. Since: 2.32 a #GAppLaunchContext the environment variable to set the value for to set the variable to. Arranges for @variable to be unset in the child's environment when @context is used to launch an application. Since: 2.32 a #GAppLaunchContext the environment variable to remove Activates the application. In essence, this results in the #GApplication::activate signal being emitted in the primary instance. The application must be registered before calling this function. Since: 2.28 a #GApplication Add an option to be handled by @application. Calling this function is the equivalent of calling g_application_add_main_option_entries() with a single #GOptionEntry that has its arg_data member set to %NULL. The parsed arguments will be packed into a #GVariantDict which is passed to #GApplication::handle-local-options. If %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also be sent to the primary instance. See g_application_add_main_option_entries() for more details. See #GOptionEntry for more documentation of the arguments. Since: 2.42 the #GApplication the long name of an option used to specify it in a commandline the short name of an option flags from #GOptionFlags the type of the option, as a #GOptionArg the description for the option in `--help` output the placeholder to use for the extra argument parsed by the option in `--help` output 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. As it has been passed outside the process at this point, the types of all values in the options dict must be checked before being used. This "packing" is done according to the type of the argument -- booleans for normal flags, strings for strings, bytestrings for filenames, etc. The packing only occurs if the flag is given (ie: we do not pack a "false" #GVariant in the case that a flag is missing). In general, it is recommended that all commandline arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where g_variant_dict_lookup() can be used. For local options, it is possible to either use @arg_data in the usual way, or to consult (and potentially remove) the option from the options dictionary. This function is new in GLib 2.40. Before then, the only real choice was to send all of the commandline arguments (options and all) to the primary instance for handling. #GApplication ignored them completely on the local side. Calling this function "opts in" to the new behaviour, and in particular, means that unrecognised options will be treated as errors. Unrecognised options have never been ignored when %G_APPLICATION_HANDLES_COMMAND_LINE is unset. If #GApplication::handle-local-options needs to see the list of filenames, then the use of %G_OPTION_REMAINING is recommended. If @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into the options dictionary. If you do use %G_OPTION_REMAINING then you need to handle these arguments for yourself because once they are consumed, they will no longer be visible to the default handling (which treats them as filenames to be opened). 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 `^a&s` - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay` Since: 2.40 a #GApplication (array zero-terminated=1) (element-type GOptionEntry) a %NULL-terminated list of #GOptionEntrys Adds a #GOptionGroup to the commandline handling of @application. This function is comparable to g_option_context_add_group(). Unlike g_application_add_main_option_entries(), this function does not deal with %NULL @arg_data and never transmits options to the primary instance. The reason for that is because, by the time the options arrive at the primary instance, it is typically too late to do anything with them. Taking the GTK option group as an example: GTK will already have been initialised by the time the #GApplication::command-line handler runs. In the case that this is not the first-running instance of the application, the existing instance may already have been running for a very long time. This means that the options from #GOptionGroup are only really usable in the case that the instance of the application being run is the first instance. Passing options like `--display=` or `--gdk-debug=` on future runs will have no effect on the existing primary instance. Calling this function will cause the options in the supplied option group to be parsed, but it does not cause you to be "opted in" to the new functionality whereby unrecognised options are rejected even if %G_APPLICATION_HANDLES_COMMAND_LINE was given. Since: 2.40 the #GApplication a #GOptionGroup Marks @application as busy (see g_application_mark_busy()) while @property on @object is %TRUE. The binding holds a reference to @application while it is active, but not to @object. Instead, the binding is destroyed when @object is finalized. Since: 2.44 a #GApplication a #GObject the name of a boolean property of @object Creates a #GFile corresponding to a filename that was given as part of the invocation of @cmdline. This differs from g_file_new_for_commandline_arg() in that it resolves relative pathnames using the current working directory of the invoking process rather than the local process. Since: 2.36 a #GApplicationCommandLine an argument from @cmdline a new #GFile 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. If you wish to use the return value with #GOptionContext, you must use g_option_context_parse_strv(). The return value is %NULL-terminated and should be freed using g_strfreev(). Since: 2.28 a #GApplicationCommandLine the length of the arguments array, or %NULL (array length=argc) (element-type filename) (transfer full) the string array containing the arguments (the argv) Gets the working directory of the command line invocation. The string may contain non-utf8 data. It is possible that the remote application did not send a working directory, so this may be %NULL. The return value should not be modified or freed and is valid for as long as @cmdline exists. Since: 2.28 a #GApplicationCommandLine the current directory, or %NULL Gets the contents of the 'environ' variable of the command line invocation, as would be returned by g_get_environ(), ie as a %NULL-terminated list of strings in the form 'NAME=VALUE'. The strings may contain non-utf8 data. The remote application usually does not send an environment. Use %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. See g_application_command_line_getenv() if you are only interested in the value of a single environment variable. Since: 2.28 a #GApplicationCommandLine the environment strings, or %NULL if they were not sent Gets the exit status of @cmdline. See g_application_command_line_set_exit_status() for more information. Since: 2.28 a #GApplicationCommandLine the exit status Determines if @cmdline represents a remote invocation. Since: 2.28 a #GApplicationCommandLine %TRUE if the invocation was remote Gets the options that were passed to g_application_command_line(). If you did not override local_command_line() then these are the same options that were parsed according to the #GOptionEntrys added to the application with g_application_add_main_option_entries() and possibly modified from your GApplication::handle-local-options handler. If no options were sent then an empty dictionary is returned so that you don't need to check for %NULL. The data has been passed via an untrusted external process, so the types of all values must be checked before being used. Since: 2.40 a #GApplicationCommandLine a #GVariantDict with the options Gets the platform data associated with the invocation of @cmdline. This is a #GVariant dictionary containing information about the context in which the invocation occurred. It typically contains information like the current working directory and the startup notification ID. It comes from an untrusted external process and hence the types of all values must be validated before being used. For local invocation, it will be %NULL. Since: 2.28 #GApplicationCommandLine the platform data, or %NULL Gets the stdin of the invoking process. The #GInputStream can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available on UNIX when using a D-Bus 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. Since: 2.34 a #GApplicationCommandLine a #GInputStream for stdin Gets the value of a particular environment variable of the command line invocation, as would be returned by g_getenv(). The strings may contain non-utf8 data. The remote application usually does not send an environment. Use %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. Since: 2.28 a #GApplicationCommandLine the environment variable to get the value of the variable, or %NULL if unset or unsent Formats a message and prints it using the stdout print handler in the invoking process. 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 a #GApplicationCommandLine a printf-style format string arguments, as per @format Formats a message and prints it using the stderr print handler in the invoking process. 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 a #GApplicationCommandLine a printf-style format string arguments, as per @format Sets the exit status that will be used when the invoking process exits. 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 a #GApplicationCommandLine the exit status Gets the unique identifier for @application. Since: 2.28 a #GApplication the identifier for @application, owned by @application Gets the #GDBusConnection being used by the application, or %NULL. 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(). Since: 2.34 a #GApplication a #GDBusConnection, or %NULL Gets the D-Bus object path being used by the application, or %NULL. 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 #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(). Since: 2.34 a #GApplication the object path, or %NULL Returns the default #GApplication instance for this process. Normally there is only one #GApplication per process and it becomes the default when it is created. You can exercise more control over this by using g_application_set_default(). If there is no default application then %NULL is returned. Since: 2.32 the default application for this process, or %NULL Gets the flags for @application. See #GApplicationFlags. Since: 2.28 a #GApplication the flags for @application Gets 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. Since: 2.28 a #GApplication the timeout, in milliseconds Gets the application's current busy state, as set through g_application_mark_busy() or g_application_bind_busy_property(). Since: 2.44 a #GApplication %TRUE if @application is currently marked as busy Checks if @application is registered. An application is registered if g_application_register() has been successfully called. Since: 2.28 a #GApplication %TRUE if @application is registered Checks if @application is remote. If @application is remote then it means that another instance of application already exists (the 'primary' instance). Calls to perform actions on @application will result in the actions being performed by the primary instance. The value of this property cannot be accessed before g_application_register() has been called. See g_application_get_is_registered(). Since: 2.28 a #GApplication %TRUE if @application is remote Gets the resource base path of @application. See g_application_set_resource_base_path() for more information. Since: 2.42 a #GApplication the base resource path, if one is set 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(). a #GApplication 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(). Application identifiers follow the same format as [D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). For convenience, the restrictions on application identifiers are reproduced here: - Application identifiers are composed of 1 or more elements separated by a period (`.`) character. All elements must contain at least one character. - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`, with `-` discouraged in new application identifiers. Each element must not begin with a digit. - Application identifiers must contain at least one `.` (period) character (and thus at least two elements). - Application identifiers must not begin with a `.` (period) character. - Application identifiers must not exceed 255 characters. Note that the hyphen (`-`) character is allowed in application identifiers, but is problematic or not allowed in various specifications and APIs that refer to D-Bus, such as [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers), the [`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus), and the convention that an application's "main" interface and object path resemble its application identifier and bus name. To avoid situations that require special-case handling, it is recommended that new application identifiers consistently replace hyphens with underscores. Like D-Bus interface names, application identifiers should start with the reversed DNS domain name of the author of the interface (in lower-case), and it is conventional for the rest of the application identifier to consist of words run together, with initial capital letters. As with D-Bus interface names, if the author's DNS domain name contains hyphen/minus characters they should be replaced by underscores, and if it contains leading digits they should be escaped by prepending an underscore. For example, if the owner of 7-zip.org used an application identifier for an archiving application, it might be named `org._7_zip.Archiver`. a potential application identifier %TRUE if @application_id is valid Increases the busy count of @application. Use this function to indicate that the application is busy, for instance while a long running operation is pending. The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user (e.g. with a spinner). To cancel the busy indication, use g_application_unmark_busy(). The application must be registered before calling this function. Since: 2.38 a #GApplication Creates a new #GApplication instance. If non-%NULL, the application id must be valid. See g_application_id_is_valid(). If no application ID is given then some features of #GApplication (most notably application uniqueness) will be disabled. the application id the application flags a new #GApplication instance Opens the given files. In essence, this results in the #GApplication::open signal being emitted in the primary instance. @n_files must be greater than zero. @hint is simply passed through to the ::open signal. It is intended to be used by applications that have multiple modes for opening files (eg: "view" vs "edit", etc). Unless you have a need for this functionality, you should use "". The application must be registered before calling this function and it must have the %G_APPLICATION_HANDLES_OPEN flag set. Since: 2.28 a #GApplication an array of #GFiles to open the length of the @files array a hint (or ""), but never %NULL Immediately quits the application. 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 a #GApplication 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. 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. Since: 2.28 a #GApplication a #GCancellable, or %NULL a pointer to a NULL #GError, or %NULL %TRUE if registration succeeded Decrease the use count of @application. When the use count reaches zero, the application will stop running. Never call this function except to cancel the effect of a previous call to g_application_hold(). a #GApplication 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][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] 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. Since: 2.28 a #GApplication the argc from main() (or 0 if @argv is %NULL) the argv from main(), or %NULL the exit status Sends a notification on behalf of @application to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all. Notifications may persist after the application exits. It will be D-Bus-activated when the notification or one of its actions is activated. Modifying @notification after this call has no effect. However, the object can be reused for a later call to this function. @id may be any string that uniquely identifies the event for the application. It does not need to be in any special format. For example, "new-message" might be appropriate for a notification about new messages. If a previous notification was sent with the same @id, it will be replaced with @notification and shown again as if it was a new notification. This works even for notifications sent from a previous execution of the application, as long as @id is the same string. @id may be %NULL, but it is impossible to replace or withdraw notifications without an id. If @notification is no longer relevant, it can be withdrawn with g_application_withdraw_notification(). Since: 2.40 a #GApplication id of the notification, or %NULL the #GNotification to send This used to be how actions were associated with a #GApplication. Now there is #GActionMap for that. Since: 2.28 Deprecated:2.32:Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead. a #GApplication a #GActionGroup, or %NULL Sets the unique identifier for @application. 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 a #GApplication the identifier for @application Sets or unsets the default application for the process, as returned by g_application_get_default(). 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 the application to set as default, or %NULL Sets the flags for @application. The flags can only be modified if @application has not yet been registered. See #GApplicationFlags. Since: 2.28 a #GApplication the flags for @application 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. 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 a #GApplication the timeout, in milliseconds Adds a description to the @application option context. See g_option_context_set_description() for more information. Since: 2.56 the #GApplication a string to be shown in `--help` output after the list of options, or %NULL Sets the parameter string to be used by the commandline handling of @application. 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 the #GApplication a string which is displayed in the first line of `--help` output, after the usage summary `programname [OPTION...]`. Adds a summary to the @application option context. See g_option_context_set_summary() for more information. Since: 2.56 the #GApplication a string to be shown in `--help` output before the list of options, or %NULL Sets (or unsets) the base resource path of @application. The path is used to automatically load various [application resources][gresource] such as menu layouts and action descriptions. The various types of resources will be found at fixed names relative to the given base path. By default, the resource base path is determined from the application ID by prefixing '/' and replacing each '.' with '/'. This is done at the time that the #GApplication object is constructed. Changes to the application ID after that point will not have an impact on the resource base path. As an example, if the application has an ID of "org.example.app" then the default resource base path will be "/org/example/app". If this is a #GtkApplication (and you have not manually changed the path) then Gtk will then search for the menus of the application at "/org/example/app/gtk/menus.ui". See #GResource for more information about adding resources to your application. You can disable automatic resource loading functionality by setting the path to %NULL. Changing the resource base path once the application is running is not recommended. The point at which the resource path is consulted for forming paths for various purposes is unspecified. 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. Since: 2.42 a #GApplication the resource path to use Destroys a binding between @property and the busy state of @application that was previously created with g_application_bind_busy_property(). Since: 2.44 a #GApplication a #GObject the name of a boolean property of @object Decreases the busy count of @application. When the busy count reaches zero, the new state will be propagated to other processes. This function must only be called to cancel the effect of a previous call to g_application_mark_busy(). Since: 2.38 a #GApplication Withdraws a notification that was sent with g_application_send_notification(). This call does nothing if a notification with @id doesn't exist or the notification was never sent. This function works even for notifications sent in previous executions of this application, as long @id is the same as it was for the sent notification. Note that notifications are dismissed when the user clicks on one of the buttons in a notification or triggers its default action, so there is no need to explicitly withdraw the notification in that case. Since: 2.40 a #GApplication id of a previously sent notification 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. 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. 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. 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. Since: 2.22 a #GAsyncInitable. the [I/O priority][io-priority] of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes asynchronous initialization and returns the result. See g_async_initable_init_async(). Since: 2.22 a #GAsyncInitable. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. Helper function for constructing #GAsyncInitable object. This is similar to g_object_new() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. Since: 2.22 a #GType supporting #GAsyncInitable. the [I/O priority][io-priority] of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished the data to pass to callback function 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. Finishes the async construction for the various g_async_initable_new calls, returning the created object or %NULL on error. Since: 2.22 the #GAsyncInitable from the callback the #GAsyncResult from the callback return location for errors, or %NULL to ignore a newly created #GObject, or %NULL on error. Free with g_object_unref(). Helper function for constructing #GAsyncInitable object. This is similar to g_object_new_valist() but also initializes the object asynchronously. When the initialization is finished, @callback will be called. You can then call g_async_initable_new_finish() to get the new object and check for any errors. Since: 2.22 a #GType supporting #GAsyncInitable. the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. The var args list generated from @first_property_name. the [I/O priority][io-priority] of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished 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. 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 Deprecated: 2.54: Use g_object_new_with_properties() and g_async_initable_init_async() instead. See #GParameter for more information. a #GType supporting #GAsyncInitable. the number of parameters in @parameters the parameters to use to construct the object the [I/O priority][io-priority] of the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the initialization is finished the data to pass to callback function Gets the source object from a #GAsyncResult. a #GAsyncResult a new reference to the source object for the @res, or %NULL if there is none. Gets the user data from a #GAsyncResult. a #GAsyncResult. the user data for @res. Checks if @res has the given @source_tag (generally a function pointer indicating the function @res was created by). Since: 2.34 a #GAsyncResult an application-defined tag %TRUE if @res has the indicated @source_tag, %FALSE if not. If @res is a #GSimpleAsyncResult, this is equivalent to g_simple_async_result_propagate_error(). Otherwise it returns %FALSE. This can be used for legacy error handling in async *_finish() wrapper functions that traditionally handled #GSimpleAsyncResult error returns themselves rather than calling into the virtual method. This should not be used in new code; #GAsyncResult errors that are set by virtual methods should also be extracted by virtual methods, to enable subclasses to chain up correctly. Since: 2.34 a #GAsyncResult a location to propagate the error to. %TRUE if @error is has been filled in with an error from @res, %FALSE if not. 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. For the asynchronous, non-blocking, version of this function, see g_buffered_input_stream_fill_async(). a #GBufferedInputStream the number of bytes that will be read from the stream optional #GCancellable object, %NULL to ignore location to store the error occurring, or %NULL to ignore the number of bytes read into @stream's buffer, up to @count, or -1 on error. 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(). If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. a #GBufferedInputStream the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request optional #GCancellable object a #GAsyncReadyCallback a #gpointer Finishes an asynchronous read. a #GBufferedInputStream a #GAsyncResult a #GError a #gssize of the read stream, or `-1` on an error. Gets the size of the available data within the stream. #GBufferedInputStream size of the available stream. Gets the size of the input buffer. a #GBufferedInputStream the current buffer size. Creates a new #GInputStream from the given @base_stream, with a buffer set to the default size (4 kilobytes). a #GInputStream a #GInputStream for the given @base_stream. Creates a new #GBufferedInputStream from the given @base_stream, with a buffer set to @size. a #GInputStream a #gsize a #GInputStream. Peeks in the buffer, copying data of size @count into @buffer, offset @offset bytes. a #GBufferedInputStream a pointer to an allocated chunk of memory a #gsize a #gsize a #gsize of the number of bytes peeked, or -1 on error. 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. a #GBufferedInputStream a #gsize to get the number of bytes available in the buffer read-only buffer Tries to read a single byte from the stream or the buffer. Will block during this read. 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. 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. a #GBufferedInputStream optional #GCancellable object, %NULL to ignore location to store the error occurring, or %NULL to ignore the byte read from the @stream, or -1 on end of stream or error. 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. a #GBufferedInputStream a #gsize Checks if the buffer automatically grows as data is added. a #GBufferedOutputStream. %TRUE if the @stream's buffer automatically grows, %FALSE otherwise. Gets the size of the buffer in the @stream. a #GBufferedOutputStream. the current size of the buffer. Creates a new buffered output stream for a base stream. a #GOutputStream. a #GOutputStream for the given @base_stream. Creates a new buffered output stream with a given buffer size. a #GOutputStream. a #gsize. a #GOutputStream with an internal buffer set to @size. 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. a #GBufferedOutputStream. a #gboolean. Sets the size of the internal buffer to @size. a #GBufferedOutputStream. a #gsize. Asynchronously connects to the message bus specified by @bus_type. When the operation is finished, @callback will be invoked. You can then call g_bus_get_finish() to get the result of the operation. This is an asynchronous failable function. See g_bus_get_sync() for the synchronous version. Since: 2.26 a #GBusType a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to @callback Finishes an operation started with g_bus_get(). 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() with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned #GDBusConnection object will (usually) have the #GDBusConnection:exit-on-close property set to %TRUE. Since: 2.26 a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get() return location for error or %NULL a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). Synchronously connects to the message bus specified by @bus_type. Note that the returned object may shared with other callers, e.g. if two separate parts of a process calls this function with the same @bus_type, they will share the same object. This is a synchronous failable function. See g_bus_get() and g_bus_get_finish() for the asynchronous version. The returned object is a singleton, that is, shared with other callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the event that you need a private message bus connection, use g_dbus_address_get_for_bus_sync() and g_dbus_connection_new_for_address() with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned #GDBusConnection object will (usually) have the #GDBusConnection:exit-on-close property set to %TRUE. Since: 2.26 a #GBusType a #GCancellable or %NULL return location for error or %NULL a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). 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). - @bus_acquired_handler then @name_lost_handler (if the name can't be obtained) - @bus_acquired_handler then @name_acquired_handler (if the name was obtained). When you are done owning the name, just call g_bus_unown_name() with the owner id this function returns. If the name is acquired or lost (for example another application could acquire the name if you allow replacement or the application currently owning the name exits), the handlers are also invoked. If the #GDBusConnection that is used for attempting to own the name closes, then @name_lost_handler is invoked since it is no longer possible for other processes to access the process. 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. Since: 2.26 the type of bus to own a name on the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration handler to invoke when connected to the bus of type @bus_type or %NULL handler to invoke when @name is acquired or %NULL handler to invoke when @name is lost or %NULL user data to pass to handlers function for freeing @user_data or %NULL an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name. Like g_bus_own_name() but takes a #GDBusConnection instead of a #GBusType. Since: 2.26 a #GDBusConnection the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration handler to invoke when @name is acquired or %NULL handler to invoke when @name is lost or %NULL user data to pass to handlers function for freeing @user_data or %NULL an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name Version of g_bus_own_name_on_connection() using closures instead of callbacks for easier binding in other languages. Since: 2.26 a #GDBusConnection the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration #GClosure to invoke when @name is acquired or %NULL #GClosure to invoke when @name is lost or %NULL an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name. Version of g_bus_own_name() using closures instead of callbacks for easier binding in other languages. Since: 2.26 the type of bus to own a name on the well-known name to own a set of flags from the #GBusNameOwnerFlags enumeration #GClosure to invoke when connected to the bus of type @bus_type or %NULL #GClosure to invoke when @name is acquired or %NULL #GClosure to invoke when @name is lost or %NULL an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the name. Stops owning a name. Note that there may still be D-Bus traffic to process (relating to owning and unowning the name) in the current thread-default #GMainContext after this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_bus_own_name() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. Since: 2.26 an identifier obtained from g_bus_own_name() Stops watching a name. Note that there may still be D-Bus traffic to process (relating to watching and unwatching the name) in the current thread-default #GMainContext after this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_bus_watch_name() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. Since: 2.26 An identifier obtained from g_bus_watch_name() Starts watching @name on the bus specified by @bus_type and calls @name_appeared_handler and @name_vanished_handler when the name is known to have an 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. 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. Since: 2.26 The type of bus to watch a name on. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. Handler to invoke when @name is known to exist or %NULL. Handler to invoke when @name is known to not exist or %NULL. User data to pass to handlers. Function for freeing @user_data or %NULL. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. Like g_bus_watch_name() but takes a #GDBusConnection instead of a #GBusType. Since: 2.26 A #GDBusConnection. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. Handler to invoke when @name is known to exist or %NULL. Handler to invoke when @name is known to not exist or %NULL. User data to pass to handlers. Function for freeing @user_data or %NULL. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. Version of g_bus_watch_name_on_connection() using closures instead of callbacks for easier binding in other languages. Since: 2.26 A #GDBusConnection. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. #GClosure to invoke when @name is known to exist or %NULL. #GClosure to invoke when @name is known to not exist or %NULL. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. Version of g_bus_watch_name() using closures instead of callbacks for easier binding in other languages. Since: 2.26 The type of bus to watch a name on. The name (well-known or unique) to watch. Flags from the #GBusNameWatcherFlags enumeration. #GClosure to invoke when @name is known to exist or %NULL. #GClosure to invoke when @name is known to not exist or %NULL. An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name. Gets the #GBytes associated with the given @icon. Since: 2.38 a #GIcon. a #GBytes. Creates a new icon for a bytes. This cannot fail, but loading and interpreting the bytes may fail later on (for example, if g_loadable_icon_load() is called) if the image is invalid. Since: 2.38 a #GBytes. a #GIcon for the given @bytes. Will set @cancellable to cancelled, and will emit the #GCancellable::cancelled signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.) This function is thread-safe. In other words, you can safely call it from a thread other than the one running the operation that was passed the @cancellable. If @cancellable is %NULL, this function returns immediately for convenience. The convention within GIO is that cancelling an asynchronous operation causes it to complete asynchronously. That is, if you cancel the operation from the same thread in which it is running, then the operation's #GAsyncReadyCallback will not be invoked until the application returns to the main loop. a #GCancellable object. 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. @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(). Since: 2.22 A #GCancellable. The #GCallback to connect. Data to pass to @callback. Free function for @data or %NULL. The id of the signal handler or 0 if @cancellable has already been cancelled. 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. 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 A #GCancellable or %NULL. Handler id of the handler to be disconnected, or `0`. Gets the top cancellable from the stack. a #GCancellable from the top of the stack, or %NULL if the stack is empty. Gets the file descriptor for a cancellable job. This can be used to implement cancellable operations on Unix systems. The returned fd will turn readable when @cancellable is cancelled. You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with g_cancellable_reset(). After a successful return from this function, you should use g_cancellable_release_fd() to free up resources allocated for the returned file descriptor. See also g_cancellable_make_pollfd(). a #GCancellable. A valid file descriptor. `-1` if the file descriptor is not supported, or on errors. Checks if a cancellable job has been cancelled. a #GCancellable or %NULL %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled. Creates a #GPollFD corresponding to @cancellable; this can be passed to g_poll() and used to poll for cancellation. This is useful both for unix systems without a native poll and for portability to windows. When this function returns %TRUE, you should use g_cancellable_release_fd() to free up resources allocated for the @pollfd. After a %FALSE return, do not call g_cancellable_release_fd(). If this function returns %FALSE, either no @cancellable was given or resource limits prevent this function from allocating the necessary structures for polling. (On Linux, you will likely have reached the maximum number of file descriptors.) The suggested way to handle these cases is to ignore the @cancellable. 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(). Since: 2.22 a #GCancellable or %NULL a pointer to a #GPollFD %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable. Creates a new #GCancellable object. Applications that want to start one or more operations that should be cancellable should create a #GCancellable and pass it to the operations. One #GCancellable can be used in multiple consecutive operations or in multiple concurrent operations. a #GCancellable. Pops @cancellable off the cancellable stack (verifying that @cancellable is on the top of the stack). a #GCancellable object Pushes @cancellable onto the cancellable stack. The current cancellable can then be received using g_cancellable_get_current(). This is useful when implementing cancellable operations in code that does not allow you to pass down the cancellable object. This is typically called automatically by e.g. #GFile operations, so you rarely have to call this yourself. a #GCancellable object Releases a resources previously allocated by g_cancellable_get_fd() or g_cancellable_make_pollfd(). For compatibility reasons with older releases, calling this function is not strictly required, the resources will be automatically freed when the @cancellable is finalized. However, the @cancellable will block scarce file descriptors until it is finalized if this function is not called. This can cause the application to run out of file descriptors when many #GCancellables are used at the same time. Since: 2.22 a #GCancellable Resets @cancellable to its uncancelled state. If cancellable is currently in use by any cancellable operation then the behavior of this function is undefined. Note that it is generally not a good idea to reuse an existing cancellable for more operations after it has been cancelled once, as this function might tempt you to do. The recommended practice is to drop the reference to a cancellable after cancelling it, and let it die with the outstanding async operations. You should create a fresh cancellable for further async operations. a #GCancellable object. If the @cancellable is cancelled, sets the error to notify that the operation was cancelled. a #GCancellable or %NULL #GError to append error state to %TRUE if @cancellable was cancelled, %FALSE if it was not 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. For convenience, you can call this with a %NULL #GCancellable, in which case the source will never trigger. The new #GSource will hold a reference to the #GCancellable. Since: 2.28 a #GCancellable, or %NULL the new #GSource. Gets the number of fallbacks that @converter has applied so far. Since: 2.24 a #GCharsetConverter the number of fallbacks that @converter has applied Gets the #GCharsetConverter:use-fallback property. Since: 2.24 a #GCharsetConverter %TRUE if fallbacks are used by @converter Creates a new #GCharsetConverter. Since: 2.24 destination charset source charset #GError for error reporting, or %NULL to ignore. a new #GCharsetConverter or %NULL on error. Sets the #GCharsetConverter:use-fallback property. Since: 2.24 a #GCharsetConverter %TRUE to use fallbacks 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). a content type string %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise. Compares two content types for equality. a content type string a content type string %TRUE if the two strings are identical or equivalent, %FALSE otherwise. Tries to find a content type based on the mime type name. Since: 2.18 a mime type string Newly allocated string with content type or %NULL. Free with g_free() Gets the human readable description of the content type. a content type string a short description of the content type @type. Free the returned string with g_free() Gets the generic icon name for a content type. See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on the generic icon name. Since: 2.34 a content type string the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free() Gets the icon for a content type. a content type string #GIcon corresponding to the content type. Free the returned object with g_object_unref() Get the list of directories which MIME data is loaded from. See g_content_type_set_mime_dirs() for details. Since: 2.60 %NULL-terminated list of directories to load MIME data from, including any `mime/` subdirectory, and with the first directory to try listed first Gets the mime type for the content type, if one is registered. a content type string the registered mime type for the given @type, or %NULL if unknown; free with g_free(). Gets the symbolic icon for a content type. Since: 2.34 a content type string symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref() 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. a path, or %NULL a stream of data, or %NULL the size of @data return location for the certainty of the result, or %NULL a string indicating a guessed content type for the given data. Free with g_free() Tries to guess the type of the tree with root @root, by looking at the files it contains. The result is an array of content types, with the best guess coming first. The types returned all have the form x-content/foo, e.g. x-content/audio-cdda (for audio CDs) or x-content/image-dcf (for a camera memory card). See the [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types. This function is useful in the implementation of g_mount_guess_content_type(). Since: 2.18 the root of the tree to guess a type for an %NULL-terminated array of zero or more content types. Free with g_strfreev() Determines if @type is a subset of @supertype. a content type string a content type string %TRUE if @type is a kind of @supertype, %FALSE otherwise. Determines if @type is a subset of @mime_type. Convenience wrapper around g_content_type_is_a(). Since: 2.52 a content type string a mime type string %TRUE if @type is a kind of @mime_type, %FALSE otherwise. 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. a content type string %TRUE if the type is the unknown type. Set the list of directories used by GIO to load the MIME database. If @dirs is %NULL, the directories used are the default: - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` This function is intended to be used when writing tests that depend on information stored in the MIME database, in order to control the data. Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they depend on the system’s MIME database, you should call this function with @dirs set to %NULL before calling g_test_init(), for instance: |[<!-- language="C" --> // Load MIME data from the system g_content_type_set_mime_dirs (NULL); // Isolate the environment g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); … return g_test_run (); ]| Since: 2.60 %NULL-terminated list of directories to load MIME data from, including any `mime/` subdirectory, and with the first directory to try listed first 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)`. list of the registered content types This is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in @outbuf) or consuming some input (from @inbuf) or both. If its not possible to do any work an error is returned. Note that a single call may not consume all input (or any input at all). Also a call may produce output even if given no input, due to state stored in the converter producing output. If any data was either produced or consumed, and then an error happens, then only the successful conversion is reported and the error is returned on the next call. A full conversion loop involves calling this method repeatedly, each time giving it new input and space output space. When there is no more input data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED each time until all data is consumed and all output is produced, then %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance in a decompression converter where the end of data is detectable from the data (and there might even be other data after the end of the compressed data). When some data has successfully been converted @bytes_read and is set to the number of bytes read from @inbuf, and @bytes_written is set to indicate how many bytes was written to @outbuf. If there are more data to output or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then %G_CONVERTER_CONVERTED is returned, and if no more data is to be output then %G_CONVERTER_FINISHED is returned. On error %G_CONVERTER_ERROR is returned and @error is set accordingly. Some errors need special handling: %G_IO_ERROR_NO_SPACE is returned if there is not enough space to write the resulting converted data, the application should call the function again with a larger @outbuf to continue. %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough input to fully determine what the conversion should produce, and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for example with an incomplete multibyte sequence when converting text, or when a regexp matches up to the end of the input (and may match further input). It may also happen when @inbuf_size is zero and there is no more data to produce. When this happens the application should read more input and then call the function again. If further input shows that there is no more data call the function again with the same data but with the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion to finish as e.g. in the regexp match case (or, to fail again with %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the input is actually partial). After g_converter_convert() has returned %G_CONVERTER_FINISHED the converter object is in an invalid state where its not allowed to call g_converter_convert() anymore. At this time you can only free the object or call g_converter_reset() to reset it to the initial state. If the flag %G_CONVERTER_FLUSH is set then conversion is modified to try to write out all internal state to the output. The application has to call the function multiple times with the flag set, and when the available input has been consumed and all internal state has been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if really at the end) is returned instead of %G_CONVERTER_CONVERTED. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data. 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). Since: 2.24 a #GConverter. the buffer containing the data to convert. the number of bytes in @inbuf a buffer to write converted data in. the number of bytes in @outbuf, must be at least one a #GConverterFlags controlling the conversion details will be set to the number of bytes read from @inbuf on success will be set to the number of bytes written to @outbuf on success location to store the error occurring, or %NULL to ignore a #GConverterResult, %G_CONVERTER_ERROR on error. Gets the #GConverter that is used by @converter_stream. Since: 2.24 a #GConverterInputStream the converter of the converter input stream Creates a new converter input stream for the @base_stream. a #GInputStream a #GConverter a new #GInputStream. Gets the #GConverter that is used by @converter_stream. Since: 2.24 a #GConverterOutputStream the converter of the converter output stream Creates a new converter output stream for the @base_stream. a #GOutputStream a #GConverter a new #GOutputStream. 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. Since: 2.24 a #GConverter. Gets a pointer to native credentials of type @native_type from @credentials. It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Since: 2.26 A #GCredentials. The type of native credentials to get. The pointer to native credentials or %NULL if 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. Tries to get the UNIX process identifier from @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX process ID. Since: 2.36 A #GCredentials Return location for error or %NULL. The UNIX process ID, or `-1` if @error is set. Tries to get the UNIX user identifier from @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. Since: 2.26 A #GCredentials Return location for error or %NULL. The UNIX user identifier or `-1` if @error is set. Checks if @credentials and @other_credentials is the same user. This operation can fail if #GCredentials is not supported on the the OS. Since: 2.26 A #GCredentials. A #GCredentials. Return location for error or %NULL. %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set. Creates a new #GCredentials object with credentials matching the the current process. Since: 2.26 A #GCredentials. Free with g_object_unref(). Copies the native credentials of type @native_type from @native into @credentials. It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Since: 2.26 A #GCredentials. The type of native credentials to set. A pointer to native credentials. Tries to set the UNIX user identifier on @credentials. This method is only available on UNIX platforms. This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. It can also fail if the OS does not allow the use of "spoofed" credentials. Since: 2.26 A #GCredentials. The UNIX user identifier to set. Return location for error or %NULL. %TRUE if @uid was set, %FALSE if error is set. 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. Since: 2.26 A #GCredentials object. A string that should be freed with g_free(). Gets the byte order for the data input stream. a given #GDataInputStream. the @stream's current #GDataStreamByteOrder. Gets the current newline type for the @stream. a given #GDataInputStream. #GDataStreamNewlineType for the given @stream. Creates a new data input stream for the @base_stream. a #GInputStream. a new #GDataInputStream. Reads an unsigned 8-bit/1-byte value from @stream. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. an unsigned 8-bit/1-byte value read from the @stream or `0` if an error occurred. Reads a 16-bit/2-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. a signed 16-bit/2-byte value read from @stream or `0` if an error occurred. Reads a signed 32-bit/4-byte value from @stream. In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. a signed 32-bit/4-byte value read from the @stream or `0` if an error occurred. 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. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. a signed 64-bit/8-byte value read from @stream or `0` if an error occurred. 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. a given #GDataInputStream. a #gsize to get the length of the data read in. optional #GCancellable object, %NULL to ignore. #GError for error reporting. 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. 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 a given #GDataInputStream. the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied. the data to pass to callback function. 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. Since: 2.20 a given #GDataInputStream. the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. #GError for error reporting. 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. Finish an asynchronous call started by g_data_input_stream_read_line_async(). Since: 2.30 a given #GDataInputStream. the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. #GError for error reporting. 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. 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. Since: 2.30 a given #GDataInputStream. a #gsize to get the length of the data read in. optional #GCancellable object, %NULL to ignore. #GError for error reporting. 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. 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(). a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. an unsigned 16-bit/2-byte value read from the @stream or `0` if an error occurred. 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. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. an unsigned 32-bit/4-byte value read from the @stream or `0` if an error occurred. 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. a given #GDataInputStream. optional #GCancellable object, %NULL to ignore. #GError for error reporting. an unsigned 64-bit/8-byte read from @stream or `0` if an error occurred. 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. Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more consistent behaviour regarding the stop character. a given #GDataInputStream. characters to terminate the read. a #gsize to get the length of the data read in. optional #GCancellable object, %NULL to ignore. #GError for error reporting. 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. 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 Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which has more consistent behaviour regarding the stop character. a given #GDataInputStream. characters to terminate the read. the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied. the data to pass to callback function. Finish an asynchronous call started by g_data_input_stream_read_until_async(). Since: 2.20 Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which has more consistent behaviour regarding the stop character. a given #GDataInputStream. the #GAsyncResult that was provided to the callback. a #gsize to get the length of the data read in. #GError for error reporting. 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. 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. The returned string will always be nul-terminated on success. Since: 2.26 a #GDataInputStream characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is nul-terminated a #gsize to get the length of the data read in optional #GCancellable object, %NULL to ignore #GError for error reporting 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 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 a #GDataInputStream characters to terminate the read length of @stop_chars. May be -1 if @stop_chars is nul-terminated the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore callback to call when the request is satisfied the data to pass to callback function 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. The returned string will always be nul-terminated on success. Since: 2.24 a #GDataInputStream the #GAsyncResult that was provided to the callback a #gsize to get the length of the data read in #GError for error reporting 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. This function sets the byte order for the given @stream. All subsequent reads from the @stream will be read in the given @order. a given #GDataInputStream. a #GDataStreamByteOrder to set. 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. a #GDataInputStream. the type of new line return as #GDataStreamNewlineType. Gets the byte order for the stream. a #GDataOutputStream. the #GDataStreamByteOrder for the @stream. Creates a new data output stream for @base_stream. a #GOutputStream. #GDataOutputStream. Puts a byte into the output stream. a #GDataOutputStream. a #guchar. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Puts a signed 16-bit integer into the output stream. a #GDataOutputStream. a #gint16. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Puts a signed 32-bit integer into the output stream. a #GDataOutputStream. a #gint32. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Puts a signed 64-bit integer into the stream. a #GDataOutputStream. a #gint64. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Puts a string into the output stream. a #GDataOutputStream. a string. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @string was successfully added to the @stream. Puts an unsigned 16-bit integer into the output stream. a #GDataOutputStream. a #guint16. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Puts an unsigned 32-bit integer into the stream. a #GDataOutputStream. a #guint32. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Puts an unsigned 64-bit integer into the stream. a #GDataOutputStream. a #guint64. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. %TRUE if @data was successfully added to the @stream. Sets the byte order of the data output stream to @order. a #GDataOutputStream. a %GDataStreamByteOrder. 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. Since: 2.48 a #GDatagramBased a #GIOCondition mask to check the #GIOCondition mask of the current state 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). Since: 2.48 a #GDatagramBased a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a #GCancellable return location for a #GError %TRUE if the condition was met, %FALSE otherwise 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(). Since: 2.48 a #GDatagramBased a #GIOCondition mask to monitor a #GCancellable a newly allocated #GSource 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. Since: 2.48 a #GDatagramBased an array of #GInputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable return location for a #GError 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. 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. Since: 2.48 a #GDatagramBased an array of #GOutputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags the maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely a %GCancellable return location for a #GError 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. 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. Since: 2.32 A #GDBusConnection the bus name which exports the action group or %NULL if @connection is not a message bus connection the object path at which the action group is exported a #GDBusActionGroup 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`. Since: 2.36 an unescaped string to be included in a D-Bus address as the value in a key-value pair a copy of @string with all non-optionally-escaped bytes escaped 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). Since: 2.26 a #GBusType a #GCancellable or %NULL return location for error or %NULL a valid D-Bus address string for @bus_type or %NULL if @error is set 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 A valid D-Bus address. A #GCancellable or %NULL. A #GAsyncReadyCallback to call when the request is satisfied. Data to pass to @callback. Finishes an operation started with g_dbus_address_get_stream(). A server is not required to set a GUID, so @out_guid may be set to %NULL even on success. Since: 2.26 A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). %NULL or return location to store the GUID extracted from @address, if any. Return location for error or %NULL. A #GIOStream or %NULL if @error is set. 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). A server is not required to set a GUID, so @out_guid may be set to %NULL even on success. This is a synchronous failable function. See g_dbus_address_get_stream() for the asynchronous version. Since: 2.26 A valid D-Bus address. %NULL or return location to store the GUID extracted from @address, if any. A #GCancellable or %NULL. Return location for error or %NULL. A #GIOStream or %NULL if @error is set. Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. Since: 2.26 A %NULL-terminated array of annotations or %NULL. The name of the annotation to look up. The value or %NULL if not found. Do not free, it is owned by @annotations. If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusNodeInfo The same @info. 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 A #GDBusAnnotationInfo. If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusArgInfo The same @info. 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 A #GDBusArgInfo. Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. Since: 2.34 A #GDBusAuthObserver. The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. Since: 2.26 A #GDBusAuthObserver. A #GIOStream for the #GDBusConnection. Credentials received from the peer or %NULL. %TRUE if the peer is authorized, %FALSE if not. Creates a new #GDBusAuthObserver object. Since: 2.26 A #GDBusAuthObserver. Free with g_object_unref(). 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. Similarly, 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.) Since: 2.26 a #GDBusConnection a filter function user data to pass to @filter_function function to free @user_data with when filter is removed or %NULL a filter identifier that can be used with g_dbus_connection_remove_filter() 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. Unless it’s %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more values. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_connection_call (connection, "org.freedesktop.StringThings", "/org/freedesktop/StringThings", "org.freedesktop.StringThings", "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), NULL, G_DBUS_CALL_FLAGS_NONE, -1, NULL, (GAsyncReadyCallback) two_strings_done, NULL); ]| 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 a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply (which will be a tuple), or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation the data to pass to @callback Finishes an operation started with g_dbus_connection_call(). Since: 2.26 a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() return location for error or %NULL %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). 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.: |[<!-- language="C" --> g_dbus_connection_call_sync (connection, "org.freedesktop.StringThings", "/org/freedesktop/StringThings", "org.freedesktop.StringThings", "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), NULL, G_DBUS_CALL_FLAGS_NONE, -1, NULL, &error); ]| The calling thread is blocked until a reply is received. See g_dbus_connection_call() for the asynchronous version of this method. Since: 2.26 a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GCancellable or %NULL return location for error or %NULL %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). Like g_dbus_connection_call() but also takes a #GUnixFDList object. The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if a message contains two file descriptors, @fd_list would have length 2, and `g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear somewhere in the body of the message (not necessarily in that order!) to represent the file descriptors at indexes 0 and 1 respectively. When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. This method is only available on UNIX. Since: 2.30 a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GUnixFDList or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation The data to pass to @callback. Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if g_variant_get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by `g_unix_fd_list_get (*out_fd_list, 5, ...)`. When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced in this way by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. Since: 2.30 a #GDBusConnection return location for a #GUnixFDList or %NULL a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list() return location for error or %NULL %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. See g_dbus_connection_call_with_unix_fd_list() and g_dbus_connection_call_with_unix_fd_list_finish() for more details. This method is only available on UNIX. Since: 2.30 a #GDBusConnection a unique or well-known bus name or %NULL if @connection is not a message bus connection path of remote object D-Bus interface to invoke method on the name of the method to invoke a #GVariant tuple with parameters for the method or %NULL if not passing parameters the expected type of the reply, or %NULL flags from the #GDBusCallFlags enumeration the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout a #GUnixFDList or %NULL return location for a #GUnixFDList or %NULL a #GCancellable or %NULL return location for error or %NULL %NULL if @error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref(). 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 a #GDBusConnection a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result The data to pass to @callback Finishes an operation started with g_dbus_connection_close(). Since: 2.26 a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close() return location for error or %NULL %TRUE if the operation succeeded, %FALSE if @error is set Synchronously closes @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. Since: 2.26 a #GDBusConnection a #GCancellable or %NULL return location for error or %NULL %TRUE if the operation succeeded, %FALSE if @error is set 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 (%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed (%G_IO_ERROR_CLOSED). Since: 2.26 a #GDBusConnection the unique bus name for the destination for the signal or %NULL to emit to all listeners path of remote object D-Bus interface to emit a signal on the name of the signal to emit a #GVariant tuple with parameters for the signal or %NULL if not passing parameters Return location for error or %NULL %TRUE unless @error is set 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. Since: 2.32 a #GDBusConnection a D-Bus object path a #GActionGroup a pointer to a %NULL #GError, or %NULL the ID of the export (never zero), or 0 in case of failure 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). Exporting menus with sections containing more than %G_MENU_EXPORTER_MAX_SECTION_SIZE items is not supported and results in undefined behavior. You can unexport the menu model using g_dbus_connection_unexport_menu_model() with the return value of this function. Since: 2.32 a #GDBusConnection a D-Bus object path a #GMenuModel return location for an error, or %NULL the ID of the export (never zero), or 0 in case of failure 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 a #GDBusConnection a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result The data to pass to @callback Finishes an operation started with g_dbus_connection_flush(). Since: 2.26 a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush() return location for error or %NULL %TRUE if the operation succeeded, %FALSE if @error is set 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. Since: 2.26 a #GDBusConnection a #GCancellable or %NULL return location for error or %NULL %TRUE if the operation succeeded, %FALSE if @error is set Gets the capabilities negotiated with the remote peer Since: 2.26 a #GDBusConnection zero or more flags from the #GDBusCapabilityFlags enumeration Gets whether the process is terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. Since: 2.26 a #GDBusConnection whether the process is terminated when @connection is closed by the remote peer Gets the flags used to construct this connection Since: 2.60 a #GDBusConnection zero or more flags from the #GDBusConnectionFlags enumeration The GUID of the peer performing the role of server when authenticating. See #GDBusConnection:guid for more details. Since: 2.26 a #GDBusConnection The GUID. Do not free this string, it is owned by @connection. Retrieves the last serial number assigned to a #GDBusMessage on the current thread. This includes messages sent via both low-level API such as g_dbus_connection_send_message() as well as high-level API such as g_dbus_connection_emit_signal(), g_dbus_connection_call() or g_dbus_proxy_call(). Since: 2.34 a #GDBusConnection the last used serial or zero when no message has been sent within the current thread 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. Since: 2.26 a #GDBusConnection a #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection. 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. Since: 2.26 a #GDBusConnection the stream used for IO 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. Since: 2.26 a #GDBusConnection the unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection. Gets whether @connection is closed. Since: 2.26 a #GDBusConnection %TRUE if the connection is closed, %FALSE otherwise 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 an asynchronous failable constructor. See g_dbus_connection_new_sync() for the synchronous version. Since: 2.26 a #GIOStream the GUID to use if authenticating as a server or %NULL flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to @callback Finishes an operation started with g_dbus_connection_new(). Since: 2.26 a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). return location for error or %NULL a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). 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, %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. When the operation is finished, @callback will be invoked. You can then call g_dbus_connection_new_for_address_finish() to get the result of the operation. If @observer is not %NULL it may be used to control the authentication process. This is an asynchronous failable constructor. See g_dbus_connection_new_for_address_sync() for the synchronous version. Since: 2.26 a D-Bus address flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to @callback Finishes an operation started with g_dbus_connection_new_for_address(). Since: 2.26 a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new() return location for error or %NULL a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by @address which must be in the [D-Bus address format](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, %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER 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. Since: 2.26 a D-Bus address flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL return location for error or %NULL a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). 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. This is a synchronous failable constructor. See g_dbus_connection_new() for the asynchronous version. Since: 2.26 a #GIOStream the GUID to use if authenticating as a server or %NULL flags describing how to make the connection a #GDBusAuthObserver or %NULL a #GCancellable or %NULL return location for error or %NULL a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). 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. Since: 2.26 a #GDBusConnection the object path to register at introspection data for the interface a #GDBusInterfaceVTable to call into or %NULL data to pass to functions in @vtable function to call when the object path is unregistered return location for error or %NULL 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() Version of g_dbus_connection_register_object() using closures instead of a #GDBusInterfaceVTable for easier binding in other languages. Since: 2.46 A #GDBusConnection. The object path to register at. Introspection data for the interface. #GClosure for handling incoming method calls. #GClosure for getting a property. #GClosure for setting a property. Return location for error or %NULL. 0 if @error is set, otherwise a registration ID (never 0) that can be used with g_dbus_connection_unregister_object() . 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. Since: 2.26 a #GDBusConnection the object path to register the subtree at a #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree flags used to fine tune the behavior of the subtree data to pass to functions in @vtable function to call when the subtree is unregistered return location for error or %NULL 0 if @error is set, otherwise a subtree registration ID (never 0) that can be used with g_dbus_connection_unregister_subtree() 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 a #GDBusConnection an identifier obtained from g_dbus_connection_add_filter() 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. While it has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. 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. Since: 2.26 a #GDBusConnection a #GDBusMessage flags affecting how the message is sent return location for serial number assigned to @message when sending it or %NULL Return location for error or %NULL %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set 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. While it has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. 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 a #GDBusConnection a #GDBusMessage flags affecting how the message is sent the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout return location for serial number assigned to @message when sending it or %NULL a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result The data to pass to @callback 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. Since: 2.26 a #GDBusConnection a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply() teturn location for error or %NULL a locked #GDBusMessage or %NULL if @error is set 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. While it has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. 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. Since: 2.26 a #GDBusConnection a #GDBusMessage flags affecting how the message is sent. the timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout return location for serial number assigned to @message when sending it or %NULL a #GCancellable or %NULL return location for error or %NULL a locked #GDBusMessage that is the reply to @message or %NULL if @error is set 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 with the session bus, and expect all of a user's 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 a #GDBusConnection whether the process should be terminated when @connection is closed by the remote peer Subscribes to signals on @connection and invokes @callback 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.) As @callback is potentially invoked in a different thread from where it’s emitted, it’s possible for this to happen after g_dbus_connection_signal_unsubscribe() has been called in another thread. Due to this, @user_data should have a strong reference which is freed with @user_data_free_func, rather than pointing to data whose lifecycle is tied to the signal subscription. For example, if a #GObject is used to store the subscription ID from g_dbus_connection_signal_subscribe(), a strong reference to that #GObject must be passed to @user_data, and g_object_unref() passed to @user_data_free_func. You are responsible for breaking the resulting reference count cycle by explicitly unsubscribing from the signal when dropping the last external reference to the #GObject. Alternatively, a weak reference may be used. It is guaranteed that if you unsubscribe from a signal using g_dbus_connection_signal_unsubscribe() from the same thread which made the corresponding g_dbus_connection_signal_subscribe() call, @callback will not be invoked after g_dbus_connection_signal_unsubscribe() returns. The returned subscription identifier is an opaque value which is guaranteed to never be zero. This function can never fail. Since: 2.26 a #GDBusConnection sender name to match on (unique or well-known name) or %NULL to listen from all senders D-Bus interface name to match on or %NULL to match on all interfaces D-Bus signal name to match on or %NULL to match on all signals object path to match on or %NULL to match on all object paths contents of first string argument to match on or %NULL to match on all kinds of arguments #GDBusSignalFlags describing how arg0 is used in subscribing to the signal callback to invoke when there is a signal matching the requested data user data to pass to @callback function to free @user_data with when subscription is removed or %NULL a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() Unsubscribes from signals. Note that there may still be D-Bus traffic to process (relating to this signal subscription) in the current thread-default #GMainContext after this function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_dbus_connection_signal_subscribe() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being iterated. Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT that was scheduled after unsubscription, also indicates that all resources of this subscription are released. Since: 2.26 a #GDBusConnection a subscription id obtained from g_dbus_connection_signal_subscribe() 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 a #GDBusConnection 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 a #GDBusConnection the ID from g_dbus_connection_export_action_group() 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 a #GDBusConnection the ID from g_dbus_connection_export_menu_model() Unregisters an object. Since: 2.26 a #GDBusConnection a registration id obtained from g_dbus_connection_register_object() %TRUE if the object was unregistered, %FALSE otherwise Unregisters a subtree. Since: 2.26 a #GDBusConnection a subtree registration id obtained from g_dbus_connection_register_subtree() %TRUE if the subtree was unregistered, %FALSE otherwise 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. Since: 2.26 A #GError. A D-Bus error name (never %NULL). Free with g_free(). 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. Since: 2.26 a #GError an allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). 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. Since: 2.26 A #GError. %TRUE if @error represents an error from a remote peer, %FALSE otherwise. 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. Since: 2.26 D-Bus error name. D-Bus error message. An allocated #GError. Free with g_error_free(). 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. Since: 2.26 A #GQuark for an error domain. An error code. A D-Bus error name. %TRUE if the association was created, %FALSE if it already exists. Helper function for associating a #GError error domain with D-Bus error names. While @quark_volatile has a `volatile` qualifier, this is a historical artifact and the argument passed to it should not be `volatile`. Since: 2.26 The error domain name. A pointer where to store the #GQuark. A pointer to @num_entries #GDBusErrorEntry struct items. Number of items to register. 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). Since: 2.26 A pointer to a #GError or %NULL. D-Bus error name. D-Bus error message. printf()-style format to prepend to @dbus_error_message or %NULL. Arguments for @format. Like g_dbus_error_set_dbus_error() but intended for language bindings. Since: 2.26 A pointer to a #GError or %NULL. D-Bus error name. D-Bus error message. printf()-style format to prepend to @dbus_error_message or %NULL. Arguments for @format. 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. Since: 2.26 A #GError. %TRUE if information was stripped, %FALSE otherwise. Destroys an association previously set up with g_dbus_error_register_error(). Since: 2.26 A #GQuark for an error domain. An error code. A D-Bus error name. %TRUE if the association was destroyed, %FALSE if it wasn't found. This is a language binding friendly version of g_dbus_escape_object_path_bytestring(). Since: 2.68 the string to escape an escaped version of @s. Free with g_free(). Escapes @bytes for use in a D-Bus object path component. @bytes is an array of zero or more nonzero bytes in an unspecified encoding, followed by a single zero byte. The escaping method consists of replacing all non-alphanumeric characters (see g_ascii_isalnum()) with their hexadecimal value preceded by an underscore (`_`). For example: `foo.bar.baz` will become `foo_2ebar_2ebaz`. This method is appropriate to use when the input is nearly a valid object path component but is not when your input is far from being a valid object path component. Other escaping algorithms are also valid to use with D-Bus object paths. This can be reversed with g_dbus_unescape_object_path(). Since: 2.68 the string of bytes to escape an escaped version of @bytes. Free with g_free(). Generate a D-Bus GUID that can be used with e.g. g_dbus_connection_new(). See the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids) regarding what strings are valid D-Bus GUIDs. The specification refers to these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as ‘GUIDs’. The terms are interchangeable. Note that D-Bus GUIDs do not follow [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). Since: 2.26 A valid D-Bus GUID. Free with g_free(). 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', i.e. %G_VARIANT_TYPE_INT32. 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. Since: 2.30 A #GValue to convert to a #GVariant A #GVariantType A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or an empty #GVariant in case of failure. Free with g_variant_unref(). 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 A #GVariant. Return location pointing to a zero-filled (uninitialized) #GValue. Gets the #GDBusObject that @interface_ belongs to, if any. Since: 2.32 An exported D-Bus interface. A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. Since: 2.30 An exported D-Bus interface. A #GDBusInterfaceInfo. Do not free. 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. Since: 2.30 An exported D-Bus interface A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. 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 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 A GDBusInterfaceInfo 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 A #GDBusNodeInfo Indentation level. A #GString to to append XML data to. 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. Since: 2.26 A #GDBusInterfaceInfo. A D-Bus method name (typically in CamelCase) A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. 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. Since: 2.26 A #GDBusInterfaceInfo. A D-Bus property name (typically in CamelCase). A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. 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. Since: 2.26 A #GDBusInterfaceInfo. A D-Bus signal name (typically in CamelCase) A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusInterfaceInfo The same @info. 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 A #GDBusInterfaceInfo. Sets the #GDBusObject for @interface_ to @object. Note that @interface_ will hold a weak reference to @object. Since: 2.30 An exported D-Bus interface. A #GDBusObject 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. Since: 2.30 The D-Bus interface to export. A #GDBusConnection to export @interface_ on. The path to export the interface at. Return location for error or %NULL. %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set. 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 A #GDBusInterfaceSkeleton. Gets the first connection that @interface_ is exported on, if any. Since: 2.30 A #GDBusInterfaceSkeleton. A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. Gets a list of the connections that @interface_ is exported on. Since: 2.32 A #GDBusInterfaceSkeleton. 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(). Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior of @interface_ Since: 2.30 A #GDBusInterfaceSkeleton. One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. Gets D-Bus introspection information for the D-Bus interface implemented by @interface_. Since: 2.30 A #GDBusInterfaceSkeleton. A #GDBusInterfaceInfo (never %NULL). Do not free. Gets the object path that @interface_ is exported on, if any. Since: 2.30 A #GDBusInterfaceSkeleton. A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. Gets all D-Bus properties for @interface_. Since: 2.30 A #GDBusInterfaceSkeleton. A #GVariant of type ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. Free with g_variant_unref(). 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. Since: 2.30 A #GDBusInterfaceSkeleton. A #GDBusInterfaceVTable (never %NULL). Checks if @interface_ is exported on @connection. Since: 2.32 A #GDBusInterfaceSkeleton. A #GDBusConnection. %TRUE if @interface_ is exported on @connection, %FALSE otherwise. Sets flags describing what the behavior of @skeleton should be. Since: 2.30 A #GDBusInterfaceSkeleton. Flags from the #GDBusInterfaceSkeletonFlags enumeration. 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 A #GDBusInterfaceSkeleton. 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 A #GDBusInterfaceSkeleton. A #GDBusConnection. 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. Since: 2.26 A string. %TRUE if @string is a valid D-Bus address, %FALSE otherwise. Check whether @string is a valid D-Bus error name. This function returns the same result as g_dbus_is_interface_name(), because D-Bus error names are defined to have exactly the same syntax as interface names. Since: 2.70 The string to check. %TRUE if valid, %FALSE otherwise. Checks if @string is a D-Bus GUID. See the documentation for g_dbus_generate_guid() for more information about the format of a GUID. Since: 2.26 The string to check. %TRUE if @string is a GUID, %FALSE otherwise. Checks if @string is a valid D-Bus interface name. Since: 2.26 The string to check. %TRUE if valid, %FALSE otherwise. Checks if @string is a valid D-Bus member (e.g. signal or method) name. Since: 2.26 The string to check. %TRUE if valid, %FALSE otherwise. Checks if @string is a valid D-Bus bus name (either unique or well-known). Since: 2.26 The string to check. %TRUE if valid, %FALSE otherwise. 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). Since: 2.26 A string. Return location for error or %NULL. %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set. Checks if @string is a valid D-Bus unique bus name. Since: 2.26 The string to check. %TRUE if valid, %FALSE otherwise. Obtains a #GDBusMenuModel for the menu model 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. Since: 2.32 a #GDBusConnection the bus name which exports the menu model or %NULL if @connection is not a message bus connection the object path at which the menu model is exported a #GDBusMenuModel object. Free with g_object_unref(). Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at @blob. Since: 2.26 A blob representing a binary D-Bus message. The length of @blob (must be at least 16). Return location for error or %NULL. 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). Copies @message. The copy is a deep copy and the returned #GDBusMessage is completely identical except that it is guaranteed to not be locked. This operation can fail if e.g. @message contains file descriptors and the per-process or system-wide open files limit is reached. Since: 2.26 A #GDBusMessage. Return location for error or %NULL. A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). Convenience to get the first item in the body of @message. Since: 2.26 A #GDBusMessage. The string item or %NULL if the first item in the body of @message is not a string. Gets the body of a message. Since: 2.26 A #GDBusMessage. A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message. Gets the byte order of @message. A #GDBusMessage. The byte order. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. Since: 2.26 A #GDBusMessage. The value. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. Since: 2.26 A #GDBusMessage. The value. Gets the flags for @message. Since: 2.26 A #GDBusMessage. Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). Gets a header field on @message. The caller is responsible for checking the type of the returned #GVariant matches what is expected. Since: 2.26 A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message. Gets an array of all header fields on @message that are set. Since: 2.26 A #GDBusMessage. An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free(). Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. Since: 2.26 A #GDBusMessage. The value. 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. Since: 2.26 A #GDBusMessage. %TRUE if @message is locked, %FALSE otherwise. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. Since: 2.26 A #GDBusMessage. The value. Gets the type of @message. Since: 2.26 A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. Since: 2.26 A #GDBusMessage. The value. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. Since: 2.26 A #GDBusMessage. The value. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. Since: 2.26 A #GDBusMessage. The value. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. Since: 2.26 A #GDBusMessage. The value. Gets the serial for @message. Since: 2.26 A #GDBusMessage. A #guint32. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. This will always be non-%NULL, but may be an empty string. Since: 2.26 A #GDBusMessage. The value. Gets the UNIX file descriptors associated with @message, if any. This method is only available on UNIX. The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if g_variant_get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by `g_unix_fd_list_get (list, 5, ...)`. Since: 2.26 A #GDBusMessage. A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. If @message is locked, does nothing. Otherwise locks the message. Since: 2.26 A #GDBusMessage. Creates a new empty #GDBusMessage. Since: 2.26 A #GDBusMessage. Free with g_object_unref(). 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(). If the @blob cannot be parsed, contains invalid fields, or contains invalid headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. Since: 2.26 A blob representing a binary D-Bus message. The length of @blob. A #GDBusCapabilityFlags describing what protocol features are supported. Return location for error or %NULL. A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). Creates a new #GDBusMessage for a method call. Since: 2.26 A valid D-Bus name or %NULL. A valid object path. A valid D-Bus interface name or %NULL. A valid method name. A #GDBusMessage. Free with g_object_unref(). Creates a new #GDBusMessage that is an error reply to @method_call_message. Since: 2.26 A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. The D-Bus error message in a printf() format. Arguments for @error_message_format. A #GDBusMessage. Free with g_object_unref(). Creates a new #GDBusMessage that is an error reply to @method_call_message. Since: 2.26 A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. The D-Bus error message. A #GDBusMessage. Free with g_object_unref(). Like g_dbus_message_new_method_error() but intended for language bindings. Since: 2.26 A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. A valid D-Bus error name. The D-Bus error message in a printf() format. Arguments for @error_message_format. A #GDBusMessage. Free with g_object_unref(). Creates a new #GDBusMessage that is a reply to @method_call_message. Since: 2.26 A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. #GDBusMessage. Free with g_object_unref(). Creates a new #GDBusMessage for a signal emission. Since: 2.26 A valid object path. A valid D-Bus interface name. A valid signal name. A #GDBusMessage. Free with g_object_unref(). Produces a human-readable multi-line description of @message. 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: |[ Type: method-call 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 |[ Type: method-return 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 ]| Since: 2.26 A #GDBusMessage. Indentation level. A string that should be freed with g_free(). 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. Since: 2.26 A #GDBusMessage. Either %NULL or a #GVariant that is a tuple. Sets the byte order of @message. A #GDBusMessage. The byte order. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. Since: 2.26 A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. Since: 2.26 A #GDBusMessage. The value to set. Sets the flags to set on @message. Since: 2.26 A #GDBusMessage. Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). Sets a header field on @message. If @value is floating, @message assumes ownership of @value. Since: 2.26 A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) A #GVariant to set the header field or %NULL to clear the header field. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. Since: 2.26 A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. Since: 2.26 A #GDBusMessage. The value to set. Sets @message to be of @type. Since: 2.26 A #GDBusMessage. A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. Since: 2.26 A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. Since: 2.26 A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. Since: 2.26 A #GDBusMessage. The value to set. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. Since: 2.26 A #GDBusMessage. The value to set. Sets the serial for @message. Since: 2.26 A #GDBusMessage. A #guint32. Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. Since: 2.26 A #GDBusMessage. The value to set. 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). This method is only available on UNIX. When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced by a value of type %G_VARIANT_TYPE_HANDLE in the body of the message. Since: 2.26 A #GDBusMessage. A #GUnixFDList or %NULL. Serializes @message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used. Since: 2.26 A #GDBusMessage. Return location for size of generated blob. A #GDBusCapabilityFlags describing what protocol features are supported. Return location for error. 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(). If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does nothing and returns %FALSE. 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. Since: 2.26 A #GDBusMessage. The #GError to set. %TRUE if @error was set, %FALSE otherwise. If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusMethodInfo The same @info. 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 A #GDBusMethodInfo. Gets the #GDBusConnection the method was invoked on. Since: 2.26 A #GDBusMethodInvocation. A #GDBusConnection. Do not free, it is owned by @invocation. Gets the name of the D-Bus interface the method was invoked on. If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then "org.freedesktop.DBus.Properties" will be returned. See #GDBusInterfaceVTable for more information. Since: 2.26 A #GDBusMethodInvocation. A string. Do not free, it is owned by @invocation. 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. 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 A #GDBusMethodInvocation. #GDBusMessage. Do not free, it is owned by @invocation. Gets information about the method call, if any. If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then %NULL will be returned. See g_dbus_method_invocation_get_property_info() and #GDBusInterfaceVTable for more information. Since: 2.26 A #GDBusMethodInvocation. A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. Gets the name of the method that was invoked. Since: 2.26 A #GDBusMethodInvocation. A string. Do not free, it is owned by @invocation. Gets the object path the method was invoked on. Since: 2.26 A #GDBusMethodInvocation. A string. Do not free, it is owned by @invocation. 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. Since: 2.26 A #GDBusMethodInvocation. A #GVariant tuple. Do not unref this because it is owned by @invocation. Gets information about the property that this method call is for, if any. This will only be set in the case of an invocation in response to a property Get or Set call that has been directed to the method call handler for an object on account of its property_get() or property_set() vtable pointers being unset. See #GDBusInterfaceVTable for more information. If the call was GetAll, %NULL will be returned. Since: 2.38 A #GDBusMethodInvocation a #GDBusPropertyInfo or %NULL Gets the bus name that invoked the method. Since: 2.26 A #GDBusMethodInvocation. A string. Do not free, it is owned by @invocation. Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). Since: 2.26 A #GDBusMethodInvocation. A #gpointer. Finishes handling a D-Bus method call by returning an error. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since: 2.26 A #GDBusMethodInvocation. A valid D-Bus error name. A valid D-Bus error message. 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(). 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 A #GDBusMethodInvocation. A #GQuark for the #GError error domain. The error code. printf()-style format. Parameters for @format. Like g_dbus_method_invocation_return_error() but without printf()-style formatting. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since: 2.26 A #GDBusMethodInvocation. A #GQuark for the #GError error domain. The error code. The error message. Like g_dbus_method_invocation_return_error() but intended for language bindings. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since: 2.26 A #GDBusMethodInvocation. A #GQuark for the #GError error domain. The error code. printf()-style format. #va_list of parameters for @format. Like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since: 2.26 A #GDBusMethodInvocation. A #GError. Finishes handling a D-Bus method call by returning @parameters. If the @parameters GVariant is floating, it is consumed. It is an error if @parameters is not of the right format: 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. |[<!-- language="C" --> 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). Since: 2.26 A #GDBusMethodInvocation. A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. 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 A #GDBusMethodInvocation. A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. A #GUnixFDList or %NULL. Like g_dbus_method_invocation_return_gerror() but takes ownership of @error so the caller does not need to free it. This method will take ownership of @invocation. See #GDBusInterfaceVTable for more information about the ownership of @invocation. Since: 2.30 A #GDBusMethodInvocation. A #GError. 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 A #GDBusNodeInfo. Indentation level. A #GString to to append XML data to. Looks up information about an interface. The cost of this function is O(n) in number of interfaces. Since: 2.26 A #GDBusNodeInfo. A D-Bus interface name. A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. Parses @xml_data and returns a #GDBusNodeInfo representing the data. The introspection XML must contain exactly one top-level <node> element. Note that this routine is using a [GMarkup][glib-Simple-XML-Subset-Parser.description]-based parser that only accepts a subset of valid XML documents. Since: 2.26 Valid D-Bus introspection XML. Return location for error. A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref(). If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusNodeInfo The same @info. 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 A #GDBusNodeInfo. Gets the D-Bus interface with name @interface_name associated with @object, if any. Since: 2.30 A #GDBusObject. A D-Bus interface name. %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). Gets the D-Bus interfaces associated with @object. Since: 2.30 A #GDBusObject. 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(). Gets the object path for @object. Since: 2.30 A #GDBusObject. A string owned by @object. Do not free. Gets the #GDBusConnection used by @manager. Since: 2.30 A #GDBusObjectManagerClient A #GDBusConnection object. Do not free, the object belongs to @manager. Gets the flags that @manager was constructed with. Since: 2.30 A #GDBusObjectManagerClient Zero of more flags from the #GDBusObjectManagerClientFlags enumeration. Gets the name that @manager is for, or %NULL if not a message bus connection. Since: 2.30 A #GDBusObjectManagerClient A unique or well-known name. Do not free, the string belongs to @manager. 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. Since: 2.30 A #GDBusObjectManagerClient. The name owner or %NULL if no name owner exists. Free with g_free(). Asynchronously creates a new #GDBusObjectManagerClient object. 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 A #GDBusConnection. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL A #GAsyncReadyCallback to call when the request is satisfied. The data to pass to @callback. Finishes an operation started with g_dbus_object_manager_client_new(). Since: 2.30 A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new(). Return location for error or %NULL. A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a #GDBusConnection. 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 A #GBusType. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL A #GAsyncReadyCallback to call when the request is satisfied. The data to pass to @callback. Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). Since: 2.30 A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus(). Return location for error or %NULL. A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead of a #GDBusConnection. 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. Since: 2.30 A #GBusType. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name). The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL Return location for error or %NULL. A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). Creates a new #GDBusObjectManagerClient object. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See g_dbus_object_manager_client_new() for the asynchronous version. Since: 2.30 A #GDBusConnection. Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. The object path of the control object. A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. User data to pass to @get_proxy_type_func. Free function for @get_proxy_type_user_data or %NULL. A #GCancellable or %NULL Return location for error or %NULL. A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). Gets the interface proxy for @interface_name at @object_path, if any. Since: 2.30 A #GDBusObjectManager. Object path to look up. D-Bus interface name to look up. A #GDBusInterface instance or %NULL. Free with g_object_unref(). Gets the #GDBusObject at @object_path, if any. Since: 2.30 A #GDBusObjectManager. Object path to look up. A #GDBusObject or %NULL. Free with g_object_unref(). Gets the object path that @manager is for. Since: 2.30 A #GDBusObjectManager. A string owned by @manager. Do not free. Gets all #GDBusObject objects known to @manager. Since: 2.30 A #GDBusObjectManager. 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(). Exports @object on @manager. 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 A #GDBusObjectManagerServer. A #GDBusObjectSkeleton. 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. Since: 2.30 A #GDBusObjectManagerServer. An object. Gets the #GDBusConnection used by @manager. Since: 2.30 A #GDBusObjectManagerServer A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref(). Returns whether @object is currently exported on @manager. Since: 2.34 A #GDBusObjectManagerServer. An object. %TRUE if @object is exported Creates a new #GDBusObjectManagerServer object. 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. Since: 2.30 The object path to export the manager object at. A #GDBusObjectManagerServer object. Free with g_object_unref(). Exports all objects managed by @manager on @connection. If @connection is %NULL, stops exporting objects. A #GDBusObjectManagerServer. A #GDBusConnection or %NULL. If @manager has an object at @path, removes the object. Otherwise does nothing. Note that @object_path must be in the hierarchy rooted by the object path for @manager. Since: 2.30 A #GDBusObjectManagerServer. An object path. %TRUE if object at @object_path was removed, %FALSE otherwise. Gets the connection that @proxy is for. Since: 2.30 a #GDBusObjectProxy A #GDBusConnection. Do not free, the object is owned by @proxy. Creates a new #GDBusObjectProxy for the given connection and object path. Since: 2.30 a #GDBusConnection the object path a new #GDBusObjectProxy Adds @interface_ to @object. 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 A #GDBusObjectSkeleton. A #GDBusInterfaceSkeleton. This method simply calls g_dbus_interface_skeleton_flush() on all interfaces belonging to @object. See that method for when flushing is useful. Since: 2.30 A #GDBusObjectSkeleton. Creates a new #GDBusObjectSkeleton. Since: 2.30 An object path. A #GDBusObjectSkeleton. Free with g_object_unref(). Removes @interface_ from @object. Since: 2.30 A #GDBusObjectSkeleton. A #GDBusInterfaceSkeleton. Removes the #GDBusInterface with @interface_name from @object. If no D-Bus interface of the given interface exists, this function does nothing. Since: 2.30 A #GDBusObjectSkeleton. A D-Bus interface name. Sets the object path for @object. Since: 2.30 A #GDBusObjectSkeleton. A valid D-Bus object path. If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusPropertyInfo The same @info. 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 A #GDBusPropertyInfo. Asynchronously invokes the @method_name method on @proxy. If @method_name contains any dots, then @name is split into interface and method name parts. This allows using @proxy for invoking methods on other interfaces. If the #GDBusConnection associated with @proxy is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value not compatible with the D-Bus protocol, the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_proxy_call (proxy, "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), G_DBUS_CALL_FLAGS_NONE, -1, NULL, (GAsyncReadyCallback) two_strings_done, &data); ]| If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @method_name is referenced by it, then the return value is checked against the return type. This is an asynchronous method. When the operation is finished, @callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method. If @callback is %NULL then the D-Bus method call message will be sent with the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. Since: 2.26 A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GCancellable or %NULL. A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. The data to pass to @callback. Finishes an operation started with g_dbus_proxy_call(). Since: 2.26 A #GDBusProxy. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). Return location for error or %NULL. %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). 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. If the @parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: |[<!-- language="C" --> g_dbus_proxy_call_sync (proxy, "TwoStrings", g_variant_new ("(ss)", "Thing One", "Thing Two"), G_DBUS_CALL_FLAGS_NONE, -1, NULL, &error); ]| The calling thread is blocked until a reply is received. See g_dbus_proxy_call() for the asynchronous version of this method. If @proxy has an expected interface (see #GDBusProxy:g-interface-info) and @method_name is referenced by it, then the return value is checked against the return type. Since: 2.26 A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GCancellable or %NULL. Return location for error or %NULL. %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). Like g_dbus_proxy_call() but also takes a #GUnixFDList object. This method is only available on UNIX. Since: 2.30 A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GUnixFDList or %NULL. A #GCancellable or %NULL. A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. The data to pass to @callback. Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). Since: 2.30 A #GDBusProxy. Return location for a #GUnixFDList or %NULL. A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list(). Return location for error or %NULL. %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. This method is only available on UNIX. Since: 2.30 A #GDBusProxy. Name of method to invoke. A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. Flags from the #GDBusCallFlags enumeration. The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. A #GUnixFDList or %NULL. Return location for a #GUnixFDList or %NULL. A #GCancellable or %NULL. Return location for error or %NULL. %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). 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. Since: 2.26 A #GDBusProxy. Property name. 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(). Gets the names of all cached properties on @proxy. Since: 2.26 A #GDBusProxy. A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev(). Gets the connection @proxy is for. Since: 2.26 A #GDBusProxy. A #GDBusConnection owned by @proxy. Do not free. 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. Since: 2.26 A #GDBusProxy. Timeout to use for @proxy. Gets the flags that @proxy was constructed with. Since: 2.26 A #GDBusProxy. Flags from the #GDBusProxyFlags enumeration. Returns the #GDBusInterfaceInfo, if any, specifying the interface that @proxy conforms to. See the #GDBusProxy:g-interface-info property for more details. Since: 2.26 A #GDBusProxy A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy. Gets the D-Bus interface name @proxy is for. Since: 2.26 A #GDBusProxy. A string owned by @proxy. Do not free. Gets the name that @proxy was constructed for. When connected to a message bus, this will usually be non-%NULL. However, it may be %NULL for a proxy that communicates using a peer-to-peer pattern. Since: 2.26 A #GDBusProxy. A string owned by @proxy. Do not free. 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. Since: 2.26 A #GDBusProxy. The name owner or %NULL if no name owner exists. Free with g_free(). Gets the object path @proxy is for. Since: 2.26 A #GDBusProxy. A string owned by @proxy. Do not free. Creates a proxy for accessing @interface_name on the remote object at @object_path owned by @name at @connection and asynchronously loads D-Bus properties unless the %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to the #GDBusProxy::g-properties-changed signal to get notified about property changes. If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the #GDBusProxy::g-signal signal to handle signals from the remote object. If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking. 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 failable asynchronous constructor - when the proxy is ready, @callback will be invoked and you can use g_dbus_proxy_new_finish() to get the result. See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. Since: 2.26 A #GDBusConnection. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. An object path. A D-Bus interface name. A #GCancellable or %NULL. Callback function to invoke when the proxy is ready. User data to pass to @callback. Finishes creating a #GDBusProxy. Since: 2.26 A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). Return location for error or %NULL. A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. Since: 2.26 A #GBusType. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique). An object path. A D-Bus interface name. A #GCancellable or %NULL. Callback function to invoke when the proxy is ready. User data to pass to @callback. Finishes creating a #GDBusProxy. Since: 2.26 A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). Return location for error or %NULL. A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. Since: 2.26 A #GBusType. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique). An object path. A D-Bus interface name. A #GCancellable or %NULL. Return location for error or %NULL. A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). 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 both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking. If @name is a well-known name and the %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name. This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version. #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. Since: 2.26 A #GDBusConnection. Flags used when constructing the proxy. A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. An object path. A D-Bus interface name. A #GCancellable or %NULL. Return location for error or %NULL. A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). 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. |[<!-- language="C" --> g_dbus_proxy_set_cached_property (proxy, "SomeProperty", g_variant_new ("(si)", "A String", 42)); ]| Normally you will not need to use this method since @proxy is tracking changes using the `org.freedesktop.DBus.Properties.PropertiesChanged` D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes. As a concrete example, consider an object with a property `ChatroomParticipants` which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals `ChatroomParticipantJoined(String name)` and `ChatroomParticipantParted(String name)`. Since: 2.26 A #GDBusProxy Property name. Value for the property or %NULL to remove it from the cache. 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. See the #GDBusProxy:g-default-timeout property for more details. Since: 2.26 A #GDBusProxy. Timeout in milliseconds. Ensure that interactions with @proxy conform to the given interface. See the #GDBusProxy:g-interface-info property for more details. Since: 2.26 A #GDBusProxy Minimum interface this proxy conforms to or %NULL to unset. 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. This is valid and non-empty if initializing the #GDBusServer succeeded. Since: 2.26 A #GDBusServer. A D-Bus address string. Do not free, the string is owned by @server. Gets the flags for @server. Since: 2.26 A #GDBusServer. A set of flags from the #GDBusServerFlags enumeration. Gets the GUID for @server, as provided to g_dbus_server_new_sync(). Since: 2.26 A #GDBusServer. A D-Bus GUID. Do not free this string, it is owned by @server. Gets whether @server is active. Since: 2.26 A #GDBusServer. %TRUE if server is active, %FALSE otherwise. Creates a new D-Bus server that listens on the first address in @address that works. Once constructed, you can use g_dbus_server_get_client_address() to get a D-Bus address string that clients can use to connect. To have control over the available authentication mechanisms and the users that are authorized to connect, it is strongly recommended to provide a non-%NULL #GDBusAuthObserver. Connect to the #GDBusServer::new-connection signal to handle incoming connections. The returned #GDBusServer isn't active - you have to start it with g_dbus_server_start(). #GDBusServer is used in this [example][gdbus-peer-to-peer]. This is a synchronous failable constructor. There is currently no asynchronous version. Since: 2.26 A D-Bus address. Flags from the #GDBusServerFlags enumeration. A D-Bus GUID. A #GDBusAuthObserver or %NULL. A #GCancellable or %NULL. Return location for server or %NULL. A #GDBusServer or %NULL if @error is set. Free with g_object_unref(). Starts @server. Since: 2.26 A #GDBusServer. Stops @server. Since: 2.26 A #GDBusServer. If @info is statically allocated does nothing. Otherwise increases the reference count. Since: 2.26 A #GDBusSignalInfo The same @info. 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 A #GDBusSignalInfo. Unescapes an string that was previously escaped with g_dbus_escape_object_path(). If the string is in a format that could not have been returned by g_dbus_escape_object_path(), this function returns %NULL. Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g `_63` is not valid, the string should contain `c` instead). Since: 2.68 the string to unescape an unescaped version of @s, or %NULL if @s is not a string returned from g_dbus_escape_object_path(). Free with g_free(). Create a new #GDebugControllerDBus and synchronously initialize it. Initializing the object will export the debug object on @connection. The object will remain registered until the last reference to the #GDebugControllerDBus is dropped. Initialization may fail if registering the object on @connection fails. Since: 2.72 a #GDBusConnection to register the debug object on a #GCancellable, or %NULL return location for a #GError, or %NULL a new #GDebugControllerDBus, or %NULL on failure Stop the debug controller, unregistering its object from the bus. Any pending method calls to the object will complete successfully, but new ones will return an error. This method will block until all pending #GDebugControllerDBus::authorize signals have been handled. This is expected to not take long, as it will just be waiting for threads to join. If any #GDebugControllerDBus::authorize signal handlers are still executing in other threads, this will block until after they have returned. This method will be called automatically when the final reference to the #GDebugControllerDBus is dropped. You may want to call it explicitly to know when the controller has been fully removed from the bus, or to break reference count cycles. Calling this method from within a #GDebugControllerDBus::authorize signal handler will cause a deadlock and must not be done. Since: 2.72 a #GDebugControllerDBus Get the value of #GDebugController:debug-enabled. Since: 2.72 a #GDebugController %TRUE if debug output should be exposed, %FALSE otherwise Set the value of #GDebugController:debug-enabled. Since: 2.72 a #GDebugController %TRUE if debug output should be exposed, %FALSE otherwise Gets the user-visible display name of the "additional application action" specified by @action_name. This corresponds to the "Name" key within the keyfile group for the action. Since: 2.38 a #GDesktopAppInfo the name of the action as from g_desktop_app_info_list_actions() the locale-specific action name Looks up a boolean value in the keyfile backing @info. The @key is looked up in the "Desktop Entry" group. Since: 2.36 a #GDesktopAppInfo the key to look up the boolean value, or %FALSE if the key is not found Gets the categories from the desktop file. a #GDesktopAppInfo The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it. 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. Since: 2.24 a #GDesktopAppInfo The full path to the file for @info, or %NULL if not known. Gets the generic name from the desktop file. a #GDesktopAppInfo The value of the GenericName key Gets all applications that implement @interface. An application implements an interface if that interface is listed in the Implements= line of the desktop file of the application. Since: 2.42 the name of the interface a list of #GDesktopAppInfo objects. A desktop file is hidden if the Hidden key in it is set to True. a #GDesktopAppInfo. %TRUE if hidden, %FALSE otherwise. Gets the keywords from the desktop file. Since: 2.32 a #GDesktopAppInfo The value of the Keywords key Looks up a localized string value in the keyfile backing @info translated to the current locale. The @key is looked up in the "Desktop Entry" group. Since: 2.56 a #GDesktopAppInfo the key to look up a newly allocated string, or %NULL if the key is not found 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(). Since: 2.30 a #GDesktopAppInfo The value of the NoDisplay key Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the `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. Note that g_app_info_should_show() for @info will include this check (with %NULL for @desktop_env) as well as additional checks. Since: 2.30 a #GDesktopAppInfo a string specifying a desktop name %TRUE if the @info should be shown in @desktop_env according to the `OnlyShowIn` and `NotShowIn` keys, %FALSE otherwise. Retrieves the StartupWMClass field from @info. This represents the WM_CLASS property of the main window of the application, if launched through @info. Since: 2.34 a #GDesktopAppInfo that supports startup notify the startup WM class, or %NULL if none is set in the desktop file. Looks up a string value in the keyfile backing @info. The @key is looked up in the "Desktop Entry" group. Since: 2.36 a #GDesktopAppInfo the key to look up a newly allocated string, or %NULL if the key is not found Looks up a string list value in the keyfile backing @info. The @key is looked up in the "Desktop Entry" group. Since: 2.60 a #GDesktopAppInfo the key to look up return location for the number of returned strings, or %NULL a %NULL-terminated string array or %NULL if the specified key cannot be found. The array should be freed with g_strfreev(). Returns whether @key exists in the "Desktop Entry" group of the keyfile backing @info. Since: 2.36 a #GDesktopAppInfo the key to look up %TRUE if the @key exists Activates the named application action. You may only call this function on action names that were returned from g_desktop_app_info_list_actions(). Note that if the main entry of the desktop file indicates that the application supports startup notification, and @launch_context is non-%NULL, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional actions, as per the desktop file specification. As with g_app_info_launch() there is no way to detect failures that occur while using this function. Since: 2.38 a #GDesktopAppInfo the name of the action as from g_desktop_app_info_list_actions() a #GAppLaunchContext 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(). If the application is launched via GSpawn, 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. See g_spawn_async_with_pipes() for information on certain parameter conditions that can enable an optimized posix_spawn() codepath to be used. 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. a #GDesktopAppInfo List of URIs a #GAppLaunchContext #GSpawnFlags, used for each process a #GSpawnChildSetupFunc, used once for each process. User data for @user_setup Callback for child processes User data for @callback return location for a #GError, or %NULL %TRUE on successful launch, %FALSE otherwise. Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process. If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. Since: 2.58 a #GDesktopAppInfo List of URIs a #GAppLaunchContext #GSpawnFlags, used for each process a #GSpawnChildSetupFunc, used once for each process. User data for @user_setup Callback for child processes User data for @callback file descriptor to use for child's stdin, or -1 file descriptor to use for child's stdout, or -1 file descriptor to use for child's stderr, or -1 return location for a #GError, or %NULL %TRUE on successful launch, %FALSE otherwise. Returns the list of "additional application actions" supported on the desktop file, as per the desktop file specification. As per the specification, this is the list of actions that are explicitly listed in the "Actions" key of the [Desktop Entry] group. Since: 2.38 a #GDesktopAppInfo a list of strings, always non-%NULL Gets the default application for launching applications using this URI scheme for a particular #GDesktopAppInfoLookup implementation. The #GDesktopAppInfoLookup interface and this function is used to implement g_app_info_get_default_for_uri_scheme() backends in a GIO module. There is no reason for applications to use it directly. Applications should use g_app_info_get_default_for_uri_scheme(). Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and unused by GIO. a #GDesktopAppInfoLookup a string containing a URI scheme. #GAppInfo for given @uri_scheme or %NULL on error. Creates a new #GDesktopAppInfo based on a desktop file id. A desktop file id is the basename of the desktop file, including the .desktop extension. GIO is looking for a desktop file with this name in the `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`). the desktop file id a new #GDesktopAppInfo, or %NULL if no desktop file with that id exists. Creates a new #GDesktopAppInfo. the path of a desktop file, in the GLib filename encoding a new #GDesktopAppInfo or %NULL on error. Creates a new #GDesktopAppInfo. Since: 2.18 an opened #GKeyFile a new #GDesktopAppInfo or %NULL on error. Searches desktop files for ones that match @search_string. The return value is an array of strvs. Each strv contains a list of applications that matched @search_string with an equal score. The outer list is sorted by score so that the first strv contains the best-matching applications, and so on. The algorithm for determining matches is undefined and may change at any time. None of the search results are subjected to the normal validation checks performed by g_desktop_app_info_new() (for example, checking that the executable referenced by a result exists), and so it is possible for g_desktop_app_info_new() to return %NULL when passed an app ID returned by this function. It is expected that calling code will do this when subsequently creating a #GDesktopAppInfo for each result. the search string to use a list of strvs. Free each item with g_strfreev() and free the outer list with g_free(). 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. Should be called only once; subsequent calls are ignored. Deprecated:2.42:do not use this API. Since 2.42 the value of the `XDG_CURRENT_DESKTOP` environment variable will be used. a string specifying what desktop this is Checks if a drive can be ejected. a #GDrive. %TRUE if the @drive can be ejected, %FALSE otherwise. Checks if a drive can be polled for media changes. a #GDrive. %TRUE if the @drive can be polled for media changes, %FALSE otherwise. Checks if a drive can be started. Since: 2.22 a #GDrive. %TRUE if the @drive can be started, %FALSE otherwise. Checks if a drive can be started degraded. Since: 2.22 a #GDrive. %TRUE if the @drive can be started degraded, %FALSE otherwise. Checks if a drive can be stopped. Since: 2.22 a #GDrive. %TRUE if the @drive can be stopped, %FALSE otherwise. Asynchronously ejects a drive. When the operation is finished, @callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation. Deprecated: 2.22: Use g_drive_eject_with_operation() instead. a #GDrive. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes ejecting a drive. Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. a #GDrive. a #GAsyncResult. a #GError, or %NULL %TRUE if the drive has been ejected successfully, %FALSE otherwise. 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. Since: 2.22 a #GDrive. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. 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.22 a #GDrive. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the drive was successfully ejected. %FALSE otherwise. Gets the kinds of identifiers that @drive has. Use g_drive_get_identifier() to obtain the identifiers themselves. a #GDrive a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. Gets the icon for @drive. a #GDrive. #GIcon for the @drive. Free the returned object with g_object_unref(). Gets the identifier of the given kind for @drive. The only identifier currently available is %G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. a #GDrive the kind of identifier to return a newly allocated string containing the requested identifier, or %NULL if the #GDrive doesn't have this kind of identifier. Gets the name of @drive. a #GDrive. a string containing @drive's name. The returned string should be freed when no longer needed. Gets the sort key for @drive, if any. Since: 2.32 A #GDrive. Sorting key for @drive or %NULL if no such key is available. Gets a hint about how a drive can be started/stopped. Since: 2.22 a #GDrive. A value from the #GDriveStartStopType enumeration. Gets the icon for @drive. Since: 2.34 a #GDrive. symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). Get a list of mountable volumes for @drive. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GDrive. #GList containing any #GVolume objects on the given @drive. 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. a #GDrive. %TRUE if @drive has media, %FALSE otherwise. Check if @drive has any mountable volumes. a #GDrive. %TRUE if the @drive contains volumes, %FALSE otherwise. Checks if @drive is capable of automatically detecting media changes. a #GDrive. %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. Checks if the @drive supports removable media. a #GDrive. %TRUE if @drive supports removable media, %FALSE otherwise. Checks if the #GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable(). Since: 2.50 a #GDrive. %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. Asynchronously polls @drive to see if media has been inserted or removed. 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. a #GDrive. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes an operation started with g_drive_poll_for_media() on a drive. a #GDrive. a #GAsyncResult. a #GError, or %NULL %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. Asynchronously starts a drive. When the operation is finished, @callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation. Since: 2.22 a #GDrive. flags affecting the start operation. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes starting a drive. Since: 2.22 a #GDrive. a #GAsyncResult. a #GError, or %NULL %TRUE if the drive has been started successfully, %FALSE otherwise. Asynchronously stops a drive. 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 a #GDrive. flags affecting the unmount if required for stopping. a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data to pass to @callback Finishes stopping a drive. Since: 2.22 a #GDrive. a #GAsyncResult. a #GError, or %NULL %TRUE if the drive has been stopped successfully, %FALSE otherwise. 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. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. Since: 2.48 the #GDtlsClientConnection 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(). Gets @conn's expected server identity Since: 2.48 the #GDtlsClientConnection a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. Gets @conn's validation flags This function does not work as originally designed and is impossible to use correctly. See #GDtlsClientConnection:validation-flags for more information. Since: 2.48 Deprecated: 2.74: Do not attempt to ignore validation errors. the #GDtlsClientConnection the validation flags Creates a new #GDtlsClientConnection wrapping @base_socket which is assumed to communicate with the server identified by @server_identity. Since: 2.48 the #GDatagramBased to wrap the expected identity of the server #GError for error reporting, or %NULL to ignore. the new #GDtlsClientConnection, or %NULL on error 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.48 the #GDtlsClientConnection a #GSocketConnectable describing the expected server identity 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. This function does not work as originally designed and is impossible to use correctly. See #GDtlsClientConnection:validation-flags for more information. Since: 2.48 Deprecated: 2.74: Do not attempt to ignore validation errors. the #GDtlsClientConnection the #GTlsCertificateFlags to use 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. #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. 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.48 a #GDtlsConnection a #GCancellable, or %NULL a #GError, or %NULL %TRUE on success, %FALSE otherwise Asynchronously close the DTLS connection. See g_dtls_connection_close() for more information. Since: 2.48 a #GDtlsConnection the [I/O priority][io-priority] of the request a #GCancellable, or %NULL callback to call when the close operation is complete the data to pass to the callback function Finish an asynchronous TLS close operation. See g_dtls_connection_close() for more information. Since: 2.48 a #GDtlsConnection a #GAsyncResult a #GError pointer, or %NULL %TRUE on success, %FALSE on failure, in which case @error will be set Used by #GDtlsConnection implementations to emit the #GDtlsConnection::accept-certificate signal. Since: 2.48 a #GDtlsConnection the peer's #GTlsCertificate the problems with @peer_cert %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert Gets @conn's certificate, as set by g_dtls_connection_set_certificate(). Since: 2.48 a #GDtlsConnection @conn's certificate, or %NULL Query the TLS backend for TLS channel binding data of @type for @conn. This call retrieves TLS channel binding data as specified in RFC [5056](https://tools.ietf.org/html/rfc5056), RFC [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The binding data is returned in @data. The @data is resized by the callee using #GByteArray buffer management and will be freed when the @data is destroyed by g_byte_array_unref(). If @data is %NULL, it will only check whether TLS backend is able to fetch the data (e.g. whether @type is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support @type or the binding data is not available yet due to additional negotiation or input required. Since: 2.66 a #GDtlsConnection #GTlsChannelBindingType type of data to fetch #GByteArray is filled with the binding data, or %NULL a #GError pointer, or %NULL %TRUE on success, %FALSE otherwise Returns the name of the current DTLS ciphersuite, or %NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended. Since: 2.70 a #GDTlsConnection The name of the current DTLS ciphersuite, or %NULL Gets the certificate database that @conn uses to verify peer certificates. See g_dtls_connection_set_database(). Since: 2.48 a #GDtlsConnection the certificate database that @conn uses or %NULL 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.48 a connection The interaction object. Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_dtls_connection_set_advertised_protocols(). Since: 2.60 a #GDtlsConnection the negotiated protocol, or %NULL Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) Since: 2.48 a #GDtlsConnection @conn's peer's certificate, or %NULL Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) Since: 2.48 a #GDtlsConnection @conn's peer's certificate errors Returns the current DTLS protocol version, which may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized #GTlsProtocolVersion. Since: 2.70 a #GDTlsConnection The current DTLS protocol version Gets @conn rehandshaking mode. See g_dtls_connection_set_rehandshake_mode() for details. Since: 2.48 Deprecated: 2.64. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. a #GDtlsConnection %G_TLS_REHANDSHAKE_SAFELY 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. Since: 2.48 a #GDtlsConnection %TRUE if @conn requires a proper TLS close notification. 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, #GDtlsConnection will handle this for you automatically when you try to send or receive data on the connection. You can call g_dtls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use @conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable. 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. Previously, calling g_dtls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything. #GDtlsConnection::accept_certificate may be emitted during the handshake. Since: 2.48 a #GDtlsConnection a #GCancellable, or %NULL a #GError, or %NULL success or failure Asynchronously performs a TLS handshake on @conn. See g_dtls_connection_handshake() for more information. Since: 2.48 a #GDtlsConnection the [I/O priority][io-priority] of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous TLS handshake operation. See g_dtls_connection_handshake() for more information. Since: 2.48 a #GDtlsConnection a #GAsyncResult. a #GError pointer, or %NULL %TRUE on success, %FALSE on failure, in which case @error will be set. Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_dtls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying %NULL for the the value of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. Since: 2.60 a #GDtlsConnection a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL 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. 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. (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.) Since: 2.48 a #GDtlsConnection the certificate to use for @conn 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). There are nonintuitive security implications when using a non-default database. See #GDtlsConnection:database for details. Since: 2.48 a #GDtlsConnection a #GTlsDatabase Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. 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 a connection an interaction object, or %NULL Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations. Since: 2.48 Deprecated: 2.60. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. a #GDtlsConnection the rehandshaking mode 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). 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. 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 a #GDtlsConnection whether or not to require close notification Shut down part or all of a DTLS connection. 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. 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. Since: 2.48 a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams a #GCancellable, or %NULL a #GError, or %NULL %TRUE on success, %FALSE otherwise Asynchronously shut down part or all of the DTLS connection. See g_dtls_connection_shutdown() for more information. Since: 2.48 a #GDtlsConnection %TRUE to stop reception of incoming datagrams %TRUE to stop sending outgoing datagrams the [I/O priority][io-priority] of the request a #GCancellable, or %NULL callback to call when the shutdown operation is complete the data to pass to the callback function Finish an asynchronous TLS shutdown operation. See g_dtls_connection_shutdown() for more information. Since: 2.48 a #GDtlsConnection a #GAsyncResult a #GError pointer, or %NULL %TRUE on success, %FALSE on failure, in which case @error will be set Creates a new #GDtlsServerConnection wrapping @base_socket. Since: 2.48 the #GDatagramBased to wrap the default server certificate, or %NULL #GError for error reporting, or %NULL to ignore the new #GDtlsServerConnection, or %NULL on error Gives back the icon from @emblem. Since: 2.18 a #GEmblem from which the icon should be extracted. a #GIcon. The returned object belongs to the emblem and should not be modified or freed. Gets the origin of the emblem. Since: 2.18 a #GEmblem the origin of the emblem Creates a new emblem for @icon. Since: 2.18 a GIcon containing the icon. a new #GEmblem. Creates a new emblem for @icon. Since: 2.18 a GIcon containing the icon. a GEmblemOrigin enum defining the emblem's origin a new #GEmblem. Adds @emblem to the #GList of #GEmblems. Since: 2.18 a #GEmblemedIcon a #GEmblem Removes all the emblems from @icon. Since: 2.28 a #GEmblemedIcon Gets the list of emblems for the @icon. Since: 2.18 a #GEmblemedIcon a #GList of #GEmblems that is owned by @emblemed Gets the main icon for @emblemed. Since: 2.18 a #GEmblemedIcon a #GIcon that is owned by @emblemed Creates a new emblemed icon for @icon with the emblem @emblem. Since: 2.18 a #GIcon a #GEmblem, or %NULL a new #GIcon Gets an output stream for appending data to the file. If the file doesn't already exist it is created. By default files created are generally readable by everyone, but if you pass %G_FILE_CREATE_PRIVATE in @flags the file will be made readable only to the current user, to the level that is supported on the target filesystem. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 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. input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). Asynchronously opens @file for appending. For more details, see g_file_append_to() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_append_to_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file append operation started with g_file_append_to_async(). input #GFile #GAsyncResult a #GError, or %NULL a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). Adds a new attribute with @name to the @list, setting its @type and @flags. a #GFileAttributeInfoList. the name of the attribute to add. the #GFileAttributeType for the attribute. #GFileAttributeInfoFlags for the attribute. Makes a duplicate of a file attribute info list. a #GFileAttributeInfoList to duplicate. a copy of the given @list. Gets the file attribute with the name @name from @list. a #GFileAttributeInfoList. the name of the attribute to look up. a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found. Creates a new file attribute info list. a #GFileAttributeInfoList. References a file attribute info list. a #GFileAttributeInfoList to reference. #GFileAttributeInfoList or %NULL on error. Removes a reference from the given @list. If the reference count falls to zero, the @list is deleted. The #GFileAttributeInfoList to unreference. 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. a #GFileAttributeMatcher. a string containing a file attribute namespace. %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise. Gets the next matched attribute from a #GFileAttributeMatcher. a #GFileAttributeMatcher. a string containing the next attribute or, %NULL if no more attribute exist. 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. a #GFileAttributeMatcher. a file attribute key. %TRUE if @attribute matches @matcher. %FALSE otherwise. Checks if a attribute matcher only matches a given attribute. Always returns %FALSE if "*" was used when creating the matcher. a #GFileAttributeMatcher. a file attribute key. %TRUE if the matcher only matches @attribute. %FALSE otherwise. 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 @attributes 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. an attribute string to match. a #GFileAttributeMatcher References a file attribute matcher. a #GFileAttributeMatcher. a #GFileAttributeMatcher. Subtracts all attributes of @subtract from @matcher and returns a matcher that supports those attributes. 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. Matcher to subtract from The matcher to subtract A file attribute matcher matching all attributes of @matcher that are not matched by @subtract Prints what the matcher is matching against. The format will be equal to the format passed to g_file_attribute_matcher_new(). The output however, might not be identical, as the matcher may decide to use a different order or omit needless parts. Since: 2.32 a #GFileAttributeMatcher. a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL. Unreferences @matcher. If the reference count falls below 1, the @matcher is automatically freed. a #GFileAttributeMatcher. Duplicates a file attribute. a #GFileAttributeValue to duplicate. a duplicate of the @other. Sets an attribute's value from another attribute. a #GFileAttributeValue to set the value in. a #GFileAttributeValue to get the value from. Prepares the file attribute query string for copying to @file. This function prepares an attribute query string to be passed to g_file_query_info() to get a list of attributes normally copied with the file (see g_file_copy_attributes() for the detailed description). This function is used by the implementation of g_file_copy_attributes() and is useful when one needs to query and set the attributes in two stages (e.g., for recursive move of a directory). Since: 2.68 a #GFile to copy attributes to a set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore a #GError, %NULL to ignore an attribute query string for g_file_query_info(), or %NULL if an error occurs. 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. If you are interested in copying the #GFile object itself (not the on-disk file), see g_file_dup(). input #GFile destination #GFile set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback #GError to set on error, or %NULL %TRUE on success, %FALSE otherwise. Copies the file @source to the location specified by @destination asynchronously. For details of the behaviour, see g_file_copy(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_copy(). 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. input #GFile destination #GFile set of #GFileCopyFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore function to callback with progress information, or %NULL if progress information is not needed user data to pass to @progress_callback a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Copies the file attributes from @source to @destination. 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. a #GFile with attributes a #GFile to copy attributes to a set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore a #GError, %NULL to ignore %TRUE if the attributes were copied successfully, %FALSE otherwise. Finishes copying the file started with g_file_copy_async(). input #GFile a #GAsyncResult a #GError, or %NULL a %TRUE on success, %FALSE on error. 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. 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. input #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see g_file_create() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_finish() to get the result of the operation. input #GFile a set of #GFileCreateFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file create operation started with g_file_create_async(). input #GFile a #GAsyncResult a #GError, or %NULL a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). 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. 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. Since: 2.22 a #GFile a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore return location for a #GError, or %NULL a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist. For more details, see g_file_create_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_create_readwrite_finish() to get the result of the operation. Since: 2.22 input #GFile a set of #GFileCreateFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file create operation started with g_file_create_readwrite_async(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). 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 @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows for deletion to be implemented avoiding [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): |[ g_autoptr(GError) local_error = NULL; if (!g_file_delete (my_file, my_cancellable, &local_error) && !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) { // deletion failed for some reason other than the file not existing: // so report the error g_warning ("Failed to delete %s: %s", g_file_peek_path (my_file), local_error->message); } ]| If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Virtual: delete_file input #GFile optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the file was deleted. %FALSE otherwise. Asynchronously delete a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). Virtual: delete_file_async Since: 2.34 input #GFile the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes deleting a file started with g_file_delete_async(). Virtual: delete_file_finish Since: 2.34 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the file was deleted. %FALSE otherwise. Gets the underlying file descriptor. Since: 2.24 a #GFileDescriptorBased. The file descriptor 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. g_file_dup() is useful when a second handle is needed to the same underlying file, for use in a separate thread (#GFile is not thread-safe). For use within the same thread, use g_object_ref() to increment the existing object’s reference count. This call does no blocking I/O. input #GFile a new #GFile that is a duplicate of the given #GFile. 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. Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes an asynchronous eject operation started by g_file_eject_mountable(). Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead. input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the @file was ejected successfully. %FALSE otherwise. 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(). If @cancellable is not %NULL, then the operation can 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 input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the @file was ejected successfully. %FALSE otherwise. Gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. The @attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like %G_FILE_ATTRIBUTE_STANDARD_NAME. %G_FILE_ATTRIBUTE_STANDARD_NAME should always be specified if you plan to call g_file_enumerator_get_child() or g_file_enumerator_iterate() on the returned enumerator. If @cancellable is not %NULL, then the operation can 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. input #GFile an attribute query string a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore #GError for error reporting A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). Asynchronously gets the requested information about the files in a directory. The result is a #GFileEnumerator object that will give out #GFileInfo objects for all the files in the directory. For more details, see g_file_enumerate_children() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_enumerate_children_finish() to get the result of the operation. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async enumerate children operation. See g_file_enumerate_children_async(). input #GFile a #GAsyncResult a #GError a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). 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. a #GFileEnumerator. optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore #TRUE on success or #FALSE on error. Asynchronously closes the file enumerator. If @cancellable is not %NULL, then the operation can 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(). a #GFileEnumerator. the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function 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. a #GFileEnumerator. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the close operation has finished successfully. 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(). To use this, %G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the attributes list used when creating the #GFileEnumerator. This is a convenience method that's equivalent to: |[<!-- language="C" --> gchar *name = g_file_info_get_name (info); GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), name); ]| Since: 2.36 a #GFileEnumerator a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents. a #GFile for the #GFileInfo passed it. Get the #GFile container which is being enumerated. Since: 2.18 a #GFileEnumerator the #GFile which is being enumerated. Checks if the file enumerator has pending operations. a #GFileEnumerator. %TRUE if the @enumerator has pending operations. Checks if the file enumerator has been closed. a #GFileEnumerator. %TRUE if the @enumerator is closed. 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 ]| Since: 2.44 an open #GFileEnumerator Output location for the next #GFileInfo, or %NULL Output location for the next #GFile, or %NULL a #GCancellable a #GError 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. a #GFileEnumerator. optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. 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. 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. a #GFileEnumerator. the number of file info objects to request the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). a #GFileEnumerator. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. 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. Sets the file enumerator as having pending operations. a #GFileEnumerator. a boolean value. 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. the first #GFile the second #GFile %TRUE if @file1 and @file2 are equal. Gets a #GMount for the #GFile. #GMount is returned only for user interesting locations, see #GVolumeMonitor. If the #GFileIface for @file does not have a #mount, @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. input #GFile optional #GCancellable object, %NULL to ignore a #GError a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). Asynchronously gets the mount for the file. For more details, see g_file_find_enclosing_mount() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_find_enclosing_mount_finish() to get the result of the operation. a #GFile the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async(). a #GFile a #GAsyncResult a #GError #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). 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(). This call does no blocking I/O. input #GFile 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. Gets a child of @file with basename equal to @name. 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. This call does no blocking I/O. input #GFile string containing the child's basename a #GFile to a child specified by @name. Free the returned object with g_object_unref(). Gets the child of @file for a given @display_name (i.e. a UTF-8 version of the name). If this function fails, it returns %NULL and @error will be set. This is very useful when constructing a #GFile for a new file and the user entered the filename in the user interface, for instance when you select a directory and type a filename in the file selector. This call does no blocking I/O. input #GFile string to a possible child return location for an error a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). Gets the parent directory for the @file. If the @file represents the root directory of the file system, then %NULL will be returned. This call does no blocking I/O. input #GFile 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(). Gets the parse name of the @file. A parse name is a UTF-8 string that describes the file such that one can get the #GFile back using g_file_parse_name(). This is generally used to show the #GFile as a nice full-pathname kind of string in a user interface, like in a location entry. For local files with names that can safely be converted to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped). This call does no blocking I/O. input #GFile a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. 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. This call does no blocking I/O. input #GFile 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. Gets the path for @descendant relative to @parent. This call does no blocking I/O. input #GFile input #GFile 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. Gets the URI for the @file. This call does no blocking I/O. input #GFile a string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. 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. The scheme can be different from the one used to construct the #GFile, in that it might be replaced with one that is logically equivalent to the #GFile. This call does no blocking I/O. input #GFile a string containing the URI scheme for the given #GFile or %NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed. Checks if @file has a parent, and optionally, if it is @parent. 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. Since: 2.24 input #GFile the parent to check for, or %NULL %TRUE if @file is an immediate child of @parent (or any parent in the case that @parent is %NULL). Checks whether @file has the prefix specified by @prefix. In other words, if the names of initial elements of @file's pathname match @prefix. Only full pathname elements are matched, so a path like /foo is not considered a prefix of /foobar, only of /foo/bar. A #GFile is not a prefix of itself. If you want to check for equality, use g_file_equal(). This call does no I/O, as it works purely on names. As such it can sometimes return %FALSE even if @file is inside a @prefix (from a filesystem point of view), because the prefix of @file is an alias of @prefix. Virtual: prefix_matches input #GFile input #GFile %TRUE if the @file's parent, grandparent, etc is @prefix, %FALSE otherwise. Checks to see if a #GFile has a given URI scheme. This call does no blocking I/O. input #GFile a string containing a URI scheme %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. Creates a hash value for a #GFile. This call does no blocking I/O. Virtual: hash #gconstpointer to a #GFile 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. Gets the #GFile associated with the given @icon. a #GIcon. a #GFile. Creates a new icon for a file. a #GFile. a #GIcon for the given @file, or %NULL on error. Clears the status information from @info. a #GFileInfo. 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. source to copy attributes from. destination to copy attributes to. Duplicates a file info structure. a #GFileInfo. a duplicate #GFileInfo of @other. Gets the access time of the current @info and returns it as a #GDateTime. This requires the %G_FILE_ATTRIBUTE_TIME_ACCESS attribute. If %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime will have microsecond precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must be queried separately using g_file_info_get_attribute_uint32(). Since: 2.70 a #GFileInfo. access time, or %NULL if unknown Gets the value of a attribute, formatted as a string. This escapes things as needed to make the string valid UTF-8. a #GFileInfo. a file attribute key. a UTF-8 string associated with the given @attribute, or %NULL if the attribute wasn’t set. When you're done with the string it must be freed with g_free(). Gets the value of a boolean attribute. If the attribute does not contain a boolean value, %FALSE will be returned. a #GFileInfo. a file attribute key. the boolean value contained within the attribute. Gets the value of a byte string attribute. If the attribute does not contain a byte string, %NULL will be returned. a #GFileInfo. a file attribute key. the contents of the @attribute value as a byte string, or %NULL otherwise. Gets the attribute type, value and status for an attribute key. a #GFileInfo a file attribute key return location for the attribute type, or %NULL return location for the attribute value, or %NULL; the attribute value will not be %NULL return location for the attribute status, or %NULL %TRUE if @info has an attribute named @attribute, %FALSE otherwise. 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. a #GFileInfo. a file attribute key. a signed 32-bit integer from the attribute. Gets a signed 64-bit integer contained within the attribute. If the attribute does not contain a signed 64-bit integer, or is invalid, 0 will be returned. a #GFileInfo. a file attribute key. a signed 64-bit integer from the attribute. Gets the value of a #GObject attribute. If the attribute does not contain a #GObject, %NULL will be returned. a #GFileInfo. a file attribute key. a #GObject associated with the given @attribute, or %NULL otherwise. Gets the attribute status for an attribute key. a #GFileInfo a file attribute key a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. Gets the value of a string attribute. If the attribute does not contain a string, %NULL will be returned. a #GFileInfo. a file attribute key. the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. Gets the value of a stringv attribute. If the attribute does not contain a stringv, %NULL will be returned. Since: 2.22 a #GFileInfo. a file attribute key. the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8. Gets the attribute type for an attribute key. a #GFileInfo. a file attribute key. a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. 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. a #GFileInfo. a file attribute key. an unsigned 32-bit integer from the attribute. 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. a #GFileInfo. a file attribute key. a unsigned 64-bit integer from the attribute. Gets the file's content type. a #GFileInfo. a string containing the file's content type, or %NULL if unknown. Gets the creation time of the current @info and returns it as a #GDateTime. This requires the %G_FILE_ATTRIBUTE_TIME_CREATED attribute. If %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime will have microsecond precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must be queried separately using g_file_info_get_attribute_uint32(). Since: 2.70 a #GFileInfo. creation time, or %NULL if unknown 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. Since: 2.36 a #GFileInfo. a #GDateTime, or %NULL. Gets a display name for a file. This is guaranteed to always be set. a #GFileInfo. a string containing the display name. Gets the edit name for a file. a #GFileInfo. a string containing the edit name. Gets the [entity tag][gfile-etag] for a given #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. a #GFileInfo. a string containing the value of the "etag:value" attribute. 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(). a #GFileInfo. a #GFileType for the given file. Gets the icon for a file. a #GFileInfo. #GIcon for the given @info. Checks if a file is a backup file. a #GFileInfo. %TRUE if file is a backup file, %FALSE otherwise. Checks if a file is hidden. a #GFileInfo. %TRUE if the file is a hidden file, %FALSE otherwise. Checks if a file is a symlink. a #GFileInfo. %TRUE if the given @info is a symlink. Gets the modification time of the current @info and returns it as a #GDateTime. This requires the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting #GDateTime will have microsecond precision. If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must be queried separately using g_file_info_get_attribute_uint32(). Since: 2.62 a #GFileInfo. modification time, or %NULL if unknown Gets the modification time of the current @info and sets it in @result. Deprecated: 2.62: Use g_file_info_get_modification_date_time() instead, as #GTimeVal is deprecated due to the year 2038 problem. a #GFileInfo. a #GTimeVal. Gets the name for a file. This is guaranteed to always be set. a #GFileInfo. a string containing the file name. Gets the file's size (in bytes). The size is retrieved through the value of the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted from #guint64 to #goffset before returning the result. a #GFileInfo. a #goffset containing the file's size (in bytes). Gets the value of the sort_order attribute from the #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. a #GFileInfo. a #gint32 containing the value of the "standard::sort_order" attribute. Gets the symbolic icon for a file. Since: 2.34 a #GFileInfo. #GIcon for the given @info. Gets the symlink target for a given #GFileInfo. a #GFileInfo. a string containing the symlink target. Checks if a file info structure has an attribute named @attribute. a #GFileInfo. a file attribute key. %TRUE if @info has an attribute named @attribute, %FALSE otherwise. Checks if a file info structure has an attribute in the specified @name_space. Since: 2.22 a #GFileInfo. a file attribute namespace. %TRUE if @info has an attribute in @name_space, %FALSE otherwise. Lists the file info structure's attributes. a #GFileInfo. a file attribute key's namespace, or %NULL to list all attributes. a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error. Creates a new file info structure. a #GFileInfo. Removes all cases of @attribute from @info if it exists. a #GFileInfo. a file attribute key. Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared. Since: 2.70 a #GFileInfo. a #GDateTime. Sets the @attribute to contain the given value, if possible. To unset the attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. a #GFileInfo. a file attribute key. a #GFileAttributeType pointer to the value Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a boolean value. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a byte string. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a signed 32-bit integer Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. attribute name to set. int64 value to set attribute to. Sets @mask on @info to match specific attribute types. a #GFileInfo. a #GFileAttributeMatcher. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a #GObject. 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. The attribute must exist in @info for this to work. Otherwise %FALSE is returned and @info is unchanged. Since: 2.22 a #GFileInfo a file attribute key a #GFileAttributeStatus %TRUE if the status was changed, %FALSE if the key was not set. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. a UTF-8 string. Sets the @attribute to contain the given @attr_value, if possible. Sinze: 2.22 a #GFileInfo. a file attribute key a %NULL terminated array of UTF-8 strings. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. an unsigned 32-bit integer. Sets the @attribute to contain the given @attr_value, if possible. a #GFileInfo. a file attribute key. an unsigned 64-bit integer. Sets the content type attribute for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. a #GFileInfo. a content type. See [GContentType][gio-GContentType] Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared. Since: 2.70 a #GFileInfo. a #GDateTime. Sets the display name for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. a #GFileInfo. a string containing a display name. Sets the edit name for the current file. See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. a #GFileInfo. a string containing an edit name. Sets the file type in a #GFileInfo to @type. See %G_FILE_ATTRIBUTE_STANDARD_TYPE. a #GFileInfo. a #GFileType. Sets the icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_ICON. a #GFileInfo. a #GIcon. Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. a #GFileInfo. a #gboolean. Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. a #GFileInfo. a #gboolean. Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given date/time value. %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. Since: 2.62 a #GFileInfo. a #GDateTime. Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given time value. %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared. Deprecated: 2.62: Use g_file_info_set_modification_date_time() instead, as #GTimeVal is deprecated due to the year 2038 problem. a #GFileInfo. a #GTimeVal. Sets the name attribute for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_NAME. a #GFileInfo. a string containing a name. Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info to the given size. a #GFileInfo. a #goffset containing the file's size. Sets the sort order attribute in the file info structure. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. a #GFileInfo. a sort order integer. Sets the symbolic icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. Since: 2.34 a #GFileInfo. a #GIcon. Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info to the given symlink target. a #GFileInfo. a static string containing a path to a symlink target. Unsets a mask set by g_file_info_set_attribute_mask(), if one is set. #GFileInfo. 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. a #GFileInputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. a #GFileInfo, or %NULL on error. 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. 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 a #GFileInputStream. a file attribute query string. the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous info query operation. a #GFileInputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. #GFileInfo. 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. Since: 2.22 a #GFileIOStream. the entity tag for the stream. 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. 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. If @cancellable is not %NULL, then the operation 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. Since: 2.22 a #GFileIOStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. a #GFileInfo for the @stream, or %NULL on error. Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_io_stream_query_info_finish(). For the synchronous version of this function, see g_file_io_stream_query_info(). Since: 2.22 a #GFileIOStream. a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finalizes the asynchronous query started by g_file_io_stream_query_info_async(). Since: 2.22 a #GFileIOStream. a #GAsyncResult. a #GError, %NULL to ignore. A #GFileInfo for the finished query. Checks to see if a file is native to the platform. A native file is 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. This call does no blocking I/O. input #GFile %TRUE if @file is native 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. Since: 2.56 a #GFile a #GCancellable or %NULL a location to place the current entity tag for the file, or %NULL if the entity tag is not needed a location for a #GError or %NULL a #GBytes or %NULL and @error is set Asynchronously loads the contents of @file 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_async() and g_bytes_new_take(). @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 a #GFile a #GCancellable or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Completes an asynchronous request to g_file_load_bytes_async(). 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. See g_file_load_bytes() for more information. Since: 2.56 a #GFile a #GAsyncResult provided to the callback a location to place the current entity tag for the file, or %NULL if the entity tag is not needed a location for a #GError, or %NULL a #GBytes or %NULL and @error is set 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 @contents should be freed with g_free() when no longer needed. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile optional #GCancellable object, %NULL to ignore a location to place the contents of the file a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the current entity tag for the file, or %NULL if the entity tag is not needed a #GError, or %NULL %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors. 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. 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. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function 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 @contents 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. input #GFile a #GAsyncResult a location to place the contents of the file a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the current entity tag for the file, or %NULL if the entity tag is not needed a #GError, or %NULL %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. Reads the partial contents of a file. A #GFileReadMoreCallback should be used to stop reading from the file when appropriate, else this function will behave exactly as g_file_load_contents_async(). This operation can be finished by g_file_load_partial_contents_finish(). Users of this function should be aware that @user_data is passed to both the @read_more_callback and the @callback. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile optional #GCancellable object, %NULL to ignore a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read a #GAsyncReadyCallback to call when the request is satisfied the data to pass to the callback functions 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 @contents should be freed with g_free() when no longer needed. input #GFile a #GAsyncResult a location to place the contents of the file a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the current entity tag for the file, or %NULL if the entity tag is not needed a #GError, or %NULL %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. 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. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE on successful creation, %FALSE otherwise. Asynchronously creates a directory. Virtual: make_directory_async Since: 2.38 input #GFile the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous directory creation, started with g_file_make_directory_async(). Virtual: make_directory_finish Since: 2.38 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE on successful directory creation, %FALSE otherwise. Creates a directory and any parent directories that may not exist similar to 'mkdir -p'. If the file system does not support creating directories, this function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike the similar g_mkdir_with_parents(). For a local #GFile the newly created directories will have the default (current) ownership and permissions of the current process. If @cancellable is not %NULL, then the operation can 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.18 input #GFile optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if all directories have been successfully created, %FALSE otherwise. Creates a symbolic link named @file which contains the string @symlink_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. a #GFile with the name of the symlink to create a string with the path for the target of the new symlink optional #GCancellable object, %NULL to ignore a #GError %TRUE on the creation of a new symlink, %FALSE otherwise. Asynchronously creates a symbolic link named @file which contains the string @symlink_value. Virtual: make_symbolic_link_async Since: 2.74 a #GFile with the name of the symlink to create a string with the path for the target of the new symlink the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous symbolic link creation, started with g_file_make_symbolic_link_async(). Virtual: make_symbolic_link_finish Since: 2.74 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE on successful directory creation, %FALSE otherwise. Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links). By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless %G_FILE_MEASURE_REPORT_ANY_ERROR 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. Since: 2.38 a #GFile #GFileMeasureFlags optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered %NULL, or a pointer to a %NULL #GError pointer %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. Recursively measures the disk usage of @file. This is the asynchronous version of g_file_measure_disk_usage(). See there for more information. Since: 2.38 a #GFile #GFileMeasureFlags the [I/O priority][io-priority] of the request optional #GCancellable a #GFileMeasureProgressCallback user_data for @progress_callback a #GAsyncReadyCallback to call when complete the data to pass to callback function Collects the results from an earlier call to g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for more information. Since: 2.38 a #GFile the #GAsyncResult passed to your #GAsyncReadyCallback the number of bytes of disk space used the number of directories encountered the number of non-directories encountered %NULL, or a pointer to a %NULL #GError pointer %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. Obtains a file or directory monitor for the given file, depending on the type of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Since: 2.18 input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). Cancels a file monitor. a #GFileMonitor. always %TRUE 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. 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(). Virtual: monitor_dir input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). Emits the #GFileMonitor::changed signal if a change has taken place. Should be called from file monitor implementations only. 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. a #GFileMonitor. a #GFile. a #GFile. a set of #GFileMonitorEvent flags. Obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 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. input #GFile a set of #GFileMonitorFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). Returns whether the monitor is canceled. a #GFileMonitor %TRUE if monitor is canceled. %FALSE otherwise. Sets the rate limit to which the @monitor will report consecutive change events to the same file. a #GFileMonitor. a non-negative integer with the limit in milliseconds to poll for changes Starts a @mount_operation, mounting the volume that contains the file @location. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_mount_enclosing_volume_finish(). If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a mount operation started by g_file_mount_enclosing_volume(). input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. Mounts a file of type G_FILE_TYPE_MOUNTABLE. Using @mount_operation, you can request callbacks when, for instance, passwords are needed during authentication. If @cancellable is not %NULL, then the operation can 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. input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a mount operation. See g_file_mount_mountable() for details. Finish an asynchronous mount operation that was started with g_file_mount_mountable(). input #GFile a #GAsyncResult a #GError, or %NULL a #GFile or %NULL on error. Free the returned object with g_object_unref(). 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 @cancellable is not %NULL, then the operation can 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). #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function #GError for returning error conditions, or %NULL %TRUE on successful move, %FALSE otherwise. Asynchronously moves a file @source to the location of @destination. For details of the behaviour, see g_file_move(). If @progress_callback is not %NULL, then that function that will be called just like in g_file_move(). The callback will run in the default main context of the thread calling g_file_move_async() — the same context as @callback is run in. When the operation is finished, @callback will be called. You can then call g_file_move_finish() to get the result of the operation. Since: 2.72 #GFile pointing to the source location #GFile pointing to the destination location set of #GFileCopyFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore #GFileProgressCallback function for updates gpointer to user data for the callback function a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file movement, started with g_file_move_async(). Since: 2.72 input source #GFile a #GAsyncResult a #GError, or %NULL %TRUE on successful file move, %FALSE otherwise. Constructs a #GFile from a series of elements using the correct separator for filenames. Using this function is equivalent to calling g_build_filename(), followed by g_file_new_for_path() on the result. Since: 2.56 the first element in the path remaining elements in path, terminated by %NULL a new #GFile Creates a #GFile with the given argument from the command line. The value of @arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if @arg points to a malformed path. Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to main(). g_win32_get_command_line() will return a UTF-8 version of the commandline. #GApplication also uses UTF-8 but g_application_command_line_create_file_for_arg() may be more useful for you there. It is also always possible to use this function with #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. a command line string a new #GFile. Free the returned object with g_object_unref(). Creates a #GFile with the given argument from the command line. This function is similar to g_file_new_for_commandline_arg() except that it allows for passing the current working directory as an argument instead of using the current working directory of the process. This is useful if the commandline argument was given in a context other than the invocation of the current process. See also g_application_command_line_create_file_for_arg(). Since: 2.36 a command line string the current working directory of the commandline a new #GFile 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. a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. a new #GFile for the given @path. Free the returned object with g_object_unref(). 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. a UTF-8 string containing a URI a new #GFile for the given @uri. Free the returned object with g_object_unref(). 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. Since: 2.32 Template for the file name, as in g_file_open_tmp(), or %NULL for a default template on return, a #GFileIOStream for the created file a #GError, or %NULL a new #GFile. Free the returned object with g_object_unref(). Asynchronously opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_file_new_tmp(). @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. Since: 2.74 Template for the file name, as in g_file_open_tmp(), or %NULL for a default template the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Asynchronously creates a directory in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp(). @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. Since: 2.74 Template for the file name, as in g_dir_make_tmp(), or %NULL for a default template the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a temporary directory creation started by g_file_new_tmp_dir_async(). Since: 2.74 a #GAsyncResult a #GError, or %NULL a new #GFile. Free the returned object with g_object_unref(). Finishes a temporary file creation started by g_file_new_tmp_async(). Since: 2.74 a #GAsyncResult on return, a #GFileIOStream for the created file a #GError, or %NULL a new #GFile. Free the returned object with g_object_unref(). Opens an existing file for reading and writing. The result is a #GFileIOStream that can be used to read and write the contents of the file. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing. Since: 2.22 #GFile to open a #GCancellable a #GError, or %NULL #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). Asynchronously opens @file for reading and writing. For more details, see g_file_open_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_open_readwrite_finish() to get the result of the operation. Since: 2.22 input #GFile the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file read operation started with g_file_open_readwrite_async(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). 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. a #GFileOutputStream. the entity tag for the stream. 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. a #GFileOutputStream. a file attribute query string. optional #GCancellable object, %NULL to ignore. a #GError, %NULL to ignore. a #GFileInfo for the @stream, or %NULL on error. Asynchronously queries the @stream for a #GFileInfo. When completed, @callback will be called with a #GAsyncResult which can be used to finish the operation with g_file_output_stream_query_info_finish(). For the synchronous version of this function, see g_file_output_stream_query_info(). a #GFileOutputStream. a file attribute query string. the [I/O priority][gio-GIOScheduler] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finalizes the asynchronous query started by g_file_output_stream_query_info_async(). a #GFileOutputStream. a #GAsyncResult. a #GError, %NULL to ignore. A #GFileInfo for the finished query. 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. a file name or path to be parsed a new #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. This call does no blocking I/O. Since: 2.56 input #GFile string containing the #GFile's path, or %NULL if no such path exists. The returned string is owned by @file. Polls a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation. Since: 2.22 input #GFile optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a poll operation. See g_file_poll_mountable() for details. Finish an asynchronous poll operation that was polled with g_file_poll_mountable(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the operation finished successfully. %FALSE otherwise. 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. a #GFile to open optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() Async version of g_file_query_default_handler(). Since: 2.60 a #GFile to open the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is done data to pass to @callback Finishes a g_file_query_default_handler_async() operation. Since: 2.60 a #GFile to open a #GAsyncResult a #GError a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() 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. 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. input #GFile optional #GCancellable object, %NULL to ignore %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). 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. Since: 2.18 input #GFile a set of #GFileQueryInfoFlags passed to g_file_query_info() optional #GCancellable object, %NULL to ignore The #GFileType of the file and %G_FILE_TYPE_UNKNOWN if the file does not exist 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. input #GFile an attribute query string optional #GCancellable object, %NULL to ignore a #GError a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). 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). For more details, see g_file_query_filesystem_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. input #GFile an attribute query string the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async(). input #GFile a #GAsyncResult a #GError #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). Gets the requested information about specified @file. The result is a #GFileInfo object that contains key-value attributes (such as the type or size of the file). The @attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. @attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like %G_FILE_ATTRIBUTE_STANDARD_NAME. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass %G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned. 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. input #GFile an attribute query string a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). 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. input #GFile an attribute query string a set of #GFileQueryInfoFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file info query. See g_file_query_info_async(). input #GFile a #GAsyncResult a #GError #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). Obtain the list of settable attributes for the file. input #GFile optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() 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. input #GFile optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() 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. Virtual: read_fn #GFile to read a #GCancellable a #GError, or %NULL #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). 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. input #GFile the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file read operation started with g_file_read_async(). input #GFile a #GAsyncResult a #GError, or %NULL a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). 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. input #GFile an optional [entity tag][gfile-etag] for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_finish() to get the result of the operation. input #GFile an [entity tag][gfile-etag] for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function 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. The returned @new_etag can be used to verify that the file hasn't changed the next time it is saved over. input #GFile a string containing the new contents for @file the length of @contents in bytes the old [entity-tag][gfile-etag] for the document, or %NULL %TRUE if a backup should be created a set of #GFileCreateFlags 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 optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. 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. If @make_backup is %TRUE, this function will attempt to make a backup of @file. Note that no copy of @contents 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. input #GFile string of contents to replace the file with the length of @contents in bytes a new [entity tag][gfile-etag] for the @file, or %NULL %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Same as g_file_replace_contents_async() but takes a #GBytes input instead. This function will keep a ref on @contents until the operation is done. Unlike g_file_replace_contents_async() this allows forgetting about the content without waiting for the callback. When this operation has completed, @callback will be called with @user_user data, and the operation can be finalized with g_file_replace_contents_finish(). Since: 2.40 input #GFile a #GBytes a new [entity tag][gfile-etag] for the @file, or %NULL %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous replace of the given @file. See g_file_replace_contents_async(). Sets @new_etag to the new entity tag for the document, if present. input #GFile a #GAsyncResult 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 a #GError, or %NULL %TRUE on success, %FALSE on failure. Finishes an asynchronous file replace operation started with g_file_replace_async(). input #GFile a #GAsyncResult a #GError, or %NULL a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). 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. 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. Since: 2.22 a #GFile an optional [entity tag][gfile-etag] for the current #GFile, or #NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags optional #GCancellable object, %NULL to ignore return location for a #GError, or %NULL a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. For more details, see g_file_replace_readwrite() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_replace_readwrite_finish() to get the result of the operation. Since: 2.22 input #GFile an [entity tag][gfile-etag] for the current #GFile, or %NULL to ignore %TRUE if a backup should be created a set of #GFileCreateFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file replace operation started with g_file_replace_readwrite_async(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). Resolves a relative path for @file to an absolute path. This call does no blocking I/O. If the @relative_path is an absolute path name, the resolution is done absolutely (without taking @file path as base). input #GFile a given relative path string a #GFile for the resolved path. Sets an attribute in the file with attribute name @attribute to @value_p. Some attributes can be unset by setting @type to %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p 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. input #GFile a string containing the attribute's name The type of the attribute a pointer to the value (or the pointer itself if the type is a pointer type) a set of #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the attribute was set, %FALSE otherwise. 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. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile a string containing the attribute's name a string containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. 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. input #GFile a string containing the attribute's name a #gint32 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. 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. input #GFile a string containing the attribute's name a #guint64 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the @attribute was successfully set, %FALSE otherwise. 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. input #GFile a string containing the attribute's name a string containing the attribute's value #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the @attribute was successfully set, %FALSE otherwise. 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. input #GFile a string containing the attribute's name a #guint32 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. 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. input #GFile a string containing the attribute's name a #guint64 containing the attribute's new value a #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. Asynchronously sets the attributes of @file with @info. For more details, see g_file_set_attributes_from_info(), which is the synchronous version of this call. 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. input #GFile a #GFileInfo a #GFileQueryInfoFlags the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback a #gpointer Finishes setting an attribute started in g_file_set_attributes_async(). input #GFile a #GAsyncResult a #GFileInfo a #GError, or %NULL %TRUE if the attributes were set correctly, %FALSE otherwise. Tries to set all attributes in the #GFileInfo on the target values, not stopping on the first error. If there is any error during this operation then @error will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect further errors. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. input #GFile a #GFileInfo #GFileQueryInfoFlags optional #GCancellable object, %NULL to ignore a #GError, or %NULL %FALSE if there was any error, %TRUE otherwise. 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. input #GFile a string optional #GCancellable object, %NULL to ignore a #GError, or %NULL a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). Asynchronously sets the display name for a given #GFile. For more details, see g_file_set_display_name() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_file_set_display_name_finish() to get the result of the operation. input #GFile a string the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes setting a display name started with g_file_set_display_name_async(). input #GFile a #GAsyncResult a #GError, or %NULL a #GFile or %NULL on error. Free the returned object with g_object_unref(). Starts a file of type %G_FILE_TYPE_MOUNTABLE. Using @start_operation, you can request callbacks when, for instance, passwords are needed during authentication. If @cancellable is not %NULL, then the operation can 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. Since: 2.22 input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a start operation. See g_file_start_mountable() for details. Finish an asynchronous start operation that was started with g_file_start_mountable(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the operation finished successfully. %FALSE otherwise. Stops a file of type %G_FILE_TYPE_MOUNTABLE. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. When the operation is finished, @callback will be called. You can then call g_file_stop_mountable_finish() to get the result of the operation. Since: 2.22 input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes a stop operation, see g_file_stop_mountable() for details. Finish an asynchronous stop operation that was started with g_file_stop_mountable(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the operation finished successfully. %FALSE 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. Since: 2.22 a #GFile Whether or not @file supports thread-default contexts. 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. Since GLib 2.66, the `x-gvfs-notrash` unix mount option can be used to disable g_file_trash() support for certain mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Virtual: trash #GFile to send to trash optional #GCancellable object, %NULL to ignore a #GError, or %NULL %TRUE on successful trash, %FALSE otherwise. Asynchronously sends @file to the Trash location, if possible. Virtual: trash_async Since: 2.38 input #GFile the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous file trashing operation, started with g_file_trash_async(). Virtual: trash_finish Since: 2.38 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE on successful trash, %FALSE otherwise. 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. input #GFile flags affecting the operation optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes an unmount operation, see g_file_unmount_mountable() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable(). Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead. input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the operation finished successfully. %FALSE otherwise. 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. Since: 2.22 input #GFile flags affecting the operation a #GMountOperation, or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback to call when the request is satisfied, or %NULL the data to pass to callback function Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. Finish an asynchronous unmount operation that was started with g_file_unmount_mountable_with_operation(). Since: 2.22 input #GFile a #GAsyncResult a #GError, or %NULL %TRUE if the operation finished successfully. %FALSE otherwise. Obtains a completion for @initial_text from @completer. the filename completer. text to be completed. a completed string, or %NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished. Gets an array of completion strings for a given initial text. the filename completer. text to be completed. array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished. Creates a new filename completer. a #GFilenameCompleter. If @dirs_only is %TRUE, @completer will only complete directory names, and not file names. the filename completer. a #gboolean. Gets the base stream for the filter stream. a #GFilterInputStream. a #GInputStream. Returns whether the base stream will be closed when @stream is closed. a #GFilterInputStream. %TRUE if the base stream will be closed. Sets whether the base stream will be closed when @stream is closed. a #GFilterInputStream. %TRUE to close the base stream. Gets the base stream for the filter stream. a #GFilterOutputStream. a #GOutputStream. Returns whether the base stream will be closed when @stream is closed. a #GFilterOutputStream. %TRUE if the base stream will be closed. Sets whether the base stream will be closed when @stream is closed. a #GFilterOutputStream. %TRUE to close the base stream. Deserializes a #GIcon previously serialized using g_icon_serialize(). Since: 2.38 a #GVariant created with g_icon_serialize() a #GIcon, or %NULL when deserialization fails. Checks if two icons are equal. pointer to the first #GIcon. pointer to the second #GIcon. %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. Gets a hash for an icon. Virtual: hash #gconstpointer to an icon object. a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. Generate a #GIcon instance from @str. This function can fail if @str is not valid - see g_icon_to_string() for discussion. 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(). Since: 2.20 A string obtained via g_icon_to_string(). Return location for error. An object implementing the #GIcon interface or %NULL if @error is set. 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. Since: 2.38 a #GIcon a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. Generates a textual representation of @icon that can be used for serialization such as when passing @icon to a different process or saving it to persistent storage. Use g_icon_new_for_string() to get @icon back from the returned string. The encoding of the returned string is proprietary to #GIcon except in the following two cases - If @icon is a #GFileIcon, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the #GFile for @icon is a native file. If the file is not native, the returned string is the result of g_file_get_uri() (such as `sftp://path/to/my%20icon.png`). - If @icon is a #GThemedIcon with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`). Since: 2.20 a #GIcon. An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free. Checks if two #GInetAddress instances are equal, e.g. the same address. Since: 2.30 A #GInetAddress. Another #GInetAddress. %TRUE if @address and @other_address are equal, %FALSE otherwise. Gets @address's family Since: 2.22 a #GInetAddress @address's family Tests whether @address is the "any" address for its family. Since: 2.22 a #GInetAddress %TRUE if @address is the "any" address for its family. 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). Since: 2.22 a #GInetAddress %TRUE if @address is a link-local address. Tests whether @address is the loopback address for its family. Since: 2.22 a #GInetAddress %TRUE if @address is the loopback address for its family. Tests whether @address is a global multicast address. Since: 2.22 a #GInetAddress %TRUE if @address is a global multicast address. Tests whether @address is a link-local multicast address. Since: 2.22 a #GInetAddress %TRUE if @address is a link-local multicast address. Tests whether @address is a node-local multicast address. Since: 2.22 a #GInetAddress %TRUE if @address is a node-local multicast address. Tests whether @address is an organization-local multicast address. Since: 2.22 a #GInetAddress %TRUE if @address is an organization-local multicast address. Tests whether @address is a site-local multicast address. Since: 2.22 a #GInetAddress %TRUE if @address is a site-local multicast address. Tests whether @address is a multicast address. Since: 2.22 a #GInetAddress %TRUE if @address is a multicast address. 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). Since: 2.22 a #GInetAddress %TRUE if @address is a site-local address. 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(). Since: 2.22 a #GInetAddress the number of bytes used for the native version of @address. Tests if @mask and @mask2 are the same mask. Since: 2.32 a #GInetAddressMask another #GInetAddressMask whether @mask and @mask2 are the same mask Gets @mask's base address Since: 2.32 a #GInetAddressMask @mask's base address Gets the #GSocketFamily of @mask's address Since: 2.32 a #GInetAddressMask the #GSocketFamily of @mask's address Gets @mask's length Since: 2.32 a #GInetAddressMask @mask's length Tests if @address falls within the range described by @mask. Since: 2.32 a #GInetAddressMask a #GInetAddress whether @address falls within the range described by @mask. Creates a new #GInetAddressMask representing all addresses whose first @length bits match @addr. Since: 2.32 a #GInetAddress number of bits of @addr to use return location for #GError, or %NULL a new #GInetAddressMask, or %NULL on error 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. Since: 2.32 an IP address or address/length string return location for #GError, or %NULL a new #GInetAddressMask corresponding to @string, or %NULL on error. Converts @mask back to its corresponding string form. Since: 2.32 a #GInetAddressMask a string corresponding to @mask. Creates a #GInetAddress for the "any" address (unassigned/"don't care") for @family. Since: 2.22 the address family a new #GInetAddress corresponding to the "any" address for @family. Free the returned object with g_object_unref(). 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. Since: 2.22 raw address data the address family of @bytes a new #GInetAddress corresponding to @family and @bytes. Free the returned object with g_object_unref(). Parses @string as an IP address and creates a new #GInetAddress. Since: 2.22 a string representation of an IP address a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed. Free the returned object with g_object_unref(). Creates a #GInetAddress for the loopback address for @family. Since: 2.22 the address family a new #GInetAddress corresponding to the loopback address for @family. Free the returned object with g_object_unref(). Gets the raw binary address data from @address. Since: 2.22 a #GInetAddress 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(). Converts @address to string form. Since: 2.22 a #GInetAddress a representation of @address as a string, which should be freed after use. Gets @address's #GInetAddress. Since: 2.22 a #GInetSocketAddress the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored Gets the `sin6_flowinfo` field from @address, which must be an IPv6 address. Since: 2.32 a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress the flowinfo field Gets @address's port. Since: 2.22 a #GInetSocketAddress the port for @address Gets the `sin6_scope_id` field from @address, which must be an IPv6 address. Since: 2.32 a %G_SOCKET_FAMILY_IPV6 #GInetAddress the scope id field Creates a new #GInetSocketAddress for @address and @port. Since: 2.22 a #GInetAddress a port number a new #GInetSocketAddress Creates a new #GInetSocketAddress for @address and @port. If @address is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). Since: 2.40 the string form of an IP address a port number a new #GInetSocketAddress, or %NULL if @address cannot be parsed. Initializes the object implementing the interface. This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead. 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. Since: 2.22 a #GInitable. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. 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. Since: 2.22 a #GType supporting #GInitable. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. 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. a newly allocated #GObject, or %NULL on error 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. Since: 2.22 a #GType supporting #GInitable. the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. The var args list generated from @first_property_name. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. a newly allocated #GObject, or %NULL on error 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. Since: 2.22 Deprecated: 2.54: Use g_object_new_with_properties() and g_initable_init() instead. See #GParameter for more information. a #GType supporting #GInitable. the number of parameters in @parameters the parameters to use to construct the object optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. a newly allocated #GObject, or %NULL on error Clears the pending flag on @stream. input stream Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return %G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user. If @cancellable is not %NULL, then the operation can 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. A #GInputStream. optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE on failure 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. A #GInputStream. the [I/O priority][io-priority] of the request optional cancellable object callback to call when the request is satisfied the data to pass to callback function Finishes closing a stream asynchronously, started from g_input_stream_close_async(). a #GInputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the stream was closed successfully. Checks if an input stream has pending actions. input stream. %TRUE if @stream has pending actions. Checks if an input stream is closed. input stream. %TRUE if the stream is closed. Tries to read @count bytes from the stream into the buffer starting at @buffer. Will block during this read. If count is zero returns zero and does nothing. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if @count is zero), but never otherwise. The returned @buffer is not a nul-terminated string, it can contain nul bytes at any position, and this function doesn't nul-terminate the @buffer. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an 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. a #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore Number of bytes read, or -1 on error, or 0 on end of file. Tries to read @count bytes from the stream into the buffer starting at @buffer. Will block during this read. This function is similar to g_input_stream_read(), except it tries to read as many bytes as requested, only stopping on an error or end of stream. On a successful read of @count bytes, or if we reached the end of the stream, %TRUE is returned, and @bytes_read is set to the number of bytes read into @buffer. If there is an error during the operation %FALSE is returned and @error is set to indicate the error status. 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(). a #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream location to store the number of bytes that was read from the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE if there was an error Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. This is the asynchronous equivalent of g_input_stream_read_all(). Call g_input_stream_read_all_finish() to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. Since: 2.44 A #GInputStream a buffer to read data into (which should be at least count bytes long) the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream read operation started with g_input_stream_read_all_async(). As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_read will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read_async(). Since: 2.44 a #GInputStream a #GAsyncResult location to store the number of bytes that was read from the stream a #GError location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE if there was an error 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. 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. 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. A #GInputStream. a buffer to read data into (which should be at least count bytes long). the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request. optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function 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. On success, a new #GBytes is returned. It is not an error if the size of this object is not the same as the requested size, as it can happen e.g. near the end of a file. A zero-length #GBytes is returned on end of file (or if @count is zero), but never otherwise. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. On error %NULL is returned and @error is set accordingly. Since: 2.34 a #GInputStream. maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore a new #GBytes, or %NULL on 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. On success, the new #GBytes will be passed to the callback. It is not an error if this is smaller than the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. Since: 2.34 A #GInputStream. the number of bytes that will be read from the stream the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream read-into-#GBytes operation. Since: 2.34 a #GInputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. the newly-allocated #GBytes, or %NULL on error Finishes an asynchronous stream read operation. a #GInputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. number of bytes read in, or -1 on error, or 0 on end of file. Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. input stream a #GError location to store the error occurring, or %NULL to ignore. %TRUE if pending was previously unset and is now set. Tries to skip @count bytes from the stream. Will block during the operation. This is identical to g_input_stream_read(), from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some streams have an implementation that is more efficient than reading the data. This function is optional for inherited classes, as the default implementation emulates it using read. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. a #GInputStream. the number of bytes that will be skipped from the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore Number of bytes skipped, or -1 on error 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. During an async request no other sync and async calls are allowed, and will result in %G_IO_ERROR_PENDING errors. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes skipped will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to skip as many bytes as requested. Zero is returned on end of file (or if @count is zero), but never otherwise. 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. A #GInputStream. the number of bytes that will be skipped from the stream the [I/O priority][io-priority] of the request optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes a stream skip operation. a #GInputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. the size of the bytes skipped, or `-1` on error. 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). 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 Error number as defined in errno.h. #GIOErrorEnum value for the given errno.h error number. Converts #GFileError error codes into GIO error codes. Since: 2.74 a #GFileError. #GIOErrorEnum value for the given #GFileError error value. Converts some common error codes (as returned from GetLastError() or WSAGetLastError()) into GIO error codes. The fallback value %G_IO_ERROR_FAILED is returned for error codes not currently handled (but note that future GLib releases may return a more specific value instead). You can use g_win32_error_message() to get a localized string corresponding to @error_code. (But note that unlike g_strerror(), g_win32_error_message() returns a string that must be freed.) Since: 2.26 Windows error number. #GIOErrorEnum value for the given error number. Gets the GIO Error Quark. a #GQuark. Gets the name under which @extension was registered. Note that the same type may be registered as extension for multiple extension points, under different names. a #GIOExtension the name of @extension. Gets the priority with which @extension was registered. a #GIOExtension the priority of @extension Gets the type associated with @extension. a #GIOExtension the type of @extension Finds a #GIOExtension for an extension point by name. a #GIOExtensionPoint the name of the extension to get the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name Gets a list of all extensions that implement this extension point. The list is sorted by priority, beginning with the highest priority. a #GIOExtensionPoint a #GList of #GIOExtensions. The list is owned by GIO and should not be modified. Gets the required type for @extension_point. a #GIOExtensionPoint the #GType that all implementations must have, or %G_TYPE_INVALID if the extension point has no required type Registers @type as extension for the extension point with name @extension_point_name. If @type has already been registered as an extension for this extension point, the existing #GIOExtension object is returned. the name of the extension point the #GType to register as extension the name for the extension the priority for the extension a #GIOExtension object for #GType Looks up an existing extension point. the name of the extension point the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. Registers an extension point. The name of the extension point the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. Sets the required type for @extension_point to @type. All implementations must henceforth have this type. a #GIOExtensionPoint the #GType to require Gets a reference to the class for the type that is associated with @extension. a #GIOExtension the #GTypeClass for the type of @extension Required API for GIO modules to implement. This function is run after the module has been loaded into GIO, to initialize the module. Typically, this function will call g_io_extension_point_implement(). Since 2.56, this function should be named `g_io_<modulename>_load`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. a #GIOModule. Creates a new GIOModule that will load the specific shared library when in use. filename of the shared library module. a #GIOModule from given @filename, or %NULL on error. Optional API for GIO modules to implement. Should return a list of all the extension points that may be implemented in this module. This method will not be called in normal use, however it may be called when probing existing modules and recording which extension points that this model is used for. This means we won't have to load and initialize this module unless its needed. If this function is not implemented by the module the module will always be loaded, initialized and then unloaded on application startup so that it can register its extension points during init. Note that a module need not actually implement all the extension points that g_io_module_query() returns, since the exact list of extension may depend on runtime issues. However all extension points actually implemented must be returned by g_io_module_query() (if defined). When installing a module that implements g_io_module_query() you must run gio-querymodules in order to build the cache files required for lazy loading. Since 2.56, this function should be named `g_io_<modulename>_query`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. Since: 2.24 A %NULL-terminated array of strings, listing the supported extension points of the module. The array must be suitable for freeing with g_strfreev(). 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(). Since: 2.30 a module loading scope the basename to block Free a module scope. Since: 2.30 a module loading scope Create a new scope for loading of IO modules. A scope can be used for blocking duplicate modules, or blocking a module you don't want to load. 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. Since: 2.30 flags for the new scope the new module scope Required API for GIO modules to implement. This function is run when the module is being unloaded from GIO, to finalize the module. Since 2.56, this function should be named `g_io_<modulename>_unload`, where `modulename` is the plugin’s filename with the `lib` or `libgio` prefix and everything after the first dot removed, and with `-` replaced with `_` throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`. Using the new symbol names avoids name clashes when building modules statically. The old symbol names continue to be supported, but cannot be used for static builds. a #GIOModule. Loads all the modules in the specified directory. 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. pathname for a directory containing modules to load. 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(). Loads all the modules in the specified directory. If don't require all modules to be initialized (and thus registering all gtypes) then you can use g_io_modules_scan_all_in_directory() which allows delayed/lazy loading of modules. Since: 2.30 pathname for a directory containing modules to load. a scope to use when scanning the modules. 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(). 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 implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name(). If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory(). Since: 2.24 pathname for a directory containing modules to scan. Scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered. 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 implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name(). If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory(). Since: 2.30 pathname for a directory containing modules to scan. a scope to use when scanning the modules Cancels all cancellable I/O jobs. 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. 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). Deprecated: Use g_main_context_invoke(). a #GIOSchedulerJob a #GSourceFunc callback that will be called in the original thread data to pass to @func a #GDestroyNotify for @user_data, or %NULL The return value of @func 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. 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(). a #GIOSchedulerJob a #GSourceFunc callback that will be called in the original thread data to pass to @func a #GDestroyNotify for @user_data, or %NULL Schedules the I/O job to run in another thread. @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() a #GIOSchedulerJobFunc. data to pass to @job_func a #GDestroyNotify for @user_data, or %NULL the [I/O priority][io-priority] of the request. optional #GCancellable object, %NULL to ignore. Clears the pending flag on @stream. Since: 2.22 a #GIOStream 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. 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. Since: 2.22 a #GIOStream optional #GCancellable object, %NULL to ignore location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE on failure Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be called. You can then call g_io_stream_close_finish() to get the result of the operation. For behaviour details see g_io_stream_close(). 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 a #GIOStream the io priority of the request optional cancellable object callback to call when the request is satisfied the data to pass to callback function Closes a stream. Since: 2.22 a #GIOStream a #GAsyncResult a #GError location to store the error occurring, or %NULL to ignore %TRUE if stream was successfully closed, %FALSE otherwise. Gets the input stream for this object. This is used for reading. Since: 2.22 a #GIOStream a #GInputStream, owned by the #GIOStream. Do not free. Gets the output stream for this object. This is used for writing. Since: 2.22 a #GIOStream a #GOutputStream, owned by the #GIOStream. Do not free. Checks if a stream has pending actions. Since: 2.22 a #GIOStream %TRUE if @stream has pending actions. Checks if a stream is closed. Since: 2.22 a #GIOStream %TRUE if the stream is closed. Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. Since: 2.22 a #GIOStream a #GError location to store the error occurring, or %NULL to ignore %TRUE if pending was previously unset and is now set. Asynchronously 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. 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 a #GIOStream. a #GIOStream. a set of #GIOStreamSpliceFlags. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback. user data passed to @callback. Finishes an asynchronous io stream splice operation. Since: 2.28 a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE on success, %FALSE otherwise. 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 ]| 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. The backend reads default values from a keyfile called `defaults` in the directory specified by the #GKeyfileSettingsBackend:defaults-dir property, and a list of locked keys from a text file with the name `locks` in the same location. the filename of the keyfile the path under which all settings keys appear the group name corresponding to @root_path, or %NULL a keyfile-backed #GSettingsBackend Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. %NULL is never returned for an index that is smaller than the length of the list. See also: g_list_model_get_n_items() Since: 2.44 a #GListModel the position of the item to fetch the item at @position. Gets the type of the items in @list. All items returned from g_list_model_get_item() are of the type returned by this function, or a subtype, or if the type is an interface, they are an implementation of that interface. The item type of a #GListModel can not change during the life of the model. Since: 2.44 a #GListModel the #GType of the items contained in @list. Gets the number of items in @list. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for @position until g_list_model_get_item() returns %NULL. Since: 2.44 a #GListModel the number of items in @list. Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. %NULL is never returned for an index that is smaller than the length of the list. This function is meant to be used by language bindings in place of g_list_model_get_item(). See also: g_list_model_get_n_items() Since: 2.44 a #GListModel the position of the item to fetch the object at @position. 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. 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 a #GListModel the position at which @list changed the number of items removed the number of items added Appends @item to @store. @item must be of type #GListStore:item-type. This function takes a ref on @item. Use g_list_store_splice() to append multiple items at the same time efficiently. Since: 2.44 a #GListStore the new item Looks up the given @item in the list store by looping over the items until the first occurrence of @item. If @item was not found, then @position will not be set, and this method will return %FALSE. If you need to compare the two items with a custom comparison function, use g_list_store_find_with_equal_func() with a custom #GEqualFunc instead. Since: 2.64 a #GListStore an item the first position of @item, if it was found. Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. Looks up the given @item in the list store by looping over the items and comparing them with @equal_func until the first occurrence of @item which matches. If @item was not found, then @position will not be set, and this method will return %FALSE. Since: 2.64 a #GListStore an item A custom equality check function the first position of @item, if it was found. Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. Like g_list_store_find_with_equal_func() but with an additional @user_data that is passed to @equal_func. Since: 2.74 a #GListStore an item A custom equality check function user data for @equal_func the first position of @item, if it was found. Whether @store contains @item. If it was found, @position will be set to the position where @item occurred for the first time. Inserts @item into @store at @position. @item must be of type #GListStore:item-type or derived from it. @position must be smaller than the length of the list, or equal to it to append. This function takes a ref on @item. Use g_list_store_splice() to insert multiple items at the same time efficiently. Since: 2.44 a #GListStore the position at which to insert the new item the new item Inserts @item into @store at a position to be determined by the @compare_func. The list must already be sorted before calling this function or the result is undefined. Usually you would approach this by only ever inserting items by way of this function. This function takes a ref on @item. Since: 2.44 a #GListStore the new item pairwise comparison function for sorting user data for @compare_func the position at which @item was inserted Creates a new #GListStore with items of type @item_type. @item_type must be a subclass of #GObject. Since: 2.44 the #GType of items in the list a new #GListStore Removes the item from @store that is at @position. @position must be smaller than the current length of the list. Use g_list_store_splice() to remove multiple items at the same time efficiently. Since: 2.44 a #GListStore the position of the item that is to be removed Removes all items from @store. Since: 2.44 a #GListStore Sort the items in @store according to @compare_func. Since: 2.46 a #GListStore pairwise comparison function for sorting user data for @compare_func Changes @store by removing @n_removals items and adding @n_additions items to it. @additions must contain @n_additions items of type #GListStore:item-type. %NULL is not permitted. This function is more efficient than g_list_store_insert() and g_list_store_remove(), because it only emits #GListModel::items-changed once for the change. This function takes a ref on each item in @additions. The parameters @position and @n_removals must be correct (ie: @position + @n_removals must be less than or equal to the length of the list at the time this function is called). Since: 2.44 a #GListStore the position at which to make the change the number of items to remove the items to add the number of items to add Loads a loadable icon. For the asynchronous version of this function, see g_loadable_icon_load_async(). a #GLoadableIcon. an integer. a location to store the type of the loaded icon, %NULL to ignore. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. a #GInputStream to read the icon from. 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(). a #GLoadableIcon. an integer. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous icon load started in g_loadable_icon_load_async(). a #GLoadableIcon. a #GAsyncResult. a location to store the type of the loaded icon, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. a #GInputStream to read the icon from. Returns a new #GVfs handle for a local vfs. a new #GVfs handle. Appends @bytes to data that can be read from the input stream. Since: 2.34 a #GMemoryInputStream input data Appends @data to data that can be read from the input stream a #GMemoryInputStream input data length of the data, may be -1 if @data is a nul-terminated string function that is called to free @data, or %NULL Creates a new empty #GMemoryInputStream. a new #GInputStream Creates a new #GMemoryInputStream with data from the given @bytes. Since: 2.34 a #GBytes new #GInputStream read from @bytes Creates a new #GMemoryInputStream with data in memory of a given size. input data length of the data, may be -1 if @data is a nul-terminated string function that is called to free @data, or %NULL new #GInputStream read from @data of @len bytes. Gets a reference to the default #GMemoryMonitor for the system. Since: 2.64 a new reference to the default #GMemoryMonitor Gets any loaded data from the @ostream. Note that the returned pointer may become invalid on the next write or truncate operation on the stream. a #GMemoryOutputStream pointer to the stream's data, or %NULL if the data has been stolen Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away. Since: 2.18 a #GMemoryOutputStream the number of bytes written to the stream 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. 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. In any case, if you want the number of bytes currently written to the stream, use g_memory_output_stream_get_data_size(). a #GMemoryOutputStream the number of bytes allocated for the data buffer 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. It is probably only meaningful to provide @data and @size in the case that you want a fixed-sized stream. Put another way: if @realloc_fn is non-%NULL then it makes most sense to give @data as %NULL and @size as 0 (allowing #GMemoryOutputStream to do the initial allocation for itself). |[<!-- language="C" --> // a stream that can grow stream = g_memory_output_stream_new (NULL, 0, realloc, free); // another stream that can grow stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); // a fixed-size stream data = malloc (200); stream3 = g_memory_output_stream_new (data, 200, NULL, free); ]| pointer to a chunk of memory to use, or %NULL the size of @data a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL a function to be called on @data when the stream is finalized, or %NULL A newly created #GMemoryOutputStream object. Creates a new #GMemoryOutputStream, using g_realloc() and g_free() for memory allocation. Since: 2.36 Returns data from the @ostream as a #GBytes. @ostream must be closed before calling this function. Since: 2.34 a #GMemoryOutputStream the stream's data 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. @ostream must be closed before calling this function. Since: 2.26 a #GMemoryOutputStream the stream's data, or %NULL if it has previously been stolen Creates a memory-backed #GSettingsBackend. 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.28 a newly created #GSettingsBackend 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. Since: 2.32 a #GMenu the section label, or %NULL the detailed action string, or %NULL Appends @item to the end of @menu. See g_menu_insert_item() for more information. Since: 2.32 a #GMenu a #GMenuItem to append 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. Since: 2.32 a #GMenu the section label, or %NULL a #GMenuModel with the items of the section 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. Since: 2.32 a #GMenu the section label, or %NULL a #GMenuModel with the items of the submenu Gets the name of the attribute at the current iterator position, as a string. The iterator is not advanced. Since: 2.32 a #GMenuAttributeIter the name of the attribute 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. Since: 2.32 a #GMenuAttributeIter the type of the attribute the attribute value %TRUE on success, or %FALSE if there is no additional attribute Gets the value of the attribute at the current iterator position. The iterator is not advanced. Since: 2.32 a #GMenuAttributeIter the value of the current attribute Attempts to advance the iterator to the next (possibly first) attribute. %TRUE is returned on success, or %FALSE if there are no more attributes. 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). Since: 2.32 a #GMenuAttributeIter %TRUE on success, or %FALSE when there are no more attributes Marks @menu as frozen. 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. This function causes g_menu_model_is_mutable() to begin returning %FALSE, which has some positive performance implications. Since: 2.32 a #GMenu 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. Since: 2.32 a #GMenu the position at which to insert the item the section label, or %NULL the detailed action string, or %NULL Inserts @item into @menu. The "insertion" is actually done by copying all of the attribute and link values of @item and using them to form a new item within @menu. As such, @item itself is not really inserted, but rather, a menu item that is exactly the same as the one presently described by @item. This means that @item is essentially useless after the insertion occurs. Any changes you make to it are ignored unless it is inserted again (at which point its updated values will be copied). You should probably just free @item once you're done. There are many convenience functions to take care of common cases. See g_menu_insert(), g_menu_insert_section() and g_menu_insert_submenu() as well as "prepend" and "append" variants of each of these functions. Since: 2.32 a #GMenu the position at which to insert the item the #GMenuItem to insert 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. Since: 2.32 a #GMenu the position at which to insert the item the section label, or %NULL a #GMenuModel with the items of the section 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. Since: 2.32 a #GMenu the position at which to insert the item the section label, or %NULL a #GMenuModel with the items of the submenu Queries the named @attribute on @menu_item. If the attribute exists and matches the #GVariantType corresponding to @format_string then @format_string is used to deconstruct the value into the positional parameters and %TRUE is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and %FALSE is returned. Since: 2.34 a #GMenuItem the attribute name to query a #GVariant format string positional parameters, as per @format_string %TRUE if the named attribute was found with the expected type Queries the named @attribute on @menu_item. If @expected_type is specified and the attribute does not have this type, %NULL is returned. %NULL is also returned if the attribute simply does not exist. Since: 2.34 a #GMenuItem the attribute name to query the expected type of the attribute the attribute value, or %NULL Queries the named @link on @menu_item. Since: 2.34 a #GMenuItem the link name to query the link, or %NULL Creates a new #GMenuItem. 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. Since: 2.32 the section label, or %NULL the detailed action string, or %NULL a new #GMenuItem 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). Since: 2.34 a #GMenuModel the index of an item in @model a new #GMenuItem. Creates a new #GMenuItem representing a section. 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: |[ <menu id='edit-menu'> <section> <item label='Undo'/> <item label='Redo'/> </section> <section> <item label='Cut'/> <item label='Copy'/> <item label='Paste'/> </section> </menu> ]| The following example is exactly equivalent. It is more illustrative of the exact relationship between the menus and items (keeping in mind that the 'link' element defines a new menu that is linked to the containing one). The style of the second example is more verbose and difficult to read (and therefore not recommended except for the purpose of understanding what is really going on). |[ <menu id='edit-menu'> <item> <link name='section'> <item label='Undo'/> <item label='Redo'/> </link> </item> <item> <link name='section'> <item label='Cut'/> <item label='Copy'/> <item label='Paste'/> </link> </item> </menu> ]| Since: 2.32 the section label, or %NULL a #GMenuModel with the items of the section a new #GMenuItem Creates a new #GMenuItem representing a submenu. This is a convenience API around g_menu_item_new() and g_menu_item_set_submenu(). Since: 2.32 the section label, or %NULL a #GMenuModel with the items of the submenu a new #GMenuItem 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. 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 a #GMenuItem the name of the action for this item 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 @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 a #GMenuItem the name of the action for this item a #GVariant to use as the action target 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. Since: 2.32 a #GMenuItem the attribute to set 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. must consist only of lowercase ASCII characters, digits and '-'. If @value is non-%NULL then it is used as the new value for the attribute. If @value is %NULL then the attribute is unset. If the @value #GVariant is floating, it is consumed. See also g_menu_item_set_attribute() for a more convenient way to do the same. Since: 2.32 a #GMenuItem the attribute to set a #GVariant to use as the value, or %NULL Sets the "action" and possibly the "target" attribute of @menu_item. The format of @detailed_action is the same format parsed by g_action_parse_detailed_name(). See g_menu_item_set_action_and_target() or g_menu_item_set_action_and_target_value() for more flexible (but slightly less convenient) alternatives. 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 a #GMenuItem the "detailed" action string Sets (or unsets) the icon on @menu_item. This call is the same as calling g_icon_serialize() and using the result as the value to g_menu_item_set_attribute_value() for %G_MENU_ATTRIBUTE_ICON. This API is only intended for use with "noun" menu items; things like bookmarks or applications in an "Open With" menu. Don't use it on menu items corresponding to verbs (eg: stock icons for 'Save' or 'Quit'). If @icon is %NULL then the icon is unset. Since: 2.38 a #GMenuItem a #GIcon, or %NULL Sets or unsets the "label" attribute of @menu_item. If @label is non-%NULL it is used as the label for the menu item. If it is %NULL then the label attribute is unset. Since: 2.32 a #GMenuItem the label to set, or %NULL to unset Creates a link from @menu_item to @model if non-%NULL, or unsets it. 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 a #GMenuItem type of link to establish or unset the #GMenuModel to link to (or %NULL to unset) Sets or unsets the "section" link of @menu_item to @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. See g_menu_item_new_section() for more information about what it means for a menu item to be a section. Since: 2.32 a #GMenuItem 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. The effect of having one menu appear as a submenu of another is exactly as it sounds. Since: 2.32 a #GMenuItem a #GMenuModel, or %NULL Gets the name of the link at the current iterator position. The iterator is not advanced. Since: 2.32 a #GMenuLinkIter the type of the link This function combines g_menu_link_iter_next() with g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). First the iterator is advanced to the next (possibly first) link. If that fails, then %FALSE is returned and there are no other effects. If successful, @out_link and @value are set to the name and #GMenuModel of the link that has just been advanced to. At this point, g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the same values again. The value returned in @out_link remains valid for as long as the iterator remains at the current position. The value returned in @value must be unreffed using g_object_unref() when it is no longer in use. Since: 2.32 a #GMenuLinkIter the name of the link the linked #GMenuModel %TRUE on success, or %FALSE if there is no additional link Gets the linked #GMenuModel at the current iterator position. The iterator is not advanced. Since: 2.32 a #GMenuLinkIter the #GMenuModel that is linked to Attempts to advance the iterator to the next (possibly first) link. %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). Since: 2.32 a #GMenuLinkIter %TRUE on success, or %FALSE when there are no more links Queries item at position @item_index in @model for the attribute specified by @attribute. If the attribute exists and matches the #GVariantType corresponding to @format_string then @format_string is used to deconstruct the value into the positional parameters and %TRUE is returned. 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. Since: 2.32 a #GMenuModel the index of the item the attribute to query a #GVariant format string positional parameters, as per @format_string %TRUE if the named attribute was found with the expected type Queries the item at position @item_index in @model for the attribute specified by @attribute. 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. Since: 2.32 a #GMenuModel the index of the item the attribute to query the expected type of the attribute, or %NULL the value of the attribute Queries the item at position @item_index in @model for the link specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. Since: 2.32 a #GMenuModel the index of the item the link to query the linked #GMenuModel, or %NULL Query the number of items in @model. Since: 2.32 a #GMenuModel the number of items Queries if @model is mutable. An immutable #GMenuModel will never emit the #GMenuModel::items-changed signal. Consumers of the model may make optimisations accordingly. Since: 2.32 a #GMenuModel %TRUE if the model is mutable (ie: "items-changed" may be emitted). Requests emission of the #GMenuModel::items-changed signal on @model. This function should never be called except by #GMenuModel subclasses. Any other calls to this function will very likely lead to a violation of the interface of the model. The implementation should update its internal representation of the menu before emitting the signal. The implementation should further expect to receive queries about the new state of the menu (and particularly added menu items) while signal handlers are running. 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 a #GMenuModel the position of the change the number of items removed the number of items added Creates a #GMenuAttributeIter to iterate over the attributes of the item at position @item_index in @model. You must free the iterator with g_object_unref() when you are done. Since: 2.32 a #GMenuModel the index of the item a new #GMenuAttributeIter 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. Since: 2.32 a #GMenuModel the index of the item a new #GMenuLinkIter Creates a new #GMenu. The new menu has no items. Since: 2.32 a new #GMenu 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. Since: 2.32 a #GMenu the section label, or %NULL the detailed action string, or %NULL Prepends @item to the start of @menu. See g_menu_insert_item() for more information. Since: 2.32 a #GMenu a #GMenuItem to prepend 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. Since: 2.32 a #GMenu the section label, or %NULL a #GMenuModel with the items of the section 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.32 a #GMenu the section label, or %NULL a #GMenuModel with the items of the submenu Removes an item from the menu. @position gives the index of the item to remove. It is an error if position is not in range the range from 0 to one less than the number of items in the menu. 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 a #GMenu the position of the item to remove Removes all items in the menu. Since: 2.38 a #GMenu Checks if @mount can be ejected. a #GMount. %TRUE if the @mount can be ejected. Checks if @mount can be unmounted. a #GMount. %TRUE if the @mount can be unmounted. 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. Deprecated: 2.22: Use g_mount_eject_with_operation() instead. a #GMount. flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead. a #GMount. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the mount was successfully ejected. %FALSE otherwise. 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.22 a #GMount. flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes ejecting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Since: 2.22 a #GMount. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the mount was successfully ejected. %FALSE otherwise. 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). a #GMount. a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. Gets the drive for the @mount. This is a convenience method for getting the #GVolume and then using that object to get the #GDrive. a #GMount. a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. Gets the icon for @mount. a #GMount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. Gets the name of @mount. a #GMount. the name for the given @mount. The returned string should be freed with g_free() when no longer needed. Gets the root directory on @mount. a #GMount. a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. Gets the sort key for @mount, if any. Since: 2.32 A #GMount. Sorting key for @mount or %NULL if no such key is available. Gets the symbolic icon for @mount. Since: 2.34 a #GMount. a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. 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. a #GMount. the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. Gets the volume for the @mount. a #GMount. 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. 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. This is an asynchronous operation (see g_mount_guess_content_type_sync() for the synchronous version), and is finished by calling g_mount_guess_content_type_finish() with the @mount and #GAsyncResult data returned in the @callback. Since: 2.18 a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback user data passed to @callback 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. Since: 2.18 a #GMount a #GAsyncResult a #GError location to store the error occurring, or %NULL to ignore a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. 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. This is a synchronous operation and as such may block doing IO; see g_mount_guess_content_type() for the asynchronous version. Since: 2.18 a #GMount Whether to force a rescan of the content. Otherwise a cached result will be used if available optional #GCancellable object, %NULL to ignore a #GError location to store the error occurring, or %NULL to ignore a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. Determines if @mount is shadowed. Applications or libraries should avoid displaying @mount in the user interface if it is shadowed. 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. 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. 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. Since: 2.20 A #GMount. %TRUE if @mount is shadowed. Check to see whether the mount operation is being used for an anonymous user. a #GMountOperation. %TRUE if mount operation is anonymous. Gets a choice from the mount operation. a #GMountOperation. an integer containing an index of the user's choice from the choice's list, or `0`. Gets the domain of the mount operation. a #GMountOperation. a string set to the domain. Check to see whether the mount operation is being used for a TCRYPT hidden volume. Since: 2.58 a #GMountOperation. %TRUE if mount operation is for hidden volume. Check to see whether the mount operation is being used for a TCRYPT system volume. Since: 2.58 a #GMountOperation. %TRUE if mount operation is for system volume. Gets a password from the mount operation. a #GMountOperation. a string containing the password within @op. Gets the state of saving passwords for the mount operation. a #GMountOperation. a #GPasswordSave flag. Gets a PIM from the mount operation. Since: 2.58 a #GMountOperation. The VeraCrypt PIM within @op. Get the user name from the mount operation. a #GMountOperation. a string containing the user name. Creates a new mount operation. a #GMountOperation. Emits the #GMountOperation::reply signal. a #GMountOperation a #GMountOperationResult Sets the mount operation to use an anonymous user if @anonymous is %TRUE. a #GMountOperation. boolean value. Sets a default choice for the mount operation. a #GMountOperation. an integer. Sets the mount operation's domain. a #GMountOperation. the domain to set. Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. Since: 2.58 a #GMountOperation. boolean value. Sets the mount operation to use a system volume if @system_volume is %TRUE. Since: 2.58 a #GMountOperation. boolean value. Sets the mount operation's password to @password. a #GMountOperation. password to set. Sets the state of saving passwords for the mount operation. a #GMountOperation. a set of #GPasswordSave flags. Sets the mount operation's PIM to @pim. Since: 2.58 a #GMountOperation. an unsigned integer. Sets the user name within @op to @username. a #GMountOperation. input username. 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. 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. a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes remounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. a #GMount. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the mount was successfully remounted. %FALSE otherwise. 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.20 A #GMount. Unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_finish() with the @mount and #GAsyncResult data returned in the @callback. Deprecated: 2.22: Use g_mount_unmount_with_operation() instead. a #GMount. flags affecting the operation optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. Finishes unmounting a mount. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead. a #GMount. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the mount was successfully unmounted. %FALSE otherwise. 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.22 a #GMount. flags affecting the operation a #GMountOperation or %NULL to avoid user interaction. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback, or %NULL. user data passed to @callback. 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.22 a #GMount. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if the mount was successfully unmounted. %FALSE otherwise. 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.20 A #GMount. Creates a new #GNativeSocketAddress for @native and @len. Since: 2.46 a native address object the length of @native, in bytes a new #GNativeSocketAddress Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, depending on what @addr was created with. Since: 2.22 a #GNetworkAddress @addr's hostname Gets @addr's port number Since: 2.22 a #GNetworkAddress @addr's port (which may be 0) Gets @addr's scheme Since: 2.26 a #GNetworkAddress @addr's scheme (%NULL if not built from URI) Creates a new #GSocketConnectable for connecting to the given @hostname and @port. Note that depending on the configuration of the machine, a @hostname of `localhost` may refer to the IPv4 loopback address only, or to both IPv4 and IPv6; use g_network_address_new_loopback() to create a #GNetworkAddress that is guaranteed to resolve to both addresses. Since: 2.22 the hostname the port the new #GNetworkAddress Creates a new #GSocketConnectable for connecting to the local host over a loopback connection to the given @port. This is intended for use in connecting to local services which may be running on IPv4 or IPv6. The connectable will return IPv4 and IPv6 loopback addresses, regardless of how the host resolves `localhost`. By contrast, g_network_address_new() will often only return an IPv4 address when resolving `localhost`, and an IPv6 address for `localhost6`. g_network_address_get_hostname() will always return `localhost` for a #GNetworkAddress created with this constructor. Since: 2.44 the port the new #GNetworkAddress 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. If no port is specified 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. (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.) Since: 2.22 the hostname and optionally a port the default port if not in @host_and_port a pointer to a #GError, or %NULL the new #GNetworkAddress, or %NULL on error Creates a new #GSocketConnectable for connecting to the given @uri. May fail and return %NULL in case parsing @uri fails. Using this rather than g_network_address_new() or g_network_address_parse() allows #GSocketClient to determine when to use application-specific proxy protocols. Since: 2.26 the hostname and optionally a port The default port if none is found in the URI a pointer to a #GError, or %NULL the new #GNetworkAddress, or %NULL on error Adds @network to @monitor's list of available networks. Since: 2.32 the #GNetworkMonitorBase a #GInetAddressMask Removes @network from @monitor's list of available networks. Since: 2.32 the #GNetworkMonitorBase a #GInetAddressMask Drops @monitor's current list of available networks and replaces it with @networks. the #GNetworkMonitorBase an array of #GInetAddressMask length of @networks 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). 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(). Since: 2.32 a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL return location for a #GError, or %NULL %TRUE if @connectable is reachable, %FALSE if not. Asynchronously attempts to determine whether or not the host pointed to by @connectable can be reached, without actually trying to connect to it. For more details, see g_network_monitor_can_reach(). 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. a #GNetworkMonitor a #GSocketConnectable a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an async network connectivity test. See g_network_monitor_can_reach_async(). a #GNetworkMonitor a #GAsyncResult return location for errors, or %NULL %TRUE if network is reachable, %FALSE if not. Gets a more detailed networking state than g_network_monitor_get_network_available(). If #GNetworkMonitor:network-available is %FALSE, then the connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL. If #GNetworkMonitor:network-available is %TRUE, then the connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if the host has a default route, but appears to be unable to actually reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the host is trapped behind a "captive portal" that requires some sort of login or acknowledgement before allowing full Internet access). Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are reachable but others are not. In this case, applications can attempt to connect to remote servers, but should gracefully fall back to their "offline" behavior if the connection attempt fails. Since: 2.44 the #GNetworkMonitor the network connectivity state Gets the default #GNetworkMonitor for the system. Since: 2.32 a #GNetworkMonitor, which will be a dummy object if no network monitor is available 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. Since: 2.32 the #GNetworkMonitor whether the network is available Checks if the network is metered. See #GNetworkMonitor:network-metered for more details. Since: 2.46 the #GNetworkMonitor whether the connection is metered Gets the domain that @srv serves. This might be either UTF-8 or ASCII-encoded, depending on what @srv was created with. Since: 2.22 a #GNetworkService @srv's domain name Gets @srv's protocol name (eg, "tcp"). Since: 2.22 a #GNetworkService @srv's protocol name Gets the URI scheme used to resolve proxies. By default, the service name is used as scheme. Since: 2.26 a #GNetworkService @srv's scheme name Gets @srv's service name (eg, "ldap"). Since: 2.22 a #GNetworkService @srv's service name Creates a new #GNetworkService representing the given @service, @protocol, and @domain. This will initially be unresolved; use the #GSocketConnectable interface to resolve it. Since: 2.22 the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in a new #GNetworkService Set's the URI scheme used to resolve proxies. By default, the service name is used as scheme. Since: 2.26 a #GNetworkService a URI scheme Initializes the platform networking libraries (eg, on Windows, this calls WSAStartup()). GLib will call this itself if it is needed, so you only need to call it if you directly call system networking functions (without calling any GLib networking functions first). Since: 2.36 Adds a button to @notification that activates the action in @detailed_action when clicked. That action must be an application-wide action (starting with "app."). If @detailed_action contains a target, the action will be activated with that target as its parameter. See g_action_parse_detailed_name() for a description of the format for @detailed_action. Since: 2.40 a #GNotification label of the button a detailed action name Adds a button to @notification that activates @action when clicked. @action must be an application-wide action (it must start with "app."). If @target_format is given, it is used to collect remaining positional parameters into a #GVariant instance, similar to g_variant_new(). @action will be activated with that #GVariant as its parameter. Since: 2.40 a #GNotification label of the button an action name a #GVariant format string, or %NULL positional parameters, as determined by @target_format Adds a button to @notification that activates @action when clicked. @action must be an application-wide action (it must start with "app."). If @target is non-%NULL, @action will be activated with @target as its parameter. Since: 2.40 a #GNotification label of the button an action name a #GVariant to use as @action's parameter, or %NULL Creates a new #GNotification with @title as its title. After populating @notification with more details, it can be sent to the desktop shell with g_application_send_notification(). Changing any properties after this call will not have any effect until resending @notification. Since: 2.40 the title of the notification a new #GNotification instance Sets the body of @notification to @body. Since: 2.40 a #GNotification the new body for @notification, or %NULL Sets the type of @notification to @category. Categories have a main type like `email`, `im` or `device` and can have a detail separated by a `.`, e.g. `im.received` or `email.arrived`. Setting the category helps the notification server to select proper feedback to the user. Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html). Since: 2.70 a #GNotification the category for @notification, or %NULL for no category Sets the default action of @notification to @detailed_action. This action is activated when the notification is clicked on. The action in @detailed_action must be an application-wide action (it must start with "app."). If @detailed_action contains a target, the given action will be activated with that target as its parameter. See g_action_parse_detailed_name() for a description of the format for @detailed_action. When no default action is set, the application that the notification was sent on is activated. Since: 2.40 a #GNotification a detailed action name Sets the default action of @notification to @action. This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app."). If @target_format is given, it is used to collect remaining positional parameters into a #GVariant instance, similar to g_variant_new(). @action will be activated with that #GVariant as its parameter. When no default action is set, the application that the notification was sent on is activated. Since: 2.40 a #GNotification an action name a #GVariant format string, or %NULL positional parameters, as determined by @target_format Sets the default action of @notification to @action. This action is activated when the notification is clicked on. It must be an application-wide action (start with "app."). If @target is non-%NULL, @action will be activated with @target as its parameter. If @target is floating, it will be consumed. When no default action is set, the application that the notification was sent on is activated. Since: 2.40 a #GNotification an action name a #GVariant to use as @action's parameter, or %NULL Sets the icon of @notification to @icon. Since: 2.40 a #GNotification the icon to be shown in @notification, as a #GIcon Sets the priority of @notification to @priority. See #GNotificationPriority for possible values. a #GNotification a #GNotificationPriority Sets the title of @notification to @title. Since: 2.40 a #GNotification the new title for @notification Deprecated in favor of g_notification_set_priority(). Since: 2.40 Deprecated: 2.42: Since 2.42, this has been deprecated in favour of g_notification_set_priority(). a #GNotification %TRUE if @notification is urgent Creates a readonly #GSettingsBackend. This backend does not allow changes to settings, so all settings will always have their default values. Since: 2.28 a newly created #GSettingsBackend Clears the pending flag on @stream. output stream Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error. Closing a stream will automatically flush any outstanding buffers in the stream. Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details. On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return %G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but there some streams can use a faster close that doesn't block to e.g. check errors. On cancellation (as with any error) there is no guarantee that all written data will reach the target. A #GOutputStream. optional cancellable object location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE on failure 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. 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. A #GOutputStream. the io priority of the request. optional cancellable object callback to call when the request is satisfied the data to pass to callback function Closes an output stream. a #GOutputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if stream was successfully closed, %FALSE otherwise. 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. 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. a #GOutputStream. optional cancellable object location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE on error Forces an asynchronous write of all user-space buffered data for the given @stream. For behaviour details see g_output_stream_flush(). 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. a #GOutputStream. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes flushing an output stream. a #GOutputStream. a GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if flush operation succeeded, %FALSE otherwise. Checks if an output stream has pending actions. a #GOutputStream. %TRUE if @stream has pending actions. Checks if an output stream has already been closed. a #GOutputStream. %TRUE if @stream is closed. %FALSE otherwise. Checks if an output stream is being closed. This can be used inside e.g. a flush implementation to see if the flush (or other i/o operation) is called from within the closing operation. Since: 2.24 a #GOutputStream. %TRUE if @stream is being closed. %FALSE otherwise. This is a utility function around g_output_stream_write_all(). It uses g_strdup_vprintf() to turn @format and @... into a string that is then written to @stream. See the documentation of g_output_stream_write_all() about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own printf()-like wrapper around g_output_stream_write() or g_output_stream_write_all(). Since: 2.40 a #GOutputStream. location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore the format string. See the printf() documentation the parameters to insert into the format string %TRUE on success, %FALSE if there was an error Sets @stream to have actions pending. If the pending flag is already set or @stream is closed, it will return %FALSE and set @error. a #GOutputStream. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if pending was previously unset and is now set. Splices an input stream into an output stream. a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. 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. 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. For the synchronous, blocking version of this function, see g_output_stream_splice(). a #GOutputStream. a #GInputStream. a set of #GOutputStreamSpliceFlags. the io priority of the request. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback. user data passed to @callback. Finishes an asynchronous stream splice operation. a #GOutputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. 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. This is a utility function around g_output_stream_write_all(). It uses g_strdup_vprintf() to turn @format and @args into a string that is then written to @stream. See the documentation of g_output_stream_write_all() about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own printf()-like wrapper around g_output_stream_write() or g_output_stream_write_all(). Since: 2.40 a #GOutputStream. location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore the format string. See the printf() documentation the parameters to insert into the format string %TRUE on success, %FALSE if there was an error Tries to write @count bytes from @buffer into the stream. Will block during the operation. If count is 0, returns 0 and does nothing. A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless @count is 0). If @cancellable is not %NULL, then the operation can 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. Virtual: write_fn a #GOutputStream. the buffer containing the data to write. the number of bytes to write optional cancellable object location to store the error occurring, or %NULL to ignore Number of bytes written, or -1 on error 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. 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(). a #GOutputStream. the buffer containing the data to write. the number of bytes to write location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE if there was an error Request an asynchronous write of @count bytes from @buffer into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_write_all_finish() to get the result of the operation. This is the asynchronous version of g_output_stream_write_all(). Call g_output_stream_write_all_finish() to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is %G_PRIORITY_DEFAULT. Note that no copy of @buffer will be made, so it must stay valid until @callback is called. Since: 2.44 A #GOutputStream the buffer containing the data to write the number of bytes to write the io priority of the request optional #GCancellable object, %NULL to ignore callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream write operation started with g_output_stream_write_all_async(). As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write_async(). Since: 2.44 a #GOutputStream a #GAsyncResult location to store the number of bytes that was written to the stream a #GError location to store the error occurring, or %NULL to ignore. %TRUE on success, %FALSE if there was an error 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. 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. A #GOutputStream. the buffer containing the data to write. the number of bytes to write the io priority of the request. optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function 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. 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. a #GOutputStream. the #GBytes to write optional cancellable object location to store the error occurring, or %NULL to ignore Number of bytes written, or -1 on error 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. 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(). A #GOutputStream. The bytes to write the io priority of the request. optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes a stream write-from-#GBytes operation. a #GOutputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. a #gssize containing the number of bytes written to the stream. Finishes a stream write operation. a #GOutputStream. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. a #gssize containing the number of bytes written to the stream. Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and does nothing. 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 @n_vectors is 0 or the sum of all bytes in @vectors 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. Some implementations of g_output_stream_writev() may have limitations on the aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these are exceeded. For example, when writing to a local file on UNIX platforms, the aggregate buffer size must not exceed %G_MAXSSIZE bytes. Virtual: writev_fn Since: 2.60 a #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream optional cancellable object location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE if there was an error Tries to write the bytes contained in the @n_vectors @vectors into the stream. Will block during the operation. This function is similar to g_output_stream_writev(), except it tries to write as many bytes as requested, only stopping on an error. On a successful write of all @n_vectors vectors, %TRUE is returned, and @bytes_written is set to the sum of all the sizes of @vectors. 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(). The content of the individual elements of @vectors might be changed by this function. Since: 2.60 a #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE if there was an error Request an asynchronous write of the bytes contained in the @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_all_finish() to get the result of the operation. This is the asynchronous version of g_output_stream_writev_all(). Call g_output_stream_writev_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 @vectors will be made, so it must stay valid until @callback is called. The content of the individual elements of @vectors might be changed by this function. Since: 2.60 A #GOutputStream the buffer containing the #GOutputVectors to write. the number of vectors to write the I/O priority of the request optional #GCancellable object, %NULL to ignore callback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous stream write operation started with g_output_stream_writev_all_async(). As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_writev_async(). Since: 2.60 a #GOutputStream a #GAsyncResult location to store the number of bytes that were written to the stream a #GError location to store the error occurring, or %NULL to ignore. %TRUE on success, %FALSE if there was an error Request an asynchronous write of the bytes contained in @n_vectors @vectors into the stream. When the operation is finished @callback will be called. You can then call g_output_stream_writev_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. 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. For the synchronous, blocking version of this function, see g_output_stream_writev(). Note that no copy of @vectors will be made, so it must stay valid until @callback is called. Since: 2.60 A #GOutputStream. the buffer containing the #GOutputVectors to write. the number of vectors to write the I/O priority of the request. optional #GCancellable object, %NULL to ignore. callback to call when the request is satisfied the data to pass to callback function Finishes a stream writev operation. Since: 2.60 a #GOutputStream. a #GAsyncResult. location to store the number of bytes that were written to the stream a #GError location to store the error occurring, or %NULL to ignore. %TRUE on success, %FALSE if there was an error Attempts to acquire the permission represented by @permission. The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is that a dialog may appear asking the user to enter their password. You should check with g_permission_get_can_acquire() before calling this function. If the permission is acquired then %TRUE is returned. Otherwise, %FALSE is returned and @error is set appropriately. 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. Since: 2.26 a #GPermission instance a #GCancellable, or %NULL a pointer to a %NULL #GError, or %NULL %TRUE if the permission was successfully acquired Attempts to acquire the permission represented by @permission. This is the first half of the asynchronous version of g_permission_acquire(). Since: 2.26 a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback 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(). Since: 2.26 a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback a pointer to a %NULL #GError, or %NULL %TRUE if the permission was successfully acquired Gets the value of the 'allowed' property. This property is %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. Since: 2.26 a #GPermission instance the value of the 'allowed' property 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(). Since: 2.26 a #GPermission instance the value of the 'can-acquire' property 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(). Since: 2.26 a #GPermission instance the value of the 'can-release' property 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 a #GPermission instance the new value for the 'allowed' property the new value for the 'can-acquire' property the new value for the 'can-release' property 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. Since: 2.26 a #GPermission instance a #GCancellable, or %NULL a pointer to a %NULL #GError, or %NULL %TRUE if the permission was successfully released Attempts to release the permission represented by @permission. This is the first half of the asynchronous version of g_permission_release(). Since: 2.26 a #GPermission instance a #GCancellable, or %NULL the #GAsyncReadyCallback to call when done the user data to pass to @callback Collects the result of attempting to release the permission represented by @permission. This is the second half of the asynchronous version of g_permission_release(). Since: 2.26 a #GPermission instance the #GAsyncResult given to the #GAsyncReadyCallback a pointer to a %NULL #GError, or %NULL %TRUE if the permission was successfully released 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. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. Since: 2.28 a #GPollableInputStream. %TRUE if @stream is pollable, %FALSE if not. 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. 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. Since: 2.28 a #GPollableInputStream. a #GCancellable, or %NULL a new #GSource Checks if @stream can be read. 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. Since: 2.28 a #GPollableInputStream. %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. 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. 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. Virtual: read_nonblocking a #GPollableInputStream a buffer to read data into (which should be at least @count bytes long). the number of bytes you want to read a #GCancellable, or %NULL #GError for error reporting, or %NULL to ignore. the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). 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. For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa. Since: 2.28 a #GPollableOutputStream. %TRUE if @stream is pollable, %FALSE if not. 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. 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. Since: 2.28 a #GPollableOutputStream. a #GCancellable, or %NULL a new #GSource Checks if @stream can be written. 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. Since: 2.28 a #GPollableOutputStream. %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. 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. 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. Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same @buffer and @count in the next write call. Virtual: write_nonblocking a #GPollableOutputStream a buffer to write data from the number of bytes you want to write a #GCancellable, or %NULL #GError for error reporting, or %NULL to ignore. the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). Attempts to write the bytes contained in the @n_vectors @vectors to @stream, as with g_output_stream_writev(). If @stream is not currently writable, this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when @stream is writable. @error will *not* be set in that case. 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. Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same @vectors and @n_vectors in the next write call. Virtual: writev_nonblocking Since: 2.60 a #GPollableOutputStream the buffer containing the #GOutputVectors to write. the number of vectors to write location to store the number of bytes that were written to the stream a #GCancellable, or %NULL #GError for error reporting, or %NULL to ignore. %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and @error is *not* set), or %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will be set. Utility method for #GPollableInputStream and #GPollableOutputStream implementations. Creates a new #GSource that expects a callback of type #GPollableSourceFunc. The new source does not actually do anything on its own; use g_source_add_child_source() to add other sources to it to cause it to trigger. Since: 2.28 the stream associated with the new source the new #GSource. 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. Since: 2.34 the stream associated with the new source optional child source to attach optional #GCancellable to attach the new #GSource. 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. 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. Since: 2.34 a #GInputStream a buffer to read data into the number of bytes to read whether to do blocking I/O optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore the number of bytes read, or -1 on error. 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. 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. Since: 2.34 a #GOutputStream. the buffer containing the data to write. the number of bytes to write whether to do blocking I/O optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore the number of bytes written, or -1 on error. 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. 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. Since: 2.34 a #GOutputStream. the buffer containing the data to write. the number of bytes to write whether to do blocking I/O location to store the number of bytes that was written to the stream optional #GCancellable object, %NULL to ignore. location to store the error occurring, or %NULL to ignore %TRUE on success, %FALSE if there was an error Gets a reference to the default #GPowerProfileMonitor for the system. Since: 2.70 a new reference to the default #GPowerProfileMonitor Gets whether the system is in “Power Saver” mode. You are expected to listen to the #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has changed. Since: 2.70 a #GPowerProfileMonitor Whether the system is in “Power Saver” mode. Creates a #GAction corresponding to the value of property @property_name on @object. The property must be existent and readable and writable (and not construct-only). This function takes a reference on @object and doesn't release it until the action is destroyed. Since: 2.38 the name of the action to create the object that has the property to wrap the name of the property a new #GPropertyAction 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. Since: 2.26 a #GProxyAddress the @proxy's destination hostname 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.26 a #GProxyAddress the @proxy's destination port Gets the protocol that is being spoken to the destination server; eg, "http" or "ftp". Since: 2.34 a #GProxyAddress the @proxy's destination protocol Gets @proxy's password. Since: 2.26 a #GProxyAddress the @proxy's password Gets @proxy's protocol. eg, "socks" or "http" Since: 2.26 a #GProxyAddress the @proxy's protocol Gets the proxy URI that @proxy was constructed from. Since: 2.34 a #GProxyAddress the @proxy's URI, or %NULL if unknown Gets @proxy's username. Since: 2.26 a #GProxyAddress the @proxy's username Creates a new #GProxyAddress for @inetaddr with @protocol that should tunnel through @dest_hostname and @dest_port. (Note that this method doesn't set the #GProxyAddress:uri or #GProxyAddress:destination-protocol fields; use g_object_new() directly if you want to set those.) Since: 2.26 The proxy server #GInetAddress. The proxy server port. The proxy protocol to support, in lower case (e.g. socks, http). The destination hostname the proxy should tunnel to. The destination port to tunnel to. The username to authenticate to the proxy server (or %NULL). The password to authenticate to the proxy server (or %NULL). a new #GProxyAddress Given @connection to communicate with a proxy (eg, a #GSocketConnection that is connected to the proxy server), this does the necessary handshake to connect to @proxy_address, and if required, wraps the #GIOStream to handle proxy payload. Since: 2.26 a #GProxy a #GIOStream a #GProxyAddress a #GCancellable return #GError a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. Asynchronous version of g_proxy_connect(). Since: 2.26 a #GProxy a #GIOStream a #GProxyAddress a #GCancellable a #GAsyncReadyCallback callback data See g_proxy_connect(). Since: 2.26 a #GProxy a #GAsyncResult return #GError a #GIOStream. Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. Since: 2.26 the proxy protocol name (e.g. http, socks, etc) return a #GProxy or NULL if protocol is not supported. Gets the default #GProxyResolver for the system. Since: 2.26 the default #GProxyResolver, which will be a dummy object if no proxy resolver is available 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.) Since: 2.26 a #GProxyResolver %TRUE if @resolver is supported. Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or `direct://`, where <protocol> could be http, rtsp, socks or other proxying protocol. 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. Since: 2.26 a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL return location for a #GError, or %NULL A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more details. Since: 2.26 a #GProxyResolver a URI representing the destination to connect to a #GCancellable, or %NULL callback to call after resolution completes data for @callback 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. Since: 2.26 a #GProxyResolver the result passed to your #GAsyncReadyCallback return location for a #GError, or %NULL A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). 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.26 a #GProxy %TRUE if hostname resolution is supported. Activates the remote 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. @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 a #GDBusActionGroup the name of the action to activate the optional parameter to the activation 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. @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 a #GRemoteActionGroup the name of the action to change the state of the new requested value for the state the platform data to send Gets the #GResolver Error Quark. Since: 2.22 a #GQuark. 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.) Since: 2.22 a #GList of #GInetAddress 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.22 a #GList of #GSrvTarget 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.22 the default #GResolver. Synchronously reverse-resolves @address to determine its associated hostname. If the DNS resolution fails, @error (if non-%NULL) will be set to a value from #GResolverError. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. Since: 2.22 a #GResolver the address to reverse-resolve a #GCancellable, or %NULL return location for a #GError, or %NULL a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. 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.22 a #GResolver the address to reverse-resolve a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_by_address_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. Since: 2.22 a #GResolver the result passed to your #GAsyncReadyCallback return location for a #GError, or %NULL a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. 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. Since: 2.22 a #GResolver the hostname to look up a #GCancellable, or %NULL return location for a #GError, or %NULL 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.) 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.22 a #GResolver the hostname to look up the address of a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a call to g_resolver_lookup_by_name_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. Since: 2.22 a #GResolver the result passed to your #GAsyncReadyCallback return location for a #GError, or %NULL a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. This differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with @flags. For example this can be used to limit results with %G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. Since: 2.60 a #GResolver the hostname to look up extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL return location for a #GError, or %NULL 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.) Begins asynchronously resolving @hostname to determine its associated IP address(es), and eventually calls @callback, which must call g_resolver_lookup_by_name_with_flags_finish() to get the result. See g_resolver_lookup_by_name() for more details. Since: 2.60 a #GResolver the hostname to look up the address of extra #GResolverNameLookupFlags for the lookup a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. Since: 2.60 a #GResolver the result passed to your #GAsyncReadyCallback return location for a #GError, or %NULL a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. 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 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. Since: 2.34 a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL return location for a #GError, or %NULL 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.) 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 a #GResolver the DNS name to look up the record for the type of DNS record to look up a #GCancellable, or %NULL callback to call after resolution completes data for @callback 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. 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. Since: 2.34 a #GResolver the result passed to your #GAsyncReadyCallback return location for a #GError, or %NULL 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.) 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. If @cancellable is non-%NULL, it can be used to cancel the operation, in which case @error (if non-%NULL) will be set to %G_IO_ERROR_CANCELLED. If you are planning to connect to the service, it is usually easier to create a #GNetworkService and use its #GSocketConnectable interface. Since: 2.22 a #GResolver the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in a #GCancellable, or %NULL return location for a #GError, or %NULL 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.) 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. Since: 2.22 a #GResolver the service type to look up (eg, "ldap") the networking protocol to use for @service (eg, "tcp") the DNS domain to look up the service in a #GCancellable, or %NULL callback to call after resolution completes data for @callback Retrieves the result of a previous call to g_resolver_lookup_service_async(). If the DNS resolution failed, @error (if non-%NULL) will be set to a value from #GResolverError. If the operation was cancelled, @error will be set to %G_IO_ERROR_CANCELLED. Since: 2.22 a #GResolver the result passed to your #GAsyncReadyCallback return location for a #GError, or %NULL a non-empty #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. Sets @resolver to be the application's default resolver (reffing @resolver, and unreffing the previous default resolver, if any). Future calls to g_resolver_get_default() will return this resolver. This can be used if an application wants to perform any sort of DNS caching or "pinning"; it can implement its own #GResolver that calls the original default resolver for DNS operations, and implements its own cache policies on top of that, and then set itself as the default resolver for all later code to use. Since: 2.22 the new default #GResolver 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(). If @path is invalid or does not exist in the #GResource, %G_RESOURCE_ERROR_NOT_FOUND will be returned. @lookup_flags controls the behaviour of the lookup. Since: 2.32 A #GResource A pathname inside the resource A #GResourceLookupFlags return location for a #GError, or %NULL an array of constant strings Gets the #GResource Error Quark. Since: 2.32 a #GQuark Looks for a file at the specified @path in the resource and if found returns information about it. @lookup_flags controls the behaviour of the lookup. Since: 2.32 A #GResource A pathname inside the resource A #GResourceLookupFlags a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the flags about the file, or %NULL if the length is not needed return location for a #GError, or %NULL %TRUE if the file was found. %FALSE if there were errors Loads a binary resource bundle and creates a #GResource representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need to register it with g_resources_register(). If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or there is an error in reading it, an error from g_mapped_file_new() will be returned. Since: 2.32 the path of a filename to load, in the GLib filename encoding return location for a #GError, or %NULL a new #GResource, or %NULL on error Looks for a file at the specified @path in the resource and returns a #GBytes that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the GBytes. For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some readonly data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data. @lookup_flags controls the behaviour of the lookup. Since: 2.32 A #GResource A pathname inside the resource A #GResourceLookupFlags return location for a #GError, or %NULL #GBytes or %NULL on error. Free the returned object with g_bytes_unref() 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. If you want to use this resource in the global resource namespace you need to register it with g_resources_register(). 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 @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. Since: 2.32 A #GBytes return location for a #GError, or %NULL a new #GResource, or %NULL on error Looks for a file at the specified @path in the resource and returns a #GInputStream that lets you read the data. @lookup_flags controls the behaviour of the lookup. Since: 2.32 A #GResource A pathname inside the resource A #GResourceLookupFlags return location for a #GError, or %NULL #GInputStream or %NULL on error. Free the returned object with g_object_unref() Atomically increments the reference count of @resource by one. This function is MT-safe and may be called from any thread. Since: 2.32 A #GResource The passed in #GResource 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. Since: 2.32 A #GResource 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(). @lookup_flags controls the behaviour of the lookup. Since: 2.32 A pathname inside the resource A #GResourceLookupFlags return location for a #GError, or %NULL an array of constant strings Looks for a file at the specified @path in the set of globally registered resources and if found returns information about it. @lookup_flags controls the behaviour of the lookup. Since: 2.32 A pathname inside the resource A #GResourceLookupFlags a location to place the length of the contents of the file, or %NULL if the length is not needed a location to place the #GResourceFlags about the file, or %NULL if the flags are not needed return location for a #GError, or %NULL %TRUE if the file was found. %FALSE if there were errors 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. 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. Since: 2.32 A pathname inside the resource A #GResourceLookupFlags return location for a #GError, or %NULL #GBytes or %NULL on error. Free the returned object with g_bytes_unref() 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. @lookup_flags controls the behaviour of the lookup. Since: 2.32 A pathname inside the resource A #GResourceLookupFlags return location for a #GError, or %NULL #GInputStream or %NULL on error. Free the returned object with g_object_unref() 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.32 A #GResource Unregisters the resource from the process-global set of resources. Since: 2.32 A #GResource Tests if the stream supports the #GSeekableIface. a #GSeekable. %TRUE if @seekable can be seeked. %FALSE otherwise. Tests if the length of the stream can be adjusted with g_seekable_truncate(). a #GSeekable. %TRUE if the stream can be truncated, %FALSE otherwise. Seeks in the stream by the given @offset, modified by @type. Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail. Any operation that would result in a negative offset will fail. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. a #GSeekable. a #goffset. a #GSeekType. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. Tells the current position within the stream. a #GSeekable. the (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable. 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 previously 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. a #GSeekable. new length for @seekable, in bytes. optional #GCancellable object, %NULL to ignore. a #GError location to store the error occurring, or %NULL to ignore. %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. 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. a #GSettings instance Signals that a single key has possibly changed. Backend implementations should call this if a key has possibly changed its value. @key must be a valid key (ie starting with a slash, not containing '//', and not ending with a slash). The implementation must call this function during any call to g_settings_backend_write(), before the call returns (except in the case that no keys are actually changed and it cares to detect this fact). It may not rely on the existence of a mainloop for dispatching the signal later. The implementation may call this function at any other time it likes in response to other events (such as changes occurring outside of the program). These calls may originate from a mainloop or may originate in response to any other action (including from calls to g_settings_backend_write()). In the case that this call is in response to a call to g_settings_backend_write() then @origin_tag must be set to the same value that was passed to that call. Since: 2.26 a #GSettingsBackend implementation the name of the key the origin tag 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 a #GSettingsBackend implementation a #GTree containing the changes the origin tag 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. You must free the value returned in @path, @keys and @values using g_free(). You should not attempt to free or unref the contents of @keys or @values. Since: 2.26 a #GTree containing the changes the location to save the path the location to save the relative keys the location to save the values, or %NULL 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. The user gets a reference to the backend. Since: 2.28 the default #GSettingsBackend, which will be a dummy (memory) settings backend if no other settings backend is available. 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. Since: 2.26 a #GSettingsBackend implementation the path containing the changes the %NULL-terminated list of changed keys the origin tag Signals that all keys below a given path may have possibly changed. Backend implementations should call this if an entire path of keys have possibly changed their values. @path must be a valid path (ie starting and ending with a slash and not containing '//'). The meaning of this signal is that any of the key which has a name starting with @path may have changed. The same rules for when notifications must occur apply as per g_settings_backend_changed(). This call might be an appropriate reasponse to a 'reset' call but implementations are also free to explicitly list the keys that were affected by that call if they can easily do so. For efficiency reasons, the implementation should strive for @path to be as long as possible (ie: the longest common prefix of all of the keys that were changed) but this is not strictly required. As an example, if this function is called with the path of "/" then every single key in the application will be notified of a possible change. Since: 2.26 a #GSettingsBackend implementation the path containing the changes the origin tag Signals that the writability of all keys below a given path may have changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. Since: 2.26 a #GSettingsBackend implementation the name of the path Signals that the writability of a single key has possibly changed. Since GSettings performs no locking operations for itself, this call will always be made in response to external events. Since: 2.26 a #GSettingsBackend implementation the name of the key Create a binding between the @key in the @settings object and the property @property of @object. The binding uses the default GIO mapping functions to map between the settings and property values. These functions handle booleans, numeric types and string types in a straightforward way. Use g_settings_bind_with_mapping() if you need a custom mapping, or map between types that are not supported by the default mapping functions. 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 a #GSettings object the key to bind a #GObject the name of the property to bind flags for the binding Create a binding between the @key in the @settings object and the property @property of @object. The binding uses the provided mapping functions to map between settings and property values. 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 a #GSettings object the key to bind a #GObject the name of the property to bind flags for the binding a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping data that gets passed to @get_mapping and @set_mapping #GDestroyNotify function for @user_data Create a binding between the writability of @key in the @settings object and the property @property of @object. The property must be boolean; "sensitive" or "visible" properties of widgets are the most likely candidates. Writable bindings are always uni-directional; changes of the writability of the setting will be propagated to the object property, not the other way. When the @inverted argument is %TRUE, the binding inverts the value as it passes from the setting to the object, i.e. @property will be set to %TRUE if the key is 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 a #GSettings object the key to bind a #GObject the name of a boolean property to bind whether to 'invert' the value Creates a #GAction corresponding to a given #GSettings key. The action has the same name as the key. 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). Since: 2.32 a #GSettings the name of a key in @settings a new #GAction 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. Since: 2.26 a #GSettings object Gets the value that is stored at @key in @settings. A convenience function that combines g_settings_get_value() with g_variant_get(). 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 a #GSettings object the key to get the value for a #GVariant format string arguments as per @format Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for booleans. It is a programmer error to give a @key that isn't specified as having a boolean type in the schema for @settings. Since: 2.26 a #GSettings object the key to get the value for a boolean Creates a child settings object which has a base path of `base-path/@name`, where `base-path` is the base path of @settings. The schema for the child settings object must have been declared in the schema of @settings using a `<child>` element. The created child settings object will inherit the #GSettings:delay-apply mode from @settings. Since: 2.26 a #GSettings object the name of the child schema a 'child' settings object Gets the "default value" of a key. This is the value that would be read if g_settings_reset() were to be called on the key. Note that this may be a different value than returned by g_settings_schema_key_get_default_value() if the system administrator has provided a default value. Comparing the return values of g_settings_get_default_value() and g_settings_get_value() is not sufficient for determining if a value has been set because the user may have explicitly set the value to something that happens to be equal to the default. The difference here is that if the default changes in the future, the user's key will still be set. This function may be useful for adding an indication to a UI of what the default value was before the user set it. It is a programmer error to give a @key that isn't contained in the schema for @settings. Since: 2.40 a #GSettings object the key to get the default value for the default value Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for doubles. It is a programmer error to give a @key that isn't specified as having a 'double' type in the schema for @settings. Since: 2.26 a #GSettings object the key to get the value for a double Gets the value that is stored in @settings for @key and converts it to the enum value that it represents. In order to use this function the type of the value must be a string and it must be marked in the schema file as an enumerated type. It is a programmer error to give a @key that isn't contained in the schema for @settings or is not marked as an enumerated type. If the value stored in the configuration database is not a valid value for the enumerated type then this function will return the default value. Since: 2.26 a #GSettings object the key to get the value for the enum value Gets the value that is stored in @settings for @key and converts it to the flags value that it represents. In order to use this function the type of the value must be an array of strings and it must be marked in the schema file as a flags type. It is a programmer error to give a @key that isn't contained in the schema for @settings or is not marked as a flags type. If the value stored in the configuration database is not a valid value for the flags type then this function will return the default value. Since: 2.26 a #GSettings object the key to get the value for the flags value Returns whether the #GSettings object has any unapplied changes. This can only be the case if it is in 'delayed-apply' mode. Since: 2.26 a #GSettings object %TRUE if @settings has unapplied changes Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() 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. Since: 2.26 a #GSettings object the key to get the value for an integer Gets the value that is stored at @key in @settings. 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. Since: 2.50 a #GSettings object the key to get the value for a 64-bit integer Gets the value that is stored at @key in @settings, subject to application-level validation/mapping. You should use this function when the application needs to perform some processing on the value of the key (for example, parsing). The @mapping function performs that processing. If the function indicates that the processing was unsuccessful (due to a parse error, for example) then the mapping is tried again with another value. This allows a robust 'fall back to defaults' behaviour to be implemented somewhat automatically. The first value that is tried is the user's setting for the key. If the mapping function fails to map this value, other values may be tried in an unspecified order (system or site defaults, translated schema default values, untranslated schema default values, etc). If the mapping function fails for all possible values, one additional attempt is made: the mapping function is called with a %NULL value. If the mapping function still indicates failure at this point then the application will be aborted. The result parameter for the @mapping function is pointed to a #gpointer which is initially set to %NULL. The same pointer is given to each invocation of @mapping. The final value of that #gpointer is what is returned by this function. %NULL is valid; it is returned just as any other value would be. a #GSettings object the key to get the value for the function to map the value in the settings database to the value used by the application user data for @mapping the result, which may be %NULL Queries the range of a key. Since: 2.28 Deprecated:2.40:Use g_settings_schema_key_get_range() instead. a #GSettings the key to query the range of Gets the value that is stored at @key in @settings. A convenience variant of g_settings_get() for strings. It is a programmer error to give a @key that isn't specified as having a string type in the schema for @settings. Since: 2.26 a #GSettings object the key to get the value for a newly-allocated string A convenience variant of g_settings_get() for string arrays. It is a programmer error to give a @key that isn't specified as having an array of strings type in the schema for @settings. Since: 2.26 a #GSettings object the key to get the value for a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. Gets the value that is stored at @key in @settings. 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. Since: 2.30 a #GSettings object the key to get the value for an unsigned integer Gets the value that is stored at @key in @settings. 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. Since: 2.50 a #GSettings object the key to get the value for a 64-bit unsigned integer Checks the "user value" of a key, if there is one. The user value of a key is the last value that was set by the user. After calling g_settings_reset() this function should always return %NULL (assuming something is not wrong with the system configuration). It is possible that g_settings_get_value() will return a different value than this function. This can happen in the case that the user set a value for a key that was subsequently locked down by the system administrator -- this function will return the user's old value. This function may be useful for adding a "reset" option to a UI or for providing indication that a particular value has been changed. It is a programmer error to give a @key that isn't contained in the schema for @settings. Since: 2.40 a #GSettings object the key to get the user value for the user's value, if set Gets the value that is stored in @settings for @key. It is a programmer error to give a @key that isn't contained in the schema for @settings. Since: 2.26 a #GSettings object the key to get the value for a new #GVariant Finds out if a key can be written or not Since: 2.26 a #GSettings object the name of a key %TRUE if the key @name is writable 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(). There is little reason to call 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. a #GSettings object a list of the children on @settings, in no defined order Introspects the list of keys on @settings. You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons. You should free the return value with g_strfreev() when you are done with it. Deprecated: 2.46: Use g_settings_schema_list_keys() instead. a #GSettings object a list of the keys on @settings, in no defined order Deprecated. Since: 2.28 Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead a list of relocatable #GSettings schemas that are available, in no defined order. The list must not be modified or freed. Deprecated. 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. a list of #GSettings schemas that are available, in no defined order. The list must not be modified or freed. Creates a new #GSettings object with the schema specified by @schema_id. It is an error for the schema to not exist: schemas are an essential part of a program, as they provide type information. If schemas need to be dynamically loaded (for example, from an optional runtime dependency), g_settings_schema_source_lookup() can be used to test for their existence before loading them. 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(). Since: 2.26 the id of the schema a new #GSettings object Creates a new #GSettings object with a given schema, backend and path. 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. Since: 2.32 a #GSettingsSchema a #GSettingsBackend the path to use a new #GSettings object Creates a new #GSettings object with the schema specified by @schema_id and a given #GSettingsBackend. 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. Since: 2.26 the id of the schema the #GSettingsBackend to use a new #GSettings object 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(). Since: 2.26 the id of the schema the #GSettingsBackend to use the path to use a new #GSettings object Creates a new #GSettings object with the relocatable schema specified by @schema_id and a given path. You only need to do this if you want to directly create a settings object with a schema that doesn't have a specified path of its own. That's quite rare. It is a programmer error to call this function for a schema that has an explicitly specified path. It is a programmer error if @path is not a valid path. A valid path begins and ends with '/' and does not contain two consecutive '/' characters. Since: 2.26 the id of the schema the path to use a new #GSettings object Checks if the given @value is of the correct type and within the permitted range for @key. Since: 2.28 Deprecated:2.40:Use g_settings_schema_key_range_check() instead. a #GSettings the key to check the value to check %TRUE if @value is valid for @key Resets @key to its default value. This call resets the key, as much as possible, to its default value. That might be the value specified in the schema or the one set by the administrator. a #GSettings object the name of a key 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. Change notifications will be emitted for affected keys. a #GSettings instance Get the ID of @schema. a #GSettingsSchema the ID Gets the key named @name from @schema. It is a programmer error to request a key that does not exist. See g_settings_schema_list_keys(). Since: 2.40 a #GSettingsSchema the name of a key the #GSettingsSchemaKey for @name 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. Relocatable schemas can be referenced by other schemas and can therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return %NULL. Since: 2.32 a #GSettingsSchema the path of the schema, or %NULL Checks if @schema has a key named @name. Since: 2.40 a #GSettingsSchema the name of a key %TRUE if such a key exists Gets the default value for @key. Note that this is the default value according to the schema. System administrator defaults and lockdown are not visible via this API. Since: 2.40 a #GSettingsSchemaKey the default value for the key Gets the description for @key. If no description has been provided in the schema for @key, returns %NULL. The description can be one sentence to several paragraphs in length. Paragraphs are delimited with a double newline. Descriptions can be translated and the value returned from this function is is the current locale. This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. Since: 2.34 a #GSettingsSchemaKey the description for @key, or %NULL Gets the name of @key. Since: 2.44 a #GSettingsSchemaKey the name of @key. Queries the range of a key. This function will return a #GVariant that fully describes the range of values that are valid for @key. The type of #GVariant returned is `(sv)`. The string describes the type of range restriction in effect. The type and meaning of the value contained in the variant depends on the string. If the string is `'type'` then the variant contains an empty array. The element type of that empty array is the expected type of value and all values of that type are valid. If the string is `'enum'` then the variant contains an array enumerating the possible values. Each item in the array is a possible valid value and no other values are valid. If the string is `'flags'` then the variant contains an array. Each item in the array is a value that may appear zero or one times in an array to be used as the value for this key. For example, if the variant contained the array `['x', 'y']` then the valid values for the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and `['y', 'x']`. Finally, if the string is `'range'` then the variant contains a pair of like-typed values -- the minimum and maximum permissible values for this key. This information should not be used by normal programs. It is considered to be a hint for introspection purposes. Normal programs should already know what is permitted by their own schema. The format may change in any way in the future -- but particularly, new forms may be added to the possibilities described above. You should free the returned value with g_variant_unref() when it is no longer needed. Since: 2.40 a #GSettingsSchemaKey a #GVariant describing the range 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. Since: 2.34 a #GSettingsSchemaKey the summary for @key, or %NULL Gets the #GVariantType of @key. Since: 2.40 a #GSettingsSchemaKey the type of @key Checks if the given @value is within the permitted range for @key. It is a programmer error if @value is not of the correct type — you must check for this first. Since: 2.40 a #GSettingsSchemaKey the value to check %TRUE if @value is valid for @key Increase the reference count of @key, returning a new reference. Since: 2.40 a #GSettingsSchemaKey a new reference to @key Decrease the reference count of @key, possibly freeing it. Since: 2.40 a #GSettingsSchemaKey Gets the list of children in @schema. You should free the return value with g_strfreev() when you are done with it. Since: 2.44 a #GSettingsSchema a list of the children on @settings, in no defined order Introspects the list of keys on @schema. 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. Since: 2.46 a #GSettingsSchema a list of the keys on @schema, in no defined order Increase the reference count of @schema, returning a new reference. Since: 2.32 a #GSettingsSchema a new reference to @schema 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. 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. Since: 2.32 the default schema source Lists the schemas in a given source. If @recursive is %TRUE then include parent sources. If %FALSE then only include the schemas from one source (ie: one directory). You probably want %TRUE. Non-relocatable schemas are those for which you can call g_settings_new(). Relocatable schemas are those for which you must use g_settings_new_with_path(). Do not call this function from normal programs. This is designed for use by database editors, commandline tools, etc. Since: 2.40 a #GSettingsSchemaSource if we should recurse the list of non-relocatable schemas, in no defined order the list of relocatable schemas, in no defined order Looks up a schema with the identifier @schema_id in @source. This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas. If the schema isn't found directly in @source and @recursive is %TRUE then the parent sources will also be checked. If the schema isn't found, %NULL is returned. Since: 2.32 a #GSettingsSchemaSource a schema ID %TRUE if the lookup should be recursive a new #GSettingsSchema 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. In either case, an empty file or some types of corruption in the file will result in %G_FILE_ERROR_INVAL being returned. If @parent is non-%NULL then there are two effects. First, if g_settings_schema_source_lookup() is called with the @recursive flag set to %TRUE and the schema can not be found in the source, the lookup will recurse to the parent. Second, any references to other schemas specified within this source (ie: `child` or `extends`) references may be resolved from the @parent. For this second reason, except in very unusual situations, the @parent should probably be given as the default schema source, as returned by g_settings_schema_source_get_default(). Since: 2.32 the filename of a directory a #GSettingsSchemaSource, or %NULL %TRUE, if the directory is trusted a pointer to a #GError pointer set to %NULL, or %NULL Increase the reference count of @source, returning a new reference. Since: 2.32 a #GSettingsSchemaSource a new reference to @source Decrease the reference count of @source, possibly freeing it. Since: 2.32 a #GSettingsSchemaSource Decrease the reference count of @schema, possibly freeing it. Since: 2.32 a #GSettingsSchema Sets @key in @settings to @value. A convenience function that combines g_settings_set_value() with g_variant_new(). 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 a #GSettings object the name of the key to set a #GVariant format string arguments as per @format %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. A convenience variant of g_settings_set() for booleans. It is a programmer error to give a @key that isn't specified as having a boolean type in the schema for @settings. Since: 2.26 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. A convenience variant of g_settings_set() for doubles. It is a programmer error to give a @key that isn't specified as having a 'double' type in the schema for @settings. Since: 2.26 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable Looks up the enumerated type nick for @value and writes it to @key, within @settings. It is a programmer error to give a @key that isn't contained in the schema for @settings or is not marked as an enumerated type, or for @value not to be a valid value for the named type. After performing the write, accessing @key directly with g_settings_get_string() will return the 'nick' associated with @value. a #GSettings object a key, within @settings an enumerated value %TRUE, if the set succeeds 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. 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. a #GSettings object a key, within @settings a flags value %TRUE, if the set succeeds Sets @key in @settings to @value. 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. Since: 2.26 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. 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. Since: 2.50 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. A convenience variant of g_settings_set() for strings. It is a programmer error to give a @key that isn't specified as having a string type in the schema for @settings. Since: 2.26 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. 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. Since: 2.26 a #GSettings object the name of the key to set the value to set it to, or %NULL %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. A convenience variant of g_settings_set() for 32-bit unsigned integers. It is a programmer error to give a @key that isn't specified as having a uint32 type in the schema for @settings. Since: 2.30 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable 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. Since: 2.50 a #GSettings object the name of the key to set the value to set it to %TRUE if setting the key succeeded, %FALSE if the key was not writable Sets @key in @settings to @value. It is a programmer error to give a @key that isn't contained in the schema for @settings or for @value to have the incorrect type, per the schema. If @value is floating then this function consumes the reference. Since: 2.26 a #GSettings object the name of the key to set a #GVariant of the correct type %TRUE if setting the key succeeded, %FALSE if the key was not writable Ensures that all pending operations are complete for the default backend. 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). Removes an existing binding for @property on @object. Note that bindings are automatically removed when the object is finalized, so it is rarely necessary to call this function. Since: 2.26 the object the property whose binding is removed A convenience function for creating multiple #GSimpleAction instances and adding them to the action group. Since: 2.30 Deprecated: 2.38: Use g_action_map_add_action_entries() a #GSimpleActionGroup a pointer to the first item in an array of #GActionEntry structs the length of @entries, or -1 the user data for signal connections Adds an action to the action group. If the action group already contains an action with the same name as @action then the old action is dropped from the group. The action group takes its own reference on @action. Since: 2.28 Deprecated: 2.38: Use g_action_map_add_action() a #GSimpleActionGroup a #GAction Looks up the action with the name @action_name in the group. If no such action exists, returns %NULL. Since: 2.28 Deprecated: 2.38: Use g_action_map_lookup_action() a #GSimpleActionGroup the name of an action a #GAction, or %NULL Creates a new, empty, #GSimpleActionGroup. Since: 2.28 a new #GSimpleActionGroup Removes the named action from the action group. If no action of this name is in the group then nothing happens. Since: 2.28 Deprecated: 2.38: Use g_action_map_remove_action() a #GSimpleActionGroup the name of the action Creates a new action. The created action is stateless. See g_simple_action_new_stateful() to create an action that has state. Since: 2.28 the name of the action the type of parameter that will be passed to handlers for the #GSimpleAction::activate signal, or %NULL for no parameter a new #GSimpleAction Creates a new stateful action. All future state values must have the same #GVariantType as the initial @state. If the @state #GVariant is floating, it is consumed. Since: 2.28 the name of the action the type of the parameter that will be passed to handlers for the #GSimpleAction::activate signal, or %NULL for no parameter the initial state of the action a new #GSimpleAction Sets the action as enabled or not. An action must be enabled in order to be activated or in order to have its state changed from outside callers. 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.28 a #GSimpleAction whether the action is enabled 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. If the @value GVariant is floating, it is consumed. Since: 2.30 a #GSimpleAction the new #GVariant for the state Sets the state hint for the action. See g_action_get_state_hint() for more information about action state hints. Since: 2.44 a #GSimpleAction a #GVariant representing the state hint Reports an error in an asynchronous function in an idle function by directly setting the contents of the #GAsyncResult with the given error information. Deprecated: 2.46: Use g_task_report_error(). a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. a #GQuark containing the error domain (usually %G_IO_ERROR). a specific error code. a formatted error reporting string. a list of variables to fill in @format. 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. Deprecated: 2.46: Use g_task_report_error(). a #GObject, or %NULL a #GAsyncReadyCallback. user data passed to @callback. the #GError to report Reports an error in an idle function. Similar to g_simple_async_report_gerror_in_idle(), but takes over the caller's ownership of @error, so the caller does not have to free it any more. Since: 2.28 Deprecated: 2.46: Use g_task_report_error(). a #GObject, or %NULL a #GAsyncReadyCallback. user data passed to @callback. the #GError to report 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(). Calling this function takes a reference to @simple for as long as is needed to complete the call. Deprecated: 2.46: Use #GTask instead. a #GSimpleAsyncResult. Completes an asynchronous function in an idle handler in the [thread-default main context][g-main-context-push-thread-default] of the thread that @simple was initially created in (and re-pushes that context around the invocation of the callback). Calling this function takes a reference to @simple for as long as is needed to complete the call. Deprecated: 2.46: Use #GTask instead. a #GSimpleAsyncResult. Gets the operation result boolean from within the asynchronous result. Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead. a #GSimpleAsyncResult. %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE. Gets a pointer result as returned by the asynchronous function. Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead. a #GSimpleAsyncResult. a pointer from the result. Gets a gssize from the asynchronous result. Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead. a #GSimpleAsyncResult. a gssize returned from the asynchronous function. Gets the source tag for the #GSimpleAsyncResult. Deprecated: 2.46. Use #GTask and g_task_get_source_tag() instead. a #GSimpleAsyncResult. a #gpointer to the source object for the #GSimpleAsyncResult. Ensures that the data passed to the _finish function of an async operation is consistent. Three checks are performed. First, @result is checked to ensure that it is really a #GSimpleAsyncResult. Second, @source is checked to ensure that it matches the source object of @result. Third, @source_tag is checked to ensure that it is equal to the @source_tag argument given to g_simple_async_result_new() (which, by convention, is a pointer to the _async function corresponding to the _finish function from which this function is called). (Alternatively, if either @source_tag or @result's source tag is %NULL, then the source tag check is skipped.) Since: 2.20 Deprecated: 2.46: Use #GTask and g_task_is_valid() instead. the #GAsyncResult passed to the _finish function. the #GObject passed to the _finish function. the asynchronous function. #TRUE if all checks passed or #FALSE if any failed. Creates a #GSimpleAsyncResult. 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 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. Deprecated: 2.46: Use g_task_new() instead. a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. the asynchronous function. a #GSimpleAsyncResult. Creates a new #GSimpleAsyncResult with a set error. Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead. a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. a #GQuark. an error code. a string with format characters. a list of values to insert into @format. a #GSimpleAsyncResult. Creates a #GSimpleAsyncResult from an error condition. Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. a #GObject, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. a #GError a #GSimpleAsyncResult. Creates a #GSimpleAsyncResult from an error condition, and takes over the caller's ownership of @error, so the caller does not need to free it anymore. Since: 2.28 Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. a #GObject, or %NULL a #GAsyncReadyCallback user data passed to @callback a #GError a #GSimpleAsyncResult Propagates an error from within the simple asynchronous result to a given destination. 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. Deprecated: 2.46: Use #GTask instead. a #GSimpleAsyncResult. a location to propagate the error to. %TRUE if the error was propagated to @dest. %FALSE otherwise. 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. 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. a #GSimpleAsyncResult. a #GSimpleAsyncThreadFunc. the io priority of the request. optional #GCancellable object, %NULL to ignore. 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). 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. a #GSimpleAsyncResult a #GCancellable to check, or %NULL to unset Sets an error within the asynchronous result without a #GError. Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead. a #GSimpleAsyncResult. a #GQuark (usually %G_IO_ERROR). an error code. a formatted error reporting string. a list of variables to fill in @format. Sets an error within the asynchronous result without a #GError. Unless writing a binding, see g_simple_async_result_set_error(). Deprecated: 2.46: Use #GTask and g_task_return_error() instead. a #GSimpleAsyncResult. a #GQuark (usually %G_IO_ERROR). an error code. a formatted error reporting string. va_list of arguments. Sets the result from a #GError. Deprecated: 2.46: Use #GTask and g_task_return_error() instead. a #GSimpleAsyncResult. #GError. Sets whether to handle cancellation within the asynchronous operation. 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(). Deprecated: 2.46 a #GSimpleAsyncResult. a #gboolean. Sets the operation result to a boolean within the asynchronous result. Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead. a #GSimpleAsyncResult. a #gboolean. Sets the operation result within the asynchronous result to a pointer. Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead. a #GSimpleAsyncResult. a pointer result from an asynchronous function. a #GDestroyNotify function. Sets the operation result within the asynchronous result to the given @op_res. Deprecated: 2.46: Use #GTask and g_task_return_int() instead. a #GSimpleAsyncResult. a #gssize. 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. Since: 2.28 Deprecated: 2.46: Use #GTask and g_task_return_error() instead. a #GSimpleAsyncResult a #GError Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. See also #GIOStream. Since: 2.44 a #GInputStream. a #GOutputStream. a new #GSimpleIOStream instance. Creates a new #GPermission instance that represents an action that is either always or never allowed. Since: 2.26 %TRUE if the action is allowed the #GSimplePermission, as a #GPermission Creates a new #GSimpleProxyResolver. See #GSimpleProxyResolver:default-proxy and #GSimpleProxyResolver:ignore-hosts for more details on how the arguments are interpreted. Since: 2.36 the default proxy to use, eg "socks://192.168.1.1" an optional list of hosts/IP addresses to not use a proxy for. (transfer full) a new #GSimpleProxyResolver Sets the default proxy on @resolver, to be used for any URIs that don't match #GSimpleProxyResolver:ignore-hosts or a proxy set via g_simple_proxy_resolver_set_uri_proxy(). If @default_proxy starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. Since: 2.36 a #GSimpleProxyResolver the default proxy to use Sets the list of ignored hosts. See #GSimpleProxyResolver:ignore-hosts for more details on how the @ignore_hosts argument is interpreted. Since: 2.36 a #GSimpleProxyResolver %NULL-terminated list of hosts/IP addresses to not use a proxy for Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme matches @uri_scheme (and which don't match #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy. As with #GSimpleProxyResolver:default-proxy, if @proxy starts with "socks://", #GSimpleProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types. Since: 2.36 a #GSimpleProxyResolver the URI scheme to add a proxy for the proxy to use for @uri_scheme Accept incoming connections on a connection-based socket. This removes the first outstanding connection request from the listening socket and creates a #GSocket object for it. The @socket must be bound to a local address with g_socket_bind() and must be listening for incoming connections (g_socket_listen()). If there are no outstanding connections then the operation will block or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the %G_IO_IN condition. Since: 2.22 a #GSocket. a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. a new #GSocket, or %NULL on error. Free the returned object with g_object_unref(). Retrieves the next #GSocketAddress from @enumerator. Note that this may block for some amount of time. (Eg, a #GNetworkAddress may need to do a DNS lookup before it can return an address.) Use g_socket_address_enumerator_next_async() if you need to avoid blocking. If @enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to g_socket_address_enumerator_next() will return an appropriate error in *@error. However, if the first call to g_socket_address_enumerator_next() succeeds, then any further internal errors (other than @cancellable being triggered) will be ignored. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. a #GError. a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses. Asynchronously retrieves the next #GSocketAddress from @enumerator and then calls @callback, which must call g_socket_address_enumerator_next_finish() to get the result. It is an error to call this multiple times before the previous callback has finished. a #GSocketAddressEnumerator optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function 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. a #GSocketAddressEnumerator a #GAsyncResult a #GError a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses. Gets the socket family type of @address. Since: 2.22 a #GSocketAddress the socket family type of @address Gets the size of @address's native struct sockaddr. You can use this to allocate memory to pass to g_socket_address_to_native(). Since: 2.22 a #GSocketAddress the size of the native struct sockaddr that @address represents Creates a #GSocketAddress subclass corresponding to the native struct sockaddr @native. Since: 2.22 a pointer to a struct sockaddr the size of the memory location pointed to by @native a new #GSocketAddress if @native could successfully be converted, otherwise %NULL Converts a #GSocketAddress to a native struct sockaddr, which can be passed to low-level functions like connect() or bind(). If not enough space is available, a %G_IO_ERROR_NO_SPACE error is returned. If the address type is not known on the system then a %G_IO_ERROR_NOT_SUPPORTED error is returned. Since: 2.22 a #GSocketAddress a pointer to a memory location that will contain the native struct sockaddr the size of @dest. Must be at least as large as g_socket_address_get_native_size() #GError for error reporting, or %NULL to ignore %TRUE if @dest was filled in, %FALSE on error 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 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.) Since: 2.22 a #GSocket. a #GSocketAddress specifying the local address. whether to allow reusing this address #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. 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. Since: 2.22 a #GSocket #GError for error reporting, or %NULL to ignore. %TRUE if no error, %FALSE otherwise, setting @error to the error Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the #GProxyResolver, #GSocketClient will consider this protocol as supported but will not try to find a #GProxy instance to handle handshaking. The application must check for this case by calling g_socket_connection_get_remote_address() on the returned #GSocketConnection, and seeing if it's a #GProxyAddress of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself. This 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. a #GSocketClient The proxy protocol 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. 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. Since: 2.22 a #GSocketClient. a #GSocketConnectable specifying the remote address. optional #GCancellable object, %NULL to ignore. #GError for error reporting, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. This is the asynchronous version of g_socket_client_connect(). You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements [RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs" recommendations to work around long connection timeouts in networks where IPv6 is broken by performing an IPv4 connection simultaneously without waiting for IPv6 to time out, which is not supported by the synchronous call. (This is not an API guarantee, and may change in the future.) 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. Since: 2.22 a #GSocketClient a #GSocketConnectable specifying the remote address. a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_async() Since: 2.22 a #GSocketClient. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. 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. In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly. Since: 2.22 a #GSocketClient the name and optionally port of the host to connect to the default port to connect to a #GCancellable, or %NULL a pointer to a #GError, or %NULL a #GSocketConnection on success, %NULL on error. This is the asynchronous version of g_socket_client_connect_to_host(). 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. Since: 2.22 a #GSocketClient the name and optionally the port of the host to connect to the default port to connect to a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_to_host_async() Since: 2.22 a #GSocketClient. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. 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. 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. a #GSocketConnection a domain name the name of the service to connect to a #GCancellable, or %NULL a pointer to a #GError, or %NULL a #GSocketConnection if successful, or %NULL on error This is the asynchronous version of g_socket_client_connect_to_service(). Since: 2.22 a #GSocketClient a domain name the name of the service to connect to a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_to_service_async() Since: 2.22 a #GSocketClient. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. This is a helper function for g_socket_client_connect(). Attempts to create a TCP connection with a network URI. @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.) 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. 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. Since: 2.26 a #GSocketClient A network URI the default port to connect to a #GCancellable, or %NULL a pointer to a #GError, or %NULL a #GSocketConnection on success, %NULL on error. This is the asynchronous version of g_socket_client_connect_to_uri(). 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 a #GSocketClient a network uri the default port to connect to a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async connect operation. See g_socket_client_connect_to_uri_async() Since: 2.26 a #GSocketClient. a #GAsyncResult. a #GError location to store the error occurring, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. Gets the proxy enable state; see g_socket_client_set_enable_proxy() Since: 2.26 a #GSocketClient. whether proxying is enabled Gets the socket family of the socket client. See g_socket_client_set_family() for details. Since: 2.22 a #GSocketClient. a #GSocketFamily Gets the local address of the socket client. See g_socket_client_set_local_address() for details. Since: 2.22 a #GSocketClient. a #GSocketAddress or %NULL. Do not free. Gets the protocol name type of the socket client. See g_socket_client_set_protocol() for details. Since: 2.22 a #GSocketClient a #GSocketProtocol 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.36 a #GSocketClient. The #GProxyResolver being used by @client. Gets the socket type of the socket client. See g_socket_client_set_socket_type() for details. Since: 2.22 a #GSocketClient. a #GSocketFamily Gets the I/O timeout time for sockets created by @client. See g_socket_client_set_timeout() for details. Since: 2.26 a #GSocketClient the timeout in seconds Gets whether @client creates TLS connections. See g_socket_client_set_tls() for details. Since: 2.28 a #GSocketClient. whether @client uses TLS Gets the TLS validation flags used creating TLS connections via @client. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information. Since: 2.28 Deprecated: 2.72: Do not attempt to ignore validation errors. a #GSocketClient. the TLS validation flags Creates a new #GSocketClient with the default options. Since: 2.22 a #GSocketClient. Free the returned object with g_object_unref(). 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(). Since: 2.26 a #GSocketClient. whether to enable proxies 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. 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. Since: 2.22 a #GSocketClient. a #GSocketFamily 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. 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. Since: 2.22 a #GSocketClient. a #GSocketAddress, or %NULL Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default protocol for the socket family and type. Since: 2.22 a #GSocketClient. a #GSocketProtocol Overrides the #GProxyResolver used by @client. You can call this if you want to use specific proxies, rather than using the system default proxy settings. Note that whether or not the proxy resolver is actually used depends on the setting of #GSocketClient:enable-proxy, which is not changed by this function (but which is %TRUE by default) Since: 2.36 a #GSocketClient. a #GProxyResolver, or %NULL for the default. Sets the socket type of the socket client. The sockets created by this object will be of the specified type. It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, as GSocketClient is used for connection oriented services. Since: 2.22 a #GSocketClient. a #GSocketType Sets the I/O timeout for sockets created by @client. @timeout is a time in seconds, or 0 for no timeout (the default). 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. Since: 2.26 a #GSocketClient. the timeout 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. 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. Since: 2.28 a #GSocketClient. whether to use TLS Sets the TLS validation flags used when creating TLS connections via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information. Since: 2.28 Deprecated: 2.72: Do not attempt to ignore validation errors. a #GSocketClient. the validation flags Closes the socket, shutting down any active connection. Closing a socket does not wait for all outstanding I/O operations to finish, so the caller should not rely on them to be guaranteed to complete even if the close returns with no error. Once the socket is closed, all other operations will return %G_IO_ERROR_CLOSED. Closing a socket multiple times will not return an error. Sockets will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible. Beware that due to the way that TCP works, it is possible for recently-sent data to be lost if either you close a socket while the %G_IO_IN condition is set, or else if the remote connection tries to send something to you after you close the socket but before it has finished reading all of the data you sent. There is no easy generic way to avoid this problem; the easiest fix is to design the network protocol such that the client will never send data "out of turn". Another solution is for the server to half-close the connection by calling g_socket_shutdown() with only the @shutdown_write flag set, and then wait for the client to notice this and close its side of the connection, after which the server can safely call g_socket_close(). (This is what #GTcpConnection does if you call g_tcp_connection_set_graceful_disconnect(). But of course, this only works if the client will close its connection after the server does.) Since: 2.22 a #GSocket #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error Checks on the readiness of @socket to perform operations. The operations specified in @condition are checked for and masked against the currently-satisfied conditions on @socket. The result is returned. Note that on Windows, it is possible for an operation to return %G_IO_ERROR_WOULD_BLOCK even immediately after g_socket_condition_check() has claimed that the socket is ready for writing. Rather than calling g_socket_condition_check() and then writing to the socket if it succeeds, it is generally better to simply try writing to the socket right away, and try again later if the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; these conditions will always be set in the output if they are true. This call never blocks. Since: 2.22 a #GSocket a #GIOCondition mask to check the @GIOCondition mask of the current state Waits for up to @timeout_us 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_us (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_us.) Note that although @timeout_us is in microseconds for consistency with other GLib APIs, this function actually only has millisecond resolution, and the behavior is undefined if @timeout_us is not an exact number of milliseconds. Since: 2.32 a #GSocket a #GIOCondition mask to wait for the maximum time (in microseconds) to wait, or -1 a #GCancellable, or %NULL a #GError pointer, or %NULL %TRUE if the condition was met, %FALSE otherwise 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(). Since: 2.22 a #GSocket a #GIOCondition mask to wait for a #GCancellable, or %NULL a #GError pointer, or %NULL %TRUE if the condition was met, %FALSE otherwise 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. 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(). Since: 2.22 a #GSocket. a #GSocketAddress specifying the remote address. a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. %TRUE if connected, %FALSE on error. Creates a #GSocketAddressEnumerator for @connectable. Since: 2.22 a #GSocketConnectable a new #GSocketAddressEnumerator. Creates a #GSocketAddressEnumerator for @connectable that will return a #GProxyAddress for each of its 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(). Since: 2.26 a #GSocketConnectable a new #GSocketAddressEnumerator. 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. If the #GSocketConnectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback. Since: 2.48 a #GSocketConnectable the formatted string Connect @connection to the specified remote address. Since: 2.32 a #GSocketConnection a #GSocketAddress specifying the remote address. a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. %TRUE if the connection succeeded, %FALSE on error Asynchronously connect @connection to the specified remote address. This clears the #GSocket:blocking flag on @connection's underlying socket if it is currently set. Use g_socket_connection_connect_finish() to retrieve the result. Since: 2.32 a #GSocketConnection a #GSocketAddress specifying the remote address. a %GCancellable or %NULL a #GAsyncReadyCallback user data for the callback Gets the result of a g_socket_connection_connect_async() call. Since: 2.32 a #GSocketConnection the #GAsyncResult #GError for error reporting, or %NULL to ignore. %TRUE if the connection succeeded, %FALSE on error Creates a #GSocketConnection subclass of the right type for @socket. Since: 2.22 a #GSocket a #GSocketConnection Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol_id. If no type is registered, the #GSocketConnection base type is returned. Since: 2.22 a #GSocketFamily a #GSocketType a protocol id a #GType Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol. If no type is registered, the #GSocketConnection base type is returned. Since: 2.22 a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION a #GSocketFamily a #GSocketType a protocol id Try to get the local address of a socket connection. Since: 2.22 a #GSocketConnection #GError for error reporting, or %NULL to ignore. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). Try to get the remote address of a socket connection. 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)...". Since: 2.22 a #GSocketConnection #GError for error reporting, or %NULL to ignore. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). 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. Since: 2.22 a #GSocketConnection a #GSocket or %NULL on error. Checks if @connection is connected. This is equivalent to calling g_socket_is_connected() on @connection's underlying #GSocket. Since: 2.32 a #GSocketConnection whether @connection is connected 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. If there is no implementation for this kind of control message, %NULL will be returned. Since: 2.22 a socket level a socket control message type for the given @level the size of the data in bytes pointer to the message data the deserialized message or %NULL Returns the "level" (i.e. the originating protocol) of the control message. This is often SOL_SOCKET. Since: 2.22 a #GSocketControlMessage an integer describing the level Returns the protocol specific type of the control message. For instance, for UNIX fd passing this would be SCM_RIGHTS. Since: 2.22 a #GSocketControlMessage an integer describing the type of control message Returns the space required for the control message, not including headers or alignment. Since: 2.22 a #GSocketControlMessage The number of bytes required. 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. Since: 2.22 a #GSocketControlMessage A buffer to write data to Creates a #GSource that can be attached to a %GMainContext to monitor for the availability of the specified @condition on the socket. The #GSource keeps a reference to the @socket. The callback on the source is of the #GSocketSourceFunc type. It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these conditions will always be reported output if they are true. @cancellable if not %NULL can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled(). If @socket has a timeout set, and it is reached before @condition occurs, the source will then trigger anyway, reporting %G_IO_IN or %G_IO_OUT depending on @condition. However, @socket will have been marked as having had a timeout, and so the next #GSocket I/O method you call will then fail with a %G_IO_ERROR_TIMED_OUT. Since: 2.22 a #GSocket a #GIOCondition mask to monitor a %GCancellable or %NULL a newly allocated %GSource, free with g_source_unref(). Get the amount of data pending in the OS input buffer, without blocking. 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. Since: 2.32 a #GSocket the number of bytes that can be read from the socket without blocking or truncating, or -1 on error. Gets the blocking mode of the socket. For details on blocking I/O, see g_socket_set_blocking(). Since: 2.22 a #GSocket. %TRUE if blocking I/O is used, %FALSE otherwise. Gets the broadcast setting on @socket; if %TRUE, it is possible to send packets to broadcast addresses. Since: 2.32 a #GSocket. the broadcast setting on @socket Returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX sockets). If this operation isn't supported on the OS, the method fails with the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented by reading the %SO_PEERCRED option on the underlying socket. This method can be expected to be available on the following platforms: - Linux since GLib 2.26 - OpenBSD since GLib 2.30 - Solaris, Illumos and OpenSolaris since GLib 2.40 - NetBSD since GLib 2.42 - macOS, tvOS, iOS since GLib 2.66 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. Since: 2.26 a #GSocket. #GError for error reporting, or %NULL to ignore. %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref(). Gets the socket family of the socket. Since: 2.22 a #GSocket. a #GSocketFamily 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.22 a #GSocket. the file descriptor of the socket. Gets the keepalive mode of the socket. For details on this, see g_socket_set_keepalive(). Since: 2.22 a #GSocket. %TRUE if keepalive is active, %FALSE otherwise. Gets the listen backlog setting of the socket. For details on this, see g_socket_set_listen_backlog(). Since: 2.22 a #GSocket. the maximum number of pending connections. 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. Since: 2.22 a #GSocket. #GError for error reporting, or %NULL to ignore. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). 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. Since: 2.32 a #GSocket. the multicast loopback setting on @socket Gets the multicast time-to-live setting on @socket; see g_socket_set_multicast_ttl() for more details. Since: 2.32 a #GSocket. the multicast time-to-live setting on @socket Gets the value of an integer-valued option on @socket, as with getsockopt(). (If you need to fetch a non-integer-valued option, you will need to call getsockopt() directly.) The [<gio/gnetworking.h>][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. Note that even for socket options that are a single byte in size, @value is still a pointer to a #gint variable, not a #guchar; g_socket_get_option() will handle the conversion internally. Since: 2.36 a #GSocket the "API level" of the option (eg, `SOL_SOCKET`) the "name" of the option (eg, `SO_BROADCAST`) return location for the option value #GError for error reporting, or %NULL to ignore. 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. Gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned. Since: 2.22 a #GSocket. a protocol id, or -1 if unknown Try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected. Since: 2.22 a #GSocket. #GError for error reporting, or %NULL to ignore. a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). Gets the socket type of the socket. Since: 2.22 a #GSocket. a #GSocketType Gets the timeout setting of the socket. For details on this, see g_socket_set_timeout(). Since: 2.26 a #GSocket. the timeout in seconds Gets the unicast time-to-live setting on @socket; see g_socket_set_ttl() for more details. Since: 2.32 a #GSocket. the time-to-live setting on @socket Checks whether a socket is closed. Since: 2.22 a #GSocket %TRUE if socket is closed, %FALSE otherwise Check whether the socket is connected. This is only useful for connection-oriented sockets. 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.22 a #GSocket. %TRUE if socket is connected, %FALSE otherwise. 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. 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. Since: 2.32 a #GSocket. a #GInetAddress specifying the group address to join. Name of the interface to use, or %NULL %TRUE if source-specific multicast should be used #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. 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. 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. 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. Since: 2.56 a #GSocket. a #GInetAddress specifying the group address to join. a #GInetAddress specifying the source-specific multicast address or %NULL to ignore. Name of the interface to use, or %NULL #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. 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). @socket remains bound to its address and port, and can still receive unicast messages after calling this. To unbind to a given source-specific multicast address, use g_socket_leave_multicast_group_ssm() instead. Since: 2.32 a #GSocket. a #GInetAddress specifying the group address to leave. Interface used %TRUE if source-specific multicast was used #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. 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). @socket remains bound to its address and port, and can still receive unicast messages after calling this. Since: 2.56 a #GSocket. a #GInetAddress specifying the group address to leave. a #GInetAddress specifying the source-specific multicast address or %NULL to ignore. Name of the interface to use, or %NULL #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using g_socket_accept(). 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(). Since: 2.22 a #GSocket. #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. 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. 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. Since: 2.22 a #GSocketListener location where #GObject pointer will be stored, or %NULL optional #GCancellable object, %NULL to ignore. #GError for error reporting, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. 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_finish() to get the result of the operation. Since: 2.22 a #GSocketListener a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async accept operation. See g_socket_listener_accept_async() Since: 2.22 a #GSocketListener a #GAsyncResult. Optional #GObject identifying this source a #GError location to store the error occurring, or %NULL to ignore. a #GSocketConnection on success, %NULL on error. 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. 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. Since: 2.22 a #GSocketListener location where #GObject pointer will be stored, or %NULL. optional #GCancellable object, %NULL to ignore. #GError for error reporting, or %NULL to ignore. a #GSocket on success, %NULL on error. 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. Since: 2.22 a #GSocketListener a #GCancellable, or %NULL a #GAsyncReadyCallback user data for the callback Finishes an async accept operation. See g_socket_listener_accept_socket_async() Since: 2.22 a #GSocketListener a #GAsyncResult. Optional #GObject identifying this source a #GError location to store the error occurring, or %NULL to ignore. a #GSocket on success, %NULL on error. 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. 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(). @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 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. Call g_socket_listener_close() to stop listening on @address; this will not be done automatically when you drop your final reference to @listener, as references may be held internally. Since: 2.22 a #GSocketListener a #GSocketAddress a #GSocketType a #GSocketProtocol Optional #GObject identifying this source location to store the address that was bound to, or %NULL. #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. Listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available). This is useful if you need to have a socket for incoming connections but don't care about the specific port number. @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. Since: 2.24 a #GSocketListener Optional #GObject identifying this source a #GError location to store the error occurring, or %NULL to ignore. the port number, or 0 in case of failure. Helper function for g_socket_listener_add_address() that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces. @source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. Call g_socket_listener_close() to stop listening on @port; this will not be done automatically when you drop your final reference to @listener, as references may be held internally. Since: 2.22 a #GSocketListener an IP port number (non-zero) Optional #GObject identifying this source #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. Adds @socket to the set of sockets that we try to accept new clients from. The socket must be bound to a local address and listened to. @source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to. 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. Since: 2.22 a #GSocketListener a listening #GSocket Optional #GObject identifying this source #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error. Closes all the sockets in the listener. Since: 2.22 a #GSocketListener 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(). Since: 2.22 a new #GSocketListener. Sets the listen backlog on the sockets in the listener. This must be called before adding any sockets, addresses or ports to the #GSocketListener (for example, by calling g_socket_listener_add_inet_port()) to be effective. See g_socket_set_listen_backlog() for details Since: 2.22 a #GSocketListener an integer 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. Since: 2.22 the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. the socket type to use. the id of the protocol to use, or 0 for default. #GError for error reporting, or %NULL to ignore. a #GSocket or %NULL on error. Free the returned object with g_object_unref(). 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. 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 Since: 2.22 a native socket file descriptor. #GError for error reporting, or %NULL to ignore. a #GSocket or %NULL on error. Free the returned object with g_object_unref(). 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. On error -1 is returned and @error is set accordingly. Since: 2.22 a #GSocket a buffer to read data into (which should be at least @size bytes long). the number of bytes you want to read from the socket a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error Receive data (up to @size bytes) from a socket. 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. See g_socket_receive() for additional information. Since: 2.22 a #GSocket a pointer to a #GSocketAddress pointer, or %NULL a buffer to read data into (which should be at least @size bytes long). the number of bytes you want to read from the socket a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error 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. On error -1 is returned and @error is set accordingly. Since: 2.22 a #GSocket a pointer to a #GSocketAddress pointer, or %NULL an array of #GInputVector structs the number of elements in @vectors, or -1 a pointer which may be filled with an array of #GSocketControlMessages, or %NULL a pointer which will be filled with the number of elements in @messages, or %NULL a pointer to an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL a #GError pointer, or %NULL Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error 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. 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. Since: 2.48 a #GSocket an array of #GInputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags for the overall operation, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore 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. 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. Since: 2.26 a #GSocket a buffer to read data into (which should be at least @size bytes long). the number of bytes you want to read from the socket whether to do blocking or non-blocking I/O a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error 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. 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. Since: 2.22 a #GSocket the buffer containing the data to send. the number of bytes to send a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes written (which may be less than @size), or -1 on error 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(). If @address is %NULL then the message is sent to the default receiver (set by g_socket_connect()). @vectors must point to an array of #GOutputVector structs and @num_vectors must be the length of this array. (If @num_vectors is -1, then @vectors is assumed to be terminated by a #GOutputVector with a %NULL buffer pointer.) The #GOutputVector structs describe the buffers that the sent data will be gathered from. Using multiple #GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to g_socket_send(). @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.) The sum of the sizes of each #GOutputVector in vectors must not be greater than %G_MAXSSIZE. If the message can be larger than this, then it is mandatory to use the g_socket_send_message_with_timeout() function. On error -1 is returned and @error is set accordingly. Since: 2.22 a #GSocket a #GSocketAddress, or %NULL an array of #GOutputVector structs the number of elements in @vectors, or -1 a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @messages, or -1. an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes written (which may be less than @size), or -1 on error This behaves exactly the same as g_socket_send_message(), except that the choice of timeout behavior is determined by the @timeout_us argument rather than by @socket's properties. On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is returned. @bytes_written will contain 0 in both cases. Since: 2.60 a #GSocket a #GSocketAddress, or %NULL an array of #GOutputVector structs the number of elements in @vectors, or -1 a pointer to an array of #GSocketControlMessages, or %NULL. number of elements in @messages, or -1. an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) the maximum time (in microseconds) to wait, or -1 location to store the number of bytes that were written to the socket a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. %G_POLLABLE_RETURN_OK if all data was successfully written, %G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or %G_POLLABLE_RETURN_FAILED if an error happened and @error is set. Send multiple data messages from @socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_send(), g_socket_send_to(), and g_socket_send_message(). @messages must point to an array of #GOutputMessage structs and @num_messages must be the length of this array. Each #GOutputMessage contains an address to send the data to, and a pointer to an array of #GOutputVector structs to describe the buffers that the data to be sent for each message will be gathered from. Using multiple #GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to g_socket_send(). Sending multiple messages in one go avoids the overhead of making a lot of syscalls in scenarios where a lot of data packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), or where the same data needs to be sent to multiple recipients. @flags modify how the message is sent. The commonly available arguments for this are available in the #GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. If the socket is in blocking mode the call will block until there is space for all the data in the socket queue. If there is no space available and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error will be returned if no data was written at all, otherwise the number of messages sent will be returned. To be notified when space is available, wait for the %G_IO_OUT condition. Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) On error -1 is returned and @error is set accordingly. 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: 2.44 a #GSocket an array of #GOutputMessage structs the number of elements in @messages an int containing #GSocketMsgFlags flags, which may additionally contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. 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. 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()). See g_socket_send() for additional information. Since: 2.22 a #GSocket a #GSocketAddress, or %NULL the buffer containing the data to send. the number of bytes to send a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes written (which may be less than @size), or -1 on error 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. Since: 2.26 a #GSocket the buffer containing the data to send. the number of bytes to send whether to do blocking or non-blocking I/O a %GCancellable or %NULL #GError for error reporting, or %NULL to ignore. Number of bytes written (which may be less than @size), or -1 on error 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. Since: 2.22 a #GSocketService %TRUE if the service is active, %FALSE otherwise 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(). 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.22 a new #GSocketService. 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 call is thread-safe, so it may be called from a thread handling an incoming client request. Since: 2.22 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.) 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 a #GSocketService 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. 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 a #GSocket. Whether to use blocking I/O or not. Sets whether @socket should allow sending to broadcast addresses. This is %FALSE by default. Since: 2.32 a #GSocket. whether @socket should allow sending to broadcast addresses 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. 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 a #GSocket. Value for the keepalive flag Sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them on time then the new connections will be refused. Note that this must be called before g_socket_listen() and has no effect if called after that. Since: 2.22 a #GSocket. the maximum number of pending connections. 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.32 a #GSocket. whether @socket should receive messages sent to its multicast groups from the local host 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.32 a #GSocket. the time-to-live value for all multicast datagrams on @socket Sets the value of an integer-valued option on @socket, as with setsockopt(). (If you need to set a non-integer-valued option, you will need to call setsockopt() directly.) The [<gio/gnetworking.h>][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers. Since: 2.36 a #GSocket the "API level" of the option (eg, `SOL_SOCKET`) the "name" of the option (eg, `SO_BROADCAST`) the value to set the option to #GError for error reporting, or %NULL to ignore. 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. Sets the time in seconds after which I/O operations on @socket will time out if they have not yet completed. 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. On a non-blocking socket, calls to g_socket_condition_wait() will also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources created with g_socket_create_source() will trigger after @timeout seconds of inactivity, with the requested condition set, at which point calling g_socket_receive(), g_socket_send(), g_socket_check_connect_result(), etc, will fail with %G_IO_ERROR_TIMED_OUT. If @timeout is 0 (the default), operations will never time out on their own. Note that if an I/O operation is interrupted by a signal, this may cause the timeout to be reset. Since: 2.26 a #GSocket. the timeout for @socket, in seconds, or 0 for none Sets the time-to-live for outgoing unicast packets on @socket. By default the platform-specific default value is used. Since: 2.32 a #GSocket. the time-to-live value for all unicast packets on @socket 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. If @shutdown_write is %TRUE then the sending side of the connection is shut down, and further writing is disallowed. It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. One example where 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. Since: 2.22 a #GSocket whether to shut down the read side whether to shut down the write side #GError for error reporting, or %NULL to ignore. %TRUE on success, %FALSE on error Checks if a socket is capable of speaking IPv4. IPv4 sockets are capable of speaking IPv4. On some operating systems and under some combinations of circumstances IPv6 sockets are also capable of speaking IPv4. See RFC 3493 section 3.7 for more information. No other types of sockets are currently considered as being capable of speaking IPv4. Since: 2.22 a #GSocket %TRUE if this socket can be used with IPv4. Copies @target Since: 2.22 a #GSrvTarget a copy of @target Frees @target Since: 2.22 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.) Since: 2.22 a #GSrvTarget @target's hostname Gets @target's port Since: 2.22 a #GSrvTarget @target's port Gets @target's priority. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782. Since: 2.22 a #GSrvTarget @target's priority Gets @target's weight. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782. Since: 2.22 a #GSrvTarget @target's weight Sorts @targets in place according to the algorithm in RFC 2782. Since: 2.22 a #GList of #GSrvTarget the head of the sorted list. Creates a new #GSrvTarget with the given parameters. You should not need to use this; normally #GSrvTargets are created by #GResolver. Since: 2.22 the host that the service is running on the port that the service is running on the target's priority the target's weight a new #GSrvTarget. Finalized a GResource initialized by g_static_resource_init(). This is normally used by code generated by [glib-compile-resources][glib-compile-resources] and is not typically used by other code. Since: 2.32 pointer to a static #GStaticResource Gets the GResource that was registered by a call to g_static_resource_init(). This is normally used by code generated by [glib-compile-resources][glib-compile-resources] and is not typically used by other code. Since: 2.32 pointer to a static #GStaticResource a #GResource Initializes a GResource from static data using a GStaticResource. This is normally used by code generated by [glib-compile-resources][glib-compile-resources] and is not typically used by other code. Since: 2.32 pointer to a static #GStaticResource Communicate with the subprocess until it terminates, and all input and output has been completed. If @stdin_buf is given, the subprocess must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the stdin of the subprocess and the pipe is closed (ie: EOF). At the same time (as not to cause blocking when dealing with large amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those streams. The data that was read is returned in @stdout and/or the @stderr. If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, @stdout_buf will contain the data read from stdout. Otherwise, for subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, @stdout_buf will be set to %NULL. Similar provisions apply to @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. As usual, any output variable may be given as %NULL to ignore it. If you desire the stdout and stderr data to be interleaved, create the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned in @stdout_buf and @stderr_buf will be set to %NULL. In case of any error (including cancellation), %FALSE will be returned with @error set. Some or all of the stdin data may have been written. Any stdout or stderr data that has been read will be discarded. None of the out variables (aside from @error) will have been set to anything in particular and should not be inspected. In the case that %TRUE is returned, the subprocess has exited and the exit status inspection APIs (eg: g_subprocess_get_if_exited(), g_subprocess_get_exit_status()) may be used. You should not attempt to use any of the subprocess pipes after starting this function, since they may be left in strange states, even if the operation was cancelled. You should especially not attempt to interact with the pipes while the operation is in progress (either from another thread or if using the asynchronous version). Since: 2.40 a #GSubprocess data to send to the stdin of the subprocess, or %NULL a #GCancellable data read from the subprocess stdout data read from the subprocess stderr a pointer to a %NULL #GError pointer, or %NULL %TRUE if successful Asynchronous version of g_subprocess_communicate(). Complete invocation with g_subprocess_communicate_finish(). Self Input data, or %NULL Cancellable Callback User data Complete an invocation of g_subprocess_communicate_async(). Self Result Return location for stdout data Return location for stderr data Error Like g_subprocess_communicate(), but validates the output of the process as UTF-8, and returns it as a regular NUL terminated string. On error, @stdout_buf and @stderr_buf will be set to undefined values and should not be used. a #GSubprocess data to send to the stdin of the subprocess, or %NULL a #GCancellable data read from the subprocess stdout data read from the subprocess stderr a pointer to a %NULL #GError pointer, or %NULL Asynchronous version of g_subprocess_communicate_utf8(). Complete invocation with g_subprocess_communicate_utf8_finish(). Self Input data, or %NULL Cancellable Callback User data Complete an invocation of g_subprocess_communicate_utf8_async(). Self Result Return location for stdout data Return location for stderr data Error Use an operating-system specific method to attempt an immediate, forceful termination of the process. There is no mechanism to determine whether or not the request itself was successful; however, you can use g_subprocess_wait() to monitor the status of the process after calling this function. On Unix, this function sends %SIGKILL. Since: 2.40 a #GSubprocess Check the exit status of the subprocess, given that it exited normally. This is the value passed to the exit() system call or the return value from main. This is equivalent to the system WEXITSTATUS macro. It is an error to call this function before g_subprocess_wait() and unless g_subprocess_get_if_exited() returned %TRUE. Since: 2.40 a #GSubprocess the exit status On UNIX, returns the process ID as a decimal string. On Windows, returns the result of GetProcessId() also as a string. If the subprocess has terminated, this will return %NULL. Since: 2.40 a #GSubprocess the subprocess identifier, or %NULL if the subprocess has terminated Check if the given subprocess exited normally (ie: by way of exit() or return from main()). This is equivalent to the system WIFEXITED macro. It is an error to call this function before g_subprocess_wait() has returned. Since: 2.40 a #GSubprocess %TRUE if the case of a normal exit Check if the given subprocess terminated in response to a signal. This is equivalent to the system WIFSIGNALED macro. It is an error to call this function before g_subprocess_wait() has returned. Since: 2.40 a #GSubprocess %TRUE if the case of termination due to a signal 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_wait_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. Since: 2.40 a #GSubprocess the (meaningless) waitpid() exit status from the kernel Gets the #GInputStream from which to read the stderr output of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE, otherwise %NULL will be returned. Since: 2.40 a #GSubprocess the stderr pipe Gets the #GOutputStream that you can write to in order to give data to the stdin of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned. Since: 2.40 a #GSubprocess the stdout pipe Gets the #GInputStream from which to read the stdout output of @subprocess. The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, otherwise %NULL will be returned. Since: 2.40 a #GSubprocess the stdout pipe Checks if the process was "successful". A process is considered successful if it exited cleanly with an exit status of 0, either by way of the exit() system call or return from main(). It is an error to call this function before g_subprocess_wait() has returned. Since: 2.40 a #GSubprocess %TRUE if the process exited cleanly with a exit status of 0 Get the signal number that caused the subprocess to terminate, given that it terminated due to a signal. This is equivalent to the system WTERMSIG macro. It is an error to call this function before g_subprocess_wait() and unless g_subprocess_get_if_signaled() returned %TRUE. Since: 2.40 a #GSubprocess the signal causing termination Closes all the file descriptors previously passed to the object with g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc. After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will return %G_IO_ERROR_CLOSED. This method is idempotent if called more than once. This function is called automatically when the #GSubprocessLauncher is disposed, but is provided separately so that garbage collected language bindings can call it earlier to guarantee when FDs are closed. Since: 2.68 a #GSubprocessLauncher Returns the value of the environment variable @variable in the environment of processes launched from this launcher. On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8. Since: 2.40 a #GSubprocessLauncher the environment variable to get the value of the environment variable, %NULL if unset Creates a new #GSubprocessLauncher. The launcher is created with the default options. A copy of the environment of the calling process is made at the time of this call and will be used as the environment that the process is launched in. Since: 2.40 #GSubprocessFlags Sets up a child setup function. The child setup function will be called after fork() but before exec() on the child's side. @destroy_notify will not be automatically called on the child's side of the fork(). It will only be called when the last reference on the #GSubprocessLauncher is dropped or when a new child setup function is given. %NULL can be given as @child_setup to disable the functionality. Child setup functions are only available on UNIX. Since: 2.40 a #GSubprocessLauncher a #GSpawnChildSetupFunc to use as the child setup function user data for @child_setup a #GDestroyNotify for @user_data Sets the current working directory that processes will be launched with. By default processes are launched with the current working directory of the launching process at the time of launch. Since: 2.40 a #GSubprocessLauncher the cwd for launched processes 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. 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 a #GSubprocessLauncher the replacement environment Sets the flags on the launcher. The default flags are %G_SUBPROCESS_FLAGS_NONE. You may not set flags that specify conflicting options for how to handle a particular stdio stream (eg: specifying both %G_SUBPROCESS_FLAGS_STDIN_PIPE and %G_SUBPROCESS_FLAGS_STDIN_INHERIT). You may also not set a flag that conflicts with a previous call to a function like g_subprocess_launcher_set_stdin_file_path() or g_subprocess_launcher_take_stdout_fd(). Since: 2.40 a #GSubprocessLauncher #GSubprocessFlags Sets the file path to use as the stderr for spawned processes. If @path is %NULL then any previously given path is unset. The file will be created or truncated when the process is spawned, as would be the case if using '2>' at the shell. If you want to send both stdout and stderr to the same file then use %G_SUBPROCESS_FLAGS_STDERR_MERGE. You may not set a stderr file path if a stderr fd is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. Since: 2.40 a #GSubprocessLauncher a filename or %NULL Sets the file path to use as the stdin for spawned processes. If @path is %NULL then any previously given path is unset. The file must exist or spawning the process will fail. You may not set a stdin file path if a stdin fd is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. Since: 2.40 a #GSubprocessLauncher (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. You may not set a stdout file path if a stdout fd is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. Since: 2.40 a #GSubprocessLauncher a filename or %NULL Sets the environment variable @variable in the environment of processes launched from this launcher. 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. Since: 2.40 a #GSubprocessLauncher the environment variable to set, must not contain '=' the new value for the variable whether to change the variable if it already exists Creates a #GSubprocess given a provided varargs list of arguments. Since: 2.40 a #GSubprocessLauncher Error Command line arguments Continued arguments, %NULL terminated A new #GSubprocess, or %NULL on error (and @error will be set) Creates a #GSubprocess given a provided array of arguments. Since: 2.40 a #GSubprocessLauncher Command line arguments Error A new #GSubprocess, or %NULL on error (and @error will be set) Transfer an arbitrary file descriptor from parent process to the child. This function takes ownership of the @source_fd; it will be closed in the parent when @self is freed. By default, all file descriptors from the parent will be closed. This function allows you to create (for example) a custom `pipe()` or `socketpair()` before launching the process, and choose the target descriptor in the child. An example use case is GNUPG, which has a command line argument `--passphrase-fd` providing a file descriptor number where it expects the passphrase to be written. a #GSubprocessLauncher File descriptor in parent process Target descriptor for child process Sets the file descriptor to use as the stderr for spawned processes. If @fd is -1 then any previously given fd is unset. Note that the default behaviour is to pass stderr through to the stderr of the parent process. The passed @fd belongs to the #GSubprocessLauncher. It will be automatically closed when the launcher is finalized. The file descriptor will also be closed on the child side when executing the spawned process. You may not set a stderr fd if a stderr file path is already set or if the launcher flags contain any flags directing stderr elsewhere. This feature is only available on UNIX. Since: 2.40 a #GSubprocessLauncher a file descriptor, or -1 Sets the file descriptor to use as the stdin for spawned processes. If @fd is -1 then any previously given fd is unset. Note that if your intention is to have the stdin of the calling process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT is a better way to go about doing that. The passed @fd is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want. You may not set a stdin fd if a stdin file path is already set or if the launcher flags contain any flags directing stdin elsewhere. This feature is only available on UNIX. Since: 2.40 a #GSubprocessLauncher a file descriptor, or -1 Sets the file descriptor to use as the stdout for spawned processes. If @fd is -1 then any previously given fd is unset. Note that the default behaviour is to pass stdout through to the stdout of the parent process. The passed @fd is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want. You may not set a stdout fd if a stdout file path is already set or if the launcher flags contain any flags directing stdout elsewhere. This feature is only available on UNIX. Since: 2.40 a #GSubprocessLauncher a file descriptor, or -1 Removes the environment variable @variable from the environment of processes launched from this launcher. 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 a #GSubprocessLauncher the environment variable to unset, must not contain '=' Create a new process with the given flags and varargs argument list. By default, matching the g_spawn_async() defaults, the child's stdin will be set to the system null device, and stdout/stderr will be inherited from the parent. You can use @flags to control this behavior. The argument list must be terminated with %NULL. Since: 2.40 flags that define the behaviour of the subprocess return location for an error, or %NULL first commandline argument to pass to the subprocess more commandline arguments, followed by %NULL A newly created #GSubprocess, or %NULL on error (and @error will be set) Create a new process with the given flags and argument list. The argument list is expected to be %NULL-terminated. Since: 2.40 commandline arguments for the subprocess flags that define the behaviour of the subprocess return location for an error, or %NULL A newly created #GSubprocess, or %NULL on error (and @error will be set) Sends the UNIX signal @signal_num to the subprocess, if it is still running. This API is race-free. If the subprocess has terminated, it will not be signalled. This API is not available on Windows. Since: 2.40 a #GSubprocess the signal number to send Synchronously wait for the subprocess to terminate. After the process terminates you can query its exit status with functions such as g_subprocess_get_if_exited() and g_subprocess_get_exit_status(). This function does not fail in the case of the subprocess having abnormal termination. See g_subprocess_wait_check() for that. Cancelling @cancellable doesn't kill the subprocess. Call g_subprocess_force_exit() if it is desirable. Since: 2.40 a #GSubprocess a #GCancellable a #GError %TRUE on success, %FALSE if @cancellable was cancelled Wait for the subprocess to terminate. This is the asynchronous version of g_subprocess_wait(). Since: 2.40 a #GSubprocess a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the operation is complete user_data for @callback Combines g_subprocess_wait() with g_spawn_check_wait_status(). Since: 2.40 a #GSubprocess a #GCancellable a #GError %TRUE on success, %FALSE if process exited abnormally, or @cancellable was cancelled Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). This is the asynchronous version of g_subprocess_wait_check(). Since: 2.40 a #GSubprocess a #GCancellable, or %NULL a #GAsyncReadyCallback to call when the operation is complete user_data for @callback Collects the result of a previous call to g_subprocess_wait_check_async(). Since: 2.40 a #GSubprocess the #GAsyncResult passed to your #GAsyncReadyCallback a pointer to a %NULL #GError, or %NULL %TRUE if successful, or %FALSE with @error set Collects the result of a previous call to g_subprocess_wait_async(). Since: 2.40 a #GSubprocess the #GAsyncResult passed to your #GAsyncReadyCallback a pointer to a %NULL #GError, or %NULL %TRUE if successful, or %FALSE with @error set 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`. It will set the @source’s name to the task’s name (as set with g_task_set_name()), if one has been set on the task and the source doesn’t yet have a name. This takes a reference on @task until @source is destroyed. Since: 2.36 a #GTask the source to attach the callback to invoke when @source triggers Gets @task's #GCancellable Since: 2.36 a #GTask @task's #GCancellable Gets @task's check-cancellable flag. See g_task_set_check_cancellable() for more details. Since: 2.36 the #GTask Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after the task’s callback is invoked, and will return %FALSE if called from inside the callback. Since: 2.44 a #GTask. %TRUE if the task has completed, %FALSE otherwise. Gets the #GMainContext that @task will return its result in (that is, the context that was the [thread-default main context][g-main-context-push-thread-default] at the point when @task was created). This will always return a non-%NULL value, even if the task's context is the default #GMainContext. Since: 2.36 a #GTask @task's #GMainContext Gets @task’s name. See g_task_set_name(). Since: 2.60 a #GTask @task’s name, or %NULL Gets @task's priority Since: 2.36 a #GTask @task's priority Gets @task's return-on-cancel flag. See g_task_set_return_on_cancel() for more details. Since: 2.36 the #GTask Gets the source object from @task. Like g_async_result_get_source_object(), but does not ref the object. Since: 2.36 a #GTask @task's source object, or %NULL Gets @task's source tag. See g_task_set_source_tag(). Since: 2.36 a #GTask @task's source tag Gets @task's `task_data`. Since: 2.36 a #GTask @task's `task_data`. Tests if @task resulted in an error. Since: 2.36 a #GTask. %TRUE if the task resulted in an error, %FALSE otherwise. 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. Since: 2.36 A #GAsyncResult the source object expected to be associated with the task %TRUE if @result and @source_object are valid, %FALSE if not Creates a #GTask acting on @source_object, which will eventually be used to invoke @callback in the current [thread-default main context][g-main-context-push-thread-default]. Call this in the "start" method of your asynchronous method, and pass the #GTask around throughout the asynchronous operation. You can use g_task_set_task_data() to attach task-specific data to the object, which you can retrieve later via g_task_get_task_data(). By default, if @cancellable is cancelled, then the return value of the task will always be %G_IO_ERROR_CANCELLED, even if the task had already completed before the cancellation. This allows for simplified handling in cases where cancellation may imply that other objects that the task depends on have been destroyed. If you do not want this behavior, you can use g_task_set_check_cancellable() to change it. Since: 2.36 the #GObject that owns this task, or %NULL. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback. user data passed to @callback. a #GTask. Gets the result of @task as a #gboolean. If the task resulted in an error, or was cancelled, then this will instead return %FALSE and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. Since: 2.36 a #GTask. return location for a #GError the task result, or %FALSE on error Gets the result of @task as an integer (#gssize). If the task resulted in an error, or was cancelled, then this will instead return -1 and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. Since: 2.36 a #GTask. return location for a #GError the task result, or -1 on error Gets the result of @task as a pointer, and transfers ownership of that value to the caller. If the task resulted in an error, or was cancelled, then this will instead return %NULL and set @error. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. Since: 2.36 a #GTask return location for a #GError the task result, or %NULL on error Gets the result of @task as a #GValue, and transfers ownership of that value to the caller. As with g_task_return_value(), this is a generic low-level method; g_task_propagate_pointer() and the like will usually be more useful for C code. If the task resulted in an error, or was cancelled, then this will instead set @error and return %FALSE. Since this method transfers ownership of the return value (or error) to the caller, you may only call it once. Since: 2.64 a #GTask return location for the #GValue return location for a #GError %TRUE if @task succeeded, %FALSE on error. Creates a #GTask and then immediately calls g_task_return_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the finish method wrapper to check if the result there is tagged as having been created by the wrapper method, and deal with it appropriately if so. See also g_task_report_new_error(). Since: 2.36 the #GObject that owns this task, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. an opaque pointer indicating the source of this task error to report Creates a #GTask and then immediately calls g_task_return_new_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the finish method wrapper to check if the result there is tagged as having been created by the wrapper method, and deal with it appropriately if so. See also g_task_report_error(). Since: 2.36 the #GObject that owns this task, or %NULL. a #GAsyncReadyCallback. user data passed to @callback. an opaque pointer indicating the source of this task a #GQuark. an error code. a string with format characters. a list of values to insert into @format. Sets @task's result to @result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Since: 2.36 a #GTask. the #gboolean result of a task function. Sets @task's result to @error (which @task assumes ownership of) and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Note that since the task takes ownership of @error, and since the task may be completed before returning from g_task_return_error(), you cannot assume that @error is still valid after calling this. Call g_error_copy() on the error if you need to keep a local copy as well. See also g_task_return_new_error(). Since: 2.36 a #GTask. the #GError result of a task function. 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.36 a #GTask %TRUE if @task has been cancelled, %FALSE if not Sets @task's result to @result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). Since: 2.36 a #GTask. the integer (#gssize) result of a task function. Sets @task's result to a new #GError created from @domain, @code, @format, and the remaining arguments, and completes the task (see g_task_return_pointer() for more discussion of exactly what this means). See also g_task_return_error(). Since: 2.36 a #GTask. a #GQuark. an error code. a string with format characters. a list of values to insert into @format. Sets @task's result to @result and completes the task. If @result is not %NULL, then @result_destroy will be used to free @result if the caller does not take ownership of it with g_task_propagate_pointer(). "Completes the task" means that for an ordinary asynchronous task it will either invoke the task's callback, or else queue that callback to be invoked in the proper #GMainContext, or in the next iteration of the current #GMainContext. For a task run via g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this method will save @result to be returned to the caller later, but the task will not actually be completed until the #GTaskThreadFunc exits. Note that since the task may be completed before returning from g_task_return_pointer(), you cannot assume that @result is still valid after calling this, unless you are still holding another reference on it. Since: 2.36 a #GTask the pointer result of a task function a #GDestroyNotify function. Sets @task's result to @result (by copying it) and completes the task. If @result is %NULL then a #GValue of type %G_TYPE_POINTER with a value of %NULL will be used for the result. This is a very generic low-level method intended primarily for use by language bindings; for C code, g_task_return_pointer() and the like will normally be much easier to use. Since: 2.64 a #GTask the #GValue result of a task function Runs @task_func in another thread. When @task_func returns, @task's #GAsyncReadyCallback will be invoked in @task's #GMainContext. This takes a ref on @task until the task completes. See #GTaskThreadFunc for more details about how @task_func is handled. 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 (several tens of tasks), but don't want them to all run at once, you should only queue a limited number of them (around ten) at a time. Since: 2.36 a #GTask a #GTaskThreadFunc Runs @task_func in another thread, and waits for it to return or be cancelled. You can use g_task_propagate_pointer(), etc, afterward to get the result of @task_func. See #GTaskThreadFunc for more details about how @task_func is handled. Normally this is used with tasks created with a %NULL `callback`, but note that even if the task does have a callback, it will not be invoked when @task_func returns. #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 a #GTask a #GTaskThreadFunc Sets or clears @task's check-cancellable flag. If this is %TRUE (the default), then g_task_propagate_pointer(), etc, and g_task_had_error() will check the task's #GCancellable first, and if it has been cancelled, then they will consider the task to have returned an "Operation was cancelled" error (%G_IO_ERROR_CANCELLED), regardless of any other error or return value the task may have had. If @check_cancellable is %FALSE, then the #GTask will not check the cancellable itself, and it is up to @task's owner to do this (eg, via g_task_return_error_if_cancelled()). If you are using g_task_set_return_on_cancel() as well, then you must leave check-cancellable set %TRUE. Since: 2.36 the #GTask whether #GTask will check the state of its #GCancellable for you. Sets @task’s name, used in debugging and profiling. The name defaults to %NULL. The task name should describe in a human readable way what the task does. For example, ‘Open file’ or ‘Connect to network host’. It is used to set the name of the #GSource used for idle completion of the task. This function may only be called before the @task is first used in a thread other than the one it was constructed in. It is called automatically by g_task_set_source_tag() if not called already. Since: 2.60 a #GTask a human readable name for the task, or %NULL to unset it Sets @task's priority. If you do not call this, it will default to %G_PRIORITY_DEFAULT. This will affect the priority of #GSources created with g_task_attach_source() and the scheduling of tasks run in threads, and can also be explicitly retrieved later via g_task_get_priority(). Since: 2.36 the #GTask the [priority][io-priority] of the request Sets or clears @task's return-on-cancel flag. This is only meaningful for tasks run via g_task_run_in_thread() or g_task_run_in_thread_sync(). If @return_on_cancel is %TRUE, then cancelling @task's #GCancellable will immediately cause it to return, as though the task's #GTaskThreadFunc had called g_task_return_error_if_cancelled() and then returned. This allows you to create a cancellable wrapper around an uninterruptible function. The #GTaskThreadFunc just needs to be careful that it does not modify any externally-visible state after it has been cancelled. To do that, the thread should call g_task_set_return_on_cancel() again to (atomically) set return-on-cancel %FALSE before making externally-visible changes; if the task gets cancelled before the return-on-cancel flag could be changed, g_task_set_return_on_cancel() will indicate this by returning %FALSE. You can disable and re-enable this flag multiple times if you wish. If the task's #GCancellable is cancelled while return-on-cancel is %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE again will cause the task to be cancelled at that point. If the task's #GCancellable is already cancelled before you call g_task_run_in_thread()/g_task_run_in_thread_sync(), then the #GTaskThreadFunc will still be run (for consistency), but the task will also be completed right away. Since: 2.36 the #GTask whether the task returns automatically when it is cancelled. %TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled. 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. A macro wrapper around this function will automatically set the task’s name to the string form of @source_tag if it’s not already set, for convenience. Since: 2.36 the #GTask an opaque pointer indicating the source of this task Sets @task’s name, used in debugging and profiling. This is a variant of g_task_set_name() that avoids copying @name. Since: 2.76 a #GTask a human readable name for the task. Must be a string literal Sets @task's task data (freeing the existing task data, if any). Since: 2.36 the #GTask task-specific data #GDestroyNotify for @task_data Checks if graceful disconnects are used. See g_tcp_connection_set_graceful_disconnect(). Since: 2.22 a #GTcpConnection %TRUE if graceful disconnect is used on close, %FALSE otherwise 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. 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. Since: 2.22 a #GTcpConnection Whether to do graceful disconnects or not Gets @conn's base #GIOStream a #GTcpWrapperConnection @conn's base #GIOStream Wraps @base_io_stream and @socket together as a #GSocketConnection. Since: 2.28 the #GIOStream to wrap the #GSocket associated with @base_io_stream the new #GSocketConnection. Add a path where dbus-daemon will look up .service files. This can't be called after g_test_dbus_up(). a #GTestDBus path to a directory containing .service files Stop the session bus started by g_test_dbus_up(). This will wait for the singleton returned by g_bus_get() or g_bus_get_sync() to be destroyed. This is done to ensure that the next unit test won't get a leaked singleton from this test. a #GTestDBus Get the address on which dbus-daemon is running. If g_test_dbus_up() has not been called yet, %NULL is returned. This can be used with g_dbus_connection_new_for_address(). a #GTestDBus the address of the bus, or %NULL. Get the flags of the #GTestDBus object. a #GTestDBus the value of #GTestDBus:flags property Create a new #GTestDBus object. a #GTestDBusFlags a new #GTestDBus. Stop the session bus started by g_test_dbus_up(). Unlike g_test_dbus_down(), this won't verify the #GDBusConnection singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit tests wanting to verify behaviour after the session bus has been stopped can use this function but should still call g_test_dbus_down() when done. a #GTestDBus Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test won't use user's session bus. This is useful for unit tests that want to verify behaviour when no session bus is running. It is not necessary to call this if unit test already calls g_test_dbus_up() before acquiring the session bus. Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this call, it is safe for unit tests to start sending messages on the session bus. If this function is called from setup callback of g_test_add(), g_test_dbus_down() must be called in its teardown callback. If this function is called from unit test's main(), then g_test_dbus_down() must be called after g_test_run(). a #GTestDBus Append 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(). a #GThemedIcon name of icon to append to list of icons from within @icon. Gets the names of icons from within @icon. a #GThemedIcon. a list of icon names. Creates a new themed icon for @iconname. a string containing an icon name. a new #GThemedIcon. Creates a new themed icon for @iconnames. an array of strings containing icon names. the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated a new #GThemedIcon 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: |[<!-- language="C" --> 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"); ]| a string containing an icon name a new #GThemedIcon. 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 a #GThemedIcon name of icon to prepend to list of icons from within @icon. Update the actual icon name list, based on the requested names (from construction, or later added with g_themed_icon_prepend_name() and g_themed_icon_append_name()). The order of the list matters, indicating priority: - The first requested icon is first in priority. - If "use-default-fallbacks" is #TRUE, then it is followed by all its fallbacks (starting from top to lower context levels). - Then next requested icons, and optionally their fallbacks, follow. - Finally all the style variants (symbolic or regular, opposite to whatever is the requested style) follow in the same order. An icon is not added twice in the list if it was previously added. For instance, if requested names are: [ "some-icon-symbolic", "some-other-icon" ] and use-default-fallbacks is TRUE, the final name list shall be: [ "some-icon-symbolic", "some-symbolic", "some-other-icon", "some-other", "some", "some-icon", "some-other-icon-symbolic", "some-other-symbolic" ] a #GThemedIcon. a new #GThemedIcon Creates a new #GThreadedSocketService with no listeners. Listeners must be added with one of the #GSocketListener "add" methods. Since: 2.22 the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit a new #GSocketService. Gets the #GType of @backend's #GTlsCertificate implementation. Since: 2.28 the #GTlsBackend the #GType of @backend's #GTlsCertificate implementation. Gets the #GType of @backend's #GTlsClientConnection implementation. Since: 2.28 the #GTlsBackend the #GType of @backend's #GTlsClientConnection implementation. Gets the default #GTlsBackend for the system. Since: 2.28 a #GTlsBackend, which will be a dummy object if no TLS backend is available Gets the default #GTlsDatabase used to verify TLS connections. Since: 2.30 the #GTlsBackend the default database, which should be unreffed when done. Gets the #GType of @backend’s #GDtlsClientConnection implementation. Since: 2.48 the #GTlsBackend the #GType of @backend’s #GDtlsClientConnection implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. Gets the #GType of @backend’s #GDtlsServerConnection implementation. Since: 2.48 the #GTlsBackend the #GType of @backend’s #GDtlsServerConnection implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. Gets the #GType of @backend's #GTlsFileDatabase implementation. Since: 2.30 the #GTlsBackend the #GType of backend's #GTlsFileDatabase implementation. Gets the #GType of @backend's #GTlsServerConnection implementation. Since: 2.28 the #GTlsBackend the #GType of @backend's #GTlsServerConnection implementation. Set the default #GTlsDatabase used to verify TLS connections Any subsequent call to g_tls_backend_get_default_database() will return the database set in this call. Existing databases and connections are not modified. Setting a %NULL default database will reset to using the system default database as if g_tls_backend_set_default_database() had never been called. Since: 2.60 the #GTlsBackend the #GTlsDatabase Checks if DTLS is supported. DTLS support may not be available even if TLS support is available, and vice-versa. Since: 2.48 the #GTlsBackend whether DTLS is supported Checks if TLS is supported; if this returns %FALSE for the default #GTlsBackend, it means no "real" TLS backend is available. Since: 2.28 the #GTlsBackend whether or not TLS is supported Gets the value of #GTlsCertificate:dns-names. Since: 2.70 a #GTlsCertificate A #GPtrArray of #GBytes elements, or %NULL if it's not available. Gets the value of #GTlsCertificate:ip-addresses. Since: 2.70 a #GTlsCertificate A #GPtrArray of #GInetAddress elements, or %NULL if it's not available. Gets the #GTlsCertificate representing @cert's issuer, if known Since: 2.28 a #GTlsCertificate The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. Returns the issuer name from the certificate. Since: 2.70 a #GTlsCertificate The issuer name, or %NULL if it's not available. Returns the time at which the certificate became or will become invalid. Since: 2.70 a #GTlsCertificate The not-valid-after date, or %NULL if it's not available. Returns the time at which the certificate became or will become valid. Since: 2.70 a #GTlsCertificate The not-valid-before date, or %NULL if it's not available. Returns the subject name from the certificate. Since: 2.70 a #GTlsCertificate The subject name, or %NULL if it's not available. 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.34 first certificate to compare second certificate to compare whether the same or not 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.28 file containing PEM-encoded certificates to import #GError for error reporting, or %NULL to ignore. a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it. Creates a #GTlsCertificate from the data in @file. As of 2.72, if the filename ends in `.p12` or `.pfx` the data is loaded by g_tls_certificate_new_from_pkcs12() otherwise it is loaded by g_tls_certificate_new_from_pem(). See those functions for exact details. If @file cannot be read or parsed, the function will return %NULL and set @error. Since: 2.28 file containing a certificate to import #GError for error reporting, or %NULL to ignore the new certificate, or %NULL on error Creates a #GTlsCertificate from the data in @file. If @file cannot be read or parsed, the function will return %NULL and set @error. Any unknown file types will error with %G_IO_ERROR_NOT_SUPPORTED. Currently only `.p12` and `.pfx` files are supported. See g_tls_certificate_new_from_pkcs12() for more details. Since: 2.72 file containing a certificate to import password for PKCS #12 files #GError for error reporting, or %NULL to ignore the new certificate, or %NULL on error 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. 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.28 file containing one or more PEM-encoded certificates to import file containing a PEM-encoded private key to import #GError for error reporting, or %NULL to ignore. the new certificate, or %NULL on error 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.) 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.28 PEM-encoded certificate data the length of @data, or -1 if it's 0-terminated. #GError for error reporting, or %NULL to ignore. the new certificate, or %NULL if @data is invalid Creates a #GTlsCertificate from a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI. An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` Where the token’s layout is: |[ Object 0: URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private Type: Private key (RSA-2048) ID: 01 Object 1: URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert Type: X.509 Certificate (RSA-2048) ID: 01 ]| In this case the certificate and private key would both be detected and used as expected. @pkcs_uri may also just reference an X.509 certificate object and then optionally @private_key_pkcs11_uri allows using a private key exposed under a different URI. Note that the private key is not accessed until usage and may fail or require a PIN later. Since: 2.68 A PKCS \#11 URI A PKCS \#11 URI #GError for error reporting, or %NULL to ignore. the new certificate, or %NULL on error Creates a #GTlsCertificate from the data in @data. It must contain a certificate and matching private key. If extra certificates are included they will be verified as a chain and the #GTlsCertificate:issuer property will be set. All other data will be ignored. You can pass as single password for all of the data which will be used both for the PKCS #12 container as well as encrypted private keys. If decryption fails it will error with %G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD. This constructor requires support in the current #GTlsBackend. If support is missing it will error with %G_IO_ERROR_NOT_SUPPORTED. Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE. Since: 2.72 DER-encoded PKCS #12 format certificate data the length of @data optional password for encrypted certificate data #GError for error reporting, or %NULL to ignore. the new certificate, or %NULL if @data is invalid 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 @cert is valid, %G_TLS_CERTIFICATE_NO_FLAGS is returned. 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. 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. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Because TLS session context is not used, #GTlsCertificate may not perform as many checks on the certificates as #GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. Since: 2.28 a #GTlsCertificate the expected peer identity the certificate of a trusted authority the appropriate #GTlsCertificateFlags Gets the TLS channel binding error quark. Since: 2.66 a #GQuark. Possibly copies session state from one connection to another, for use in TLS session resumption. 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, since TLS 1.3, it should have been used to read data at least once. @conn should not have completed a handshake. It is not possible to know whether a call to this function will actually do anything. Because session resumption is normally used only for performance benefit, the TLS backend might not implement this function. Even if implemented, it may not actually succeed in allowing @conn to resume @source's TLS session, because the server may not have sent a session resumption token to @source, or it may refuse to accept the token from @conn. There is no way to know whether a call to this function is actually successful. Using this function is not required to benefit from session resumption. If the TLS backend supports session resumption, the session will be resumed automatically if it is possible to do so without weakening the privacy guarantees normally provided by TLS, without need to call this function. For example, with TLS 1.3, a session ticket will be automatically copied from any #GTlsClientConnection that has previously received session tickets from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations. Since: 2.46 a #GTlsClientConnection a #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. Each item in the list is a #GByteArray which contains the complete subject DN of the certificate authority. Since: 2.28 the #GTlsClientConnection 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(). Gets @conn's expected server identity Since: 2.28 the #GTlsClientConnection a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. Since: 2.28 Deprecated: 2.56: SSL 3.0 is insecure. the #GTlsClientConnection %FALSE Gets @conn's validation flags This function does not work as originally designed and is impossible to use correctly. See #GTlsClientConnection:validation-flags for more information. Since: 2.28 Deprecated: 2.72: Do not attempt to ignore validation errors. the #GTlsClientConnection the validation flags 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. 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. Since: 2.28 the #GIOStream to wrap the expected identity of the server #GError for error reporting, or %NULL to ignore. the new #GTlsClientConnection, or %NULL on error 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.28 the #GTlsClientConnection a #GSocketConnectable describing the expected server identity Since GLib 2.42.1, SSL 3.0 is no longer supported. From GLib 2.42.1 through GLib 2.62, this function could be used to force use of TLS 1.0, the lowest-supported TLS protocol version at the time. In the past, this was needed to connect to broken TLS servers that exhibited protocol version intolerance. Such servers are no longer common, and using TLS 1.0 is no longer considered acceptable. Since GLib 2.64, this function does nothing. Since: 2.28 Deprecated: 2.56: SSL 3.0 is insecure. the #GTlsClientConnection a #gboolean, ignored 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. This function does not work as originally designed and is impossible to use correctly. See #GTlsClientConnection:validation-flags for more information. Since: 2.28 Deprecated: 2.72: Do not attempt to ignore validation errors. the #GTlsClientConnection the #GTlsCertificateFlags to use Used by #GTlsConnection implementations to emit the #GTlsConnection::accept-certificate signal. Since: 2.28 a #GTlsConnection the peer's #GTlsCertificate the problems with @peer_cert %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert Gets @conn's certificate, as set by g_tls_connection_set_certificate(). Since: 2.28 a #GTlsConnection @conn's certificate, or %NULL Query the TLS backend for TLS channel binding data of @type for @conn. This call retrieves TLS channel binding data as specified in RFC [5056](https://tools.ietf.org/html/rfc5056), RFC [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The binding data is returned in @data. The @data is resized by the callee using #GByteArray buffer management and will be freed when the @data is destroyed by g_byte_array_unref(). If @data is %NULL, it will only check whether TLS backend is able to fetch the data (e.g. whether @type is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support @type or the binding data is not available yet due to additional negotiation or input required. Since: 2.66 a #GTlsConnection #GTlsChannelBindingType type of data to fetch #GByteArray is filled with the binding data, or %NULL a #GError pointer, or %NULL %TRUE on success, %FALSE otherwise Returns the name of the current TLS ciphersuite, or %NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended. Since: 2.70 a #GTlsConnection The name of the current TLS ciphersuite, or %NULL Gets the certificate database that @conn uses to verify peer certificates. See g_tls_connection_set_database(). Since: 2.30 a #GTlsConnection the certificate database that @conn uses or %NULL 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.30 a connection The interaction object. Gets the name of the application-layer protocol negotiated during the handshake. If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of @conn's protocols, or the TLS backend does not support ALPN, then this will be %NULL. See g_tls_connection_set_advertised_protocols(). Since: 2.60 a #GTlsConnection the negotiated protocol, or %NULL Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) Since: 2.28 a #GTlsConnection @conn's peer's certificate, or %NULL Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) See #GTlsConnection:peer-certificate-errors for more information. Since: 2.28 a #GTlsConnection @conn's peer's certificate errors Returns the current TLS protocol version, which may be %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized #GTlsProtocolVersion. Since: 2.70 a #GTlsConnection The current TLS protocol version Gets @conn rehandshaking mode. See g_tls_connection_set_rehandshake_mode() for details. Since: 2.28 Deprecated: 2.60. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. a #GTlsConnection %G_TLS_REHANDSHAKE_SAFELY 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.28 a #GTlsConnection %TRUE if @conn requires a proper TLS close notification. Gets whether @conn uses the system certificate database to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Deprecated: 2.30: Use g_tls_connection_get_database() instead a #GTlsConnection whether @conn uses the system certificate database 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), #GTlsConnection will handle this for you automatically when you try to send or receive data on the connection. You can call g_tls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use @conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable. 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. Previously, calling g_tls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything. When using a #GTlsConnection created by #GSocketClient, the #GSocketClient performs the initial handshake, so calling this function manually is not recommended. #GTlsConnection::accept_certificate may be emitted during the handshake. Since: 2.28 a #GTlsConnection a #GCancellable, or %NULL a #GError, or %NULL success or failure Asynchronously performs a TLS handshake on @conn. See g_tls_connection_handshake() for more information. Since: 2.28 a #GTlsConnection the [I/O priority][io-priority] of the request a #GCancellable, or %NULL callback to call when the handshake is complete the data to pass to the callback function Finish an asynchronous TLS handshake operation. See g_tls_connection_handshake() for more information. Since: 2.28 a #GTlsConnection a #GAsyncResult. a #GError pointer, or %NULL %TRUE on success, %FALSE on failure, in which case @error will be set. Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_tls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying %NULL for the the value of @protocols will disable ALPN negotiation. See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs. Since: 2.60 a #GTlsConnection a %NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL 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. (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 a #GTlsConnection the certificate to use for @conn 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). There are nonintuitive security implications when using a non-default database. See #GTlsConnection:database for details. Since: 2.30 a #GTlsConnection a #GTlsDatabase Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. 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 a connection an interaction object, or %NULL Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations. Since: 2.28 Deprecated: 2.60. Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. a #GTlsConnection the rehandshaking mode 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). 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. 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.28 a #GTlsConnection whether or not to require close notification 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). Deprecated: 2.30: Use g_tls_connection_set_database() instead a #GTlsConnection whether to use the system certificate database 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. 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. Since: 2.30 a #GTlsDatabase certificate for which to create a handle. a newly allocated string containing the handle. Look up 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. 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. Since: 2.30 a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL a #GError, or %NULL a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. Asynchronously look up a certificate by its handle in the database. See g_tls_database_lookup_certificate_for_handle() for more information. Since: 2.30 a #GTlsDatabase a certificate handle used to interact with the user if necessary Flags which affect the lookup. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup of a certificate by its handle. See g_tls_database_lookup_certificate_for_handle() for more information. If the handle is no longer valid, or does not point to a certificate in this database, then %NULL will be returned. Since: 2.30 a #GTlsDatabase a #GAsyncResult. a #GError pointer, or %NULL a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. Look up the issuer of @certificate in the database. The #GTlsCertificate:issuer property of @certificate is not modified, and the two certificates are not hooked into a chain. This function can block. Use g_tls_database_lookup_certificate_issuer_async() to perform the lookup operation asynchronously. Beware this function cannot be used to build certification paths. The issuer certificate returned by this function may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used when verifying a TLS certificate. Accordingly, this function cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates. Since: 2.30 a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL a #GError, or %NULL a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. Asynchronously look up the issuer of @certificate in the database. See g_tls_database_lookup_certificate_issuer() for more information. Since: 2.30 a #GTlsDatabase a #GTlsCertificate used to interact with the user if necessary flags which affect the lookup operation a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup issuer operation. See g_tls_database_lookup_certificate_issuer() for more information. Since: 2.30 a #GTlsDatabase a #GAsyncResult. a #GError pointer, or %NULL a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. Look up certificates issued by this issuer in the database. This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform the lookup operation asynchronously. Since: 2.30 a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL a #GError, or %NULL a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. Asynchronously look up certificates issued by this issuer in the database. See g_tls_database_lookup_certificates_issued_by() for more information. 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.30 a #GTlsDatabase a #GByteArray which holds the DER encoded issuer DN. used to interact with the user if necessary Flags which affect the lookup operation. a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous lookup of certificates. See g_tls_database_lookup_certificates_issued_by() for more information. Since: 2.30 a #GTlsDatabase a #GAsyncResult. a #GError pointer, or %NULL a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. Determines the validity of a certificate chain, outside the context of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next certificate in the chain by its #GTlsCertificate:issuer property. @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 ensure the server certificate is valid for the expected peer identity. If the identity does not match the certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value. If @identity is %NULL, that bit will never be set in the return value. The peer identity may also be used to check for pinned certificates (trust exceptions) in the database. These may 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 at least one problem found. If the function is unable to determine whether @chain is valid (for example, 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. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Prior to GLib 2.48, GLib's default TLS backend modified @chain to represent the certification path built by #GTlsDatabase during certificate verification by adjusting the #GTlsCertificate:issuer property of each certificate in @chain. Since GLib 2.48, this no longer occurs, so you cannot rely on #GTlsCertificate:issuer to represent the actual certification path used during certificate verification. Because TLS session context is not used, #GTlsDatabase may not perform as many checks on the certificates as #GTlsConnection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let #GTlsConnection handle the verification. The TLS backend may attempt to look up and add missing certificates to the chain. This may involve HTTP requests to download missing certificates. This function can block. Use g_tls_database_verify_chain_async() to perform the verification operation asynchronously. Since: 2.30 a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL a #GError, or %NULL the appropriate #GTlsCertificateFlags which represents the result of verification. 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.30 a #GTlsDatabase a #GTlsCertificate chain the purpose that this certificate chain will be used for. the expected peer identity used to interact with the user if necessary additional verify flags a #GCancellable, or %NULL callback to call when the operation completes the data to pass to the callback function Finish an asynchronous verify chain operation. See g_tls_database_verify_chain() for more information. 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. Since: 2.30 a #GTlsDatabase a #GAsyncResult. a #GError pointer, or %NULL the appropriate #GTlsCertificateFlags which represents the result of verification. Gets the TLS error quark. Since: 2.28 a #GQuark. Creates a new #GTlsFileDatabase which uses anchor certificate authorities in @anchors to verify certificate chains. The certificates in @anchors must be PEM encoded. Since: 2.30 filename of anchor certificate authorities. #GError for error reporting, or %NULL to ignore. the new #GTlsFileDatabase, or %NULL on error 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. 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 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.30 a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object an optional location to place an error on failure The status of the ask password interaction. 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. 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 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. Certain implementations may not support immediate cancellation. Since: 2.30 a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback Complete an ask password user interaction request. This should be once the g_tls_interaction_ask_password_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed to g_tls_interaction_ask_password() will have its password filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Since: 2.30 a #GTlsInteraction object the result passed to the callback an optional location to place an error on failure The status of the ask password interaction. 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. Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The @password value will be filled in and then @callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection. The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Since: 2.30 a #GTlsInteraction object a #GTlsPassword object an optional #GCancellable cancellation object an optional location to place an error on failure The status of the ask password interaction. Invoke the interaction to ask the user to choose a certificate to use with the connection. It invokes this interaction in the main loop, specifically the #GMainContext returned by g_main_context_get_thread_default() when the interaction is created. This is called by called by #GTlsConnection when the peer requests a certificate during the handshake. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which may or may not abort the TLS connection. The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Since: 2.40 a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object an optional location to place an error on failure The status of the certificate request interaction. Run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection passed to g_tls_interaction_request_certificate() will have had its #GTlsConnection:certificate filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation. Since: 2.40 a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object an optional location to place an error on failure The status of the request certificate interaction. Run asynchronous interaction to ask the user for a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function. Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. @callback will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection. Since: 2.40 a #GTlsInteraction object a #GTlsConnection object flags providing more information about the request an optional #GCancellable cancellation object will be called when the interaction completes data to pass to the @callback Complete a request certificate user interaction request. This should be once the g_tls_interaction_request_certificate_async() completion callback is called. If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection passed to g_tls_interaction_request_certificate_async() will have had its #GTlsConnection:certificate filled in. If the interaction is cancelled by the cancellation object, or by the user then %G_TLS_INTERACTION_FAILED will be returned with an error that contains a %G_IO_ERROR_CANCELLED error code. Since: 2.40 a #GTlsInteraction object the result passed to the callback an optional location to place an error on failure The status of the request certificate interaction. Get a description string about what the password will be used for. Since: 2.30 a #GTlsPassword object The description of the password. Get flags about the password. Since: 2.30 a #GTlsPassword object The flags about the password. 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.) Since: 2.30 a #GTlsPassword object location to place the length of the password. The password value (owned by the password object). Get a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). Since: 2.30 a #GTlsPassword object The warning. Create a new #GTlsPassword object. the password flags description of what the password is for The newly allocated password object Set a description string about what the password will be used for. Since: 2.30 a #GTlsPassword object The description of the password Set flags about the password. Since: 2.30 a #GTlsPassword object The flags about the password Set the value for this password. The @value will be copied by the password object. 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 a #GTlsPassword object the new password value the length of the password, or -1 Provide the value for this password. 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.) Virtual: set_value Since: 2.30 a #GTlsPassword object the value for the password the length of the password, or -1 a function to use to free the password. Set a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). Since: 2.30 a #GTlsPassword object The user readable warning Creates a new #GTlsServerConnection wrapping @base_io_stream (which must have pollable input and output streams). 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. Since: 2.28 the #GIOStream to wrap the default server certificate, or %NULL #GError for error reporting, or %NULL to ignore. the new #GTlsServerConnection, or %NULL on error 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. This method can be expected to be available on the following platforms: - Linux since GLib 2.26 - FreeBSD since GLib 2.26 - GNU/kFreeBSD since GLib 2.36 - Solaris, Illumos and OpenSolaris since GLib 2.40 - GNU/Hurd since GLib 2.40 Other ways to exchange credentials with a foreign peer includes the #GUnixCredentialsMessage type and g_socket_get_credentials() function. Since: 2.26 A #GUnixConnection. A #GCancellable or %NULL. Return location for error or %NULL. Received credentials on success (free with g_object_unref()), %NULL if @error is set. Asynchronously receive credentials. For more details, see g_unix_connection_receive_credentials() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_unix_connection_receive_credentials_finish() to get the result of the operation. Since: 2.32 A #GUnixConnection. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous receive credentials operation started with g_unix_connection_receive_credentials_async(). Since: 2.32 A #GUnixConnection. a #GAsyncResult. a #GError, or %NULL a #GCredentials, or %NULL on error. Free the returned object with g_object_unref(). 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. 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. Since: 2.22 a #GUnixConnection optional #GCancellable object, %NULL to ignore #GError for error reporting, or %NULL to ignore a file descriptor on success, -1 on error. 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. This method can be expected to be available on the following platforms: - Linux since GLib 2.26 - FreeBSD since GLib 2.26 - GNU/kFreeBSD since GLib 2.36 - Solaris, Illumos and OpenSolaris since GLib 2.40 - GNU/Hurd since GLib 2.40 Other ways to exchange credentials with a foreign peer includes the #GUnixCredentialsMessage type and g_socket_get_credentials() function. Since: 2.26 A #GUnixConnection. A #GCancellable or %NULL. Return location for error or %NULL. %TRUE on success, %FALSE if @error is set. Asynchronously send credentials. For more details, see g_unix_connection_send_credentials() which is the synchronous version of this call. When the operation is finished, @callback will be called. You can then call g_unix_connection_send_credentials_finish() to get the result of the operation. Since: 2.32 A #GUnixConnection. optional #GCancellable object, %NULL to ignore. a #GAsyncReadyCallback to call when the request is satisfied the data to pass to callback function Finishes an asynchronous send credentials operation started with g_unix_connection_send_credentials_async(). Since: 2.32 A #GUnixConnection. a #GAsyncResult. a #GError, or %NULL %TRUE if the operation was successful, otherwise %FALSE. 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. 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. Since: 2.22 a #GUnixConnection a file descriptor optional #GCancellable object, %NULL to ignore. #GError for error reporting, or %NULL to ignore. a %TRUE on success, %NULL on error. Gets the credentials stored in @message. Since: 2.26 A #GUnixCredentialsMessage. A #GCredentials instance. Do not free, it is owned by @message. Checks if passing #GCredentials on a #GSocket is supported on this platform. Since: 2.26 %TRUE if supported, %FALSE otherwise Creates a new #GUnixCredentialsMessage with credentials matching the current processes. Since: 2.26 a new #GUnixCredentialsMessage Creates a new #GUnixCredentialsMessage holding @credentials. Since: 2.26 A #GCredentials object. a new #GUnixCredentialsMessage Adds a file descriptor to @list. 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. Since: 2.24 a #GUnixFDList a valid open file descriptor a #GError pointer the index of the appended fd in case of success, else -1 (and @error is set) 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. A possible cause of failure is exceeding the per-process or system-wide file descriptor limit. Since: 2.24 a #GUnixFDList the index into the list a #GError pointer the file descriptor, or -1 in case of error Gets the length of @list (ie: the number of file descriptors contained within). Since: 2.24 a #GUnixFDList the length of @list Creates a new #GUnixFDList containing no file descriptors. Since: 2.24 a new #GUnixFDList 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. 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. Since: 2.24 the initial list of file descriptors the length of #fds, or -1 a new #GUnixFDList 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. This function never returns %NULL. In case there are no file descriptors contained in @list, an empty array is returned. Since: 2.24 a #GUnixFDList pointer to the length of the returned array, or %NULL an array of file descriptors 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. 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. Since: 2.24 a #GUnixFDList pointer to the length of the returned array, or %NULL an array of file descriptors Adds a file descriptor to @message. 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. Since: 2.22 a #GUnixFDMessage a valid open file descriptor a #GError pointer %TRUE in case of success, else %FALSE (and @error is set) 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. Since: 2.24 a #GUnixFDMessage the #GUnixFDList from @message Creates a new #GUnixFDMessage containing an empty file descriptor list. Since: 2.22 a new #GUnixFDMessage Creates a new #GUnixFDMessage containing @list. Since: 2.24 a #GUnixFDList a new #GUnixFDMessage 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). 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. This function never returns %NULL. In case there are no file descriptors contained in @message, an empty array is returned. Since: 2.22 a #GUnixFDMessage pointer to the length of the returned array, or %NULL an array of file descriptors Returns whether the file descriptor of @stream will be closed when the stream is closed. Since: 2.20 a #GUnixInputStream %TRUE if the file descriptor is closed when done Return the UNIX file descriptor that the stream reads from. Since: 2.20 a #GUnixInputStream The file descriptor of @stream Creates a new #GUnixInputStream for the given @fd. If @close_fd is %TRUE, the file descriptor will be closed when the stream is closed. a UNIX file descriptor %TRUE to close the file descriptor when done a new #GUnixInputStream Sets whether the file descriptor of @stream shall be closed when the stream is closed. Since: 2.20 a #GUnixInputStream %TRUE to close the file descriptor 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. a mount path, e.g. `/media/disk` or `/usr` %TRUE if @mount_path is considered an implementation detail of the OS. 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. The list of device paths considered ‘system’ ones may change over time. Since: 2.56 a device path, e.g. `/dev/loop0` or `nfsd` %TRUE if @device_path is considered an implementation detail of the OS. 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. The list of file system types considered ‘system’ ones may change over time. Since: 2.56 a file system type, e.g. `procfs` or `tmpfs` %TRUE if @fs_type is considered an implementation detail of the OS. 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(). If more mounts have the same mount path, the last matching mount is returned. This will return %NULL if there is no mount point at @mount_path. path for a possible unix mount. guint64 to contain a timestamp. a #GUnixMountEntry. Compares two unix mounts. first #GUnixMountEntry to compare. second #GUnixMountEntry to compare. 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. Makes a copy of @mount_entry. Since: 2.54 a #GUnixMountEntry. a new #GUnixMountEntry 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(). If more mounts have the same mount path, the last matching mount is returned. This will return %NULL if looking up the mount entry fails, if @file_path doesn’t exist or there is an I/O error. Since: 2.52 file path on some unix mount. guint64 to contain a timestamp. a #GUnixMountEntry. Frees a unix mount. a #GUnixMountEntry. Gets the device path for a unix mount. a #GUnixMount. a string containing the device path. Gets the filesystem type for the unix mount. a #GUnixMount. a string containing the file system type. Gets the mount path for a unix mount. input #GUnixMountEntry to get the mount path for. the mount path for @mount_entry. Gets a comma-separated list of mount options for the unix mount. For example, `rw,relatime,seclabel,data=ordered`. This is similar to g_unix_mount_point_get_options(), but it takes a #GUnixMountEntry as an argument. Since: 2.58 a #GUnixMountEntry. a string containing the options, or %NULL if not available. Gets the root of the mount within the filesystem. This is useful e.g. for mounts created by bind operation, or btrfs subvolumes. For example, the root path is equal to "/" for mount created by "mount /dev/sda1 /mnt/foo" and "/bar" for "mount --bind /mnt/foo/bar /mnt/bar". Since: 2.60 a #GUnixMountEntry. a string containing the root, or %NULL if not supported. Guesses whether a Unix mount can be ejected. a #GUnixMountEntry %TRUE if @mount_entry is deemed to be ejectable. Guesses the icon of a Unix mount. a #GUnixMountEntry a #GIcon Guesses the name of a Unix mount. The result is a translated string. a #GUnixMountEntry A newly allocated string that must be freed with g_free() Guesses whether a Unix mount should be displayed in the UI. a #GUnixMountEntry %TRUE if @mount_entry is deemed to be displayable. Guesses the symbolic icon of a Unix mount. Since: 2.34 a #GUnixMountEntry a #GIcon Guesses the type of a unix mount. If the mount type cannot be determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. a #GUnixMount. a #GUnixMountType. Checks if a unix mount is mounted read only. a #GUnixMount. %TRUE if @mount_entry is read only. 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. The definition of what a ‘system’ mount entry is may change over time as new file system types and device paths are ignored. a #GUnixMount. %TRUE if the unix mount is for a system path. Gets the #GUnixMountMonitor for the current thread-default main context. The mount monitor can be used to monitor for changes to the list of mounted filesystems as well as the list of mount points (ie: fstab entries). You must only call g_object_unref() on the return value from under the same main context as you called this function. Since: 2.44 the #GUnixMountMonitor. Deprecated alias for g_unix_mount_monitor_get(). This function was never a true constructor, which is why it was renamed. Deprecated:2.44:Use g_unix_mount_monitor_get() instead. a #GUnixMountMonitor. This function does nothing. Before 2.44, this was a partially-effective way of controlling the rate at which events would be reported under some uncommon circumstances. Since @mount_monitor is a singleton, it also meant that calling this function would have side effects for other users of the monitor. Since: 2.18 Deprecated:2.44:This function does nothing. Don't call it. a #GUnixMountMonitor a integer with the limit in milliseconds to poll for changes. Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it will be filled with a unix timestamp for checking if the mount points have changed since with g_unix_mount_points_changed_since(). If more mount points have the same mount path, the last matching mount point is returned. Since: 2.66 path for a possible unix mount point. guint64 to contain a timestamp. a #GUnixMountPoint, or %NULL if no match is found. Compares two unix mount points. a #GUnixMount. a #GUnixMount. 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. Makes a copy of @mount_point. Since: 2.54 a #GUnixMountPoint. a new #GUnixMountPoint Frees a unix mount point. unix mount point to free. Gets the device path for a unix mount point. a #GUnixMountPoint. a string containing the device path. Gets the file system type for the mount point. a #GUnixMountPoint. a string containing the file system type. Gets the mount path for a unix mount point. a #GUnixMountPoint. a string containing the mount path. Gets the options for the mount point. Since: 2.32 a #GUnixMountPoint. a string containing the options. Guesses whether a Unix mount point can be ejected. a #GUnixMountPoint %TRUE if @mount_point is deemed to be ejectable. Guesses the icon of a Unix mount point. a #GUnixMountPoint a #GIcon Guesses the name of a Unix mount point. The result is a translated string. a #GUnixMountPoint A newly allocated string that must be freed with g_free() Guesses the symbolic icon of a Unix mount point. Since: 2.34 a #GUnixMountPoint a #GIcon Guesses the type of a unix mount point. If the mount type cannot be determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. a #GUnixMountPoint. a #GUnixMountType. Checks if a unix mount point is a loopback device. a #GUnixMountPoint. %TRUE if the mount point is a loopback. %FALSE otherwise. Checks if a unix mount point is read only. a #GUnixMountPoint. %TRUE if a mount point is read only. Checks if a unix mount point is mountable by the user. a #GUnixMountPoint. %TRUE if the mount point is user mountable. Checks if the unix mount points have changed since a given unix time. guint64 to contain a timestamp. %TRUE if the mount points have changed since @time. 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(). guint64 to contain a timestamp. a #GList of the UNIX mountpoints. Checks if the unix mounts have changed since a given unix time. guint64 to contain a timestamp. %TRUE if the mounts have changed since @time. 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(). guint64 to contain a timestamp, or %NULL a #GList of the UNIX mounts. Returns whether the file descriptor of @stream will be closed when the stream is closed. Since: 2.20 a #GUnixOutputStream %TRUE if the file descriptor is closed when done Return the UNIX file descriptor that the stream writes to. Since: 2.20 a #GUnixOutputStream The file descriptor of @stream Creates a new #GUnixOutputStream for the given @fd. If @close_fd, is %TRUE, the file descriptor will be closed when the output stream is destroyed. a UNIX file descriptor %TRUE to close the file descriptor when done a new #GOutputStream Sets whether the file descriptor of @stream shall be closed when the stream is closed. Since: 2.20 a #GUnixOutputStream %TRUE to close the file descriptor when done Checks if abstract UNIX domain socket names are supported. Since: 2.22 %TRUE if supported, %FALSE otherwise Gets @address's type. Since: 2.26 a #GInetSocketAddress a #GUnixSocketAddressType Tests if @address is abstract. Since: 2.22 Deprecated: Use g_unix_socket_address_get_address_type() a #GInetSocketAddress %TRUE if the address is abstract, %FALSE otherwise Gets @address's path, or for abstract sockets the "name". 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. Since: 2.22 a #GInetSocketAddress the path for @address Gets the length of @address's path. For details, see g_unix_socket_address_get_path(). Since: 2.22 a #GInetSocketAddress the length of the path Creates a new #GUnixSocketAddress for @path. To create abstract socket addresses, on systems that support that, use g_unix_socket_address_new_abstract(). Since: 2.22 the socket path a new #GUnixSocketAddress Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED #GUnixSocketAddress for @path. Deprecated: Use g_unix_socket_address_new_with_type(). the abstract name the length of @path, or -1 a new #GUnixSocketAddress 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"). 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. Since: 2.26 the name the length of @path, or -1 a #GUnixSocketAddressType a new #GUnixSocketAddress Gets the default #GVfs for the system. a #GVfs, which will be the local file system #GVfs if no other implementation is available. Gets a #GFile for @path. a #GVfs. a string containing a VFS path. a #GFile. Free the returned object with g_object_unref(). Gets a #GFile for @uri. 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. a#GVfs. a string containing a URI a #GFile. Free the returned object with g_object_unref(). Gets the local #GVfs for the system. a #GVfs. Gets a list of URI schemes supported by @vfs. a #GVfs. a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. Checks if the VFS is active. a #GVfs. %TRUE if construction of the @vfs was successful and it is now active. 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. a #GVfs. a string to be parsed by the VFS module. a #GFile for the given @parse_name. Free the returned object with g_object_unref(). 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. 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(). Since: 2.50 a #GVfs an URI scheme, e.g. "http" a #GVfsFileLookupFunc custom data passed to be passed to @uri_func, or %NULL function to be called when unregistering the URI scheme, or when @vfs is disposed, to free the resources used by the URI lookup function a #GVfsFileLookupFunc custom data passed to be passed to @parse_name_func, or %NULL 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 %TRUE if @scheme was successfully registered, or %FALSE if a handler for @scheme already exists. Unregisters the URI handler for @scheme previously registered with g_vfs_register_uri_scheme(). Since: 2.50 a #GVfs an URI scheme, e.g. "http" %TRUE if @scheme was successfully unregistered, or %FALSE if a handler for @scheme does not exist. Checks if a volume can be ejected. a #GVolume %TRUE if the @volume can be ejected. %FALSE otherwise Checks if a volume can be mounted. a #GVolume %TRUE if the @volume can be mounted. %FALSE otherwise 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. Deprecated: 2.22: Use g_volume_eject_with_operation() instead. a #GVolume flags affecting the unmount if required for eject optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes ejecting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. pointer to a #GVolume a #GAsyncResult a #GError location to store an error, or %NULL to ignore %TRUE, %FALSE if operation failed 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. Since: 2.22 a #GVolume flags affecting the unmount if required for eject a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data passed to @callback 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.22 a #GVolume a #GAsyncResult a #GError location to store the error occurring, or %NULL %TRUE if the volume was successfully ejected. %FALSE otherwise Gets the kinds of [identifiers][volume-identifier] that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. a #GVolume a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. 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 |[<!-- language="C" --> GMount *mount; GFile *mount_root GFile *volume_activation_root; mount = g_volume_get_mount (volume); // mounted, so never NULL mount_root = g_mount_get_root (mount); volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL ]| then the expression |[<!-- language="C" --> (g_file_has_prefix (volume_activation_root, mount_root) || g_file_equal (volume_activation_root, mount_root)) ]| will always be %TRUE. Activation roots are typically used in #GVolumeMonitor implementations to find the underlying mount to shadow, see g_mount_is_shadowed() for more details. Since: 2.18 a #GVolume the activation root of @volume or %NULL. Use g_object_unref() to free. Gets the drive for the @volume. a #GVolume 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. Gets the icon for @volume. a #GVolume a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. Gets the identifier of the given kind for @volume. See the [introduction][volume-identifier] for more information about volume identifiers. a #GVolume the kind of identifier to return a newly allocated string containing the requested identifier, or %NULL if the #GVolume doesn't have this kind of identifier Gets the mount for the @volume. a #GVolume a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. Gets the name of @volume. a #GVolume the name for the given @volume. The returned string should be freed with g_free() when no longer needed. Gets the sort key for @volume, if any. Since: 2.32 a #GVolume Sorting key for @volume or %NULL if no such key is available Gets the symbolic icon for @volume. Since: 2.34 a #GVolume a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. 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. a #GVolume 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. 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. 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 Similarly, 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. There are two main use cases for this function. 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. 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. a #GMount object to find a parent for the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount. Gets the volume monitor used by gio. a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it. Gets a list of drives connected to the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. a #GList of connected #GDrive objects. Finds a #GMount object by its UUID (see g_mount_get_uuid()) a #GVolumeMonitor. the UUID to look for a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). Gets a list of the mounts on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. a #GList of #GMount objects. Finds a #GVolume object by its UUID (see g_volume_get_uuid()) a #GVolumeMonitor. the UUID to look for a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). Gets a list of the volumes on the system. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref(). a #GVolumeMonitor. a #GList of #GVolume objects. Mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the @volume and #GAsyncResult returned in the @callback. Virtual: mount_fn a #GVolume flags affecting the operation a #GMountOperation or %NULL to avoid user interaction optional #GCancellable object, %NULL to ignore a #GAsyncReadyCallback, or %NULL user data that gets passed to @callback Finishes mounting a volume. If any errors occurred during the operation, @error will be set to contain the errors and %FALSE will be returned. 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. a #GVolume a #GAsyncResult a #GError location to store an error, or %NULL to ignore %TRUE, %FALSE if operation failed Returns whether the volume should be automatically mounted. a #GVolume %TRUE if the volume should be automatically mounted Creates an IStream object backed by a HANDLE. @stgm_mode should match the mode of the @handle, otherwise the stream might attempt to perform operations that the @handle does not allow. The implementation itself ignores these flags completely, they are only used to report the mode of the stream to third parties. The stream only does synchronous access and will never return `E_PENDING` on I/O. The returned stream object should be treated just like any other COM object, and released via `IUnknown_Release()`. its elements have been unreffed with g_object_unref(). a Win32 HANDLE for a file. %TRUE if newly-created stream owns the handle (and closes it when destroyed) a combination of [STGM constants](https://docs.microsoft.com/en-us/windows/win32/stg/stgm-constants) that specify the mode with which the stream is opened. a HRESULT from the internal COM calls. Will be `S_OK` on success. a new IStream object on success, %NULL on failure. Returns whether the handle of @stream will be closed when the stream is closed. Since: 2.26 a #GWin32InputStream %TRUE if the handle is closed when done Return the Windows file handle that the stream reads from. Since: 2.26 a #GWin32InputStream The file handle of @stream Creates a new #GWin32InputStream for the given @handle. If @close_handle is %TRUE, the handle will be closed when the stream is closed. Note that "handle" here means a Win32 HANDLE, not a "file descriptor" as used in the Windows C libraries. a Win32 file handle %TRUE to close the handle when done a new #GWin32InputStream Sets whether the handle of @stream shall be closed when the stream is closed. Since: 2.26 a #GWin32InputStream %TRUE to close the handle when done Returns whether the handle of @stream will be closed when the stream is closed. Since: 2.26 a #GWin32OutputStream %TRUE if the handle is closed when done Return the Windows handle that the stream writes to. Since: 2.26 a #GWin32OutputStream The handle descriptor of @stream Creates a new #GWin32OutputStream for the given @handle. If @close_handle, is %TRUE, the handle will be closed when the output stream is destroyed. Since: 2.26 a Win32 file handle %TRUE to close the handle when done a new #GOutputStream Sets whether the handle of @stream shall be closed when the stream is closed. Since: 2.26 a #GWin32OutputStream %TRUE to close the handle when done Returns a list of directories for DLL lookups. Can be used with g_win32_registry_key_get_value(). Since: 2.66 a %NULL-terminated array of UTF-8 strings. Returns a list of directories for DLL lookups. Can be used with g_win32_registry_key_get_value_w(). Since: 2.66 a %NULL-terminated array of UTF-16 strings. Erases change indicator of the @key. 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. Since: 2.46 a #GWin32RegistryKey Opens a @subkey of the @key. a parent #GWin32RegistryKey name of a child key to open (in UTF-8), relative to @key a pointer to a %NULL #GError, or %NULL a #GWin32RegistryKey or %NULL if can't be opened. Free with g_object_unref(). Opens a @subkey of the @key. a parent #GWin32RegistryKey name of a child key to open (in UTF-8), relative to @key a pointer to a %NULL #GError, or %NULL a #GWin32RegistryKey or %NULL if can't be opened. Free with g_object_unref(). Get full path to the key Since: 2.46 a #GWin32RegistryKey a full path to the key (in UTF-8), or %NULL if it can't be converted to UTF-8. Get full path to the key Since: 2.46 a #GWin32RegistryKey a full path to the key (in UTF-16) Get data from a value of a key. String data is guaranteed to be appropriately terminated and will be in UTF-8. When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API should be used instead of the usual `RegQueryValueExW()`. This implies that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function falls back to `RegQueryValueExW()`), and that this string must undergo special processing (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what kinds of strings are processed) to get the result. If no specific MUI DLL directories need to be used, pass the return value of g_win32_registry_get_os_dirs() as @mui_dll_dirs (as an bonus, the value from g_win32_registry_get_os_dirs() does not add any extra UTF8->UTF16 conversion overhead). @auto_expand works with @mui_dll_dirs, but only affects the processed string, making it somewhat useless. The unprocessed string is always expanded internally, if its type is `REG_EXPAND_SZ` - there is no need to enable @auto_expand for this to work. The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument. Since: 2.66 a #GWin32RegistryKey a %NULL-terminated array of directory names where the OS should look for a DLL indicated in a MUI string, if the DLL path in the string is not absolute (in) %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to G_WIN32_REGISTRY_VALUE_STR. name of the value to get (in UTF-8). Empty string means the '(Default)' value. type of the value retrieved. contents of the value. size of the buffer pointed by @value_data. a pointer to %NULL #GError, or %NULL %TRUE on success, %FALSE on failure. 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 retrieved too. When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API should be used instead of the usual `RegQueryValueExW()`. This implies that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function falls back to `RegQueryValueExW()`), and that this string must undergo special processing (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what kinds of strings are processed) to get the result. If no specific MUI DLL directories need to be used, pass the return value of g_win32_registry_get_os_dirs_w() as @mui_dll_dirs. @auto_expand works with @mui_dll_dirs, but only affects the processed string, making it somewhat useless. The unprocessed string is always expanded internally, if its type is `REG_EXPAND_SZ` - there is no need to enable @auto_expand for this to work. The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument. Since: 2.66 a #GWin32RegistryKey a %NULL-terminated array of directory names where the OS should look for a DLL indicated in a MUI string, if the DLL path in the string is not absolute (in) %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to G_WIN32_REGISTRY_VALUE_STR. name of the value to get (in UTF-16). Empty string means the '(Default)' value. type of the value retrieved. contents of the value. size of the buffer pointed by @value_data. a pointer to %NULL #GError, or %NULL %TRUE on success, %FALSE on failure. Check the @key's status indicator. Since: 2.46 a #GWin32RegistryKey %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. 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 '\\'. absolute full name of a key to open (in UTF-8) a pointer to a %NULL #GError, or %NULL a #GWin32RegistryKey or %NULL if can't be opened. Free with g_object_unref(). 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'\\'. absolute full name of a key to open (in UTF-16) a pointer to a %NULL #GError, or %NULL a #GWin32RegistryKey or %NULL if can't be opened. Free with g_object_unref(). 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. 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). Since: 2.46 a #GWin32RegistryKey (in) %TRUE also watch the children of the @key, %FALSE to watch the key only. specifies the types of changes to watch for. a function to invoke when a change occurs. a pointer to pass to @callback on invocation. a pointer to %NULL #GError, or %NULL %TRUE on success, %FALSE on failure. 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. Since: 2.46 a #GWin32RegistrySubkeyIter another #GWin32RegistrySubkeyIter Frees internal buffers of a #GWin32RegistrySubkeyIter. Since: 2.46 a #GWin32RegistrySubkeyIter Creates a dynamically-allocated copy of an iterator. Dynamically-allocated state of the iterator is duplicated too. Since: 2.46 an iterator a copy of the @iter, free with g_win32_registry_subkey_iter_free () Free an iterator allocated on the heap. For iterators that are allocated on the stack use g_win32_registry_subkey_iter_clear () instead. Since: 2.46 a dynamically-allocated iterator Gets the name of the subkey at the @iter potision. Since: 2.46 a #GWin32RegistrySubkeyIter Pointer to a location to store the name of a subkey (in UTF-8). Free with g_free(). Pointer to a location to store the length of @subkey_name, in gchars, excluding NUL-terminator. %NULL if length is not needed. a pointer to %NULL #GError, or %NULL %TRUE if the name was retrieved, %FALSE otherwise. Same as g_win32_registry_subkey_iter_get_next(), but outputs UTF-16-encoded data, without converting it to UTF-8 first. Since: 2.46 a #GWin32RegistrySubkeyIter Pointer to a location to store the name of a subkey (in UTF-16). Pointer to a location to store the length of @subkey_name, in gunichar2s, excluding NUL-terminator. %NULL if length is not needed. a pointer to %NULL #GError, or %NULL %TRUE if the name was retrieved, %FALSE otherwise. Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be completely uninitialised prior to this call; its old value is 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. Since: 2.46 a pointer to a #GWin32RegistrySubkeyIter a #GWin32RegistryKey to iterate over a pointer to %NULL #GError, or %NULL %TRUE if iterator was initialized successfully, %FALSE on error. 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. This information is accurate at the point of iterator initialization, and may go out of sync with reality even while subkeys are enumerated. Since: 2.46 a #GWin32RegistrySubkeyIter the number of subkeys in the key 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(): |[<!-- language="C" --> // 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); } g_win32_registry_subkey_iter_clear (&iter); } ]| Since: 2.46 a #GWin32RegistrySubkeyIter %TRUE if iterator should silently ignore errors (such as the actual number of subkeys being less than expected) and proceed forward a pointer to %NULL #GError, or %NULL %TRUE if next subkey info was retrieved, %FALSE otherwise. 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.46 a #GWin32RegistryValueIter another #GWin32RegistryValueIter Frees internal buffers of a #GWin32RegistryValueIter. Since: 2.46 a #GWin32RegistryValueIter Creates a dynamically-allocated copy of an iterator. Dynamically-allocated state of the iterator is duplicated too. Since: 2.46 an iterator a copy of the @iter, free with g_win32_registry_value_iter_free (). 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 a dynamically-allocated iterator Stores the data of the value currently being iterated over in @value_data, and its length - in @value_data_len (if not %NULL). Since: 2.46 a #GWin32RegistryValueIter %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to G_WIN32_REGISTRY_VALUE_STR Pointer to a location to store the data of the value (in UTF-8, if it's a string) 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 a pointer to %NULL #GError, or %NULL %TRUE if value data was retrieved, %FALSE otherwise. Stores the data of the value currently being iterated over in @value_data, and its length - in @value_data_len (if not %NULL). Since: 2.46 a #GWin32RegistryValueIter %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to G_WIN32_REGISTRY_VALUE_STR Pointer to a location to store the data of the value (in UTF-16, if it's a string) 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. a pointer to %NULL #GError, or %NULL %TRUE if value data was retrieved, %FALSE otherwise. Stores the name of the value currently being iterated over in @value_name, and its length - in @value_name_len (if not %NULL). Since: 2.46 a #GWin32RegistryValueIter Pointer to a location to store the name of a value (in UTF-8). Pointer to a location to store the length of @value_name, in gchars, excluding NUL-terminator. %NULL if length is not needed. a pointer to %NULL #GError, or %NULL %TRUE if value name was retrieved, %FALSE otherwise. Stores the name of the value currently being iterated over in @value_name, and its length - in @value_name (if not %NULL). Since: 2.46 a #GWin32RegistryValueIter Pointer to a location to store the name of a value (in UTF-16). Pointer to a location to store the length of @value_name, in gunichar2s, excluding NUL-terminator. %NULL if length is not needed. a pointer to %NULL #GError, or %NULL %TRUE if value name was retrieved, %FALSE otherwise. Stores the type of the value currently being iterated over in @value_type. Since: 2.46 a #GWin32RegistryValueIter Pointer to a location to store the type of the value. a pointer to %NULL #GError, or %NULL %TRUE if value type was retrieved, %FALSE otherwise. Initialises (without allocating) a #GWin32RegistryValueIter. @iter may be completely uninitialised prior to this call; its old value is ignored. 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. Since: 2.46 a pointer to a #GWin32RegistryValueIter a #GWin32RegistryKey to iterate over a pointer to %NULL #GError, or %NULL %TRUE if iterator was initialized successfully, %FALSE on error. 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. This information is accurate at the point of iterator initialization, and may go out of sync with reality even while values are enumerated. Since: 2.46 a #GWin32RegistryValueIter the number of values in the key 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(): |[<!-- language="C" --> // 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); } ]| Since: 2.46 a #GWin32RegistryValueIter %TRUE if iterator should silently ignore errors (such as the actual number of values being less than expected) and proceed forward a pointer to %NULL #GError, or %NULL %TRUE if next value info was retrieved, %FALSE otherwise. Returns the #GZlibCompressor:file-info property. Since: 2.26 a #GZlibCompressor a #GFileInfo, or %NULL Creates a new #GZlibCompressor. Since: 2.24 The format to use for the compressed data compression level (0-9), -1 for default a new #GZlibCompressor 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. 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 a #GZlibCompressor a #GFileInfo 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. Since: 2.26 a #GZlibDecompressor a #GFileInfo, or %NULL Creates a new #GZlibDecompressor. Since: 2.24 The format to use for the compressed data a new #GZlibDecompressor 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. bitmask with same meaning as returned by GetLogicalDrives()