[gobject-introspection] Update gio-2.0.c and gobject-2.0.c from glib
- From: Colin Walters <walters src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Update gio-2.0.c and gobject-2.0.c from glib
- Date: Thu, 9 Jun 2011 20:24:57 +0000 (UTC)
commit f1b4adbcacc9d9fbeebf4c0fffe9b7bb9ea2e9ae
Author: Colin Walters <walters verbum org>
Date: Thu Jun 9 16:12:53 2011 -0400
Update gio-2.0.c and gobject-2.0.c from glib
Using commit 4db88bd6e2957893b9f232527cc46bda799f2027
gir/gio-2.0.c |21805 ++++++++++++++++++++++++++++-------------------------
gir/gobject-2.0.c | 190 +-
2 files changed, 11781 insertions(+), 10214 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 9b679a3..cf52afc 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -57,8 +57,9 @@
* @action_group: the #GActionGroup that changed
* @action_name: the name of the action in @action_group
*
- * 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.
+ * 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
*/
@@ -105,17 +106,17 @@
* GActionGroupInterface:
* @has_action: the virtual function pointer for g_action_group_has_action()
* @list_actions: the virtual function pointer for g_action_group_list_actions()
- * @get_parameter_type: the virtual function pointer for g_action_group_get_parameter_type()
- * @get_state_type: the virtual function pointer for g_action_group_get_state_type()
- * @get_state_hint: the virtual function pointer for g_action_group_get_state_hint()
- * @get_enabled: the virtual function pointer for g_action_group_get_enabled()
- * @get_state: the virtual function pointer for g_action_group_get_state()
- * @set_state: the virtual function pointer for g_action_group_set_state()
- * @activate: the virtual function pointer for g_action_group_activate()
- * @action_added: the class closure for the action-added signal
- * @action_removed: the class closure for the action-removed signal
- * @action_enabled_changed: the class closure for the action-enabled-changed signal
- * @action_state_changed: the class closure for the action-enabled-changed signal
+ * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
+ * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
+ * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
+ * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
+ * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
+ * @set_action_state: the virtual function pointer for g_action_group_set_action_state()
+ * @activate_action: the virtual function pointer for g_action_group_activate_action()
+ * @action_added: the class closure for the #GActionGroup::action-added signal
+ * @action_removed: the class closure for the #GActionGroup::action-removed signal
+ * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
+ * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
*
* The virtual function table for #GActionGroup.
*
@@ -298,6 +299,7 @@
* @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for details.
* @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details.
* @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected to use the <envar>GIT_COMMITTER_NAME</envar> environment variable when editing a git commit message. The environment is available to the #GApplication::command-line signal handler, via g_application_command_line_getenv().
+ * @G_APPLICATION_NON_UNIQUE: Make no attempts to do any of the typical single-instance application negotiation. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process. Since: 2.30.
*
* Flags used to define the behaviour of a #GApplication.
*
@@ -1001,6 +1003,7 @@
* @G_CREDENTIALS_TYPE_INVALID: Indicates an invalid native credential type.
* @G_CREDENTIALS_TYPE_LINUX_UCRED: The native credentials type is a <type>struct ucred</type>.
* @G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED: The native credentials type is a <type>struct cmsgcred</type>.
+ * @G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED: The native credentials type is a <type>struct sockpeercred</type>. Added in 2.30.
*
* Enumeration describing different kinds of native credential types.
*
@@ -1013,7 +1016,7 @@
* @ref_count: The reference count or -1 if statically allocated.
* @key: The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".
* @value: The value of the annotation.
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
*
* Information about an annotation.
*
@@ -1026,7 +1029,7 @@
* @ref_count: The reference count or -1 if statically allocated.
* @name: Name of the argument, e.g. @unix_user_id.
* @signature: D-Bus signature of the argument (a single complete type).
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
*
* Information about an argument for a method or a signal.
*
@@ -1228,6 +1231,8 @@
* GDBusConnection:stream:
*
* The underlying #GIOStream used for I/O.
+ * If this is passed on construction and is a #GSocketConnection,
+ * then the corresponding #GSocket will be put into non-blocking mode.
*
* Since: 2.26
*/
@@ -1340,6 +1345,15 @@
/**
+ * GDBusInterface:
+ *
+ * Base type for D-Bus interfaces.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GDBusInterfaceGetPropertyFunc:
* @connection: A #GDBusConnection.
* @sender: The unique bus name of the remote caller.
@@ -1358,13 +1372,26 @@
/**
+ * GDBusInterfaceIface:
+ * @parent_iface: The parent interface.
+ * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_get_info().
+ * @get_object: Gets the enclosing #GDBusObject. See g_dbus_interface_get_object().
+ * @set_object: Sets the enclosing #GDBusObject. See g_dbus_interface_set_object().
+ *
+ * Base type for D-Bus interfaces.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GDBusInterfaceInfo:
* @ref_count: The reference count or -1 if statically allocated.
* @name: The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".
- * @methods: A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods.
- * @signals: A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals.
- * @properties: A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties.
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * @methods: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods.
+ * @signals: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals.
+ * @properties: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
*
* Information about a D-Bus interface.
*
@@ -1408,6 +1435,89 @@
/**
+ * GDBusInterfaceSkeleton:
+ *
+ * The #GDBusInterfaceSkeleton structure contains private data and should
+ * only be accessed using the provided API.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GDBusInterfaceSkeleton::g-authorize-method:
+ * @interface: The #GDBusInterfaceSkeleton emitting the signal.
+ * @invocation: A #GDBusMethodInvocation.
+ *
+ * Emitted when a method is invoked by a remote caller and used to
+ * determine if the method call is authorized.
+ * Note that this signal is emitted in a thread dedicated to
+ * handling the method call so handlers are allowed to perform
+ * blocking IO. This means that it is appropriate to call
+ * e.g. <ulink
+ * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync";>polkit_authority_check_authorization_sync()</ulink>
+ * with the <ulink
+ * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS";>POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION</ulink> flag set.
+ * If %FALSE is returned then no further handlers are run and the
+ * signal handler must take a reference to @invocation and finish
+ * handling the call (e.g. return an error via
+ * g_dbus_method_invocation_return_error()).
+ * Otherwise, if %TRUE is returned, signal emission continues. If no
+ * handlers return %FALSE, then the method is dispatched. If
+ * #GDBusObjectSkeleton::authorize-method signal handlers run before
+ * the handlers for this signal.
+ * The default class handler just returns %TRUE.
+ * 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.
+ *
+ * Please note that the common case is optimized: if no signals
+ * Returns: %TRUE if the call is authorized, %FALSE otherwise.
+ * Since: 2.30
+ */
+
+
+/**
+ * GDBusInterfaceSkeleton:g-flags:
+ *
+ * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GDBusInterfaceSkeletonClass:
+ * @parent_class: The parent class.
+ * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_skeleton_get_info() for details.
+ * @get_vtable: Returns a #GDBusInterfaceVTable. See g_dbus_interface_skeleton_get_vtable() for details.
+ * @get_properties: Returns a new, floating, #GVariant with all properties. See g_dbus_interface_skeleton_get_properties().
+ * @flush: Emits outstanding changes, if any. See g_dbus_interface_skeleton_flush().
+ * @g_authorize_method: Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal.
+ *
+ * Class structure for #GDBusInterfaceSkeleton.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GDBusInterfaceSkeletonFlags:
+ * @G_DBUS_INTERFACE_SKELETON_FLAGS_NONE: No flags set.
+ * @G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD: Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must use locking to access data structures used by other threads.
+ *
+ * Flags describing the behavior of a #GDBusInterfaceSkeleton instance.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GDBusInterfaceVTable:
* @method_call: Function for handling incoming method calls.
* @get_property: Function for getting a property.
@@ -1572,9 +1682,9 @@
* GDBusMethodInfo:
* @ref_count: The reference count or -1 if statically allocated.
* @name: The name of the D-Bus method, e.g. @RequestName.
- * @in_args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments.
- * @out_args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments.
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * @in_args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments.
+ * @out_args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
*
* Information about a method on an D-Bus interface.
*
@@ -1605,9 +1715,9 @@
* GDBusNodeInfo:
* @ref_count: The reference count or -1 if statically allocated.
* @path: The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details.
- * @interfaces: A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
- * @nodes: A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * @interfaces: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
+ * @nodes: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
*
* Information about nodes in a remote object hierarchy.
*
@@ -1616,16879 +1726,18167 @@
/**
- * GDBusPropertyInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: The name of the D-Bus property, e.g. "SupportedFilesystems".
- * @signature: The D-Bus signature of the property (a single complete type).
- * @flags: Access control flags for the property.
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GDBusObject::interface-added:
+ * @object: The #GDBusObject emitting the signal.
+ * @interface: The #GDBusInterface that was added.
*
- * Information about a D-Bus property on a D-Bus interface.
+ * Emitted when @interface is added to @object.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusPropertyInfoFlags:
- * @G_DBUS_PROPERTY_INFO_FLAGS_NONE: No flags set.
- * @G_DBUS_PROPERTY_INFO_FLAGS_READABLE: Property is readable.
- * @G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE: Property is writable.
+ * GDBusObject::interface-removed:
+ * @object: The #GDBusObject emitting the signal.
+ * @interface: The #GDBusInterface that was removed.
*
- * Flags describing the access control of a D-Bus property.
+ * Emitted when @interface is removed from @object.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:
+ * GDBusObjectIface:
+ * @parent_iface: The parent interface.
+ * @get_object_path: Returns the object path. See g_dbus_object_get_object_path().
+ * @get_interfaces: Returns all interfaces. See g_dbus_object_get_interfaces().
+ * @get_interface: Returns an interface by name. See g_dbus_object_get_interface().
+ * @interface_added: Signal handler for the #GDBusObject::interface-added signal.
+ * @interface_removed: Signal handler for the #GDBusObject::interface-removed signal.
*
- * The #GDBusProxy structure contains only private data and
- * should only be accessed using the provided API.
+ * Base object type for D-Bus objects.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy::g-properties-changed:
- * @proxy: The #GDBusProxy emitting the signal.
- * @changed_properties: A #GVariant containing the properties that changed
- * @invalidated_properties: A %NULL terminated array of properties that was invalidated
+ * GDBusObjectManager::interface-added:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject on which an interface was added.
+ * @interface: The #GDBusInterface that was added.
*
- * Emitted when one or more D-Bus properties on @proxy changes. The
- * local cache has already been updated when this signal fires. Note
- * that both @changed_properties and @invalidated_properties are
- * guaranteed to never be %NULL (either may be empty though).
- * This signal corresponds to the
- * <literal>PropertiesChanged</literal> D-Bus signal on the
- * <literal>org.freedesktop.DBus.Properties</literal> interface.
+ * 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.26
+ * Since: 2.30
*/
/**
- * GDBusProxy::g-signal:
- * @proxy: The #GDBusProxy emitting the signal.
- * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection.
- * @signal_name: The name of the signal.
- * @parameters: A #GVariant tuple with parameters for the signal.
+ * GDBusObjectManager::interface-removed:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject on which an interface was removed.
+ * @interface: The #GDBusInterface that was removed.
*
- * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
+ * 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.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-bus-type:
+ * GDBusObjectManager::object-added:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject that was added.
*
- * 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.
+ * Emitted when @object is added to @manager.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-connection:
+ * GDBusObjectManager::object-removed:
+ * @manager: The #GDBusObjectManager emitting the signal.
+ * @object: The #GDBusObject that was removed.
*
- * The #GDBusConnection the proxy is for.
+ * Emitted when @object is removed from @manager.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-default-timeout:
+ * GDBusObjectManagerClient:
*
- * 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.
+ * The #GDBusObjectManagerClient structure contains private data and should
+ * only be accessed using the provided API.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-flags:
+ * GDBusObjectManagerClient::interface-proxy-properties-changed:
+ * @manager: The #GDBusObjectManagerClient emitting the signal.
+ * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
+ * @interface_proxy: The #GDBusProxy that has properties that are changing.
+ * @changed_properties: A #GVariant containing the properties that changed.
+ * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
*
- * Flags from the #GDBusProxyFlags enumeration.
+ * Emitted when one or more D-Bus properties on proxy changes. The
+ * local cache has already been updated when this signal fires. Note
+ * that both @changed_properties and @invalidated_properties are
+ * guaranteed to never be %NULL (either may be empty though).
+ * This signal exists purely as a convenience to avoid having to
+ * connect signals to all interface proxies managed by @manager.
+ * This signal is emitted in the
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * that @manager was constructed in.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-interface-info:
+ * GDBusObjectManagerClient::interface-proxy-signal:
+ * @manager: The #GDBusObjectManagerClient emitting the signal.
+ * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
+ * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
+ * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
+ * @signal_name: The signal name.
+ * @parameters: A #GVariant tuple with parameters for the signal.
*
- * Ensure that interactions with this proxy conform to the given
- * interface. For example, when completing a method call, if the
- * type signature of the message isn't what's expected, the given
- * #GError is set. Signals that have a type signature mismatch are
- * simply dropped.
+ * 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
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * that @manager was constructed in.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-interface-name:
+ * GDBusObjectManagerClient:bus-type:
*
- * The D-Bus interface name the proxy is for.
+ * 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.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-name:
+ * GDBusObjectManagerClient:connection:
*
- * The well-known or unique name that the proxy is for.
+ * The #GDBusConnection to use.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-name-owner:
+ * GDBusObjectManagerClient:flags:
*
- * The unique name that owns #GDBusProxy:name or %NULL if no-one
- * currently owns that name. You may connect to #GObject::notify signal to
- * track changes to this property.
+ * Flags from the #GDBusObjectManagerClientFlags enumeration.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxy:g-object-path:
+ * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
*
- * The object path the proxy is for.
+ * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxyClass:
- * @g_properties_changed: Signal class handler for the #GDBusProxy::g-properties-changed signal.
- * @g_signal: Signal class handler for the #GDBusProxy::g-signal signal.
+ * GDBusObjectManagerClient:get-proxy-type-func:
*
- * Class structure for #GDBusProxy.
+ * The #GDBusProxyTypeFunc to use when determining what #GType to
+ * use for interface proxies or %NULL.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusProxyFlags:
- * @G_DBUS_PROXY_FLAGS_NONE: No flags set.
- * @G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES: Don't load properties.
- * @G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS: Don't connect to signals on the remote object.
- * @G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START: If not set and the proxy if for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in proxies for well-known names.
+ * GDBusObjectManagerClient:get-proxy-type-user-data:
*
- * Flags used when constructing an instance of a #GDBusProxy derived class.
+ * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusSendMessageFlags:
- * @G_DBUS_SEND_MESSAGE_FLAGS_NONE: No flags set.
- * @G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL: Do not automatically assign a serial number from the #GDBusConnection object when sending a message.
+ * GDBusObjectManagerClient:name:
*
- * Flags used when sending #GDBusMessage<!-- -->s on a #GDBusConnection.
+ * The well-known name or unique name that the manager is for.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:
+ * GDBusObjectManagerClient:name-owner:
*
- * The #GDBusServer structure contains only private data and
- * should only be accessed using the provided API.
+ * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
+ * no-one is currently owning the name. Connect to the
+ * #GObject::notify signal to track changes to this property.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer::new-connection:
- * @server: The #GDBusServer emitting the signal.
- * @connection: A #GDBusConnection for the new connection.
+ * GDBusObjectManagerClient:object-path:
*
- * 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 call g_dbus_connection_close() and give up your
- * reference. Note that the other peer may disconnect at any time -
- * a typical thing to do when accepting a connection is to listen to
- * the #GDBusConnection::closed signal.
- * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
- * then the signal is emitted in a new thread dedicated to the
- * connection. Otherwise the signal is emitted in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread that @server was constructed in.
- * 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.
- * run.
+ * The object path the manager is for.
*
- * Returns: %TRUE to claim @connection, %FALSE to let other handlers
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:active:
+ * GDBusObjectManagerClientClass:
+ * @parent_class: The parent class.
+ * @interface_proxy_signal: Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal.
+ * @interface_proxy_properties_changed: Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal.
*
- * Whether the server is currently active.
+ * Class structure for #GDBusObjectManagerClient.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:address:
+ * GDBusObjectManagerClientFlags:
+ * @G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE: No flags set.
+ * @G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START: If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in managers for well-known names.
*
- * The D-Bus address to listen on.
+ * Flags used when constructing a #GDBusObjectManagerClient.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:authentication-observer:
+ * GDBusObjectManagerIface:
+ * @parent_iface: The parent interface.
+ * @get_object_path: Virtual function for g_dbus_object_manager_get_object_path().
+ * @get_objects: Virtual function for g_dbus_object_manager_get_objects().
+ * @get_object: Virtual function for g_dbus_object_manager_get_object().
+ * @get_interface: Virtual function for g_dbus_object_manager_get_interface().
+ * @object_added: Signal handler for the #GDBusObjectManager::object-added signal.
+ * @object_removed: Signal handler for the #GDBusObjectManager::object-removed signal.
+ * @interface_added: Signal handler for the #GDBusObjectManager::interface-added signal.
+ * @interface_removed: Signal handler for the #GDBusObjectManager::interface-removed signal.
*
- * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
+ * Base type for D-Bus object managers.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:client-address:
+ * GDBusObjectManagerServer:
*
- * The D-Bus address that clients can use.
+ * The #GDBusObjectManagerServer structure contains private data and should
+ * only be accessed using the provided API.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:flags:
+ * GDBusObjectManagerServer:connection:
*
- * Flags from the #GDBusServerFlags enumeration.
+ * The #GDBusConnection to export objects on.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServer:guid:
+ * GDBusObjectManagerServer:object-path:
*
- * The guid of the server.
+ * The object path to register the manager object at.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServerClass:
- * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
+ * GDBusObjectManagerServerClass:
+ * @parent_class: The parent class.
*
- * Class structure for #GDBusServer.
+ * Class structure for #GDBusObjectManagerServer.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusServerFlags:
- * @G_DBUS_SERVER_FLAGS_NONE: No flags set.
- * @G_DBUS_SERVER_FLAGS_RUN_IN_THREAD: All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details).
- * @G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: Allow the anonymous authentication method.
+ * GDBusObjectProxy:
*
- * Flags used when creating a #GDBusServer.
+ * The #GDBusObjectProxy structure contains private data and should
+ * only be accessed using the provided API.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusSignalCallback:
- * @connection: A #GDBusConnection.
- * @sender_name: The unique bus name of the sender of the signal.
- * @object_path: The object path that the signal was emitted on.
- * @interface_name: The name of the interface.
- * @signal_name: The name of the signal.
- * @parameters: A #GVariant tuple with parameters for the signal.
- * @user_data: User data passed when subscribing to the signal.
+ * GDBusObjectProxy:connection:
*
- * Signature for callback function used in g_dbus_connection_signal_subscribe().
+ * The connection of the proxy.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusSignalFlags:
- * @G_DBUS_SIGNAL_FLAGS_NONE: No flags set.
- * @G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE: Don't actually send the AddMatch DBus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually).
+ * GDBusObjectProxy:object-path:
*
- * Flags used when subscribing to signals via g_dbus_connection_signal_subscribe().
+ * The object path of the proxy.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusSignalInfo:
- * @ref_count: The reference count or -1 if statically allocated.
- * @name: The name of the D-Bus signal, e.g. "NameOwnerChanged".
- * @args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments.
- * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ * GDBusObjectProxyClass:
+ * @parent_class: The parent class.
*
- * Information about a signal on a D-Bus interface.
+ * Class structure for #GDBusObjectProxy.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusSubtreeDispatchFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
- * @interface_name: The D-Bus interface name that the method call or property access is for.
- * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
- * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
+ * GDBusObjectSkeleton:
*
- * The type of the @dispatch function in #GDBusSubtreeVTable.
- * Subtrees are flat. @node, if non-%NULL, is always exactly one
+ * The #GDBusObjectSkeleton structure contains private data and should only be
+ * accessed using the provided API.
*
- * Segment of the object path (ie: it never contains a slash).
- * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * GDBusSubtreeEnumerateFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
+ * GDBusObjectSkeleton::authorize-method:
+ * @object: The #GDBusObjectSkeleton emitting the signal.
+ * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
+ * @invocation: A #GDBusMethodInvocation.
*
- * The type of the @enumerate function in #GDBusSubtreeVTable.
- * This function is called when generating introspection data and also
- * when preparing to dispatch incoming messages in the event that the
- * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
- * Hierarchies are not supported; the items that you return should not
- * contain the '/' character.
- * The return value will be freed with g_strfreev().
+ * 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.
*
- * Specified (ie: to verify that the object path is valid).
- * Returns: A newly allocated array of strings for node names that are children of @object_path.
- * Since: 2.26
+ * Returns: %TRUE if the call is authorized, %FALSE otherwise.
+ * Since: 2.30
*/
/**
- * GDBusSubtreeFlags:
- * @G_DBUS_SUBTREE_FLAGS_NONE: No flags set.
- * @G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES: Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree.
+ * GDBusObjectSkeleton:object-path:
*
- * Flags passed to g_dbus_connection_register_subtree().
+ * The object path where the object is exported.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GDBusObjectSkeletonClass:
+ * @parent_class: The parent class.
+ * @authorize_method: Signal class handler for the #GDBusObjectSkeleton::authorize-method signal.
+ *
+ * Class structure for #GDBusObjectSkeleton.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GDBusPropertyInfo:
+ * @ref_count: The reference count or -1 if statically allocated.
+ * @name: The name of the D-Bus property, e.g. "SupportedFilesystems".
+ * @signature: The D-Bus signature of the property (a single complete type).
+ * @flags: Access control flags for the property.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
+ *
+ * Information about a D-Bus property on a D-Bus interface.
*
* Since: 2.26
*/
/**
- * GDBusSubtreeIntrospectFunc:
- * @connection: A #GDBusConnection.
- * @sender: The unique bus name of the remote caller.
- * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
- * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
- * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
+ * GDBusPropertyInfoFlags:
+ * @G_DBUS_PROPERTY_INFO_FLAGS_NONE: No flags set.
+ * @G_DBUS_PROPERTY_INFO_FLAGS_READABLE: Property is readable.
+ * @G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE: Property is writable.
*
- * The type of the @introspect function in #GDBusSubtreeVTable.
- * Subtrees are flat. @node, if non-%NULL, is always exactly one
- * This function should return %NULL to indicate that there is no object
- * at this node.
- * If this function returns non-%NULL, the return value is expected to
- * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
- * structures describing the interfaces implemented by @node. This
- * array will have g_dbus_interface_info_unref() called on each item
- * before being freed with g_free().
- * The difference between returning %NULL and an array containing zero
- * items is that the standard DBus interfaces will returned to the
- * remote introspector in the empty array case, but not in the %NULL
- * case.
+ * Flags describing the access control of a D-Bus property.
*
- * Segment of the object path (ie: it never contains a slash).
- * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
* Since: 2.26
*/
/**
- * GDBusSubtreeVTable:
- * @enumerate: Function for enumerating child nodes.
- * @introspect: Function for introspecting a child node.
- * @dispatch: Function for dispatching a remote call on a child node.
+ * GDBusProxy:
*
- * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
+ * The #GDBusProxy structure contains only private data and
+ * should only be accessed using the provided API.
*
* Since: 2.26
*/
/**
- * GDataInputStream:
+ * GDBusProxy::g-properties-changed:
+ * @proxy: The #GDBusProxy emitting the signal.
+ * @changed_properties: A #GVariant containing the properties that changed
+ * @invalidated_properties: A %NULL terminated array of properties that was invalidated
*
- * An implementation of #GBufferedInputStream that allows for high-level
- * data manipulation of arbitrary data (including binary operations).
+ * Emitted when one or more D-Bus properties on @proxy changes. The
+ * local cache has already been updated when this signal fires. Note
+ * that both @changed_properties and @invalidated_properties are
+ * guaranteed to never be %NULL (either may be empty though).
+ * This signal corresponds to the
+ * <literal>PropertiesChanged</literal> D-Bus signal on the
+ * <literal>org.freedesktop.DBus.Properties</literal> interface.
+ *
+ * Since: 2.26
*/
/**
- * GDataOutputStream:
+ * GDBusProxy::g-signal:
+ * @proxy: The #GDBusProxy emitting the signal.
+ * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection.
+ * @signal_name: The name of the signal.
+ * @parameters: A #GVariant tuple with parameters for the signal.
*
- * An implementation of #GBufferedOutputStream that allows for high-level
- * data manipulation of arbitrary data (including binary operations).
+ * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
+ *
+ * Since: 2.26
*/
/**
- * GDataOutputStream:byte-order:
+ * GDBusProxy:g-bus-type:
*
- * Determines the byte ordering that is used when writing
- * multi-byte entities (such as integers) to the stream.
+ * 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
*/
/**
- * GDataStream:byte-order:
+ * GDBusProxy:g-connection:
*
- * The ::byte-order property determines the byte ordering that
- * is used when reading multi-byte entities (such as integers)
- * from the stream.
+ * The #GDBusConnection the proxy is for.
+ *
+ * Since: 2.26
*/
/**
- * GDataStream:newline-type:
+ * GDBusProxy:g-default-timeout:
*
- * The :newline-type property determines what is considered
- * as a line ending when reading complete lines from the stream.
+ * 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
*/
/**
- * GDataStreamByteOrder:
- * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order.
- * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order.
- * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture.
+ * GDBusProxy:g-flags:
*
- * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources
- * across various machine architectures.
+ * Flags from the #GDBusProxyFlags enumeration.
+ *
+ * Since: 2.26
*/
/**
- * GDataStreamNewlineType:
- * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms.
- * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings.
- * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows.
- * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type.
+ * GDBusProxy:g-interface-info:
*
- * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
+ * Ensure that interactions with this proxy conform to the given
+ * interface. For example, when completing a method call, if the
+ * type signature of the message isn't what's expected, the given
+ * #GError is set. Signals that have a type signature mismatch are
+ * simply dropped.
+ *
+ * Since: 2.26
*/
/**
- * GDateTime:
+ * GDBusProxy:g-interface-name:
*
- * <structname>GDateTime</structname> is an opaque structure whose members
- * cannot be accessed directly.
+ * The D-Bus interface name the proxy is for.
*
* Since: 2.26
*/
/**
- * GDesktopAppInfo:
+ * GDBusProxy:g-name:
*
- * Information about an installed application from a desktop file.
+ * The well-known or unique name that the proxy is for.
+ *
+ * Since: 2.26
*/
/**
- * GDesktopAppInfoLookup:
+ * GDBusProxy:g-name-owner:
+ *
+ * The unique name that owns #GDBusProxy:name or %NULL if no-one
+ * currently owns that name. You may connect to #GObject::notify signal to
+ * track changes to this property.
*
- * Interface that is used by backends to associate default
- * handlers with URI schemes.
+ * Since: 2.26
*/
/**
- * GDesktopAppLaunchCallback:
- * @appinfo: a #GDesktopAppInfo
- * @pid: Process identifier
- * @user_data: User data
+ * GDBusProxy:g-object-path:
+ *
+ * The object path the proxy is for.
*
- * During invocation, g_desktop_app_info_launch_uris_as_manager() may
- * create one or more child processes. This callback is invoked once
- * for each, providing the process ID.
+ * Since: 2.26
*/
/**
- * GDrive:
+ * GDBusProxyClass:
+ * @g_properties_changed: Signal class handler for the #GDBusProxy::g-properties-changed signal.
+ * @g_signal: Signal class handler for the #GDBusProxy::g-signal signal.
*
- * Opaque drive object.
+ * Class structure for #GDBusProxy.
+ *
+ * Since: 2.26
*/
/**
- * GDrive::changed:
- * @drive: a #GDrive.
+ * GDBusProxyFlags:
+ * @G_DBUS_PROXY_FLAGS_NONE: No flags set.
+ * @G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES: Don't load properties.
+ * @G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS: Don't connect to signals on the remote object.
+ * @G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START: If not set and the proxy if for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in proxies for well-known names.
*
- * Emitted when the drive's state has changed.
+ * Flags used when constructing an instance of a #GDBusProxy derived class.
+ *
+ * Since: 2.26
*/
/**
- * GDrive::disconnected:
- * @drive: a #GDrive.
+ * GDBusProxyTypeFunc:
+ * @manager: A #GDBusObjectManagerClient.
+ * @object_path: The object path of the remote object.
+ * @interface_name: (allow-none): The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested.
+ * @user_data: User data.
*
- * 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.
+ * Function signature for a function used to determine the #GType to
+ * use for an interface proxy (if @interface_name is not %NULL) or
+ * object proxy (if @interface_name is %NULL).
+ * This function is called in the
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * that @manager was constructed in.
+ * must be a #GDBusProxy<!-- -->- or #GDBusObjectProxy<!-- -->-derived
+ * type.
+ *
+ * Returns: A #GType to use for the remote object. The returned type
+ * Since: 2.30
*/
/**
- * GDrive::eject-button:
- * @drive: a #GDrive.
+ * GDBusSendMessageFlags:
+ * @G_DBUS_SEND_MESSAGE_FLAGS_NONE: No flags set.
+ * @G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL: Do not automatically assign a serial number from the #GDBusConnection object when sending a message.
*
- * Emitted when the physical eject button (if any) of a drive has
- * been pressed.
+ * Flags used when sending #GDBusMessage<!-- -->s on a #GDBusConnection.
+ *
+ * Since: 2.26
*/
/**
- * GDrive::stop-button:
- * @drive: a #GDrive.
+ * GDBusServer:
*
- * Emitted when the physical stop button (if any) of a drive has
- * been pressed.
+ * The #GDBusServer structure contains only private data and
+ * should only be accessed using the provided API.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * GDriveIface:
- * @g_iface: The parent interface.
- * @changed: Signal emitted when the drive is changed.
- * @disconnected: The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.
- * @eject_button: Signal emitted when the physical eject button (if any) of a drive have been pressed.
- * @get_name: Returns the name for the given #GDrive.
- * @get_icon: Returns a #GIcon for the given #GDrive.
- * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes.
- * @get_volumes: Returns a list #GList of #GVolume for the #GDrive.
- * @is_media_removable: Returns %TRUE if the #GDrive supports removal and insertion of media.
- * @has_media: Returns %TRUE if the #GDrive has media inserted.
- * @is_media_check_automatic: Returns %TRUE if the #GDrive is capabable of automatically detecting media changes.
- * @can_poll_for_media: Returns %TRUE if the #GDrive is capable of manually polling for media change.
- * @can_eject: Returns %TRUE if the #GDrive can eject media.
- * @eject: Ejects a #GDrive.
- * @eject_finish: Finishes an eject operation.
- * @poll_for_media: Poll for media insertion/removal on a #GDrive.
- * @poll_for_media_finish: Finishes a media poll operation.
- * @get_identifier: Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one.
- * @enumerate_identifiers: Returns an array strings listing the kinds of identifiers which the #GDrive has.
- * @get_start_stop_type: Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22.
- * @can_stop: Returns %TRUE if a #GDrive can be stopped. Since 2.22.
- * @stop: Stops a #GDrive. Since 2.22.
- * @stop_finish: Finishes a stop operation. Since 2.22.
- * @can_start: Returns %TRUE if a #GDrive can be started. Since 2.22.
- * @can_start_degraded: Returns %TRUE if a #GDrive can be started degraded. Since 2.22.
- * @start: Starts a #GDrive. Since 2.22.
- * @start_finish: Finishes a start operation. Since 2.22.
- * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.
- * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22.
- * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ * GDBusServer::new-connection:
+ * @server: The #GDBusServer emitting the signal.
+ * @connection: A #GDBusConnection for the new connection.
*
- * Interface for creating #GDrive implementations.
+ * 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 call g_dbus_connection_close() and give up your
+ * reference. Note that the other peer may disconnect at any time -
+ * a typical thing to do when accepting a connection is to listen to
+ * the #GDBusConnection::closed signal.
+ * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
+ * then the signal is emitted in a new thread dedicated to the
+ * connection. Otherwise the signal is emitted in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread that @server was constructed in.
+ * 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.
+ * run.
+ *
+ * Returns: %TRUE to claim @connection, %FALSE to let other handlers
+ * Since: 2.26
*/
/**
- * GDriveStartFlags:
- * @G_DRIVE_START_NONE: No flags set.
+ * GDBusServer:active:
*
- * Flags used when starting a drive.
+ * Whether the server is currently active.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * GDriveStartStopType:
- * @G_DRIVE_START_STOP_TYPE_UNKNOWN: Unknown or drive doesn't support start/stop.
- * @G_DRIVE_START_STOP_TYPE_SHUTDOWN: The stop method will physically shut down the drive and e.g. power down the port the drive is attached to.
- * @G_DRIVE_START_STOP_TYPE_NETWORK: The start/stop methods are used for connecting/disconnect to the drive over the network.
- * @G_DRIVE_START_STOP_TYPE_MULTIDISK: The start/stop methods will assemble/disassemble a virtual drive from several physical drives.
- * @G_DRIVE_START_STOP_TYPE_PASSWORD: The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command)
+ * GDBusServer:address:
*
- * Enumeration describing how a drive can be started/stopped.
+ * The D-Bus address to listen on.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * GEmblem:
+ * GDBusServer:authentication-observer:
*
- * An object for Emblems
+ * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
+ *
+ * Since: 2.26
*/
/**
- * GEmblemOrigin:
- * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin
- * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information
- * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly"
- * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)
+ * GDBusServer:client-address:
*
- * GEmblemOrigin is used to add information about the origin of the emblem
- * to #GEmblem.
+ * The D-Bus address that clients can use.
*
- * Since: 2.18
+ * Since: 2.26
*/
/**
- * GEmblemedIcon:
+ * GDBusServer:flags:
*
- * An implementation of #GIcon for icons with emblems.
+ * Flags from the #GDBusServerFlags enumeration.
+ *
+ * Since: 2.26
*/
/**
- * GEnumClass:
- * @g_type_class: the parent class
- * @minimum: the smallest possible value.
- * @maximum: the largest possible value.
- * @n_values: the number of possible values.
- * @values: an array of #GEnumValue structs describing the individual values.
+ * GDBusServer:guid:
*
- * The class of an enumeration type holds information about its
- * possible values.
+ * The guid of the server.
+ *
+ * Since: 2.26
*/
/**
- * GEnumValue:
- * @value: the enum value
- * @value_name: the name of the value
- * @value_nick: the nickname of the value
+ * GDBusServerClass:
+ * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
*
- * A structure which contains a single enum value, its name, and its
- * nickname.
+ * Class structure for #GDBusServer.
+ *
+ * Since: 2.26
*/
/**
- * GFile:
+ * GDBusServerFlags:
+ * @G_DBUS_SERVER_FLAGS_NONE: No flags set.
+ * @G_DBUS_SERVER_FLAGS_RUN_IN_THREAD: All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details).
+ * @G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: Allow the anonymous authentication method.
*
- * A handle to an object implementing the #GFileIface interface.
- * Generally stores a location within the file system. Handles do not
- * necessarily represent files or directories that currently exist.
+ * Flags used when creating a #GDBusServer.
+ *
+ * Since: 2.26
*/
/**
- * GFileAttributeInfo:
- * @name: the name of the attribute.
- * @type: the #GFileAttributeType type of the attribute.
- * @flags: a set of #GFileAttributeInfoFlags.
+ * GDBusSignalCallback:
+ * @connection: A #GDBusConnection.
+ * @sender_name: The unique bus name of the sender of the signal.
+ * @object_path: The object path that the signal was emitted on.
+ * @interface_name: The name of the interface.
+ * @signal_name: The name of the signal.
+ * @parameters: A #GVariant tuple with parameters for the signal.
+ * @user_data: User data passed when subscribing to the signal.
*
- * Information about a specific attribute.
+ * Signature for callback function used in g_dbus_connection_signal_subscribe().
+ *
+ * Since: 2.26
*/
/**
- * GFileAttributeInfoFlags:
- * @G_FILE_ATTRIBUTE_INFO_NONE: no flags set.
- * @G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE: copy the attribute values when the file is copied.
- * @G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED: copy the attribute values when the file is moved.
+ * GDBusSignalFlags:
+ * @G_DBUS_SIGNAL_FLAGS_NONE: No flags set.
+ * @G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE: Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually).
*
- * Flags specifying the behaviour of an attribute.
+ * Flags used when subscribing to signals via g_dbus_connection_signal_subscribe().
+ *
+ * Since: 2.26
*/
/**
- * GFileAttributeInfoList:
- * @infos: an array of #GFileAttributeInfo<!-- -->s.
- * @n_infos: the number of values in the array.
+ * GDBusSignalInfo:
+ * @ref_count: The reference count or -1 if statically allocated.
+ * @name: The name of the D-Bus signal, e.g. "NameOwnerChanged".
+ * @args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments.
+ * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
*
- * Acts as a lightweight registry for possible valid file attributes.
- * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s.
+ * Information about a signal on a D-Bus interface.
+ *
+ * Since: 2.26
*/
/**
- * GFileAttributeMatcher:
+ * GDBusSubtreeDispatchFunc:
+ * @connection: A #GDBusConnection.
+ * @sender: The unique bus name of the remote caller.
+ * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
+ * @interface_name: The D-Bus interface name that the method call or property access is for.
+ * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
+ * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
+ * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
- * Determines if a string matches a file attribute.
+ * The type of the @dispatch function in #GDBusSubtreeVTable.
+ * Subtrees are flat. @node, if non-%NULL, is always exactly one
+ *
+ * Segment of the object path (ie: it never contains a slash).
+ * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
+ * Since: 2.26
*/
/**
- * GFileAttributeStatus:
- * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty).
- * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set.
- * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value.
+ * GDBusSubtreeEnumerateFunc:
+ * @connection: A #GDBusConnection.
+ * @sender: The unique bus name of the remote caller.
+ * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
+ * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
- * Used by g_file_set_attributes_from_info() when setting file attributes.
+ * The type of the @enumerate function in #GDBusSubtreeVTable.
+ * This function is called when generating introspection data and also
+ * when preparing to dispatch incoming messages in the event that the
+ * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
+ * Hierarchies are not supported; the items that you return should not
+ * contain the '/' character.
+ * The return value will be freed with g_strfreev().
+ *
+ * Specified (ie: to verify that the object path is valid).
+ * Returns: A newly allocated array of strings for node names that are children of @object_path.
+ * Since: 2.26
*/
/**
- * GFileAttributeType:
- * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type.
- * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string.
- * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes.
- * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value.
- * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer.
- * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject.
- * @G_FILE_ATTRIBUTE_TYPE_STRINGV: a %NULL terminated char **. Since 2.22
+ * GDBusSubtreeFlags:
+ * @G_DBUS_SUBTREE_FLAGS_NONE: No flags set.
+ * @G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES: Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree.
*
- * The data types for file attributes.
+ * Flags passed to g_dbus_connection_register_subtree().
+ *
+ * Since: 2.26
*/
/**
- * GFileCopyFlags:
- * @G_FILE_COPY_NONE: No flags set.
- * @G_FILE_COPY_OVERWRITE: Overwrite any existing files
- * @G_FILE_COPY_BACKUP: Make a backup of any existing files.
- * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks.
- * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo).
- * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported.
- * @G_FILE_COPY_TARGET_DEFAULT_PERMS: Leaves target file with default perms, instead of setting the source file perms.
+ * GDBusSubtreeIntrospectFunc:
+ * @connection: A #GDBusConnection.
+ * @sender: The unique bus name of the remote caller.
+ * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
+ * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
+ * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
- * Flags used when copying or moving files.
+ * The type of the @introspect function in #GDBusSubtreeVTable.
+ * Subtrees are flat. @node, if non-%NULL, is always exactly one
+ * This function should return %NULL to indicate that there is no object
+ * at this node.
+ * If this function returns non-%NULL, the return value is expected to
+ * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
+ * structures describing the interfaces implemented by @node. This
+ * array will have g_dbus_interface_info_unref() called on each item
+ * before being freed with g_free().
+ * The difference between returning %NULL and an array containing zero
+ * items is that the standard DBus interfaces will returned to the
+ * remote introspector in the empty array case, but not in the %NULL
+ * case.
+ *
+ * Segment of the object path (ie: it never contains a slash).
+ * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
+ * Since: 2.26
*/
/**
- * GFileCreateFlags:
- * @G_FILE_CREATE_NONE: No flags set.
- * @G_FILE_CREATE_PRIVATE: Create a file that can only be accessed by the current user.
- * @G_FILE_CREATE_REPLACE_DESTINATION: Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. Since 2.20
+ * GDBusSubtreeVTable:
+ * @enumerate: Function for enumerating child nodes.
+ * @introspect: Function for introspecting a child node.
+ * @dispatch: Function for dispatching a remote call on a child node.
*
- * Flags used when an operation may create a file.
+ * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
+ *
+ * Since: 2.26
*/
/**
- * GFileDescriptorBased:
- *
- * An interface for file descriptor based io objects.
- */
-
-
-/**
- * GFileDescriptorBasedIface:
- * @g_iface: The parent interface.
- *
+ * GDataInputStream:
*
+ * An implementation of #GBufferedInputStream that allows for high-level
+ * data manipulation of arbitrary data (including binary operations).
*/
/**
- * GFileEnumerator:
+ * GDataOutputStream:
*
- * A per matched file iterator.
+ * An implementation of #GBufferedOutputStream that allows for high-level
+ * data manipulation of arbitrary data (including binary operations).
*/
/**
- * GFileIOStream:
+ * GDataOutputStream:byte-order:
*
- * A subclass of GIOStream for opened files. This adds
- * a few file-specific operations and seeking and truncating.
- * #GFileIOStream implements GSeekable.
+ * Determines the byte ordering that is used when writing
+ * multi-byte entities (such as integers) to the stream.
*/
/**
- * GFileIcon:
+ * GDataStream:byte-order:
*
- * Gets an icon for a #GFile. Implements #GLoadableIcon.
+ * The ::byte-order property determines the byte ordering that
+ * is used when reading multi-byte entities (such as integers)
+ * from the stream.
*/
/**
- * GFileIcon:file:
+ * GDataStream:newline-type:
*
- * The file containing the icon.
+ * The :newline-type property determines what is considered
+ * as a line ending when reading complete lines from the stream.
*/
/**
- * GFileIface:
- * @g_iface: The parent interface.
- * @dup: Duplicates a #GFile.
- * @hash: Creates a hash of a #GFile.
- * @equal: Checks equality of two given #GFile<!-- -->s.
- * @is_native: Checks to see if a file is native to the system.
- * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme.
- * @get_uri_scheme: Gets the URI scheme for a #GFile.
- * @get_basename: Gets the basename for a given #GFile.
- * @get_path: Gets the current path within a #GFile.
- * @get_uri: Gets a URI for the path within a #GFile.
- * @get_parse_name: Gets the parsed name for the #GFile.
- * @get_parent: Gets the parent directory for the #GFile.
- * @prefix_matches: Checks whether a #GFile contains a specified file.
- * @get_relative_path: Gets the path for a #GFile relative to a given path.
- * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path.
- * @get_child_for_display_name: Gets the child #GFile for a given display name.
- * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile.
- * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile.
- * @enumerate_children_finish: Finishes asynchronously enumerating the children.
- * @query_info: Gets the #GFileInfo for a #GFile.
- * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile.
- * @query_info_finish: Finishes an asynchronous query info operation.
- * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on.
- * @query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on.
- * @query_filesystem_info_finish: Finishes asynchronously getting the file system info.
- * @find_enclosing_mount: Gets a #GMount for the #GFile.
- * @find_enclosing_mount_async: Asynchronously gets the #GMount for a #GFile.
- * @find_enclosing_mount_finish: Finishes asynchronously getting the volume.
- * @set_display_name: Sets the display name for a #GFile.
- * @set_display_name_async: Asynchronously sets a #GFile's display name.
- * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name.
- * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set.
- * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set.
- * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes.
- * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable.
- * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable.
- * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces.
- * @set_attribute: Sets a #GFileAttribute.
- * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo.
- * @set_attributes_async: Asynchronously sets a file's attributes.
- * @set_attributes_finish: Finishes setting a file's attributes asynchronously.
- * @read_fn: Reads a file asynchronously.
- * @read_async: Asynchronously reads a file.
- * @read_finish: Finishes asynchronously reading a file.
- * @append_to: Writes to the end of a file.
- * @append_to_async: Asynchronously writes to the end of a file.
- * @append_to_finish: Finishes an asynchronous file append operation.
- * @create: Creates a new file.
- * @create_async: Asynchronously creates a file.
- * @create_finish: Finishes asynchronously creating a file.
- * @replace: Replaces the contents of a file.
- * @replace_async: Asynchronously replaces the contents of a file.
- * @replace_finish: Finishes asynchronously replacing a file.
- * @delete_file: Deletes a file.
- * @_delete_file_async: Asynchronously deletes a file.
- * @_delete_file_finish: Finishes an asynchronous delete.
- * @trash: Sends a #GFile to the Trash location.
- * @_trash_async: Asynchronously sends a #GFile to the Trash location.
- * @_trash_finish: Finishes an asynchronous file trashing operation.
- * @make_directory: Makes a directory.
- * @_make_directory_async: Asynchronously makes a directory.
- * @_make_directory_finish: Finishes making a directory asynchronously.
- * @make_symbolic_link: Makes a symbolic link.
- * @_make_symbolic_link_async: Asynchronously makes a symbolic link
- * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously.
- * @copy: Copies a file.
- * @copy_async: Asynchronously copies a file.
- * @copy_finish: Finishes an asynchronous copy operation.
- * @move: Moves a file.
- * @_move_async: Asynchronously moves a file.
- * @_move_finish: Finishes an asynchronous move operation.
- * @mount_mountable: Mounts a mountable object.
- * @mount_mountable_finish: Finishes a mounting operation.
- * @unmount_mountable: Unmounts a mountable object.
- * @unmount_mountable_finish: Finishes an unmount operation.
- * @eject_mountable: Ejects a mountable.
- * @eject_mountable_finish: Finishes an eject operation.
- * @mount_enclosing_volume: Mounts a specified location.
- * @mount_enclosing_volume_finish: Finishes mounting a specified location.
- * @monitor_dir: Creates a #GFileMonitor for the location.
- * @monitor_file: Creates a #GFileMonitor for the location.
- * @open_readwrite: Open file read/write. Since 2.22.
- * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22.
- * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22.
- * @create_readwrite: Creates file read/write. Since 2.22.
- * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22.
- * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22.
- * @replace_readwrite: Replaces file read/write. Since 2.22.
- * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22.
- * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22.
- * @start_mountable: Starts a mountable object. Since 2.22.
- * @start_mountable_finish: Finishes an start operation. Since 2.22.
- * @stop_mountable: Stops a mountable. Since 2.22.
- * @stop_mountable_finish: Finishes an stop operation. Since 2.22.
- * @supports_thread_contexts: a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.
- * @unmount_mountable_with_operation: Unmounts a mountable object using a #GMountOperation. Since 2.22.
- * @unmount_mountable_with_operation_finish: Finishes an unmount operation using a #GMountOperation. Since 2.22.
- * @eject_mountable_with_operation: Ejects a mountable object using a #GMountOperation. Since 2.22.
- * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
- * @poll_mountable: Polls a mountable object for media changes. Since 2.22.
- * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22.
+ * GDataStreamByteOrder:
+ * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order.
+ * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order.
+ * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture.
*
- * An interface for writing VFS file handles.
+ * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources
+ * across various machine architectures.
*/
/**
- * GFileInfo:
+ * GDataStreamNewlineType:
+ * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms.
+ * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings.
+ * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows.
+ * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type.
*
- * Stores information about a file system object referenced by a #GFile.
+ * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
*/
/**
- * GFileInputStream:
+ * GDateTime:
*
- * A subclass of GInputStream for opened files. This adds
- * a few file-specific operations and seeking.
- * #GFileInputStream implements #GSeekable.
- */
-
-
-/**
- * GFileMonitor:
+ * <structname>GDateTime</structname> is an opaque structure whose members
+ * cannot be accessed directly.
*
- * Watches for changes to a file.
+ * Since: 2.26
*/
/**
- * GFileMonitor::changed:
- * @monitor: a #GFileMonitor.
- * @file: a #GFile.
- * @other_file: a #GFile or #NULL.
- * @event_type: a #GFileMonitorEvent.
+ * GDebugKey:
+ * @key: the string
+ * @value: the flag
*
- * Emitted when @file has been changed.
- * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
- * #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the
- * old path, and @other_file will be set to a #GFile containing the new path.
- * In all the other cases, @other_file will be set to #NULL.
+ * Associates a string with a bit flag.
+ * Used in g_parse_debug_string().
*/
/**
- * GFileMonitorEvent:
- * @G_FILE_MONITOR_EVENT_CHANGED: a file changed.
- * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes.
- * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted.
- * @G_FILE_MONITOR_EVENT_CREATED: a file was created.
- * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed.
- * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted.
- * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was unmounted.
- * @G_FILE_MONITOR_EVENT_MOVED: the file was moved.
+ * GDesktopAppInfo:
*
- * Specifies what type of event a monitor event is.
+ * Information about an installed application from a desktop file.
*/
/**
- * GFileMonitorFlags:
- * @G_FILE_MONITOR_NONE: No flags set.
- * @G_FILE_MONITOR_WATCH_MOUNTS: Watch for mount events.
- * @G_FILE_MONITOR_SEND_MOVED: Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events).
+ * GDesktopAppInfo:filename:
*
- * Flags used to set what a #GFileMonitor will watch for.
+ * The origin filename of this #GDesktopAppInfo
*/
/**
- * GFileOutputStream:
+ * GDrive:
*
- * A subclass of GOutputStream for opened files. This adds
- * a few file-specific operations and seeking and truncating.
- * #GFileOutputStream implements GSeekable.
+ * Opaque drive object.
*/
/**
- * GFileProgressCallback:
- * @current_num_bytes: the current number of bytes in the operation.
- * @total_num_bytes: the total number of bytes in the operation.
- * @user_data: user data passed to the callback.
+ * GDrive::changed:
+ * @drive: a #GDrive.
*
- * When doing file operations that may take a while, such as moving
- * a file or copying a file, a progress callback is used to pass how
- * far along that operation is to the application.
+ * Emitted when the drive's state has changed.
*/
/**
- * GFileQueryInfoFlags:
- * @G_FILE_QUERY_INFO_NONE: No flags set.
- * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: Don't follow symlinks.
+ * GDrive::disconnected:
+ * @drive: a #GDrive.
*
- * Flags used when querying a #GFileInfo.
+ * 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.
*/
/**
- * GFileReadMoreCallback:
- * @file_contents: the data as currently read.
- * @file_size: the size of the data currently read.
- * @callback_data: data passed to the callback.
- *
- * When loading the partial contents of a file with g_file_load_partial_contents_async(),
- * it may become necessary to determine if any more data from the file should be loaded.
- * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data
- * should be read, or %FALSE otherwise.
+ * GDrive::eject-button:
+ * @drive: a #GDrive.
*
- * Returns: %TRUE if more data should be read back. %FALSE otherwise.
+ * Emitted when the physical eject button (if any) of a drive has
+ * been pressed.
*/
/**
- * GFileType:
- * @G_FILE_TYPE_UNKNOWN: File's type is unknown.
- * @G_FILE_TYPE_REGULAR: File handle represents a regular file.
- * @G_FILE_TYPE_DIRECTORY: File handle represents a directory.
- * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems).
- * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, block device, or character device.
- * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems).
- * @G_FILE_TYPE_MOUNTABLE: File is a mountable location.
+ * GDrive::stop-button:
+ * @drive: a #GDrive.
*
- * Indicates the file's on-disk type.
- */
-
-
-/**
- * GFilenameCompleter:
+ * Emitted when the physical stop button (if any) of a drive has
+ * been pressed.
*
- * Completes filenames based on files that exist within the file system.
+ * Since: 2.22
*/
/**
- * GFilenameCompleter::got-completion-data:
- *
- * Emitted when the file name completion information comes available.
- */
-
-
+ * GDriveIface:
+ * @g_iface: The parent interface.
+ * @changed: Signal emitted when the drive is changed.
+ * @disconnected: The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.
+ * @eject_button: Signal emitted when the physical eject button (if any) of a drive have been pressed.
+ * @get_name: Returns the name for the given #GDrive.
+ * @get_icon: Returns a #GIcon for the given #GDrive.
+ * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes.
+ * @get_volumes: Returns a list #GList of #GVolume for the #GDrive.
+ * @is_media_removable: Returns %TRUE if the #GDrive supports removal and insertion of media.
+ * @has_media: Returns %TRUE if the #GDrive has media inserted.
+ * @is_media_check_automatic: Returns %TRUE if the #GDrive is capabable of automatically detecting media changes.
+ * @can_poll_for_media: Returns %TRUE if the #GDrive is capable of manually polling for media change.
+ * @can_eject: Returns %TRUE if the #GDrive can eject media.
+ * @eject: Ejects a #GDrive.
+ * @eject_finish: Finishes an eject operation.
+ * @poll_for_media: Poll for media insertion/removal on a #GDrive.
+ * @poll_for_media_finish: Finishes a media poll operation.
+ * @get_identifier: Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one.
+ * @enumerate_identifiers: Returns an array strings listing the kinds of identifiers which the #GDrive has.
+ * @get_start_stop_type: Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22.
+ * @can_stop: Returns %TRUE if a #GDrive can be stopped. Since 2.22.
+ * @stop: Stops a #GDrive. Since 2.22.
+ * @stop_finish: Finishes a stop operation. Since 2.22.
+ * @can_start: Returns %TRUE if a #GDrive can be started. Since 2.22.
+ * @can_start_degraded: Returns %TRUE if a #GDrive can be started degraded. Since 2.22.
+ * @start: Starts a #GDrive. Since 2.22.
+ * @start_finish: Finishes a start operation. Since 2.22.
+ * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.
+ * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22.
+ * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ *
+ * Interface for creating #GDrive implementations.
+ */
+
+
/**
- * GFilesystemPreviewType:
- * @G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS: Only preview files if user has explicitly requested it.
- * @G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL: Preview files if user has requested preview of "local" files.
- * @G_FILESYSTEM_PREVIEW_TYPE_NEVER: Never preview files.
+ * GDriveStartFlags:
+ * @G_DRIVE_START_NONE: No flags set.
*
- * 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.
+ * Flags used when starting a drive.
+ *
+ * Since: 2.22
*/
/**
- * GFilterInputStream:
+ * GDriveStartStopType:
+ * @G_DRIVE_START_STOP_TYPE_UNKNOWN: Unknown or drive doesn't support start/stop.
+ * @G_DRIVE_START_STOP_TYPE_SHUTDOWN: The stop method will physically shut down the drive and e.g. power down the port the drive is attached to.
+ * @G_DRIVE_START_STOP_TYPE_NETWORK: The start/stop methods are used for connecting/disconnect to the drive over the network.
+ * @G_DRIVE_START_STOP_TYPE_MULTIDISK: The start/stop methods will assemble/disassemble a virtual drive from several physical drives.
+ * @G_DRIVE_START_STOP_TYPE_PASSWORD: The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command)
*
- * A base class for all input streams that work on an underlying stream.
+ * Enumeration describing how a drive can be started/stopped.
+ *
+ * Since: 2.22
*/
/**
- * GFilterOutputStream:
+ * GEmblem:
*
- * A base class for all output streams that work on an underlying stream.
+ * An object for Emblems
*/
/**
- * GFlagsClass:
+ * GEmblemOrigin:
+ * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin
+ * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information
+ * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly"
+ * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)
+ *
+ * GEmblemOrigin is used to add information about the origin of the emblem
+ * to #GEmblem.
+ *
+ * Since: 2.18
+ */
+
+
+/**
+ * GEmblemedIcon:
+ *
+ * An implementation of #GIcon for icons with emblems.
+ */
+
+
+/**
+ * GEnumClass:
* @g_type_class: the parent class
- * @mask: a mask covering all possible values.
+ * @minimum: the smallest possible value.
+ * @maximum: the largest possible value.
* @n_values: the number of possible values.
- * @values: an array of #GFlagsValue structs describing the individual values.
+ * @values: an array of #GEnumValue structs describing the individual values.
*
- * The class of a flags type holds information about its
+ * The class of an enumeration type holds information about its
* possible values.
*/
/**
- * GFlagsValue:
- * @value: the flags value
+ * GEnumValue:
+ * @value: the enum value
* @value_name: the name of the value
* @value_nick: the nickname of the value
*
- * A structure which contains a single flags value, its name, and its
+ * A structure which contains a single enum value, its name, and its
* nickname.
*/
/**
- * GIOErrorEnum:
- * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
- * @G_IO_ERROR_NOT_FOUND: File not found error.
- * @G_IO_ERROR_EXISTS: File already exists error.
- * @G_IO_ERROR_IS_DIRECTORY: File is a directory error.
- * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory.
- * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty.
- * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file.
- * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link.
- * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted.
- * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters.
- * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters.
- * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links.
- * @G_IO_ERROR_NO_SPACE: No space left on drive.
- * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument.
- * @G_IO_ERROR_PERMISSION_DENIED: Permission denied.
- * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend.
- * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted.
- * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted.
- * @G_IO_ERROR_CLOSED: File was closed.
- * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable.
- * @G_IO_ERROR_PENDING: Operations are still pending.
- * @G_IO_ERROR_READ_ONLY: File is read only.
- * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created.
- * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect.
- * @G_IO_ERROR_TIMED_OUT: Operation timed out.
- * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive.
- * @G_IO_ERROR_BUSY: File is busy.
- * @G_IO_ERROR_WOULD_BLOCK: Operation would block.
- * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations).
- * @G_IO_ERROR_WOULD_MERGE: Operation would merge files.
- * @G_IO_ERROR_FAILED_HANDLED: Operation failed and a helper program has already interacted with the user. Do not display any error dialog.
- * @G_IO_ERROR_TOO_MANY_OPEN_FILES: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20
- * @G_IO_ERROR_NOT_INITIALIZED: The object has not been initialized. Since 2.22
- * @G_IO_ERROR_ADDRESS_IN_USE: The requested address is already in use. Since 2.22
- * @G_IO_ERROR_PARTIAL_INPUT: Need more input to finish operation. Since 2.24
- * @G_IO_ERROR_INVALID_DATA: There input data was invalid. Since 2.24
- * @G_IO_ERROR_DBUS_ERROR: A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26.
- * @G_IO_ERROR_HOST_UNREACHABLE: Host unreachable. Since 2.26
- * @G_IO_ERROR_NETWORK_UNREACHABLE: Network unreachable. Since 2.26
- * @G_IO_ERROR_CONNECTION_REFUSED: Connection refused. Since 2.26
- * @G_IO_ERROR_PROXY_FAILED: Connection to proxy server failed. Since 2.26
- * @G_IO_ERROR_PROXY_AUTH_FAILED: Proxy authentication failed. Since 2.26
- * @G_IO_ERROR_PROXY_NEED_AUTH: Proxy server needs authentication. Since 2.26
- * @G_IO_ERROR_PROXY_NOT_ALLOWED: Proxy connection is not allowed by ruleset. Since 2.26
+ * GFile:
*
- * Error codes returned by GIO functions.
+ * A handle to an object implementing the #GFileIface interface.
+ * Generally stores a location within the file system. Handles do not
+ * necessarily represent files or directories that currently exist.
*/
/**
- * GIOModule:
+ * GFileAttributeInfo:
+ * @name: the name of the attribute.
+ * @type: the #GFileAttributeType type of the attribute.
+ * @flags: a set of #GFileAttributeInfoFlags.
*
- * Opaque module base class for extending GIO.
+ * Information about a specific attribute.
*/
/**
- * GIOSchedulerJob:
+ * GFileAttributeInfoFlags:
+ * @G_FILE_ATTRIBUTE_INFO_NONE: no flags set.
+ * @G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE: copy the attribute values when the file is copied.
+ * @G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED: copy the attribute values when the file is moved.
*
- * Opaque class for definining and scheduling IO jobs.
+ * Flags specifying the behaviour of an attribute.
*/
/**
- * GIOSchedulerJobFunc:
- * @job: a #GIOSchedulerJob.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @user_data: the data to pass to callback function
- *
- * I/O Job function.
- * Note that depending on whether threads are available, the
- * #GIOScheduler may run jobs in separate threads or in an idle
- * in the mainloop.
- * Long-running jobs should periodically check the @cancellable
- * to see if they have been cancelled.
- * complete the job, %FALSE if the job is complete (or cancelled)
+ * GFileAttributeInfoList:
+ * @infos: an array of #GFileAttributeInfo<!-- -->s.
+ * @n_infos: the number of values in the array.
*
- * Returns: %TRUE if this function should be called again to
+ * Acts as a lightweight registry for possible valid file attributes.
+ * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s.
*/
/**
- * GIOStream:
+ * GFileAttributeMatcher:
*
- * Base class for read-write streams.
+ * Determines if a string matches a file attribute.
*/
/**
- * GIOStreamSpliceFlags:
- * @G_IO_STREAM_SPLICE_NONE: Do not close either stream.
- * @G_IO_STREAM_SPLICE_CLOSE_STREAM1: Close the first stream after the splice.
- * @G_IO_STREAM_SPLICE_CLOSE_STREAM2: Close the second stream after the splice.
- * @G_IO_STREAM_SPLICE_WAIT_FOR_BOTH: Wait for both splice operations to finish before calling the callback.
- *
- * GIOStreamSpliceFlags determine how streams should be spliced.
+ * GFileAttributeStatus:
+ * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty).
+ * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set.
+ * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value.
*
- * Since: 2.28
+ * Used by g_file_set_attributes_from_info() when setting file attributes.
*/
/**
- * GIcon:
+ * GFileAttributeType:
+ * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type.
+ * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string.
+ * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes.
+ * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value.
+ * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject.
+ * @G_FILE_ATTRIBUTE_TYPE_STRINGV: a %NULL terminated char **. Since 2.22
*
- * An abstract type that specifies an icon.
+ * The data types for file attributes.
*/
/**
- * GIconIface:
- * @g_iface: The parent interface.
- * @hash: A hash for a given #GIcon.
- * @equal: Checks if two #GIcon<!-- -->s are equal.
- * @to_tokens: Serializes a #GIcon into tokens. The tokens must not contain any whitespace. Don't implement if the #GIcon can't be serialized (Since 2.20).
- * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if the tokens are malformed. Don't implement if the #GIcon can't be serialized (Since 2.20).
+ * GFileCopyFlags:
+ * @G_FILE_COPY_NONE: No flags set.
+ * @G_FILE_COPY_OVERWRITE: Overwrite any existing files
+ * @G_FILE_COPY_BACKUP: Make a backup of any existing files.
+ * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks.
+ * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo).
+ * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported.
+ * @G_FILE_COPY_TARGET_DEFAULT_PERMS: Leaves target file with default perms, instead of setting the source file perms.
*
- * GIconIface is used to implement GIcon types for various
- * different systems. See #GThemedIcon and #GLoadableIcon for
- * examples of how to implement this interface.
+ * Flags used when copying or moving files.
*/
/**
- * GIconv:
+ * GFileCreateFlags:
+ * @G_FILE_CREATE_NONE: No flags set.
+ * @G_FILE_CREATE_PRIVATE: Create a file that can only be accessed by the current user.
+ * @G_FILE_CREATE_REPLACE_DESTINATION: Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. Since 2.20
*
- * The <structname>GIConv</structname> struct wraps an
- * iconv() conversion descriptor. It contains private data
- * and should only be accessed using the following functions.
+ * Flags used when an operation may create a file.
*/
/**
- * GInetAddress:
+ * GFileEnumerator:
*
- * An IPv4 or IPv6 internet address.
+ * A per matched file iterator.
*/
/**
- * GInetAddress:is-any:
- *
- * Whether this is the "any" address for its family.
- * See g_inet_address_get_is_any().
+ * GFileIOStream:
*
- * Since: 2.22
+ * A subclass of GIOStream for opened files. This adds
+ * a few file-specific operations and seeking and truncating.
+ * #GFileIOStream implements GSeekable.
*/
/**
- * GInetAddress:is-link-local:
+ * GFileIcon:
*
- * Whether this is a link-local address.
- * See g_inet_address_get_is_link_local().
- *
- * Since: 2.22
+ * Gets an icon for a #GFile. Implements #GLoadableIcon.
*/
/**
- * GInetAddress:is-loopback:
- *
- * Whether this is the loopback address for its family.
- * See g_inet_address_get_is_loopback().
+ * GFileIcon:file:
*
- * Since: 2.22
+ * The file containing the icon.
*/
/**
- * GInetAddress:is-mc-global:
- *
- * Whether this is a global multicast address.
- * See g_inet_address_get_is_mc_global().
+ * GFileIface:
+ * @g_iface: The parent interface.
+ * @dup: Duplicates a #GFile.
+ * @hash: Creates a hash of a #GFile.
+ * @equal: Checks equality of two given #GFile<!-- -->s.
+ * @is_native: Checks to see if a file is native to the system.
+ * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme.
+ * @get_uri_scheme: Gets the URI scheme for a #GFile.
+ * @get_basename: Gets the basename for a given #GFile.
+ * @get_path: Gets the current path within a #GFile.
+ * @get_uri: Gets a URI for the path within a #GFile.
+ * @get_parse_name: Gets the parsed name for the #GFile.
+ * @get_parent: Gets the parent directory for the #GFile.
+ * @prefix_matches: Checks whether a #GFile contains a specified file.
+ * @get_relative_path: Gets the path for a #GFile relative to a given path.
+ * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path.
+ * @get_child_for_display_name: Gets the child #GFile for a given display name.
+ * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile.
+ * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile.
+ * @enumerate_children_finish: Finishes asynchronously enumerating the children.
+ * @query_info: Gets the #GFileInfo for a #GFile.
+ * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile.
+ * @query_info_finish: Finishes an asynchronous query info operation.
+ * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on.
+ * @query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on.
+ * @query_filesystem_info_finish: Finishes asynchronously getting the file system info.
+ * @find_enclosing_mount: Gets a #GMount for the #GFile.
+ * @find_enclosing_mount_async: Asynchronously gets the #GMount for a #GFile.
+ * @find_enclosing_mount_finish: Finishes asynchronously getting the volume.
+ * @set_display_name: Sets the display name for a #GFile.
+ * @set_display_name_async: Asynchronously sets a #GFile's display name.
+ * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name.
+ * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set.
+ * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set.
+ * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes.
+ * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable.
+ * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable.
+ * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces.
+ * @set_attribute: Sets a #GFileAttribute.
+ * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo.
+ * @set_attributes_async: Asynchronously sets a file's attributes.
+ * @set_attributes_finish: Finishes setting a file's attributes asynchronously.
+ * @read_fn: Reads a file asynchronously.
+ * @read_async: Asynchronously reads a file.
+ * @read_finish: Finishes asynchronously reading a file.
+ * @append_to: Writes to the end of a file.
+ * @append_to_async: Asynchronously writes to the end of a file.
+ * @append_to_finish: Finishes an asynchronous file append operation.
+ * @create: Creates a new file.
+ * @create_async: Asynchronously creates a file.
+ * @create_finish: Finishes asynchronously creating a file.
+ * @replace: Replaces the contents of a file.
+ * @replace_async: Asynchronously replaces the contents of a file.
+ * @replace_finish: Finishes asynchronously replacing a file.
+ * @delete_file: Deletes a file.
+ * @_delete_file_async: Asynchronously deletes a file.
+ * @_delete_file_finish: Finishes an asynchronous delete.
+ * @trash: Sends a #GFile to the Trash location.
+ * @_trash_async: Asynchronously sends a #GFile to the Trash location.
+ * @_trash_finish: Finishes an asynchronous file trashing operation.
+ * @make_directory: Makes a directory.
+ * @_make_directory_async: Asynchronously makes a directory.
+ * @_make_directory_finish: Finishes making a directory asynchronously.
+ * @make_symbolic_link: Makes a symbolic link.
+ * @_make_symbolic_link_async: Asynchronously makes a symbolic link
+ * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously.
+ * @copy: Copies a file.
+ * @copy_async: Asynchronously copies a file.
+ * @copy_finish: Finishes an asynchronous copy operation.
+ * @move: Moves a file.
+ * @_move_async: Asynchronously moves a file.
+ * @_move_finish: Finishes an asynchronous move operation.
+ * @mount_mountable: Mounts a mountable object.
+ * @mount_mountable_finish: Finishes a mounting operation.
+ * @unmount_mountable: Unmounts a mountable object.
+ * @unmount_mountable_finish: Finishes an unmount operation.
+ * @eject_mountable: Ejects a mountable.
+ * @eject_mountable_finish: Finishes an eject operation.
+ * @mount_enclosing_volume: Mounts a specified location.
+ * @mount_enclosing_volume_finish: Finishes mounting a specified location.
+ * @monitor_dir: Creates a #GFileMonitor for the location.
+ * @monitor_file: Creates a #GFileMonitor for the location.
+ * @open_readwrite: Open file read/write. Since 2.22.
+ * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22.
+ * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22.
+ * @create_readwrite: Creates file read/write. Since 2.22.
+ * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22.
+ * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22.
+ * @replace_readwrite: Replaces file read/write. Since 2.22.
+ * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22.
+ * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22.
+ * @start_mountable: Starts a mountable object. Since 2.22.
+ * @start_mountable_finish: Finishes an start operation. Since 2.22.
+ * @stop_mountable: Stops a mountable. Since 2.22.
+ * @stop_mountable_finish: Finishes an stop operation. Since 2.22.
+ * @supports_thread_contexts: a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.
+ * @unmount_mountable_with_operation: Unmounts a mountable object using a #GMountOperation. Since 2.22.
+ * @unmount_mountable_with_operation_finish: Finishes an unmount operation using a #GMountOperation. Since 2.22.
+ * @eject_mountable_with_operation: Ejects a mountable object using a #GMountOperation. Since 2.22.
+ * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ * @poll_mountable: Polls a mountable object for media changes. Since 2.22.
+ * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22.
*
- * Since: 2.22
+ * An interface for writing VFS file handles.
*/
/**
- * GInetAddress:is-mc-link-local:
- *
- * Whether this is a link-local multicast address.
- * See g_inet_address_get_is_mc_link_local().
+ * GFileInfo:
*
- * Since: 2.22
+ * Stores information about a file system object referenced by a #GFile.
*/
/**
- * GInetAddress:is-mc-node-local:
- *
- * Whether this is a node-local multicast address.
- * See g_inet_address_get_is_mc_node_local().
+ * GFileInputStream:
*
- * Since: 2.22
+ * A subclass of GInputStream for opened files. This adds
+ * a few file-specific operations and seeking.
+ * #GFileInputStream implements #GSeekable.
*/
/**
- * GInetAddress:is-mc-org-local:
- *
- * Whether this is an organization-local multicast address.
- * See g_inet_address_get_is_mc_org_local().
+ * GFileMonitor:
*
- * Since: 2.22
+ * Watches for changes to a file.
*/
/**
- * GInetAddress:is-mc-site-local:
- *
- * Whether this is a site-local multicast address.
- * See g_inet_address_get_is_mc_site_local().
+ * GFileMonitor::changed:
+ * @monitor: a #GFileMonitor.
+ * @file: a #GFile.
+ * @other_file: a #GFile or #NULL.
+ * @event_type: a #GFileMonitorEvent.
*
- * Since: 2.22
+ * Emitted when @file has been changed.
+ * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
+ * #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the
+ * old path, and @other_file will be set to a #GFile containing the new path.
+ * In all the other cases, @other_file will be set to #NULL.
*/
/**
- * GInetAddress:is-multicast:
- *
- * Whether this is a multicast address.
- * See g_inet_address_get_is_multicast().
+ * GFileMonitorEvent:
+ * @G_FILE_MONITOR_EVENT_CHANGED: a file changed.
+ * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes.
+ * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted.
+ * @G_FILE_MONITOR_EVENT_CREATED: a file was created.
+ * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed.
+ * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted.
+ * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was unmounted.
+ * @G_FILE_MONITOR_EVENT_MOVED: the file was moved.
*
- * Since: 2.22
+ * Specifies what type of event a monitor event is.
*/
/**
- * GInetAddress:is-site-local:
- *
- * Whether this is a site-local address.
- * See g_inet_address_get_is_loopback().
+ * GFileMonitorFlags:
+ * @G_FILE_MONITOR_NONE: No flags set.
+ * @G_FILE_MONITOR_WATCH_MOUNTS: Watch for mount events.
+ * @G_FILE_MONITOR_SEND_MOVED: Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events).
*
- * Since: 2.22
+ * Flags used to set what a #GFileMonitor will watch for.
*/
/**
- * GInetSocketAddress:
+ * GFileOutputStream:
*
- * An IPv4 or IPv6 socket address, corresponding to a <type>struct
- * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
+ * A subclass of GOutputStream for opened files. This adds
+ * a few file-specific operations and seeking and truncating.
+ * #GFileOutputStream implements GSeekable.
*/
/**
- * GInitable:
- *
- * Interface for initializable objects.
+ * GFileProgressCallback:
+ * @current_num_bytes: the current number of bytes in the operation.
+ * @total_num_bytes: the total number of bytes in the operation.
+ * @user_data: user data passed to the callback.
*
- * Since: 2.22
+ * When doing file operations that may take a while, such as moving
+ * a file or copying a file, a progress callback is used to pass how
+ * far along that operation is to the application.
*/
/**
- * GInitableIface:
- * @g_iface: The parent interface.
- * @init: Initializes the object.
- *
- * Provides an interface for initializing object such that initialization
- * may fail.
+ * GFileQueryInfoFlags:
+ * @G_FILE_QUERY_INFO_NONE: No flags set.
+ * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: Don't follow symlinks.
*
- * Since: 2.22
+ * Flags used when querying a #GFileInfo.
*/
/**
- * GInitiallyUnowned:
+ * GFileReadMoreCallback:
+ * @file_contents: the data as currently read.
+ * @file_size: the size of the data currently read.
+ * @callback_data: data passed to the callback.
*
- * All the fields in the <structname>GInitiallyUnowned</structname> structure
- * are private to the #GInitiallyUnowned implementation and should never be
- * accessed directly.
+ * When loading the partial contents of a file with g_file_load_partial_contents_async(),
+ * it may become necessary to determine if any more data from the file should be loaded.
+ * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data
+ * should be read, or %FALSE otherwise.
+ *
+ * Returns: %TRUE if more data should be read back. %FALSE otherwise.
*/
/**
- * GInitiallyUnownedClass:
+ * GFileType:
+ * @G_FILE_TYPE_UNKNOWN: File's type is unknown.
+ * @G_FILE_TYPE_REGULAR: File handle represents a regular file.
+ * @G_FILE_TYPE_DIRECTORY: File handle represents a directory.
+ * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems).
+ * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, block device, or character device.
+ * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems).
+ * @G_FILE_TYPE_MOUNTABLE: File is a mountable location.
*
- * The class structure for the <structname>GInitiallyUnowned</structname> type.
+ * Indicates the file's on-disk type.
*/
/**
- * GInputStream:
+ * GFilenameCompleter:
*
- * Base class for streaming input operations.
+ * Completes filenames based on files that exist within the file system.
*/
/**
- * GInputVector:
- * @buffer: Pointer to a buffer where data will be written.
- * @size: the available size in @buffer.
- *
- * Structure used for scatter/gather data input.
- * You generally pass in an array of #GInputVector<!-- -->s
- * and the operation will store the read data starting in the
- * first buffer, switching to the next as needed.
+ * GFilenameCompleter::got-completion-data:
*
- * Since: 2.22
+ * Emitted when the file name completion information comes available.
*/
/**
- * GInstanceInitFunc:
- * @instance: The instance to initialize.
- * @g_class: The class of the type the instance is created for.
- *
- * A callback function used by the type system to initialize a new
- * instance of a type. This function initializes all instance members and
- * allocates any resources required by it.
- * Initialization of a derived instance involves calling all its parent
- * types instance initializers, so the class member of the instance
- * is altered during its initialization to always point to the class that
- * belongs to the type the current initializer was introduced for.
+ * GFilesystemPreviewType:
+ * @G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS: Only preview files if user has explicitly requested it.
+ * @G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL: Preview files if user has requested preview of "local" files.
+ * @G_FILESYSTEM_PREVIEW_TYPE_NEVER: Never preview files.
+ *
+ * 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.
*/
/**
- * GInterfaceFinalizeFunc:
- * @g_iface: The interface structure to finalize.
- * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ * GFilterInputStream:
*
- * A callback function used by the type system to finalize an interface.
- * This function should destroy any internal data and release any resources
- * allocated by the corresponding GInterfaceInitFunc() function.
+ * A base class for all input streams that work on an underlying stream.
*/
/**
- * GInterfaceInfo:
- * @interface_init: location of the interface initialization function
- * @interface_finalize: location of the interface finalization function
- * @interface_data: user-supplied data passed to the interface init/finalize functions
+ * GFilterOutputStream:
*
- * A structure that provides information to the type system which is
- * used specifically for managing interface types.
+ * A base class for all output streams that work on an underlying stream.
*/
/**
- * GInterfaceInitFunc:
- * @g_iface: The interface structure to initialize.
- * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ * GFlagsClass:
+ * @g_type_class: the parent class
+ * @mask: a mask covering all possible values.
+ * @n_values: the number of possible values.
+ * @values: an array of #GFlagsValue structs describing the individual values.
*
- * A callback function used by the type system to initialize a new
- * interface. This function should initialize all internal data and
- * allocate any resources required by the interface.
+ * The class of a flags type holds information about its
+ * possible values.
*/
/**
- * GLoadableIcon:
+ * GFlagsValue:
+ * @value: the flags value
+ * @value_name: the name of the value
+ * @value_nick: the nickname of the value
*
- * Generic type for all kinds of icons that can be loaded
- * as a stream.
+ * A structure which contains a single flags value, its name, and its
+ * nickname.
*/
/**
- * GLoadableIconIface:
- * @g_iface: The parent interface.
- * @load: Loads an icon.
- * @load_async: Loads an icon asynchronously.
- * @load_finish: Finishes an asynchronous icon load.
+ * GFreeFunc:
+ * @data: a data pointer
*
- * Interface for icons that can be loaded as a stream.
+ * Declares a type of function which takes an arbitrary
+ * data pointer argument and has no return value. It is
+ * not currently used in GLib or GTK+.
*/
/**
- * GMainContext:
+ * GIOErrorEnum:
+ * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
+ * @G_IO_ERROR_NOT_FOUND: File not found error.
+ * @G_IO_ERROR_EXISTS: File already exists error.
+ * @G_IO_ERROR_IS_DIRECTORY: File is a directory error.
+ * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory.
+ * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty.
+ * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file.
+ * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link.
+ * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted.
+ * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters.
+ * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters.
+ * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links.
+ * @G_IO_ERROR_NO_SPACE: No space left on drive.
+ * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument.
+ * @G_IO_ERROR_PERMISSION_DENIED: Permission denied.
+ * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend.
+ * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted.
+ * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted.
+ * @G_IO_ERROR_CLOSED: File was closed.
+ * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable.
+ * @G_IO_ERROR_PENDING: Operations are still pending.
+ * @G_IO_ERROR_READ_ONLY: File is read only.
+ * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created.
+ * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect.
+ * @G_IO_ERROR_TIMED_OUT: Operation timed out.
+ * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive.
+ * @G_IO_ERROR_BUSY: File is busy.
+ * @G_IO_ERROR_WOULD_BLOCK: Operation would block.
+ * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations).
+ * @G_IO_ERROR_WOULD_MERGE: Operation would merge files.
+ * @G_IO_ERROR_FAILED_HANDLED: Operation failed and a helper program has already interacted with the user. Do not display any error dialog.
+ * @G_IO_ERROR_TOO_MANY_OPEN_FILES: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20
+ * @G_IO_ERROR_NOT_INITIALIZED: The object has not been initialized. Since 2.22
+ * @G_IO_ERROR_ADDRESS_IN_USE: The requested address is already in use. Since 2.22
+ * @G_IO_ERROR_PARTIAL_INPUT: Need more input to finish operation. Since 2.24
+ * @G_IO_ERROR_INVALID_DATA: There input data was invalid. Since 2.24
+ * @G_IO_ERROR_DBUS_ERROR: A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26.
+ * @G_IO_ERROR_HOST_UNREACHABLE: Host unreachable. Since 2.26
+ * @G_IO_ERROR_NETWORK_UNREACHABLE: Network unreachable. Since 2.26
+ * @G_IO_ERROR_CONNECTION_REFUSED: Connection refused. Since 2.26
+ * @G_IO_ERROR_PROXY_FAILED: Connection to proxy server failed. Since 2.26
+ * @G_IO_ERROR_PROXY_AUTH_FAILED: Proxy authentication failed. Since 2.26
+ * @G_IO_ERROR_PROXY_NEED_AUTH: Proxy server needs authentication. Since 2.26
+ * @G_IO_ERROR_PROXY_NOT_ALLOWED: Proxy connection is not allowed by ruleset. Since 2.26
*
- * The <structname>GMainContext</structname> struct is an opaque data
- * type representing a set of sources to be handled in a main loop.
+ * Error codes returned by GIO functions.
*/
/**
- * GMainLoop:
+ * GIOModule:
*
- * The <structname>GMainLoop</structname> struct is an opaque data type
- * representing the main event loop of a GLib or GTK+ application.
+ * Opaque module base class for extending GIO.
*/
/**
- * GMarkupError:
- * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
- * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
- * @G_MARKUP_ERROR_PARSE: document was ill-formed
- * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
- * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
- * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid
- * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing
+ * GIOSchedulerJob:
*
- * Error codes returned by markup parsing.
+ * Opaque class for definining and scheduling IO jobs.
*/
/**
- * GMarkupParseContext:
+ * GIOSchedulerJobFunc:
+ * @job: a #GIOSchedulerJob.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @user_data: the data to pass to callback function
*
- * A parse context is used to parse a stream of bytes that
- * you expect to contain marked-up text.
- * See g_markup_parse_context_new(), #GMarkupParser, and so
- * on for more details.
+ * I/O Job function.
+ * Note that depending on whether threads are available, the
+ * #GIOScheduler may run jobs in separate threads or in an idle
+ * in the mainloop.
+ * Long-running jobs should periodically check the @cancellable
+ * to see if they have been cancelled.
+ * complete the job, %FALSE if the job is complete (or cancelled)
+ *
+ * Returns: %TRUE if this function should be called again to
*/
/**
- * GMarkupParseFlags:
- * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
- * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12
- * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions
+ * GIOStream:
*
- * Flags that affect the behaviour of the parser.
+ * Base class for read-write streams.
*/
/**
- * GMarkupParser:
- * @start_element: Callback to invoke when the opening tag of an element is seen.
- * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>.
- * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections.
- * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections.
- * @error: Callback to invoke when an error occurs.
+ * GIOStreamSpliceFlags:
+ * @G_IO_STREAM_SPLICE_NONE: Do not close either stream.
+ * @G_IO_STREAM_SPLICE_CLOSE_STREAM1: Close the first stream after the splice.
+ * @G_IO_STREAM_SPLICE_CLOSE_STREAM2: Close the second stream after the splice.
+ * @G_IO_STREAM_SPLICE_WAIT_FOR_BOTH: Wait for both splice operations to finish before calling the callback.
*
- * Any of the fields in #GMarkupParser can be %NULL, in which case they
- * will be ignored. Except for the @error function, any of these callbacks
- * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
- * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
- * errors are intended to be set from these callbacks. If you set an error
- * from a callback, g_markup_parse_context_parse() will report that error
- * back to its caller.
+ * GIOStreamSpliceFlags determine how streams should be spliced.
+ *
+ * Since: 2.28
*/
/**
- * GMemVTable:
- * @malloc: function to use for allocating memory.
- * @realloc: function to use for reallocating memory.
- * @free: function to use to free memory.
- * @calloc: function to use for allocating zero-filled memory.
- * @try_malloc: function to use for allocating memory without a default error handler.
- * @try_realloc: function to use for reallocating memory without a default error handler.
+ * GIcon:
*
- * A set of functions used to perform memory allocation. The same #GMemVTable must
- * be used for all allocations in the same program; a call to g_mem_set_vtable(),
- * if it exists, should be prior to any use of GLib.
+ * An abstract type that specifies an icon.
*/
/**
- * GMemoryInputStream:
+ * GIconIface:
+ * @g_iface: The parent interface.
+ * @hash: A hash for a given #GIcon.
+ * @equal: Checks if two #GIcon<!-- -->s are equal.
+ * @to_tokens: Serializes a #GIcon into tokens. The tokens must not contain any whitespace. Don't implement if the #GIcon can't be serialized (Since 2.20).
+ * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if the tokens are malformed. Don't implement if the #GIcon can't be serialized (Since 2.20).
*
- * Implements #GInputStream for arbitrary memory chunks.
+ * GIconIface is used to implement GIcon types for various
+ * different systems. See #GThemedIcon and #GLoadableIcon for
+ * examples of how to implement this interface.
*/
/**
- * GMemoryOutputStream:
+ * GIconv:
*
- * Implements #GOutputStream for arbitrary memory chunks.
+ * The <structname>GIConv</structname> struct wraps an
+ * iconv() conversion descriptor. It contains private data
+ * and should only be accessed using the following functions.
*/
/**
- * GMemoryOutputStream:data:
- *
- * Pointer to buffer where data will be written.
+ * GInetAddress:
*
- * Since: 2.24
+ * An IPv4 or IPv6 internet address.
*/
/**
- * GMemoryOutputStream:data-size:
+ * GInetAddress:is-any:
*
- * Size of data written to the buffer.
+ * Whether this is the "any" address for its family.
+ * See g_inet_address_get_is_any().
*
- * Since: 2.24
+ * Since: 2.22
*/
/**
- * GMemoryOutputStream:destroy-function: (skip)
+ * GInetAddress:is-link-local:
*
- * Function called with the buffer as argument when the stream is destroyed.
+ * Whether this is a link-local address.
+ * See g_inet_address_get_is_link_local().
*
- * Since: 2.24
+ * Since: 2.22
*/
/**
- * GMemoryOutputStream:realloc-function: (skip)
+ * GInetAddress:is-loopback:
*
- * Function with realloc semantics called to enlarge the buffer.
+ * Whether this is the loopback address for its family.
+ * See g_inet_address_get_is_loopback().
*
- * Since: 2.24
+ * Since: 2.22
*/
/**
- * GMemoryOutputStream:size:
+ * GInetAddress:is-mc-global:
*
- * Current size of the data buffer.
+ * Whether this is a global multicast address.
+ * See g_inet_address_get_is_mc_global().
*
- * Since: 2.24
+ * Since: 2.22
*/
/**
- * GMount:
+ * GInetAddress:is-mc-link-local:
*
- * A handle to an object implementing the #GMountIface interface.
+ * Whether this is a link-local multicast address.
+ * See g_inet_address_get_is_mc_link_local().
+ *
+ * Since: 2.22
*/
/**
- * GMount::changed:
- * @mount: the object on which the signal is emitted
+ * GInetAddress:is-mc-node-local:
*
- * Emitted when the mount has been changed.
+ * Whether this is a node-local multicast address.
+ * See g_inet_address_get_is_mc_node_local().
+ *
+ * Since: 2.22
*/
/**
- * GMount::pre-unmount:
- * @mount: the object on which the signal is emitted
+ * GInetAddress:is-mc-org-local:
*
- * This signal is emitted when the #GMount is about to be
- * unmounted.
+ * Whether this is an organization-local multicast address.
+ * See g_inet_address_get_is_mc_org_local().
*
* Since: 2.22
*/
/**
- * GMount::unmounted:
- * @mount: the object on which the signal is emitted
+ * GInetAddress:is-mc-site-local:
*
- * 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.
+ * Whether this is a site-local multicast address.
+ * See g_inet_address_get_is_mc_site_local().
+ *
+ * Since: 2.22
*/
/**
- * GMountIface:
- * @g_iface: The parent interface.
- * @changed: Changed signal that is emitted when the mount's state has changed.
- * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized.
- * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file.
- * @get_root: Gets a #GFile to the root directory of the #GMount.
- * @get_name: Gets a string containing the name of the #GMount.
- * @get_icon: Gets a #GIcon for the #GMount.
- * @get_uuid: Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
- * @get_volume: Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume.
- * @get_drive: Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive.
- * @can_unmount: Checks if a #GMount can be unmounted.
- * @can_eject: Checks if a #GMount can be ejected.
- * @unmount: Starts unmounting a #GMount.
- * @unmount_finish: Finishes an unmounting operation.
- * @eject: Starts ejecting a #GMount.
- * @eject_finish: Finishes an eject operation.
- * @remount: Starts remounting a #GMount.
- * @remount_finish: Finishes a remounting operation.
- * @guess_content_type: Starts guessing the type of the content of a #GMount. See g_mount_guess_content_type() for more information on content type guessing. This operation was added in 2.18.
- * @guess_content_type_finish: Finishes a contenet type guessing operation. Added in 2.18.
- * @guess_content_type_sync: Synchronous variant of @guess_content_type. Added in 2.18
- * @unmount_with_operation: Starts unmounting a #GMount using a #GMountOperation. Since 2.22.
- * @unmount_with_operation_finish: Finishes an unmounting operation using a #GMountOperation. Since 2.22.
- * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22.
- * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
- * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24.
+ * GInetAddress:is-multicast:
*
- * Interface for implementing operations for mounts.
+ * Whether this is a multicast address.
+ * See g_inet_address_get_is_multicast().
+ *
+ * Since: 2.22
*/
/**
- * GMountMountFlags:
- * @G_MOUNT_MOUNT_NONE: No flags set.
+ * GInetAddress:is-site-local:
*
- * Flags used when mounting a mount.
+ * Whether this is a site-local address.
+ * See g_inet_address_get_is_loopback().
+ *
+ * Since: 2.22
*/
/**
- * GMountOperation:
+ * GInetSocketAddress:
*
- * Class for providing authentication methods for mounting operations,
- * such as mounting a file locally, or authenticating with a server.
+ * An IPv4 or IPv6 socket address, corresponding to a <type>struct
+ * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
*/
/**
- * GMountOperation::aborted:
+ * GInitable:
*
- * 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.
+ * Interface for initializable objects.
*
- * Since: 2.20
+ * Since: 2.22
*/
/**
- * GMountOperation::ask-password:
- * @op: a #GMountOperation requesting a password.
- * @message: string containing a message to display to the user.
- * @default_user: string containing the default user name.
- * @default_domain: string containing the default domain.
- * @flags: a set of #GAskPasswordFlags.
+ * GInitableIface:
+ * @g_iface: The parent interface.
+ * @init: Initializes the object.
*
- * 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.
+ * Provides an interface for initializing object such that initialization
+ * may fail.
+ *
+ * Since: 2.22
*/
/**
- * GMountOperation::ask-question:
- * @op: a #GMountOperation asking a question.
- * @message: string containing a message to display to the user.
- * @choices: an array of strings for each possible choice.
+ * GInitiallyUnowned:
*
- * 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.
+ * All the fields in the <structname>GInitiallyUnowned</structname> structure
+ * are private to the #GInitiallyUnowned implementation and should never be
+ * accessed directly.
*/
/**
- * GMountOperation::reply:
- * @op: a #GMountOperation.
- * @result: a #GMountOperationResult indicating how the request was handled
+ * GInitiallyUnownedClass:
*
- * Emitted when the user has replied to the mount operation.
+ * The class structure for the <structname>GInitiallyUnowned</structname> type.
*/
/**
- * GMountOperation::show-processes:
- * @op: a #GMountOperation.
- * @message: string containing a message to display to the user.
- * @processes: an array of #GPid for processes blocking the operation.
- * @choices: an array of strings for each possible choice.
+ * GInputStream:
*
- * 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.
+ * Base class for streaming input operations.
+ */
+
+
+/**
+ * GInputVector:
+ * @buffer: Pointer to a buffer where data will be written.
+ * @size: the available size in @buffer.
+ *
+ * Structure used for scatter/gather data input.
+ * You generally pass in an array of #GInputVector<!-- -->s
+ * and the operation will store the read data starting in the
+ * first buffer, switching to the next as needed.
*
* Since: 2.22
*/
/**
- * GMountOperation:anonymous:
+ * GInstanceInitFunc:
+ * @instance: The instance to initialize.
+ * @g_class: The class of the type the instance is created for.
*
- * Whether to use an anonymous user when authenticating.
+ * A callback function used by the type system to initialize a new
+ * instance of a type. This function initializes all instance members and
+ * allocates any resources required by it.
+ * Initialization of a derived instance involves calling all its parent
+ * types instance initializers, so the class member of the instance
+ * is altered during its initialization to always point to the class that
+ * belongs to the type the current initializer was introduced for.
*/
/**
- * GMountOperation:choice:
+ * GInterfaceFinalizeFunc:
+ * @g_iface: The interface structure to finalize.
+ * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
*
- * The index of the user's choice when a question is asked during the
- * mount operation. See the #GMountOperation::ask-question signal.
+ * A callback function used by the type system to finalize an interface.
+ * This function should destroy any internal data and release any resources
+ * allocated by the corresponding GInterfaceInitFunc() function.
*/
/**
- * GMountOperation:domain:
+ * GInterfaceInfo:
+ * @interface_init: location of the interface initialization function
+ * @interface_finalize: location of the interface finalization function
+ * @interface_data: user-supplied data passed to the interface init/finalize functions
*
- * The domain to use for the mount operation.
+ * A structure that provides information to the type system which is
+ * used specifically for managing interface types.
*/
/**
- * GMountOperation:password:
+ * GInterfaceInitFunc:
+ * @g_iface: The interface structure to initialize.
+ * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
*
- * The password that is used for authentication when carrying out
- * the mount operation.
+ * A callback function used by the type system to initialize a new
+ * interface. This function should initialize all internal data and
+ * allocate any resources required by the interface.
*/
/**
- * GMountOperation:password-save:
+ * GLoadableIcon:
*
- * Determines if and how the password information should be saved.
+ * Generic type for all kinds of icons that can be loaded
+ * as a stream.
*/
/**
- * GMountOperation:username:
+ * GLoadableIconIface:
+ * @g_iface: The parent interface.
+ * @load: Loads an icon.
+ * @load_async: Loads an icon asynchronously.
+ * @load_finish: Finishes an asynchronous icon load.
*
- * The user name that is used for authentication when carrying out
- * the mount operation.
+ * Interface for icons that can be loaded as a stream.
*/
/**
- * GMountOperationResult:
- * @G_MOUNT_OPERATION_HANDLED: The request was fulfilled and the user specified data is now available
- * @G_MOUNT_OPERATION_ABORTED: The user requested the mount operation to be aborted
- * @G_MOUNT_OPERATION_UNHANDLED: The request was unhandled (i.e. not implemented)
+ * GMainContext:
*
- * #GMountOperationResult is returned as a result when a request for
- * information is send by the mounting operation.
+ * The <structname>GMainContext</structname> struct is an opaque data
+ * type representing a set of sources to be handled in a main loop.
*/
/**
- * GMountUnmountFlags:
- * @G_MOUNT_UNMOUNT_NONE: No flags set.
- * @G_MOUNT_UNMOUNT_FORCE: Unmount even if there are outstanding file operations on the mount.
+ * GMainLoop:
*
- * Flags used when an unmounting a mount.
+ * The <structname>GMainLoop</structname> struct is an opaque data type
+ * representing the main event loop of a GLib or GTK+ application.
*/
/**
- * GNetworkAddress:
+ * GMarkupError:
+ * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
+ * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
+ * @G_MARKUP_ERROR_PARSE: document was ill-formed
+ * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
+ * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
+ * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid
+ * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing
*
- * A #GSocketConnectable for resolving a hostname and connecting to
- * that host.
+ * Error codes returned by markup parsing.
*/
/**
- * GNetworkService:
+ * GMarkupParseContext:
*
- * A #GSocketConnectable for resolving a SRV record and connecting to
- * that service.
+ * A parse context is used to parse a stream of bytes that
+ * you expect to contain marked-up text.
+ * See g_markup_parse_context_new(), #GMarkupParser, and so
+ * on for more details.
*/
/**
- * GObject:
+ * GMarkupParseFlags:
+ * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
+ * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12
+ * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions
*
- * All the fields in the <structname>GObject</structname> structure are private
- * to the #GObject implementation and should never be accessed directly.
+ * Flags that affect the behaviour of the parser.
*/
/**
- * GObjectClass:
- * @g_type_class: the parent class
- * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons.
- * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system.
- * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
- * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class.
- * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class.
- * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed.
- * @notify: the class closure for the notify signal
- * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation.
+ * GMarkupParser:
+ * @start_element: Callback to invoke when the opening tag of an element is seen.
+ * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>.
+ * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections.
+ * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections.
+ * @error: Callback to invoke when an error occurs.
*
- * The class structure for the <structname>GObject</structname> type.
- * <example>
- * <title>Implementing singletons using a constructor</title>
- * <programlisting>
- * static MySingleton *the_singleton = NULL;
- * static GObject*
- * my_singleton_constructor (GType type,
- * guint n_construct_params,
- * GObjectConstructParam *construct_params)
- * {
- * GObject *object;
- * if (!the_singleton)
- * {
- * object = G_OBJECT_CLASS (parent_class)->constructor (type,
- * n_construct_params,
- * construct_params);
- * the_singleton = MY_SINGLETON (object);
- * }
- * else
- * object = g_object_ref (G_OBJECT (the_singleton));
- * return object;
- * }
- * </programlisting></example>
+ * Any of the fields in #GMarkupParser can be %NULL, in which case they
+ * will be ignored. Except for the @error function, any of these callbacks
+ * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
+ * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
+ * errors are intended to be set from these callbacks. If you set an error
+ * from a callback, g_markup_parse_context_parse() will report that error
+ * back to its caller.
*/
/**
- * GObjectConstructParam:
- * @pspec: the #GParamSpec of the construct parameter
- * @value: the value to set the parameter to
+ * GMemVTable:
+ * @malloc: function to use for allocating memory.
+ * @realloc: function to use for reallocating memory.
+ * @free: function to use to free memory.
+ * @calloc: function to use for allocating zero-filled memory.
+ * @try_malloc: function to use for allocating memory without a default error handler.
+ * @try_realloc: function to use for reallocating memory without a default error handler.
*
- * The <structname>GObjectConstructParam</structname> struct is an auxiliary
- * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
- * a #GObjectClass.
+ * A set of functions used to perform memory allocation. The same #GMemVTable must
+ * be used for all allocations in the same program; a call to g_mem_set_vtable(),
+ * if it exists, should be prior to any use of GLib.
*/
/**
- * GObjectFinalizeFunc:
- * @object: the #GObject being finalized
+ * GMemoryInputStream:
*
- * The type of the @finalize function of #GObjectClass.
+ * Implements #GInputStream for arbitrary memory chunks.
*/
/**
- * GObjectGetPropertyFunc:
- * @object: a #GObject
- * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
- * @value: a #GValue to return the property value in
- * @pspec: the #GParamSpec describing the property
+ * GMemoryOutputStream:
*
- * The type of the @get_property function of #GObjectClass.
+ * Implements #GOutputStream for arbitrary memory chunks.
*/
/**
- * GObjectSetPropertyFunc:
- * @object: a #GObject
- * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
- * @value: the new value for the property
- * @pspec: the #GParamSpec describing the property
+ * GMemoryOutputStream:data:
*
- * The type of the @set_property function of #GObjectClass.
+ * Pointer to buffer where data will be written.
+ *
+ * Since: 2.24
*/
/**
- * GOptionArg:
- * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
- * @G_OPTION_ARG_STRING: The option takes a string argument.
- * @G_OPTION_ARG_INT: The option takes an integer argument.
- * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument.
- * @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
- * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings.
- * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings.
- * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12
- * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12
+ * GMemoryOutputStream:data-size:
*
- * The #GOptionArg enum values determine which type of extra argument the
- * options expect to find. If an option expects an extra argument, it
- * can be specified in several ways; with a short option:
- * <option>-x arg</option>, with a long option: <option>--name arg</option>
+ * Size of data written to the buffer.
*
- * Or combined in a single argument: <option>--name=arg</option>.
+ * Since: 2.24
*/
/**
- * GOptionArgFunc:
- * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name.
- * @value: The value to be parsed.
- * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
- * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks.
+ * GMemoryOutputStream:destroy-function: (skip)
*
- * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
- * options.
- * occurred, in which case @error should be set with g_set_error()
+ * Function called with the buffer as argument when the stream is destroyed.
*
- * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
+ * Since: 2.24
*/
/**
- * GOptionContext:
+ * GMemoryOutputStream:realloc-function: (skip)
*
- * A <structname>GOptionContext</structname> struct defines which options
- * are accepted by the commandline option parser. The struct has only private
- * fields and should not be directly accessed.
+ * Function with realloc semantics called to enlarge the buffer.
+ *
+ * Since: 2.24
*/
/**
- * GOptionEntry:
- * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
- * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name.
- * @flags: Flags from #GOptionFlags.
- * @arg: The type of the option, as a #GOptionArg.
- * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <
term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().
- * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain().
- * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain().
+ * GMemoryOutputStream:size:
*
- * A <structname>GOptionEntry</structname> defines a single option.
- * To have an effect, they must be added to a #GOptionGroup with
- * g_option_context_add_main_entries() or g_option_group_add_entries().
+ * Current size of the data buffer.
+ *
+ * Since: 2.24
*/
/**
- * GOptionError:
- * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options().
- * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
- * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
+ * GMount:
*
- * Error codes returned by option parsing.
+ * A handle to an object implementing the #GMountIface interface.
*/
/**
- * GOptionErrorFunc:
- * @context: The active #GOptionContext
- * @group: The group to which the function belongs
- * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
- * @error: The #GError containing details about the parse error
+ * GMount::changed:
+ * @mount: the object on which the signal is emitted
*
- * The type of function to be used as callback when a parse error occurs.
+ * Emitted when the mount has been changed.
*/
/**
- * GOptionFlags:
- * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output.
- * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group.
- * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed.
- * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8
- * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8
- * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
- * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8.
+ * GMount::pre-unmount:
+ * @mount: the object on which the signal is emitted
*
- * Flags which modify individual options.
+ * This signal is emitted when the #GMount is about to be
+ * unmounted.
+ *
+ * Since: 2.22
*/
/**
- * GOptionGroup:
+ * GMount::unmounted:
+ * @mount: the object on which the signal is emitted
*
- * A <structname>GOptionGroup</structname> struct defines the options in a single
- * group. The struct has only private fields and should not be directly accessed.
- * All options in a group share the same translation function. Libraries which
- * need to parse commandline options are expected to provide a function for
- * getting a <structname>GOptionGroup</structname> holding their options, which
- * the application can then add to its #GOptionContext.
+ * 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.
*/
/**
- * GOptionParseFunc:
- * @context: The active #GOptionContext
- * @group: The group to which the function belongs
- * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
- * @error: A return location for error details
- *
- * The type of function that can be called before and after parsing.
- * occurred, in which case @error should be set with g_set_error()
+ * GMountIface:
+ * @g_iface: The parent interface.
+ * @changed: Changed signal that is emitted when the mount's state has changed.
+ * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized.
+ * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file.
+ * @get_root: Gets a #GFile to the root directory of the #GMount.
+ * @get_name: Gets a string containing the name of the #GMount.
+ * @get_icon: Gets a #GIcon for the #GMount.
+ * @get_uuid: Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
+ * @get_volume: Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume.
+ * @get_drive: Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive.
+ * @can_unmount: Checks if a #GMount can be unmounted.
+ * @can_eject: Checks if a #GMount can be ejected.
+ * @unmount: Starts unmounting a #GMount.
+ * @unmount_finish: Finishes an unmounting operation.
+ * @eject: Starts ejecting a #GMount.
+ * @eject_finish: Finishes an eject operation.
+ * @remount: Starts remounting a #GMount.
+ * @remount_finish: Finishes a remounting operation.
+ * @guess_content_type: Starts guessing the type of the content of a #GMount. See g_mount_guess_content_type() for more information on content type guessing. This operation was added in 2.18.
+ * @guess_content_type_finish: Finishes a contenet type guessing operation. Added in 2.18.
+ * @guess_content_type_sync: Synchronous variant of @guess_content_type. Added in 2.18
+ * @unmount_with_operation: Starts unmounting a #GMount using a #GMountOperation. Since 2.22.
+ * @unmount_with_operation_finish: Finishes an unmounting operation using a #GMountOperation. Since 2.22.
+ * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22.
+ * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24.
*
- * Returns: %TRUE if the function completed successfully, %FALSE if an error
+ * Interface for implementing operations for mounts.
*/
/**
- * GOutputStream:
+ * GMountMountFlags:
+ * @G_MOUNT_MOUNT_NONE: No flags set.
*
- * Base class for writing output.
- * All classes derived from GOutputStream should implement synchronous
- * writing, splicing, flushing and closing streams, but may implement
- * asynchronous versions.
+ * Flags used when mounting a mount.
*/
/**
- * GOutputStreamSpliceFlags:
- * @G_OUTPUT_STREAM_SPLICE_NONE: Do not close either stream.
- * @G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE: Close the source stream after the splice.
- * @G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET: Close the target stream after the splice.
+ * GMountOperation:
*
- * GOutputStreamSpliceFlags determine how streams should be spliced.
+ * Class for providing authentication methods for mounting operations,
+ * such as mounting a file locally, or authenticating with a server.
*/
/**
- * GOutputVector:
- * @buffer: Pointer to a buffer of data to read.
- * @size: the size of @buffer.
+ * GMountOperation::aborted:
*
- * Structure used for scatter/gather data output.
- * You generally pass in an array of #GOutputVector<!-- -->s
- * and the operation will use all the buffers as if they were
- * one buffer.
+ * 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.22
+ * Since: 2.20
*/
/**
- * GParamFlags:
- * @G_PARAM_READABLE: the parameter is readable
- * @G_PARAM_WRITABLE: the parameter is writable
- * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
- * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
- * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required
- * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
- * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8
- * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
- * @G_PARAM_PRIVATE: internal
- * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26
+ * GMountOperation::ask-password:
+ * @op: a #GMountOperation requesting a password.
+ * @message: string containing a message to display to the user.
+ * @default_user: string containing the default user name.
+ * @default_domain: string containing the default domain.
+ * @flags: a set of #GAskPasswordFlags.
*
- * Through the #GParamFlags flag values, certain aspects of parameters
- * can be configured.
+ * 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.
*/
/**
- * GParamSpec:
- * @g_type_instance: private #GTypeInstance portion
- * @name: name of this parameter
- * @flags: #GParamFlags flags for this parameter
- * @value_type: the #GValue type for this parameter
- * @owner_type: #GType type that uses (introduces) this parameter
+ * GMountOperation::ask-question:
+ * @op: a #GMountOperation asking a question.
+ * @message: string containing a message to display to the user.
+ * @choices: an array of strings for each possible choice.
*
- * All other fields of the <structname>GParamSpec</structname> struct are private and
- * should not be used directly.
- */
-
-
-/**
- * GParamSpecBoolean:
- * @parent_instance: private #GParamSpec portion
- * @default_value: default value for the property specified
- *
- * A #GParamSpec derived structure that contains the meta data for boolean properties.
+ * 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.
*/
/**
- * GParamSpecBoxed:
- * @parent_instance: private #GParamSpec portion
+ * GMountOperation::reply:
+ * @op: a #GMountOperation.
+ * @result: a #GMountOperationResult indicating how the request was handled
*
- * A #GParamSpec derived structure that contains the meta data for boxed properties.
+ * Emitted when the user has replied to the mount operation.
*/
/**
- * GParamSpecChar:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GMountOperation::show-processes:
+ * @op: a #GMountOperation.
+ * @message: string containing a message to display to the user.
+ * @processes: an array of #GPid for processes blocking the operation.
+ * @choices: an array of strings for each possible choice.
*
- * A #GParamSpec derived structure that contains the meta data for character properties.
- */
-
-
-/**
- * GParamSpecClass:
- * @g_type_class: the parent class
- * @value_type: the #GValue type for this parameter
- * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class.
- * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default().
- * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate().
- * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp().
+ * 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.
*
- * The class structure for the <structname>GParamSpec</structname> type.
- * Normally, <structname>GParamSpec</structname> classes are filled by
- * g_param_type_register_static().
+ * Since: 2.22
*/
/**
- * GParamSpecDouble:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
- * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90.
+ * GMountOperation:anonymous:
*
- * A #GParamSpec derived structure that contains the meta data for double properties.
+ * Whether to use an anonymous user when authenticating.
*/
/**
- * GParamSpecEnum:
- * @parent_instance: private #GParamSpec portion
- * @enum_class: the #GEnumClass for the enum
- * @default_value: default value for the property specified
+ * GMountOperation:choice:
*
- * A #GParamSpec derived structure that contains the meta data for enum
- * properties.
+ * The index of the user's choice when a question is asked during the
+ * mount operation. See the #GMountOperation::ask-question signal.
*/
/**
- * GParamSpecFlags:
- * @parent_instance: private #GParamSpec portion
- * @flags_class: the #GFlagsClass for the flags
- * @default_value: default value for the property specified
+ * GMountOperation:domain:
*
- * A #GParamSpec derived structure that contains the meta data for flags
- * properties.
+ * The domain to use for the mount operation.
*/
/**
- * GParamSpecFloat:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
- * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30.
+ * GMountOperation:password:
*
- * A #GParamSpec derived structure that contains the meta data for float properties.
+ * The password that is used for authentication when carrying out
+ * the mount operation.
*/
/**
- * GParamSpecGType:
- * @parent_instance: private #GParamSpec portion
- * @is_a_type: a #GType whose subtypes can occur as values
- *
- * A #GParamSpec derived structure that contains the meta data for #GType properties.
+ * GMountOperation:password-save:
*
- * Since: 2.10
+ * Determines if and how the password information should be saved.
*/
/**
- * GParamSpecInt:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GMountOperation:username:
*
- * A #GParamSpec derived structure that contains the meta data for integer properties.
+ * The user name that is used for authentication when carrying out
+ * the mount operation.
*/
/**
- * GParamSpecInt64:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GMountOperationResult:
+ * @G_MOUNT_OPERATION_HANDLED: The request was fulfilled and the user specified data is now available
+ * @G_MOUNT_OPERATION_ABORTED: The user requested the mount operation to be aborted
+ * @G_MOUNT_OPERATION_UNHANDLED: The request was unhandled (i.e. not implemented)
*
- * A #GParamSpec derived structure that contains the meta data for 64bit integer properties.
+ * #GMountOperationResult is returned as a result when a request for
+ * information is send by the mounting operation.
*/
/**
- * GParamSpecLong:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GMountUnmountFlags:
+ * @G_MOUNT_UNMOUNT_NONE: No flags set.
+ * @G_MOUNT_UNMOUNT_FORCE: Unmount even if there are outstanding file operations on the mount.
*
- * A #GParamSpec derived structure that contains the meta data for long integer properties.
+ * Flags used when an unmounting a mount.
*/
/**
- * GParamSpecObject:
- * @parent_instance: private #GParamSpec portion
+ * GNetworkAddress:
*
- * A #GParamSpec derived structure that contains the meta data for object properties.
+ * A #GSocketConnectable for resolving a hostname and connecting to
+ * that host.
*/
/**
- * GParamSpecOverride:
- *
- * This is a type of #GParamSpec type that simply redirects operations to
- * another paramspec. All operations other than getting or
- * setting the value are redirected, including accessing the nick and
- * blurb, validating a value, and so forth. See
- * g_param_spec_get_redirect_target() for retrieving the overidden
- * property. #GParamSpecOverride is used in implementing
- * g_object_class_override_property(), and will not be directly useful
- * unless you are implementing a new base type similar to GObject.
+ * GNetworkService:
*
- * Since: 2.4
+ * A #GSocketConnectable for resolving a SRV record and connecting to
+ * that service.
*/
/**
- * GParamSpecParam:
- * @parent_instance: private #GParamSpec portion
+ * GObject:
*
- * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM
- * properties.
+ * All the fields in the <structname>GObject</structname> structure are private
+ * to the #GObject implementation and should never be accessed directly.
*/
/**
- * GParamSpecPointer:
- * @parent_instance: private #GParamSpec portion
+ * GObjectClass:
+ * @g_type_class: the parent class
+ * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons.
+ * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system.
+ * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
+ * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class.
+ * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class.
+ * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed.
+ * @notify: the class closure for the notify signal
+ * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation.
*
- * A #GParamSpec derived structure that contains the meta data for pointer properties.
+ * The class structure for the <structname>GObject</structname> type.
+ * <example>
+ * <title>Implementing singletons using a constructor</title>
+ * <programlisting>
+ * static MySingleton *the_singleton = NULL;
+ * static GObject*
+ * my_singleton_constructor (GType type,
+ * guint n_construct_params,
+ * GObjectConstructParam *construct_params)
+ * {
+ * GObject *object;
+ * if (!the_singleton)
+ * {
+ * object = G_OBJECT_CLASS (parent_class)->constructor (type,
+ * n_construct_params,
+ * construct_params);
+ * the_singleton = MY_SINGLETON (object);
+ * }
+ * else
+ * object = g_object_ref (G_OBJECT (the_singleton));
+ * return object;
+ * }
+ * </programlisting></example>
*/
/**
- * GParamSpecString:
- * @parent_instance: private #GParamSpec portion
- * @default_value: default value for the property specified
- * @cset_first: a string containing the allowed values for the first byte
- * @cset_nth: a string containing the allowed values for the subsequent bytes
- * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth.
- * @null_fold_if_empty: replace empty string by %NULL
- * @ensure_non_null: replace %NULL strings by an empty string
+ * GObjectConstructParam:
+ * @pspec: the #GParamSpec of the construct parameter
+ * @value: the value to set the parameter to
*
- * A #GParamSpec derived structure that contains the meta data for string
- * properties.
+ * The <structname>GObjectConstructParam</structname> struct is an auxiliary
+ * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
+ * a #GObjectClass.
*/
/**
- * GParamSpecTypeInfo:
- * @instance_size: Size of the instance (object) structure.
- * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
- * @instance_init: Location of the instance initialization function (optional).
- * @value_type: The #GType of values conforming to this #GParamSpec
- * @finalize: The instance finalization function (optional).
- * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default().
- * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate().
- * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp().
+ * GObjectFinalizeFunc:
+ * @object: the #GObject being finalized
*
- * This structure is used to provide the type system with the information
- * required to initialize and destruct (finalize) a parameter's class and
- * instances thereof.
- * The initialized structure is passed to the g_param_type_register_static()
- * The type system will perform a deep copy of this structure, so its memory
- * does not need to be persistent across invocation of
- * g_param_type_register_static().
+ * The type of the @finalize function of #GObjectClass.
*/
/**
- * GParamSpecUChar:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GObjectGetPropertyFunc:
+ * @object: a #GObject
+ * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
+ * @value: a #GValue to return the property value in
+ * @pspec: the #GParamSpec describing the property
*
- * A #GParamSpec derived structure that contains the meta data for unsigned character properties.
+ * The type of the @get_property function of #GObjectClass.
*/
/**
- * GParamSpecUInt:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GObjectSetPropertyFunc:
+ * @object: a #GObject
+ * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
+ * @value: the new value for the property
+ * @pspec: the #GParamSpec describing the property
*
- * A #GParamSpec derived structure that contains the meta data for unsigned integer properties.
+ * The type of the @set_property function of #GObjectClass.
*/
/**
- * GParamSpecUInt64:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * GOptionArg:
+ * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
+ * @G_OPTION_ARG_STRING: The option takes a string argument.
+ * @G_OPTION_ARG_INT: The option takes an integer argument.
+ * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument.
+ * @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
+ * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings.
+ * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings.
+ * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12
+ * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12
*
- * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.
- */
-
-
-/**
- * GParamSpecULong:
- * @parent_instance: private #GParamSpec portion
- * @minimum: minimum value for the property specified
- * @maximum: maximum value for the property specified
- * @default_value: default value for the property specified
+ * The #GOptionArg enum values determine which type of extra argument the
+ * options expect to find. If an option expects an extra argument, it
+ * can be specified in several ways; with a short option:
+ * <option>-x arg</option>, with a long option: <option>--name arg</option>
*
- * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.
+ * Or combined in a single argument: <option>--name=arg</option>.
*/
/**
- * GParamSpecUnichar:
- * @parent_instance: private #GParamSpec portion
- * @default_value: default value for the property specified
+ * GOptionArgFunc:
+ * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name.
+ * @value: The value to be parsed.
+ * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
+ * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks.
*
- * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.
+ * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
+ * options.
+ * occurred, in which case @error should be set with g_set_error()
+ *
+ * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
*/
/**
- * GParamSpecValueArray:
- * @parent_instance: private #GParamSpec portion
- * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL
- * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements
+ * GOptionContext:
*
- * A #GParamSpec derived structure that contains the meta data for #GValueArray properties.
+ * A <structname>GOptionContext</structname> struct defines which options
+ * are accepted by the commandline option parser. The struct has only private
+ * fields and should not be directly accessed.
*/
/**
- * GParamSpecVariant:
- * @parent_instance: private #GParamSpec portion
- * @type: a #GVariantType, or %NULL
- * @default_value: a #GVariant, or %NULL
- *
- * A #GParamSpec derived structure that contains the meta data for #GVariant properties.
+ * GOptionEntry:
+ * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
+ * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name.
+ * @flags: Flags from #GOptionFlags.
+ * @arg: The type of the option, as a #GOptionArg.
+ * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <
term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().
+ * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain().
+ * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain().
*
- * Since: 2.26
+ * A <structname>GOptionEntry</structname> defines a single option.
+ * To have an effect, they must be added to a #GOptionGroup with
+ * g_option_context_add_main_entries() or g_option_group_add_entries().
*/
/**
- * GParameter:
- * @name: the parameter name
- * @value: the parameter value
+ * GOptionError:
+ * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options().
+ * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
+ * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
*
- * The <structname>GParameter</structname> struct is an auxiliary structure used
- * to hand parameter name/value pairs to g_object_newv().
+ * Error codes returned by option parsing.
*/
/**
- * GPasswordSave:
- * @G_PASSWORD_SAVE_NEVER: never save a password.
- * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session.
- * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently.
+ * GOptionErrorFunc:
+ * @context: The active #GOptionContext
+ * @group: The group to which the function belongs
+ * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
+ * @error: The #GError containing details about the parse error
*
- * #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.
+ * The type of function to be used as callback when a parse error occurs.
*/
/**
- * GPermission:
+ * GOptionFlags:
+ * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output.
+ * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group.
+ * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed.
+ * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8
+ * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8
+ * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
+ * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8.
*
- * #GPermission is an opaque data structure and can only be accessed
- * using the following functions.
+ * Flags which modify individual options.
*/
/**
- * GPermission:allowed:
+ * GOptionGroup:
*
- * %TRUE if the caller currently has permission to perform the action that
+ * A <structname>GOptionGroup</structname> struct defines the options in a single
+ * group. The struct has only private fields and should not be directly accessed.
+ * All options in a group share the same translation function. Libraries which
+ * need to parse commandline options are expected to provide a function for
+ * getting a <structname>GOptionGroup</structname> holding their options, which
+ * the application can then add to its #GOptionContext.
*/
/**
- * GPermission:can-acquire:
+ * GOptionParseFunc:
+ * @context: The active #GOptionContext
+ * @group: The group to which the function belongs
+ * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
+ * @error: A return location for error details
*
- * %TRUE if it is generally possible to acquire the permission by calling
- * g_permission_acquire().
+ * The type of function that can be called before and after parsing.
+ * occurred, in which case @error should be set with g_set_error()
+ *
+ * Returns: %TRUE if the function completed successfully, %FALSE if an error
*/
/**
- * GPermission:can-release:
+ * GOutputStream:
*
- * %TRUE if it is generally possible to release the permission by calling
- * g_permission_release().
+ * Base class for writing output.
+ * All classes derived from GOutputStream should implement synchronous
+ * writing, splicing, flushing and closing streams, but may implement
+ * asynchronous versions.
*/
/**
- * GPid:
+ * GOutputStreamSpliceFlags:
+ * @G_OUTPUT_STREAM_SPLICE_NONE: Do not close either stream.
+ * @G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE: Close the source stream after the splice.
+ * @G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET: Close the target stream after the splice.
*
- * A type which is used to hold a process identification.
- * On UNIX, processes are identified by a process id (an integer),
- * while Windows uses process handles (which are pointers).
+ * GOutputStreamSpliceFlags determine how streams should be spliced.
*/
/**
- * GPollFD:
- * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32)
- * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR.
- * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
+ * GOutputVector:
+ * @buffer: Pointer to a buffer of data to read.
+ * @size: the size of @buffer.
*
+ * Structure used for scatter/gather data output.
+ * You generally pass in an array of #GOutputVector<!-- -->s
+ * and the operation will use all the buffers as if they were
+ * one buffer.
*
+ * Since: 2.22
*/
/**
- * GPollFunc:
- * @ufds: an array of #GPollFD elements
- * @nfsd: the number of elements in @ufds
- * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout.
- *
- * Specifies the type of function passed to g_main_context_set_poll_func().
- * The semantics of the function should match those of the poll() system call.
- * reported, or -1 if an error occurred.
+ * GParamFlags:
+ * @G_PARAM_READABLE: the parameter is readable
+ * @G_PARAM_WRITABLE: the parameter is writable
+ * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
+ * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
+ * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required
+ * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
+ * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8
+ * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
+ * @G_PARAM_PRIVATE: internal
+ * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26
*
- * Returns: the number of #GPollFD elements which have events or errors
+ * Through the #GParamFlags flag values, certain aspects of parameters
+ * can be configured.
*/
/**
- * GPollableInputStream:
- *
- * An interface for a #GInputStream that can be polled for readability.
+ * GParamSpec:
+ * @g_type_instance: private #GTypeInstance portion
+ * @name: name of this parameter
+ * @flags: #GParamFlags flags for this parameter
+ * @value_type: the #GValue type for this parameter
+ * @owner_type: #GType type that uses (introduces) this parameter
*
- * Since: 2.28
+ * All other fields of the <structname>GParamSpec</structname> struct are private and
+ * should not be used directly.
*/
/**
- * GPollableInputStreamInterface:
- * @g_iface: The parent interface.
- * @can_poll: Checks if the #GPollableInputStream instance is actually pollable
- * @is_readable: Checks if the stream is readable
- * @create_source: Creates a #GSource to poll the stream
- * @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK
- *
- * The interface for pollable input streams.
- * The default implementation of @can_poll always returns %TRUE.
- * The default implementation of @read_nonblocking calls
- * g_pollable_input_stream_is_readable(), and then calls
- * g_input_stream_read() if it returns %TRUE. This means you only need
- * to override it if it is possible that your @is_readable
- * implementation may return %TRUE when the stream is not actually
- * readable.
+ * GParamSpecBoolean:
+ * @parent_instance: private #GParamSpec portion
+ * @default_value: default value for the property specified
*
- * Since: 2.28
+ * A #GParamSpec derived structure that contains the meta data for boolean properties.
*/
/**
- * GPollableOutputStream:
- *
- * An interface for a #GOutputStream that can be polled for readability.
+ * GParamSpecBoxed:
+ * @parent_instance: private #GParamSpec portion
*
- * Since: 2.28
+ * A #GParamSpec derived structure that contains the meta data for boxed properties.
*/
/**
- * GPollableOutputStreamInterface:
- * @g_iface: The parent interface.
- * @can_poll: Checks if the #GPollableOutputStream instance is actually pollable
- * @is_writable: Checks if the stream is writable
- * @create_source: Creates a #GSource to poll the stream
- * @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK
- *
- * The interface for pollable output streams.
- * The default implementation of @can_poll always returns %TRUE.
- * The default implementation of @write_nonblocking calls
- * g_pollable_output_stream_is_writable(), and then calls
- * g_output_stream_write() if it returns %TRUE. This means you only
- * need to override it if it is possible that your @is_writable
- * implementation may return %TRUE when the stream is not actually
- * writable.
+ * GParamSpecChar:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Since: 2.28
+ * A #GParamSpec derived structure that contains the meta data for character properties.
*/
/**
- * GPollableSourceFunc:
- * @pollable_stream: the #GPollableInputStream or #GPollableOutputStream
- * @user_data: data passed in by the user.
- *
- * This is the function type of the callback used for the #GSource
- * returned by g_pollable_input_stream_create_source() and
- * g_pollable_output_stream_create_source().
+ * GParamSpecClass:
+ * @g_type_class: the parent class
+ * @value_type: the #GValue type for this parameter
+ * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class.
+ * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default().
+ * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate().
+ * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp().
*
- * Returns: it should return %FALSE if the source should be removed.
- * Since: 2.28
+ * The class structure for the <structname>GParamSpec</structname> type.
+ * Normally, <structname>GParamSpec</structname> classes are filled by
+ * g_param_type_register_static().
*/
/**
- * GProxy:
- *
- * Interface that handles proxy connection and payload.
+ * GParamSpecDouble:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90.
*
- * Since: 2.26
+ * A #GParamSpec derived structure that contains the meta data for double properties.
*/
/**
- * GProxyAddress:
- *
- * A #GInetSocketAddress representing a connection via a proxy server
+ * GParamSpecEnum:
+ * @parent_instance: private #GParamSpec portion
+ * @enum_class: the #GEnumClass for the enum
+ * @default_value: default value for the property specified
*
- * Since: 2.26
+ * A #GParamSpec derived structure that contains the meta data for enum
+ * properties.
*/
/**
- * GProxyAddressEnumerator:
+ * GParamSpecFlags:
+ * @parent_instance: private #GParamSpec portion
+ * @flags_class: the #GFlagsClass for the flags
+ * @default_value: default value for the property specified
*
- * A subclass of #GSocketAddressEnumerator that takes another address
- * enumerator and wraps its results in #GProxyAddress<!-- -->es as
- * directed by the default #GProxyResolver.
+ * A #GParamSpec derived structure that contains the meta data for flags
+ * properties.
*/
/**
- * GProxyInterface:
- * @g_iface: The parent interface.
- * @connect: Connect to proxy server and wrap (if required) the #connection to handle payload.
- * @connect_async: Same has connect() but asynchronous.
- * @connect_finish: Returns the result of connect_async()
- *
- * Provides an interface for handling proxy connection and payload.
+ * GParamSpecFloat:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
+ * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30.
*
- * Since: 2.26
+ * A #GParamSpec derived structure that contains the meta data for float properties.
*/
/**
- * GProxyResolver:
+ * GParamSpecGType:
+ * @parent_instance: private #GParamSpec portion
+ * @is_a_type: a #GType whose subtypes can occur as values
*
- * Interface that can be used to resolve proxy address.
+ * A #GParamSpec derived structure that contains the meta data for #GType properties.
+ *
+ * Since: 2.10
*/
/**
- * GReallocFunc:
- * @data: memory block to reallocate
- * @size: size to reallocate @data to
- *
- * Changes the size of the memory block pointed to by @data to
- * The function should have the same semantics as realloc().
+ * GParamSpecInt:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Returns: a pointer to the reallocated memory
+ * A #GParamSpec derived structure that contains the meta data for integer properties.
*/
/**
- * GRegex:
- *
- * A GRegex is the "compiled" form of a regular expression pattern. This
- * structure is opaque and its fields cannot be accessed directly.
+ * GParamSpecInt64:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Since: 2.14
+ * A #GParamSpec derived structure that contains the meta data for 64bit integer properties.
*/
/**
- * GRegexCompileFlags:
- * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting.
- * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting.
- * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting.
- * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting.
- * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
- * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
- * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
- * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
- * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
- * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
- * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
- * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'.
- * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'.
- *
- * Flags specifying compile-time options.
+ * GParamSpecLong:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Since: 2.14
+ * A #GParamSpec derived structure that contains the meta data for long integer properties.
*/
/**
- * GRegexError:
- * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed.
- * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed.
- * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string.
- * @G_REGEX_ERROR_MATCH: The match process failed.
- * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16
- * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16
- * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16
- * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16
- * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16
- * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16
- * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16
- * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16
- * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16
- * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16
- * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16
- * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16
- * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16
- * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16
- * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16
- * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16
- * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16
- * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16
- * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16
- * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16
- * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16
- * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16
- * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16
- * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16
- * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16
- * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16
- * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16
- * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16
- * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16
- * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16
- * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16
- * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16
- * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16
- * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16
- * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16
- * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16
- * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16
- * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16
- *
- * Error codes returned by regular expressions functions.
+ * GParamSpecObject:
+ * @parent_instance: private #GParamSpec portion
*
- * Since: 2.14
+ * A #GParamSpec derived structure that contains the meta data for object properties.
*/
/**
- * GRegexEvalCallback:
- * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string.
- * @result: a #GString containing the new string
- * @user_data: user data passed to g_regex_replace_eval()
+ * GParamSpecOverride:
*
- * Specifies the type of the function passed to g_regex_replace_eval().
- * It is called for each occurance of the pattern in the string passed
- * to g_regex_replace_eval(), and it should append the replacement to
+ * This is a type of #GParamSpec type that simply redirects operations to
+ * another paramspec. All operations other than getting or
+ * setting the value are redirected, including accessing the nick and
+ * blurb, validating a value, and so forth. See
+ * g_param_spec_get_redirect_target() for retrieving the overidden
+ * property. #GParamSpecOverride is used in implementing
+ * g_object_class_override_property(), and will not be directly useful
+ * unless you are implementing a new base type similar to GObject.
*
- * Returns: %FALSE to continue the replacement process, %TRUE to stop it
- * Since: 2.14
+ * Since: 2.4
*/
/**
- * GRegexMatchFlags:
- * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
- * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A".
- * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z".
- * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b".
- * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match().
- * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator.
- * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator.
- * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator.
- * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized.
- *
- * Flags specifying match-time options.
+ * GParamSpecParam:
+ * @parent_instance: private #GParamSpec portion
*
- * Since: 2.14
+ * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM
+ * properties.
*/
/**
- * GResolver:
+ * GParamSpecPointer:
+ * @parent_instance: private #GParamSpec portion
*
- * The object that handles DNS resolution. Use g_resolver_get_default()
- * to get the default resolver.
+ * A #GParamSpec derived structure that contains the meta data for pointer properties.
*/
/**
- * GResolver::reload:
- * @resolver: a #GResolver
+ * GParamSpecString:
+ * @parent_instance: private #GParamSpec portion
+ * @default_value: default value for the property specified
+ * @cset_first: a string containing the allowed values for the first byte
+ * @cset_nth: a string containing the allowed values for the subsequent bytes
+ * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth.
+ * @null_fold_if_empty: replace empty string by %NULL
+ * @ensure_non_null: replace %NULL strings by an empty string
*
- * Emitted when the resolver notices that the system resolver
- * configuration has changed.
+ * A #GParamSpec derived structure that contains the meta data for string
+ * properties.
*/
/**
- * GResolverError:
- * @G_RESOLVER_ERROR_NOT_FOUND: the requested name/address/service was not found
- * @G_RESOLVER_ERROR_TEMPORARY_FAILURE: the requested information could not be looked up due to a network error or similar problem
- * @G_RESOLVER_ERROR_INTERNAL: unknown error
- *
- * An error code used with %G_RESOLVER_ERROR in a #GError returned
- * from a #GResolver routine.
+ * GParamSpecTypeInfo:
+ * @instance_size: Size of the instance (object) structure.
+ * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
+ * @instance_init: Location of the instance initialization function (optional).
+ * @value_type: The #GType of values conforming to this #GParamSpec
+ * @finalize: The instance finalization function (optional).
+ * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default().
+ * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate().
+ * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp().
*
- * Since: 2.22
+ * This structure is used to provide the type system with the information
+ * required to initialize and destruct (finalize) a parameter's class and
+ * instances thereof.
+ * The initialized structure is passed to the g_param_type_register_static()
+ * The type system will perform a deep copy of this structure, so its memory
+ * does not need to be persistent across invocation of
+ * g_param_type_register_static().
*/
/**
- * GSeekable:
+ * GParamSpecUChar:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Seek object for streaming operations.
+ * A #GParamSpec derived structure that contains the meta data for unsigned character properties.
*/
/**
- * GSeekableIface:
- * @g_iface: The parent interface.
- * @tell: Tells the current location within a stream.
- * @can_seek: Checks if seeking is supported by the stream.
- * @seek: Seeks to a location within a stream.
- * @can_truncate: Chekcs if truncation is suppored by the stream.
- * @truncate_fn: Truncates a stream.
+ * GParamSpecUInt:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Provides an interface for implementing seekable functionality on I/O Streams.
+ * A #GParamSpec derived structure that contains the meta data for unsigned integer properties.
*/
/**
- * GSettings::change-event:
- * @settings: the object on which the signal was emitted
- * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL
- * @n_keys: the length of the @keys array, or 0
- * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
- *
- * 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
- * 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 supressed.
+ * GParamSpecUInt64:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * Whole (ie: potentially every key has been changed) then @keys will
+ * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.
*/
/**
- * GSettings::changed:
- * @settings: the object on which the signal was emitted
- * @key: the name of the key that changed
+ * GParamSpecULong:
+ * @parent_instance: private #GParamSpec portion
+ * @minimum: minimum value for the property specified
+ * @maximum: maximum value for the property specified
+ * @default_value: default value for the property specified
*
- * The "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.
+ * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.
*/
/**
- * GSettings::writable-change-event:
- * @settings: the object on which the signal was emitted
- * @key: the quark of the key, or 0
- * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
+ * GParamSpecUnichar:
+ * @parent_instance: private #GParamSpec portion
+ * @default_value: default value for the property specified
*
- * 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,
- * 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 supressed.
+ * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.
*/
/**
- * GSettings::writable-changed:
- * @settings: the object on which the signal was emitted
- * @key: the key
+ * GParamSpecValueArray:
+ * @parent_instance: private #GParamSpec portion
+ * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL
+ * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements
*
- * 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.
+ * A #GParamSpec derived structure that contains the meta data for #GValueArray properties.
*/
/**
- * GSettings:context:
+ * GParamSpecVariant:
+ * @parent_instance: private #GParamSpec portion
+ * @type: a #GVariantType, or %NULL
+ * @default_value: a #GVariant, or %NULL
*
- * The name of the context that the settings are stored in.
+ * A #GParamSpec derived structure that contains the meta data for #GVariant properties.
+ *
+ * Since: 2.26
*/
/**
- * GSettings:delay-apply:
- *
- * Whether the #GSettings object is in 'delay-apply' mode. See
- * g_settings_delay() for details.
+ * GParameter:
+ * @name: the parameter name
+ * @value: the parameter value
*
- * Since: 2.28
+ * The <structname>GParameter</structname> struct is an auxiliary structure used
+ * to hand parameter name/value pairs to g_object_newv().
*/
/**
- * GSettings:has-unapplied:
+ * GPasswordSave:
+ * @G_PASSWORD_SAVE_NEVER: never save a password.
+ * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session.
+ * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently.
*
- * If this property is %TRUE, the #GSettings object has outstanding
- * changes that will be applied when g_settings_apply() is called.
+ * #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.
*/
/**
- * GSettings:path:
+ * GPermission:
*
- * The path within the backend where the settings are stored.
+ * #GPermission is an opaque data structure and can only be accessed
+ * using the following functions.
*/
/**
- * GSettings:schema:
+ * GPermission:allowed:
*
- * The name of the schema that describes the types of keys
- * for this #GSettings object.
+ * %TRUE if the caller currently has permission to perform the action that
*/
/**
- * GSettingsBackend:
+ * GPermission:can-acquire:
*
- * An implementation of a settings storage repository.
+ * %TRUE if it is generally possible to acquire the permission by calling
+ * g_permission_acquire().
*/
/**
- * GSettingsBindFlags:
- * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
- * @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable.
- * @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable.
- * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting
- * @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting
- * @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to g_settings_bind_with_mapping().
+ * GPermission:can-release:
*
- * Flags used when creating a binding. These flags determine in which
- * direction the binding works. The default is to synchronize in both
- * directions.
+ * %TRUE if it is generally possible to release the permission by calling
+ * g_permission_release().
*/
/**
- * GSettingsBindGetMapping:
- * @value: return location for the property value
- * @variant: the #GVariant
- * @user_data: user data that was specified when the binding was created
- * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error
+ * GPid:
*
- * The type for the function that is used to convert from #GSettings to
- * an object property. The @value is already initialized to hold values
- * of the appropriate type.
+ * A type which is used to hold a process identification.
+ * On UNIX, processes are identified by a process id (an integer),
+ * while Windows uses process handles (which are pointers).
*/
/**
- * GSettingsBindSetMapping:
- * @value: a #GValue containing the property value to map
- * @expected_type: the #GVariantType to create
- * @user_data: user data that was specified when the binding was created
- * @returns: a new #GVariant holding the data from @value, or %NULL in case of an error
+ * GPollFD:
+ * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32)
+ * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR.
+ * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
+ *
*
- * The type for the function that is used to convert an object property
- * value to a #GVariant for storing it in #GSettings.
*/
/**
- * GSettingsGetMapping:
- * @value: the #GVariant to map, or %NULL
- * @result: (out): the result of the mapping
- * @user_data: (closure): the user data that was passed to g_settings_get_mapped()
- * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error
+ * GPollFunc:
+ * @ufds: an array of #GPollFD elements
+ * @nfsd: the number of elements in @ufds
+ * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout.
*
- * The type of the function that is used to convert from a value stored
- * in a #GSettings to a value that is useful to the application.
- * If the value is successfully mapped, the result should be stored at
- * is not in the right format) then %FALSE should be returned.
- * If @value is %NULL then it means that the mapping function is being
- * given a "last chance" to successfully return a valid value. %TRUE
- * must be returned in this case.
+ * Specifies the type of function passed to g_main_context_set_poll_func().
+ * The semantics of the function should match those of the poll() system call.
+ * reported, or -1 if an error occurred.
+ *
+ * Returns: the number of #GPollFD elements which have events or errors
*/
/**
- * GSignalAccumulator:
- * @ihint: Signal invocation hint, see #GSignalInvocationHint.
- * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission.
- * @handler_return: A #GValue holding the return value of the signal handler.
- * @data: Callback data that was specified when creating the signal.
+ * GPollableInputStream:
*
- * The signal accumulator is a special callback function that can be used
- * to collect return values of the various callbacks that are called
- * during a signal emission. The signal accumulator is specified at signal
- * creation time, if it is left %NULL, no accumulation of callback return
- * values is performed. The return value of signal emissions is then the
- * value returned by the last callback.
- * should be aborted. Returning %FALSE means to abort the
- * current emission and %TRUE is returned for continuation.
+ * An interface for a #GInputStream that can be polled for readability.
*
- * Returns: The accumulator function returns whether the signal emission
+ * Since: 2.28
*/
/**
- * GSignalCMarshaller:
+ * GPollableInputStreamInterface:
+ * @g_iface: The parent interface.
+ * @can_poll: Checks if the #GPollableInputStream instance is actually pollable
+ * @is_readable: Checks if the stream is readable
+ * @create_source: Creates a #GSource to poll the stream
+ * @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK
*
- * This is the signature of marshaller functions, required to marshall
- * arrays of parameter values to signal emissions into C language callback
- * invocations. It is merely an alias to #GClosureMarshal since the #GClosure
- * mechanism takes over responsibility of actual function invocation for the
- * signal system.
+ * The interface for pollable input streams.
+ * The default implementation of @can_poll always returns %TRUE.
+ * The default implementation of @read_nonblocking calls
+ * g_pollable_input_stream_is_readable(), and then calls
+ * g_input_stream_read() if it returns %TRUE. This means you only need
+ * to override it if it is possible that your @is_readable
+ * implementation may return %TRUE when the stream is not actually
+ * readable.
+ *
+ * Since: 2.28
*/
/**
- * GSignalEmissionHook:
- * @ihint: Signal invocation hint, see #GSignalInvocationHint.
- * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted.
- * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission.
- * @data: user data associated with the hook.
+ * GPollableOutputStream:
*
- * A simple function pointer to get invoked when the signal is emitted. This
- * allows you to tie a hook to the signal type, so that it will trap all
- * emissions of that signal, from any object.
- * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
- * hook is disconnected (and destroyed).
+ * An interface for a #GOutputStream that can be polled for readability.
*
- * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
+ * Since: 2.28
*/
/**
- * GSignalFlags:
- * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
- * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
- * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
- * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted.
- * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions.
- * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code.
- * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
- * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30.
+ * GPollableOutputStreamInterface:
+ * @g_iface: The parent interface.
+ * @can_poll: Checks if the #GPollableOutputStream instance is actually pollable
+ * @is_writable: Checks if the stream is writable
+ * @create_source: Creates a #GSource to poll the stream
+ * @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK
*
- * The signal flags are used to specify a signal's behaviour, the overall
- * signal description outlines how especially the RUN flags control the
- * stages of a signal emission.
+ * The interface for pollable output streams.
+ * The default implementation of @can_poll always returns %TRUE.
+ * The default implementation of @write_nonblocking calls
+ * g_pollable_output_stream_is_writable(), and then calls
+ * g_output_stream_write() if it returns %TRUE. This means you only
+ * need to override it if it is possible that your @is_writable
+ * implementation may return %TRUE when the stream is not actually
+ * writable.
+ *
+ * Since: 2.28
*/
/**
- * GSignalInvocationHint:
- * @signal_id: The signal id of the signal invoking the callback
- * @detail: The detail passed on for this emission
- * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
+ * GPollableSourceFunc:
+ * @pollable_stream: the #GPollableInputStream or #GPollableOutputStream
+ * @user_data: data passed in by the user.
*
- * The #GSignalInvocationHint structure is used to pass on additional information
- * to callbacks during a signal emission.
- */
-
-
-/**
- * GSignalMatchType:
- * @G_SIGNAL_MATCH_ID: The signal id must be equal.
- * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
- * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
- * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
- * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
- * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
+ * This is the function type of the callback used for the #GSource
+ * returned by g_pollable_input_stream_create_source() and
+ * g_pollable_output_stream_create_source().
*
- * The match types specify what g_signal_handlers_block_matched(),
- * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
- * match signals by.
+ * Returns: it should return %FALSE if the source should be removed.
+ * Since: 2.28
*/
/**
- * GSignalQuery:
- * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown.
- * @signal_name: The signal name.
- * @itype: The interface/instance type that this signal can be emitted for.
- * @signal_flags: The signal flags as passed in to g_signal_new().
- * @return_type: The return type for user callbacks.
- * @n_params: The number of parameters that user callbacks take.
- * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting>
+ * GProxy:
*
- * A structure holding in-depth information for a specific signal. It is
- * filled in by the g_signal_query() function.
+ * Interface that handles proxy connection and payload.
+ *
+ * Since: 2.26
*/
/**
- * GSimpleAction:
+ * GProxyAddress:
*
- * The <structname>GSimpleAction</structname> structure contains private
- * data and should only be accessed using the provided API
+ * A #GInetSocketAddress representing a connection via a proxy server
*
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * GSimpleAction::activate:
- * @simple: the #GSimpleAction
- * @parameter: (allow-none): the parameter to the activation
- *
- * Indicates that the action was just activated.
- * an incorrect type was given, no signal will be emitted.
+ * GProxyAddressEnumerator:
*
- * Since: 2.28
+ * A subclass of #GSocketAddressEnumerator that takes another address
+ * enumerator and wraps its results in #GProxyAddress<!-- -->es as
+ * directed by the default #GProxyResolver.
*/
/**
- * GSimpleAction:enabled:
+ * GProxyInterface:
+ * @g_iface: The parent interface.
+ * @connect: Connect to proxy server and wrap (if required) the #connection to handle payload.
+ * @connect_async: Same has connect() but asynchronous.
+ * @connect_finish: Returns the result of connect_async()
*
- * If @action is currently enabled.
- * If the action is disabled then calls to g_simple_action_activate() and
- * g_simple_action_set_state() have no effect.
+ * Provides an interface for handling proxy connection and payload.
*
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * GSimpleAction:name:
- *
- * The name of the action. This is mostly meaningful for identifying
- * the action once it has been added to a #GSimpleActionGroup.
+ * GProxyResolver:
*
- * Since: 2.28
+ * Interface that can be used to resolve proxy address.
*/
/**
- * GSimpleAction:parameter-type:
+ * GReallocFunc:
+ * @data: memory block to reallocate
+ * @size: size to reallocate @data to
*
- * The type of the parameter that must be given when activating the
- * action.
+ * Changes the size of the memory block pointed to by @data to
+ * The function should have the same semantics as realloc().
*
- * Since: 2.28
+ * Returns: a pointer to the reallocated memory
*/
/**
- * GSimpleAction:state:
+ * GRegex:
*
- * The state of the action, or %NULL if the action is stateless.
+ * A GRegex is the "compiled" form of a regular expression pattern. This
+ * structure is opaque and its fields cannot be accessed directly.
*
- * Since: 2.28
+ * Since: 2.14
*/
/**
- * GSimpleAction:state-type:
+ * GRegexCompileFlags:
+ * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting.
+ * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting.
+ * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting.
+ * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting.
+ * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
+ * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
+ * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
+ * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
+ * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
+ * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
+ * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'.
+ * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'.
*
- * The #GVariantType of the state that the action has, or %NULL if the
- * action is stateless.
+ * Flags specifying compile-time options.
*
- * Since: 2.28
+ * Since: 2.14
*/
/**
- * GSimpleActionClass:
- * @activate: the class closure for the activate signal
- *
+ * GRegexError:
+ * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed.
+ * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed.
+ * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string.
+ * @G_REGEX_ERROR_MATCH: The match process failed.
+ * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16
+ * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16
+ * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16
+ * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16
+ * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16
+ * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16
+ * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16
+ * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16
+ * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16
+ * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16
+ * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16
+ * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16
+ * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16
+ * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16
+ * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16
+ * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16
+ * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16
+ * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16
+ * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16
+ * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16
+ * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16
+ * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16
+ * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16
+ * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16
+ * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16
+ * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16
+ * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16
+ * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16
+ * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16
+ * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16
+ * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16
+ * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16
+ * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16
+ * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16
+ * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16
+ * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16
+ * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16
+ * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16
*
+ * Error codes returned by regular expressions functions.
*
- * Since: 2.28
+ * Since: 2.14
*/
/**
- * GSimpleActionGroup:
+ * GRegexEvalCallback:
+ * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string.
+ * @result: a #GString containing the new string
+ * @user_data: user data passed to g_regex_replace_eval()
*
- * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API.
+ * Specifies the type of the function passed to g_regex_replace_eval().
+ * It is called for each occurance of the pattern in the string passed
+ * to g_regex_replace_eval(), and it should append the replacement to
*
- * Since: 2.28
+ * Returns: %FALSE to continue the replacement process, %TRUE to stop it
+ * Since: 2.14
*/
/**
- * GSimpleAsyncResult:
+ * GRegexMatchFlags:
+ * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
+ * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A".
+ * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z".
+ * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b".
+ * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match().
+ * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator.
+ * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator.
+ * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator.
+ * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized.
*
- * A simple implementation of #GAsyncResult.
+ * Flags specifying match-time options.
+ *
+ * Since: 2.14
*/
/**
- * GSimpleAsyncThreadFunc:
- * @res: a #GSimpleAsyncResult.
- * @object: a #GObject.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * GResolver:
*
- * Simple thread function that runs an asynchronous operation and
- * checks for cancellation.
+ * The object that handles DNS resolution. Use g_resolver_get_default()
+ * to get the default resolver.
*/
/**
- * GSimplePermission:
+ * GResolver::reload:
+ * @resolver: a #GResolver
*
- * #GSimplePermission is an opaque data structure. There are no methods
- * except for those defined by #GPermission.
+ * Emitted when the resolver notices that the system resolver
+ * configuration has changed.
*/
/**
- * GSocket:
+ * GResolverError:
+ * @G_RESOLVER_ERROR_NOT_FOUND: the requested name/address/service was not found
+ * @G_RESOLVER_ERROR_TEMPORARY_FAILURE: the requested information could not be looked up due to a network error or similar problem
+ * @G_RESOLVER_ERROR_INTERNAL: unknown error
*
- * A lowlevel network socket object.
+ * An error code used with %G_RESOLVER_ERROR in a #GError returned
+ * from a #GResolver routine.
*
* Since: 2.22
*/
/**
- * GSocket:timeout:
- *
- * The timeout in seconds on socket I/O
+ * GSeekable:
*
- * Since: 2.26
+ * Seek object for streaming operations.
*/
/**
- * GSocketAddress:
+ * GSeekableIface:
+ * @g_iface: The parent interface.
+ * @tell: Tells the current location within a stream.
+ * @can_seek: Checks if seeking is supported by the stream.
+ * @seek: Seeks to a location within a stream.
+ * @can_truncate: Chekcs if truncation is suppored by the stream.
+ * @truncate_fn: Truncates a stream.
*
- * A socket endpoint address, corresponding to <type>struct sockaddr</type>
- * or one of its subtypes.
+ * Provides an interface for implementing seekable functionality on I/O Streams.
*/
/**
- * GSocketAddressEnumerator:
+ * GSettings::change-event:
+ * @settings: the object on which the signal was emitted
+ * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL
+ * @n_keys: the length of the @keys array, or 0
+ * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
*
- * Enumerator type for objects that contain or generate
- * #GSocketAddress<!-- -->es.
+ * 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
+ * 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 supressed.
+ *
+ * Whole (ie: potentially every key has been changed) then @keys will
*/
/**
- * GSocketClient:
+ * GSettings::changed:
+ * @settings: the object on which the signal was emitted
+ * @key: the name of the key that changed
*
- * A helper class for network servers to listen for and accept connections.
+ * The "changed" signal is emitted when a key has potentially changed.
+ * You should call one of the g_settings_get() calls to check the new
+ * value.
+ * This signal supports detailed connections. You can connect to the
+ * detailed signal "changed::x" in order to only receive callbacks
+ * when key "x" changes.
+ */
+
+
+/**
+ * GSettings::writable-change-event:
+ * @settings: the object on which the signal was emitted
+ * @key: the quark of the key, or 0
+ * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
*
- * Since: 2.22
+ * 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,
+ * 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 supressed.
*/
/**
- * GSocketConnectable:
+ * GSettings::writable-changed:
+ * @settings: the object on which the signal was emitted
+ * @key: the key
*
- * Interface for objects that contain or generate #GSocketAddress<!-- -->es.
+ * 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.
*/
/**
- * GSocketConnectableIface:
- * @g_iface: The parent interface.
- * @enumerate: Creates a #GSocketAddressEnumerator
- * @proxy_enumerate: Creates a #GProxyAddressEnumerator
+ * GSettings:context:
*
- * Provides an interface for returning a #GSocketAddressEnumerator
- * and #GProxyAddressEnumerator
+ * The name of the context that the settings are stored in.
*/
/**
- * GSocketConnection:
+ * GSettings:delay-apply:
*
- * A socket connection GIOStream object for connection-oriented sockets.
+ * Whether the #GSettings object is in 'delay-apply' mode. See
+ * g_settings_delay() for details.
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GSocketControlMessage:
+ * GSettings:has-unapplied:
*
- * Base class for socket-type specific control messages that can be sent and
- * received over #GSocket.
+ * If this property is %TRUE, the #GSettings object has outstanding
+ * changes that will be applied when g_settings_apply() is called.
*/
/**
- * GSocketControlMessageClass:
- * @get_size: gets the size of the message.
- * @get_level: gets the protocol of the message.
- * @get_type: gets the protocol specific type of the message.
- * @serialize: Writes out the message data.
- * @deserialize: Tries to deserialize a message.
- *
+ * GSettings:path:
*
+ * The path within the backend where the settings are stored.
*/
/**
- * GSocketFamily:
- * @G_SOCKET_FAMILY_INVALID: no address family
- * @G_SOCKET_FAMILY_IPV4: the IPv4 family
- * @G_SOCKET_FAMILY_IPV6: the IPv6 family
- * @G_SOCKET_FAMILY_UNIX: the UNIX domain family
- *
- * The protocol family of a #GSocketAddress. (These values are
- * identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX,
- * if available.)
+ * GSettings:schema:
*
- * Since: 2.22
+ * The name of the schema that describes the types of keys
+ * for this #GSettings object.
*/
/**
- * GSocketListenerClass:
- * @changed: virtual method called when the set of socket listened to changes
- *
+ * GSettingsBackend:
*
+ * An implementation of a settings storage repository.
*/
/**
- * GSocketMsgFlags:
- * @G_SOCKET_MSG_NONE: No flags.
- * @G_SOCKET_MSG_OOB: Request to send/receive out of band data.
- * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue.
- * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks.
- *
- * Flags used in g_socket_receive_message() and g_socket_send_message().
- * The flags listed in the enum are some commonly available flags, but the
- * values used for them are the same as on the platform, and any other flags
- * are passed in/out as is. So to use a platform specific flag, just include
- * the right system header and pass in the flag.
+ * GSettingsBindFlags:
+ * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
+ * @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable.
+ * @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable.
+ * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting
+ * @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting
+ * @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to g_settings_bind_with_mapping().
*
- * Since: 2.22
+ * Flags used when creating a binding. These flags determine in which
+ * direction the binding works. The default is to synchronize in both
+ * directions.
*/
/**
- * GSocketProtocol:
- * @G_SOCKET_PROTOCOL_UNKNOWN: The protocol type is unknown
- * @G_SOCKET_PROTOCOL_DEFAULT: The default protocol for the family/type
- * @G_SOCKET_PROTOCOL_TCP: TCP over IP
- * @G_SOCKET_PROTOCOL_UDP: UDP over IP
- * @G_SOCKET_PROTOCOL_SCTP: SCTP over IP
- *
- * A protocol identifier is specified when creating a #GSocket, which is a
- * family/type specific identifier, where 0 means the default protocol for
- * the particular family/type.
- * This enum contains a set of commonly available and used protocols. You
- * can also pass any other identifiers handled by the platform in order to
- * use protocols not listed here.
+ * GSettingsBindGetMapping:
+ * @value: return location for the property value
+ * @variant: the #GVariant
+ * @user_data: user data that was specified when the binding was created
+ * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error
*
- * Since: 2.22
+ * The type for the function that is used to convert from #GSettings to
+ * an object property. The @value is already initialized to hold values
+ * of the appropriate type.
*/
/**
- * GSocketService:
- *
- * A helper class for handling accepting incomming connections in the
- * glib mainloop.
+ * GSettingsBindSetMapping:
+ * @value: a #GValue containing the property value to map
+ * @expected_type: the #GVariantType to create
+ * @user_data: user data that was specified when the binding was created
+ * @returns: a new #GVariant holding the data from @value, or %NULL in case of an error
*
- * Since: 2.22
+ * The type for the function that is used to convert an object property
+ * value to a #GVariant for storing it in #GSettings.
*/
/**
- * GSocketService::incoming:
- * @service: the #GSocketService.
- * @connection: a new #GSocketConnection object.
- * @source_object: the source_object passed to g_socket_listener_add_address().
- *
- * The ::incoming signal is emitted when a new incoming connection
- * to @service needs to be handled. The handler must initiate the
- * handling of @connection, but may not block; in essence,
- * asynchronous operations must be used.
+ * GSettingsGetMapping:
+ * @value: the #GVariant to map, or %NULL
+ * @result: (out): the result of the mapping
+ * @user_data: (closure): the user data that was passed to g_settings_get_mapped()
+ * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error
*
- * Returns: %TRUE to stop other handlers from being called
- * Since: 2.22
+ * The type of the function that is used to convert from a value stored
+ * in a #GSettings to a value that is useful to the application.
+ * If the value is successfully mapped, the result should be stored at
+ * is not in the right format) then %FALSE should be returned.
+ * If @value is %NULL then it means that the mapping function is being
+ * given a "last chance" to successfully return a valid value. %TRUE
+ * must be returned in this case.
*/
/**
- * GSocketServiceClass:
- * @incomming: signal emitted when new connections are accepted
+ * GSignalAccumulator:
+ * @ihint: Signal invocation hint, see #GSignalInvocationHint.
+ * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission.
+ * @handler_return: A #GValue holding the return value of the signal handler.
+ * @data: Callback data that was specified when creating the signal.
*
+ * The signal accumulator is a special callback function that can be used
+ * to collect return values of the various callbacks that are called
+ * during a signal emission. The signal accumulator is specified at signal
+ * creation time, if it is left %NULL, no accumulation of callback return
+ * values is performed. The return value of signal emissions is then the
+ * value returned by the last callback.
+ * should be aborted. Returning %FALSE means to abort the
+ * current emission and %TRUE is returned for continuation.
*
+ * Returns: The accumulator function returns whether the signal emission
*/
/**
- * GSocketSourceFunc:
- * @socket: the #GSocket
- * @condition: the current condition at the source fired.
- * @user_data: data passed in by the user.
- *
- * This is the function type of the callback used for the #GSource
- * returned by g_socket_create_source().
+ * GSignalCMarshaller:
*
- * Returns: it should return %FALSE if the source should be removed.
- * Since: 2.22
+ * This is the signature of marshaller functions, required to marshall
+ * arrays of parameter values to signal emissions into C language callback
+ * invocations. It is merely an alias to #GClosureMarshal since the #GClosure
+ * mechanism takes over responsibility of actual function invocation for the
+ * signal system.
*/
/**
- * GSocketType:
- * @G_SOCKET_TYPE_INVALID: Type unknown or wrong
- * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP).
- * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP)
- * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP).
+ * GSignalEmissionHook:
+ * @ihint: Signal invocation hint, see #GSignalInvocationHint.
+ * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted.
+ * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission.
+ * @data: user data associated with the hook.
*
- * Flags used when creating a #GSocket. Some protocols may not implement
- * all the socket types.
+ * A simple function pointer to get invoked when the signal is emitted. This
+ * allows you to tie a hook to the signal type, so that it will trap all
+ * emissions of that signal, from any object.
+ * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
+ * hook is disconnected (and destroyed).
*
- * Since: 2.22
+ * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
*/
/**
- * GSource:
+ * GSignalFlags:
+ * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
+ * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
+ * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
+ * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted.
+ * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions.
+ * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code.
+ * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
+ * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30.
*
- * The <structname>GSource</structname> struct is an opaque data type
- * representing an event source.
+ * The signal flags are used to specify a signal's behaviour, the overall
+ * signal description outlines how especially the RUN flags control the
+ * stages of a signal emission.
*/
/**
- * GSourceCallbackFuncs:
- * @ref: Called when a reference is added to the callback object
- * @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object.
+ * GSignalInvocationHint:
+ * @signal_id: The signal id of the signal invoking the callback
+ * @detail: The detail passed on for this emission
+ * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
*
- * The <structname>GSourceCallbackFuncs</structname> struct contains
- * functions for managing callback objects.
+ * The #GSignalInvocationHint structure is used to pass on additional information
+ * to callbacks during a signal emission.
*/
/**
- * GSourceFuncs:
- * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the
- * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
- * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source.
- * @finalize: Called when the source is finalized.
- *
- * The <structname>GSourceFuncs</structname> struct contains a table of
- * functions used to handle event sources in a generic manner.
- * For idle sources, the prepare and check functions always return %TRUE
- * to indicate that the source is always ready to be processed. The prepare
- * function also returns a timeout value of 0 to ensure that the poll() call
- * doesn't block (since that would be time wasted which could have been spent
- * running the idle function).
- * For timeout sources, the prepare and check functions both return %TRUE
- * if the timeout interval has expired. The prepare function also returns
- * a timeout value to ensure that the poll() call doesn't block too long
- * and miss the next timeout.
- * For file descriptor sources, the prepare function typically returns %FALSE,
- * since it must wait until poll() has been called before it knows whether
- * any events need to be processed. It sets the returned timeout to -1 to
- * indicate that it doesn't mind how long the poll() call blocks. In the
- * check function, it tests the results of the poll() call to see if the
- * required condition has been met, and returns %TRUE if so.
- */
-
-
-/**
- * GSrvTarget:
+ * GSignalMatchType:
+ * @G_SIGNAL_MATCH_ID: The signal id must be equal.
+ * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
+ * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
+ * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
+ * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
+ * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
*
- * A single target host/port that a network service is running on.
+ * The match types specify what g_signal_handlers_block_matched(),
+ * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
+ * match signals by.
*/
/**
- * GStrv:
+ * GSignalQuery:
+ * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown.
+ * @signal_name: The signal name.
+ * @itype: The interface/instance type that this signal can be emitted for.
+ * @signal_flags: The signal flags as passed in to g_signal_new().
+ * @return_type: The return type for user callbacks.
+ * @n_params: The number of parameters that user callbacks take.
+ * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting>
*
- * A C representable type name for #G_TYPE_STRV.
+ * A structure holding in-depth information for a specific signal. It is
+ * filled in by the g_signal_query() function.
*/
/**
- * GTcpConnection:
+ * GSimpleAction:
*
- * A #GSocketConnection for UNIX domain socket connections.
+ * The <structname>GSimpleAction</structname> structure contains private
+ * data and should only be accessed using the provided API
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GTestLogFatalFunc:
- * @log_domain: the log domain of the message
- * @log_level: the log level of the message (including the fatal and recursion flags)
- * @message: the message to process
- * @user_data: user data, set in g_test_log_set_fatal_handler()
+ * GSimpleAction::activate:
+ * @simple: the #GSimpleAction
+ * @parameter: (allow-none): the parameter to the activation
*
- * Specifies the prototype of fatal log handler functions.
+ * Indicates that the action was just activated.
+ * an incorrect type was given, no signal will be emitted.
*
- * Returns: %TRUE if the program should abort, %FALSE otherwise
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GThemedIcon:
+ * GSimpleAction:enabled:
*
- * An implementation of #GIcon for themed icons.
+ * If @action is currently enabled.
+ * If the action is disabled then calls to g_simple_action_activate() and
+ * g_simple_action_set_state() have no effect.
+ *
+ * Since: 2.28
*/
/**
- * GThemedIcon:name:
+ * GSimpleAction:name:
*
- * The icon name.
+ * The name of the action. This is mostly meaningful for identifying
+ * the action once it has been added to a #GSimpleActionGroup.
+ *
+ * Since: 2.28
*/
/**
- * GThemedIcon:names:
+ * GSimpleAction:parameter-type:
*
- * A %NULL-terminated array of icon names.
+ * The type of the parameter that must be given when activating the
+ * action.
+ *
+ * Since: 2.28
*/
/**
- * GThemedIcon:use-default-fallbacks:
+ * GSimpleAction:state:
*
- * Whether to use the default fallbacks found by shortening the icon name
- * at '-' characters. If the "names" array has more than one element,
- * ignores any past the first.
- * For example, if the icon name was "gnome-dev-cdrom-audio", the array
- * would become
- * |[
- * {
- * "gnome-dev-cdrom-audio",
- * "gnome-dev-cdrom",
- * "gnome-dev",
- * "gnome",
- * NULL
- * };
- * ]|
+ * The state of the action, or %NULL if the action is stateless.
+ *
+ * Since: 2.28
*/
/**
- * GThreadedSocketService:
+ * GSimpleAction:state-type:
*
- * A helper class for handling accepting incomming connections in the
- * glib mainloop and handling them in a thread.
+ * The #GVariantType of the state that the action has, or %NULL if the
+ * action is stateless.
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * GThreadedSocketService::run:
- * @service: the #GThreadedSocketService.
- * @connection: a new #GSocketConnection object.
- * @source_object: the source_object passed to g_socket_listener_add_address().
+ * GSimpleActionClass:
+ * @activate: the class closure for the activate signal
+ *
*
- * The ::run signal is emitted in a worker thread in response to an
- * incoming connection. This thread is dedicated to handling
- * not return until the connection is closed.
*
- * Returns: %TRUE to stope further signal handlers from being called
+ * Since: 2.28
*/
/**
- * GTimeSpan:
+ * GSimpleActionGroup:
*
- * A value representing an interval of time, in microseconds.
+ * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * GTimeType:
- * @G_TIME_TYPE_STANDARD: the time is in local standard time
- * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time
- * @G_TIME_TYPE_UNIVERSAL: the time is in UTC
+ * GSimpleAsyncResult:
*
- * Disambiguates a given time in two ways.
- * First, specifies if the given time is in universal or local time.
- * Second, if the time is in local time, specifies if it is local
- * standard time or local daylight time. This is important for the case
- * where the same local time occurs twice (during daylight savings time
- * transitions, for example).
+ * A simple implementation of #GAsyncResult.
*/
/**
- * GTlsAuthenticationMode:
- * @G_TLS_AUTHENTICATION_NONE: client authentication not required
- * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested
- * @G_TLS_AUTHENTICATION_REQUIRED: client authentication is required
- *
- * The client authentication mode for a #GTlsServerConnection.
+ * GSimpleAsyncThreadFunc:
+ * @res: a #GSimpleAsyncResult.
+ * @object: a #GObject.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
*
- * Since: 2.28
+ * Simple thread function that runs an asynchronous operation and
+ * checks for cancellation.
*/
/**
- * GTlsBackend:
- *
- * TLS (Transport Layer Security, aka SSL) backend. This is an
- * internal type used to coordinate the different classes implemented
- * by a TLS backend.
+ * GSimplePermission:
*
- * Since: 2.28
+ * #GSimplePermission is an opaque data structure. There are no methods
+ * except for those defined by #GPermission.
*/
/**
- * GTlsBackendInterface:
- * @g_iface: The parent interface.
- * @get_certificate_type: returns the #GTlsCertificate implementation type
- * @get_client_connection_type: returns the #GTlsClientConnection implementation type
- * @get_server_connection_type: returns the #GTlsServerConnection implementation type
+ * GSocket:
*
- * Provides an interface for describing TLS-related types.
+ * A lowlevel network socket object.
*
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * GTlsCertificate:
+ * GSocket:timeout:
*
- * Abstract base class for TLS certificate types.
+ * The timeout in seconds on socket I/O
*
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * GTlsCertificate:certificate:
- *
- * The DER (binary) encoded representation of the certificate's
- * public key. This property and the
- * #GTlsCertificate:certificate-pem property represent the same
- * data, just in different forms.
+ * GSocketAddress:
*
- * Since: 2.28
+ * A socket endpoint address, corresponding to <type>struct sockaddr</type>
+ * or one of its subtypes.
*/
/**
- * GTlsCertificate:certificate-pem:
- *
- * The PEM (ASCII) encoded representation of the certificate's
- * public key. This property and the #GTlsCertificate:certificate
- * property represent the same data, just in different forms.
+ * GSocketAddressEnumerator:
*
- * Since: 2.28
+ * Enumerator type for objects that contain or generate
+ * #GSocketAddress<!-- -->es.
*/
/**
- * GTlsCertificate:issuer:
+ * GSocketClient:
*
- * 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.
+ * A helper class for network servers to listen for and accept connections.
*
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * GTlsCertificate:private-key:
- *
- * The DER (binary) encoded representation of the certificate's
- * private key. This property (or the
- * #GTlsCertificate:private-key-pem property) can be set when
- * constructing a key (eg, from a file), but cannot be read.
+ * GSocketConnectable:
*
- * Since: 2.28
+ * Interface for objects that contain or generate #GSocketAddress<!-- -->es.
*/
/**
- * GTlsCertificate:private-key-pem:
- *
- * The PEM (ASCII) encoded representation of the certificate's
- * private key. This property (or the #GTlsCertificate:private-key
- * property) can be set when constructing a key (eg, from a file),
- * but cannot be read.
+ * GSocketConnectableIface:
+ * @g_iface: The parent interface.
+ * @enumerate: Creates a #GSocketAddressEnumerator
+ * @proxy_enumerate: Creates a #GProxyAddressEnumerator
*
- * Since: 2.28
+ * Provides an interface for returning a #GSocketAddressEnumerator
+ * and #GProxyAddressEnumerator
*/
/**
- * GTlsCertificateFlags:
- * @G_TLS_CERTIFICATE_UNKNOWN_CA: The signing certificate authority is not known.
- * @G_TLS_CERTIFICATE_BAD_IDENTITY: The certificate does not match the expected identity of the site that it was retrieved from.
- * @G_TLS_CERTIFICATE_NOT_ACTIVATED: The certificate's activation time is still in the future
- * @G_TLS_CERTIFICATE_EXPIRED: The certificate has expired
- * @G_TLS_CERTIFICATE_REVOKED: The certificate has been revoked according to the #GTlsContext's certificate revocation list.
- * @G_TLS_CERTIFICATE_INSECURE: The certificate's algorithm is considered insecure.
- * @G_TLS_CERTIFICATE_GENERIC_ERROR: Some other error occurred validating the certificate
- * @G_TLS_CERTIFICATE_VALIDATE_ALL: the combination of all of the above flags
+ * GSocketConnection:
*
- * A set of flags describing TLS certification validation. This can be
- * used to set which validation steps to perform (eg, with
- * g_tls_client_connection_set_validation_flags()), or to describe why
- * a particular certificate was rejected (eg, in
- * #GTlsConnection::accept-certificate).
+ * A socket connection GIOStream object for connection-oriented sockets.
*
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * GTlsClientConnection:
- *
- * TLS client-side connection; the client-side implementation of a
- * #GTlsConnection
+ * GSocketControlMessage:
*
- * Since: 2.28
+ * Base class for socket-type specific control messages that can be sent and
+ * received over #GSocket.
*/
/**
- * GTlsClientConnection:accepted-cas:
- *
- * A list of the distinguished names of the Certificate Authorities
- * that the server will accept client certificates signed by. If the
- * server requests a client certificate during the handshake, then
- * this property will be set after the handshake completes.
- * Each item in the list is a #GByteArray which contains the complete
- * subject DN of the certificate authority.
+ * GSocketControlMessageClass:
+ * @get_size: gets the size of the message.
+ * @get_level: gets the protocol of the message.
+ * @get_type: gets the protocol specific type of the message.
+ * @serialize: Writes out the message data.
+ * @deserialize: Tries to deserialize a message.
+ *
*
- * Since: 2.28
*/
/**
- * GTlsClientConnection:server-identity:
+ * GSocketFamily:
+ * @G_SOCKET_FAMILY_INVALID: no address family
+ * @G_SOCKET_FAMILY_IPV4: the IPv4 family
+ * @G_SOCKET_FAMILY_IPV6: the IPv6 family
+ * @G_SOCKET_FAMILY_UNIX: the UNIX domain family
*
- * 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.
+ * 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.28
+ * Since: 2.22
*/
/**
- * GTlsClientConnection:use-ssl3:
+ * GSocketListenerClass:
+ * @changed: virtual method called when the set of socket listened to changes
*
- * If %TRUE, tells the connection to use SSL 3.0 rather than trying
- * to negotiate the best version of TLS or SSL to use. This can be
- * used when talking to servers that don't implement version
- * negotiation correctly and therefore refuse to handshake at all with
- * a "modern" TLS handshake.
*
- * Since: 2.28
*/
/**
- * GTlsClientConnection:validation-flags:
+ * GSocketMsgFlags:
+ * @G_SOCKET_MSG_NONE: No flags.
+ * @G_SOCKET_MSG_OOB: Request to send/receive out of band data.
+ * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue.
+ * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks.
*
- * What steps to perform when validating a certificate received from
- * a server. Server certificates that fail to validate in all of the
- * ways indicated here will be rejected unless the application
- * overrides the default via #GTlsConnection::accept-certificate.
+ * 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.28
+ * Since: 2.22
*/
/**
- * GTlsConnection:
+ * GSocketProtocol:
+ * @G_SOCKET_PROTOCOL_UNKNOWN: The protocol type is unknown
+ * @G_SOCKET_PROTOCOL_DEFAULT: The default protocol for the family/type
+ * @G_SOCKET_PROTOCOL_TCP: TCP over IP
+ * @G_SOCKET_PROTOCOL_UDP: UDP over IP
+ * @G_SOCKET_PROTOCOL_SCTP: SCTP over IP
*
- * TLS connection. This is an abstract type that will be subclassed by
- * a TLS-library-specific subtype.
+ * 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.28
+ * Since: 2.22
*/
/**
- * GTlsConnection::accept-certificate:
- * @conn: a #GTlsConnection
- * @peer_cert: the peer's #GTlsCertificate
- * @errors: the problems with @peer_cert.
+ * GSocketService:
*
- * Emitted during the TLS handshake after the peer certificate has
- * been received. You can examine @peer_cert's certification path by
- * calling g_tls_certificate_get_issuer() on it.
- * For a client-side connection, @peer_cert is the server's
- * certificate, and the signal will only be emitted if the
- * certificate was not acceptable according to @conn's
- * #GTlsClientConnection:validation_flags. If you would like the
- * certificate to be accepted despite @errors, return %TRUE from the
- * signal handler. Otherwise, if no handler accepts the certificate,
- * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
- * For a server-side connection, @peer_cert is the certificate
- * presented by the client, if this was requested via the server's
- * #GTlsServerConnection:authentication_mode. On the server side,
- * the signal is always emitted when the client presents a
- * certificate, and the certificate will only be accepted if a
- * handler returns %TRUE.
- * Note that if this signal is emitted as part of asynchronous I/O
- * in the main thread, then you should not attempt to interact with
- * the user before returning from the signal handler. If you want to
- * let the user decide whether or not to accept the certificate, you
- * would have to return %FALSE from the signal handler on the first
- * attempt, and then after the connection attempt returns a
- * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
- * the user decides to accept the certificate, remember that fact,
- * create a new connection, and return %TRUE from the signal handler
- * the next time.
- * If you are doing I/O in another thread, you do not
- * need to worry about this, and can simply block in the signal
- * handler until the UI thread returns an answer.
- * immediately end the signal emission). %FALSE to allow the signal
- * emission to continue, which will cause the handshake to fail if
- * no one else overrides it.
+ * A helper class for handling accepting incomming connections in the
+ * glib mainloop.
*
- * Returns: %TRUE to accept @peer_cert (which will also
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * GTlsConnection:base-io-stream:
+ * GSocketService::incoming:
+ * @service: the #GSocketService
+ * @connection: a new #GSocketConnection object
+ * @source_object: the source_object passed to g_socket_listener_add_address()
*
- * The #GIOStream that the connection wraps
+ * 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.
+ * so you need to ref it yourself if you are planning to use it.
*
- * Since: 2.28
+ * Returns: %TRUE to stop other handlers from being called
+ * Since: 2.22
*/
/**
- * GTlsConnection:certificate:
+ * GSocketServiceClass:
+ * @incomming: signal emitted when new connections are accepted
*
- * The connection's certificate; see
- * g_tls_connection_set_certificate().
*
- * Since: 2.28
*/
/**
- * GTlsConnection:peer-certificate:
+ * GSocketSourceFunc:
+ * @socket: the #GSocket
+ * @condition: the current condition at the source fired.
+ * @user_data: data passed in by the user.
*
- * The connection's peer's certificate, after the TLS handshake has
- * completed and the certificate has been accepted. Note in
- * particular that this is not yet set during the emission of
- * #GTlsConnection::accept-certificate.
- * (You can watch for a #GObject::notify signal on this property to
- * detect when a handshake has occurred.)
+ * This is the function type of the callback used for the #GSource
+ * returned by g_socket_create_source().
*
- * Since: 2.28
+ * Returns: it should return %FALSE if the source should be removed.
+ * Since: 2.22
*/
/**
- * GTlsConnection:peer-certificate-errors:
+ * GSocketType:
+ * @G_SOCKET_TYPE_INVALID: Type unknown or wrong
+ * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP).
+ * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP)
+ * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP).
*
- * The errors noticed-and-ignored while verifying
- * #GTlsConnection:peer-certificate. Normally this should be %0, but
- * it may not be if #GTlsClientConnection::validation-flags is not
- * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
- * #GTlsConnection::accept-certificate overrode the default
- * behavior.
+ * Flags used when creating a #GSocket. Some protocols may not implement
+ * all the socket types.
*
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * GTlsConnection:rehandshake-mode:
- *
- * The rehandshaking mode. See
- * g_tls_connection_set_rehandshake_mode().
+ * GSource:
*
- * Since: 2.28
+ * The <structname>GSource</structname> struct is an opaque data type
+ * representing an event source.
*/
/**
- * GTlsConnection:require-close-notify:
- *
- * Whether or not proper TLS close notification is required.
- * See g_tls_connection_set_require_close_notify().
+ * GSourceCallbackFuncs:
+ * @ref: Called when a reference is added to the callback object
+ * @unref: Called when a reference to the callback object is dropped
+ * @get: Called to extract the callback function and data from the callback object.
*
- * Since: 2.28
+ * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * functions for managing callback objects.
*/
/**
- * GTlsConnection:use-system-certdb:
- *
- * Whether or not the system certificate database will be used to
- * verify peer certificates. See
- * g_tls_connection_set_use_system_certdb().
+ * GSourceDummyMarshal:
*
- * Since: 2.28
+ * This is just a placeholder for #GClosureMarshal,
+ * which cannot be used here for dependency reasons.
*/
/**
- * GTlsError:
- * @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available
- * @G_TLS_ERROR_MISC: Miscellaneous TLS error
- * @G_TLS_ERROR_BAD_CERTIFICATE: A certificate could not be parsed
- * @G_TLS_ERROR_NOT_TLS: The TLS handshake failed because the peer does not seem to be a TLS server.
- * @G_TLS_ERROR_HANDSHAKE: The TLS handshake failed because the peer's certificate was not acceptable.
- * @G_TLS_ERROR_CERTIFICATE_REQUIRED: The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate().
- * @G_TLS_ERROR_EOF: The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify().
+ * GSourceFunc:
+ * @data: data passed to the function, set when the source was created with one of the above functions
*
- * An error code used with %G_TLS_ERROR in a #GError returned from a
- * TLS-related routine.
+ * Specifies the type of function passed to g_timeout_add(),
+ * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
*
- * Since: 2.28
+ * Returns: %FALSE if the source should be removed
*/
/**
- * GTlsRehandshakeMode:
- * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking
- * @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only
- * @G_TLS_REHANDSHAKE_UNSAFELY: Allow unsafe rehandshaking
- *
- * When to allow rehandshaking. See
- * g_tls_connection_set_rehandshake_mode().
+ * GSourceFuncs:
+ * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the
+ * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
+ * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source.
+ * @finalize: Called when the source is finalized.
*
- * Since: 2.28
+ * The <structname>GSourceFuncs</structname> struct contains a table of
+ * functions used to handle event sources in a generic manner.
+ * For idle sources, the prepare and check functions always return %TRUE
+ * to indicate that the source is always ready to be processed. The prepare
+ * function also returns a timeout value of 0 to ensure that the poll() call
+ * doesn't block (since that would be time wasted which could have been spent
+ * running the idle function).
+ * For timeout sources, the prepare and check functions both return %TRUE
+ * if the timeout interval has expired. The prepare function also returns
+ * a timeout value to ensure that the poll() call doesn't block too long
+ * and miss the next timeout.
+ * For file descriptor sources, the prepare function typically returns %FALSE,
+ * since it must wait until poll() has been called before it knows whether
+ * any events need to be processed. It sets the returned timeout to -1 to
+ * indicate that it doesn't mind how long the poll() call blocks. In the
+ * check function, it tests the results of the poll() call to see if the
+ * required condition has been met, and returns %TRUE if so.
*/
/**
- * GTlsServerConnection:
+ * GSrvTarget:
*
- * TLS server-side connection. This is the server-side implementation
- * of a #GTlsConnection.
+ * A single target host/port that a network service is running on.
+ */
+
+
+/**
+ * GStrv:
*
- * Since: 2.28
+ * A C representable type name for #G_TYPE_STRV.
*/
/**
- * GTlsServerConnection:authentication-mode:
+ * GTcpConnection:
*
- * 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.
+ * A #GSocketConnection for TCP/IP connections.
*
- * Since: 2.28
+ * Since: 2.22
*/
/**
- * GToggleNotify:
- * @data: Callback data passed to g_object_add_toggle_ref()
- * @object: The object on which g_object_add_toggle_ref() was called.
- * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references.
+ * GTestLogFatalFunc:
+ * @log_domain: the log domain of the message
+ * @log_level: the log level of the message (including the fatal and recursion flags)
+ * @message: the message to process
+ * @user_data: user data, set in g_test_log_set_fatal_handler()
*
- * A callback function used for notification when the state
- * of a toggle reference changes. See g_object_add_toggle_ref().
+ * Specifies the prototype of fatal log handler functions.
+ *
+ * Returns: %TRUE if the program should abort, %FALSE otherwise
+ * Since: 2.22
*/
/**
- * GTranslateFunc:
- * @str: the untranslated string
- * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func()
- *
- * The type of functions which are used to translate user-visible
- * strings, for <option>--help</option> output.
- * The returned string is owned by GLib and must not be freed.
+ * GThemedIcon:
*
- * Returns: a translation of the string for the current locale.
+ * An implementation of #GIcon for themed icons.
*/
/**
- * GType:
+ * GThemedIcon:name:
*
- * A numerical value which represents the unique identifier of a registered
- * type.
+ * The icon name.
*/
/**
- * GTypeClass:
+ * GThemedIcon:names:
*
- * An opaque structure used as the base of all classes.
+ * A %NULL-terminated array of icon names.
*/
/**
- * GTypeClassCacheFunc:
- * @cache_data: data that was given to the g_type_add_class_cache_func() call
- * @g_class: The #GTypeClass structure which is unreferenced
- *
- * A callback function which is called when the reference count of a class
- * drops to zero. It may use g_type_class_ref() to prevent the class from
- * being freed. You should not call g_type_class_unref() from a
- * #GTypeClassCacheFunc function to prevent infinite recursion, use
- * g_type_class_unref_uncached() instead.
- * The functions have to check the class id passed in to figure
- * whether they actually want to cache the class of this type, since all
- * classes are routed through the same #GTypeClassCacheFunc chain.
- * called, %FALSE to continue.
+ * GThemedIcon:use-default-fallbacks:
*
- * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
+ * Whether to use the default fallbacks found by shortening the icon name
+ * at '-' characters. If the "names" array has more than one element,
+ * ignores any past the first.
+ * For example, if the icon name was "gnome-dev-cdrom-audio", the array
+ * would become
+ * |[
+ * {
+ * "gnome-dev-cdrom-audio",
+ * "gnome-dev-cdrom",
+ * "gnome-dev",
+ * "gnome",
+ * NULL
+ * };
+ * ]|
*/
/**
- * GTypeDebugFlags:
- * @G_TYPE_DEBUG_NONE: Print no messages.
- * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
- * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
- * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
+ * GThreadedSocketService:
*
- * The <type>GTypeDebugFlags</type> enumeration values can be passed to
- * g_type_init_with_debug_flags() to trigger debugging messages during runtime.
- * Note that the messages can also be triggered by setting the
- * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of
- * "objects" and "signals".
+ * A helper class for handling accepting incomming connections in the
+ * glib mainloop and handling them in a thread.
+ *
+ * Since: 2.22
*/
/**
- * GTypeFlags:
- * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type.
- * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init().
+ * GThreadedSocketService::run:
+ * @service: the #GThreadedSocketService.
+ * @connection: a new #GSocketConnection object.
+ * @source_object: the source_object passed to g_socket_listener_add_address().
*
- * Bit masks used to check or determine characteristics of a type.
+ * The ::run signal is emitted in a worker thread in response to an
+ * incoming connection. This thread is dedicated to handling
+ * not return until the connection is closed.
+ *
+ * Returns: %TRUE to stop further signal handlers from being called
*/
/**
- * GTypeFundamentalFlags:
- * @G_TYPE_FLAG_CLASSED: Indicates a classed type.
- * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
- * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
- * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
+ * GTimeSpan:
*
- * Bit masks used to check or determine specific characteristics of a
- * fundamental type.
+ * A value representing an interval of time, in microseconds.
+ *
+ * Since: 2.26
*/
/**
- * GTypeFundamentalInfo:
- * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
+ * GTimeType:
+ * @G_TIME_TYPE_STANDARD: the time is in local standard time
+ * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time
+ * @G_TIME_TYPE_UNIVERSAL: the time is in UTC
*
- * A structure that provides information to the type system which is
- * used specifically for managing fundamental types.
+ * Disambiguates a given time in two ways.
+ * First, specifies if the given time is in universal or local time.
+ * Second, if the time is in local time, specifies if it is local
+ * standard time or local daylight time. This is important for the case
+ * where the same local time occurs twice (during daylight savings time
+ * transitions, for example).
*/
/**
- * GTypeInfo:
- * @class_size: Size of the class structure (required for interface, classed and instantiatable types).
- * @base_init: Location of the base initialization function (optional).
- * @base_finalize: Location of the base finalization function (optional).
- * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties.
- * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional)
- * @class_data: User-supplied data passed to the class init/finalize functions.
- * @instance_size: Size of the instance (object) structure (required for instantiatable types only).
- * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
- * @instance_init: Location of the instance initialization function (optional, for instantiatable types only).
- * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types).
+ * GTimeZoneMonitor:
*
- * This structure is used to provide the type system with the information
- * required to initialize and destruct (finalize) a type's class and
- * its instances.
- * The initialized structure is passed to the g_type_register_static() function
- * (or is copied into the provided #GTypeInfo structure in the
- * g_type_plugin_complete_type_info()). The type system will perform a deep
- * copy of this structure, so its memory does not need to be persistent
- * across invocation of g_type_register_static().
+ * This is an opaque structure type.
*/
/**
- * GTypeInstance:
+ * GTimeZoneMonitor::changed:
+ * @monitor: the #GTimeZoneMonitor
*
- * An opaque structure used as the base of all type instances.
+ * Indicates that the local timezone has changed.
+ * The g_time_zone_refresh_local() function is called just before this
+ * signal is emitted, so any new #GTimeZone or #GDateTime instances
+ * created from signal handlers will be as per the new timezone.
+ * Note that this signal is not emitted in response to entering or
+ * exiting daylight savings time within a given timezone. It's only
+ * for when the user has changed the timezone to that of a different
+ * location.
*/
/**
- * GTypeInterface:
+ * GTlsAuthenticationMode:
+ * @G_TLS_AUTHENTICATION_NONE: client authentication not required
+ * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested
+ * @G_TLS_AUTHENTICATION_REQUIRED: client authentication is required
*
- * An opaque structure used as the base of all interface types.
+ * The client authentication mode for a #GTlsServerConnection.
+ *
+ * Since: 2.28
*/
/**
- * GTypeInterfaceCheckFunc:
- * @check_data: data passed to g_type_add_interface_check().
- * @g_iface: the interface that has been initialized
+ * GTlsBackend:
*
- * A callback called after an interface vtable is initialized.
- * See g_type_add_interface_check().
+ * TLS (Transport Layer Security, aka SSL) backend. This is an
+ * internal type used to coordinate the different classes implemented
+ * by a TLS backend.
*
- * Since: 2.4
+ * Since: 2.28
*/
/**
- * GTypeModule:
- * @name: the name of the module
+ * GTlsBackendInterface:
+ * @g_iface: The parent interface.
+ * @get_certificate_type: returns the #GTlsCertificate implementation type
+ * @get_client_connection_type: returns the #GTlsClientConnection implementation type
+ * @get_server_connection_type: returns the #GTlsServerConnection implementation type
*
- * The members of the <structname>GTypeModule</structname> structure should not
- * be accessed directly, except for the @name field.
+ * Provides an interface for describing TLS-related types.
+ *
+ * Since: 2.28
*/
/**
- * GTypeModuleClass:
- * @parent_class: the parent class
- * @load: loads the module and registers one or more types using g_type_module_register_type().
- * @unload: unloads the module
+ * GTlsCertificate:
*
- * In order to implement dynamic loading of types based on #GTypeModule,
- * the @load and @unload functions in #GTypeModuleClass must be implemented.
+ * Abstract base class for TLS certificate types.
+ *
+ * Since: 2.28
*/
/**
- * GTypePlugin:
+ * GTlsCertificate:certificate:
*
- * The <structname>GTypePlugin</structname> typedef is used as a placeholder
- * for objects that implement the <structname>GTypePlugin</structname>
- * interface.
+ * The DER (binary) encoded representation of the certificate's
+ * public key. This property and the
+ * #GTlsCertificate:certificate-pem property represent the same
+ * data, just in different forms.
+ *
+ * Since: 2.28
*/
/**
- * GTypePluginClass:
- * @use_plugin: Increases the use count of the plugin.
- * @unuse_plugin: Decreases the use count of the plugin.
- * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function.
- * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function.
+ * GTlsCertificate:certificate-pem:
*
- * The #GTypePlugin interface is used by the type system in order to handle
- * the lifecycle of dynamically loaded types.
+ * The PEM (ASCII) encoded representation of the certificate's
+ * public key. This property and the #GTlsCertificate:certificate
+ * property represent the same data, just in different forms.
+ *
+ * Since: 2.28
*/
/**
- * GTypePluginCompleteInterfaceInfo:
- * @plugin: the #GTypePlugin
- * @instance_type: the #GType of an instantiable type to which the interface is added
- * @interface_type: the #GType of the interface whose info is completed
- * @info: the #GInterfaceInfo to fill in
+ * GTlsCertificate:issuer:
*
- * The type of the @complete_interface_info function of #GTypePluginClass.
+ * A #GTlsCertificate representing the entity that issued this
+ * certificate. If %NULL, this means that the certificate is either
+ * self-signed, or else the certificate of the issuer is not
+ * available.
+ *
+ * Since: 2.28
*/
/**
- * GTypePluginCompleteTypeInfo:
- * @plugin: the #GTypePlugin
- * @g_type: the #GType whose info is completed
- * @info: the #GTypeInfo struct to fill in
- * @value_table: the #GTypeValueTable to fill in
+ * GTlsCertificate:private-key:
*
- * The type of the @complete_type_info function of #GTypePluginClass.
+ * The DER (binary) encoded representation of the certificate's
+ * private key. This property (or the
+ * #GTlsCertificate:private-key-pem property) can be set when
+ * constructing a key (eg, from a file), but cannot be read.
+ *
+ * Since: 2.28
*/
/**
- * GTypePluginUnuse:
- * @plugin: the #GTypePlugin whose use count should be decreased
+ * GTlsCertificate:private-key-pem:
*
- * The type of the @unuse_plugin function of #GTypePluginClass.
+ * The PEM (ASCII) encoded representation of the certificate's
+ * private key. This property (or the #GTlsCertificate:private-key
+ * property) can be set when constructing a key (eg, from a file),
+ * but cannot be read.
+ *
+ * Since: 2.28
*/
/**
- * GTypePluginUse:
- * @plugin: the #GTypePlugin whose use count should be increased
+ * GTlsCertificateFlags:
+ * @G_TLS_CERTIFICATE_UNKNOWN_CA: The signing certificate authority is not known.
+ * @G_TLS_CERTIFICATE_BAD_IDENTITY: The certificate does not match the expected identity of the site that it was retrieved from.
+ * @G_TLS_CERTIFICATE_NOT_ACTIVATED: The certificate's activation time is still in the future
+ * @G_TLS_CERTIFICATE_EXPIRED: The certificate has expired
+ * @G_TLS_CERTIFICATE_REVOKED: The certificate has been revoked according to the #GTlsConnection's certificate revocation list.
+ * @G_TLS_CERTIFICATE_INSECURE: The certificate's algorithm is considered insecure.
+ * @G_TLS_CERTIFICATE_GENERIC_ERROR: Some other error occurred validating the certificate
+ * @G_TLS_CERTIFICATE_VALIDATE_ALL: the combination of all of the above flags
*
- * The type of the @use_plugin function of #GTypePluginClass, which gets called
- * to increase the use count of @plugin.
+ * A set of flags describing TLS certification validation. This can be
+ * used to set which validation steps to perform (eg, with
+ * g_tls_client_connection_set_validation_flags()), or to describe why
+ * a particular certificate was rejected (eg, in
+ * #GTlsConnection::accept-certificate).
+ *
+ * Since: 2.28
*/
/**
- * GTypeQuery:
- * @type: the #GType value of the type.
- * @type_name: the name of the type.
- * @class_size: the size of the class structure.
- * @instance_size: the size of the instance structure.
+ * GTlsClientConnection:
*
- * A structure holding information for a specific type. It is
- * filled in by the g_type_query() function.
+ * TLS client-side connection; the client-side implementation of a
+ * #GTlsConnection
+ *
+ * Since: 2.28
*/
/**
- * GTypeValueTable:
- * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]|
- * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]|
- * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
- * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]|
- * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i
' needs to be used, and for collection of floats 'd'.
- * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_p
ointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour i
s undefined.
- * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
- * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
+ * GTlsClientConnection:accepted-cas:
*
- * The #GTypeValueTable provides the functions required by the #GValue implementation,
- * to serve as a container for values of a type.
+ * 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
*/
/**
- * GUnixCredentialsMessage:
+ * GTlsClientConnection:server-identity:
*
- * The #GUnixCredentialsMessage structure contains only private data
- * and should only be accessed using the provided API.
+ * 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.26
+ * Since: 2.28
*/
/**
- * GUnixCredentialsMessage:credentials:
+ * GTlsClientConnection:use-ssl3:
*
- * The credentials stored in the message.
+ * If %TRUE, tells the connection to use SSL 3.0 rather than trying
+ * to negotiate the best version of TLS or SSL to use. This can be
+ * used when talking to servers that don't implement version
+ * negotiation correctly and therefore refuse to handshake at all with
+ * a "modern" TLS handshake.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * GUnixCredentialsMessageClass:
+ * GTlsClientConnection:validation-flags:
*
- * Class structure for #GUnixCredentialsMessage.
+ * What steps to perform when validating a certificate received from
+ * a server. Server certificates that fail to validate in all of the
+ * ways indicated here will be rejected unless the application
+ * overrides the default via #GTlsConnection::accept-certificate.
*
- * Since: 2.26
+ * Since: 2.28
*/
/**
- * GUnixInputStream:
+ * GTlsConnection:
+ *
+ * TLS connection. This is an abstract type that will be subclassed by
+ * a TLS-library-specific subtype.
*
- * Implements #GInputStream for reading from selectable unix file descriptors
+ * Since: 2.28
*/
/**
- * GUnixInputStream:close-fd:
+ * GTlsConnection::accept-certificate:
+ * @conn: a #GTlsConnection
+ * @peer_cert: the peer's #GTlsCertificate
+ * @errors: the problems with @peer_cert.
*
- * Whether to close the file descriptor when the stream is closed.
+ * Emitted during the TLS handshake after the peer certificate has
+ * been received. You can examine @peer_cert's certification path by
+ * calling g_tls_certificate_get_issuer() on it.
+ * For a client-side connection, @peer_cert is the server's
+ * certificate, and the signal will only be emitted if the
+ * certificate was not acceptable according to @conn's
+ * #GTlsClientConnection:validation_flags. If you would like the
+ * certificate to be accepted despite @errors, return %TRUE from the
+ * signal handler. Otherwise, if no handler accepts the certificate,
+ * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
+ * For a server-side connection, @peer_cert is the certificate
+ * presented by the client, if this was requested via the server's
+ * #GTlsServerConnection:authentication_mode. On the server side,
+ * the signal is always emitted when the client presents a
+ * certificate, and the certificate will only be accepted if a
+ * handler returns %TRUE.
+ * Note that if this signal is emitted as part of asynchronous I/O
+ * in the main thread, then you should not attempt to interact with
+ * the user before returning from the signal handler. If you want to
+ * let the user decide whether or not to accept the certificate, you
+ * would have to return %FALSE from the signal handler on the first
+ * attempt, and then after the connection attempt returns a
+ * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
+ * the user decides to accept the certificate, remember that fact,
+ * create a new connection, and return %TRUE from the signal handler
+ * the next time.
+ * If you are doing I/O in another thread, you do not
+ * need to worry about this, and can simply block in the signal
+ * handler until the UI thread returns an answer.
+ * immediately end the signal emission). %FALSE to allow the signal
+ * emission to continue, which will cause the handshake to fail if
+ * no one else overrides it.
*
- * Since: 2.20
+ * Returns: %TRUE to accept @peer_cert (which will also
+ * Since: 2.28
*/
/**
- * GUnixInputStream:fd:
+ * GTlsConnection:base-io-stream:
*
- * The file descriptor that the stream reads from.
+ * The #GIOStream that the connection wraps
*
- * Since: 2.20
+ * Since: 2.28
*/
/**
- * GUnixMount:
+ * GTlsConnection:certificate:
+ *
+ * The connection's certificate; see
+ * g_tls_connection_set_certificate().
*
- * Implementation of the #GMount interface for Unix systems.
+ * Since: 2.28
*/
/**
- * GUnixMountEntry:
+ * GTlsConnection:peer-certificate:
*
- * Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>).
- * This corresponds roughly to a mtab entry.
+ * The connection's peer's certificate, after the TLS handshake has
+ * completed and the certificate has been accepted. Note in
+ * particular that this is not yet set during the emission of
+ * #GTlsConnection::accept-certificate.
+ * (You can watch for a #GObject::notify signal on this property to
+ * detect when a handshake has occurred.)
+ *
+ * Since: 2.28
*/
/**
- * GUnixMountMonitor:
+ * GTlsConnection:peer-certificate-errors:
+ *
+ * The errors noticed-and-ignored while verifying
+ * #GTlsConnection:peer-certificate. Normally this should be 0, but
+ * it may not be if #GTlsClientConnection:validation-flags is not
+ * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
+ * #GTlsConnection::accept-certificate overrode the default
+ * behavior.
*
- * Watches #GUnixMount<!-- -->s for changes.
+ * Since: 2.28
*/
/**
- * GUnixMountMonitor::mountpoints-changed:
- * @monitor: the object on which the signal is emitted
+ * GTlsConnection:rehandshake-mode:
*
- * Emitted when the unix mount points have changed.
+ * The rehandshaking mode. See
+ * g_tls_connection_set_rehandshake_mode().
+ *
+ * Since: 2.28
*/
/**
- * GUnixMountMonitor::mounts-changed:
- * @monitor: the object on which the signal is emitted
+ * GTlsConnection:require-close-notify:
*
- * Emitted when the unix mounts have changed.
+ * Whether or not proper TLS close notification is required.
+ * See g_tls_connection_set_require_close_notify().
+ *
+ * Since: 2.28
*/
/**
- * GUnixMountPoint:
+ * GTlsConnection:use-system-certdb:
*
- * Defines a Unix mount point (e.g. <filename>/dev</filename>).
- * This corresponds roughly to a fstab entry.
+ * Whether or not the system certificate database will be used to
+ * verify peer certificates. See
+ * g_tls_connection_set_use_system_certdb().
+ *
+ * Since: 2.28
*/
/**
- * GUnixOutputStream:
+ * GTlsError:
+ * @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available
+ * @G_TLS_ERROR_MISC: Miscellaneous TLS error
+ * @G_TLS_ERROR_BAD_CERTIFICATE: A certificate could not be parsed
+ * @G_TLS_ERROR_NOT_TLS: The TLS handshake failed because the peer does not seem to be a TLS server.
+ * @G_TLS_ERROR_HANDSHAKE: The TLS handshake failed because the peer's certificate was not acceptable.
+ * @G_TLS_ERROR_CERTIFICATE_REQUIRED: The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate().
+ * @G_TLS_ERROR_EOF: The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify().
+ *
+ * An error code used with %G_TLS_ERROR in a #GError returned from a
+ * TLS-related routine.
*
- * Implements #GOutputStream for outputting to selectable unix file descriptors
+ * Since: 2.28
*/
/**
- * GUnixOutputStream:close-fd:
+ * GTlsRehandshakeMode:
+ * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking
+ * @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only
+ * @G_TLS_REHANDSHAKE_UNSAFELY: Allow unsafe rehandshaking
*
- * Whether to close the file descriptor when the stream is closed.
+ * When to allow rehandshaking. See
+ * g_tls_connection_set_rehandshake_mode().
*
- * Since: 2.20
+ * Since: 2.28
*/
/**
- * GUnixOutputStream:fd:
+ * GTlsServerConnection:
*
- * The file descriptor that the stream writes to.
+ * TLS server-side connection. This is the server-side implementation
+ * of a #GTlsConnection.
*
- * Since: 2.20
+ * Since: 2.28
*/
/**
- * GUnixSocketAddress:
+ * GTlsServerConnection:authentication-mode:
*
- * A UNIX-domain (local) socket address, corresponding to a
- * <type>struct sockaddr_un</type>.
+ * 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
*/
/**
- * GUnixSocketAddress:abstract:
- *
- * Whether or not this is an abstract address
- * distinguishes between zero-padded and non-zero-padded
- * abstract addresses.
+ * GToggleNotify:
+ * @data: Callback data passed to g_object_add_toggle_ref()
+ * @object: The object on which g_object_add_toggle_ref() was called.
+ * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references.
*
- * Deprecated: Use #GUnixSocketAddress:address-type, which
+ * A callback function used for notification when the state
+ * of a toggle reference changes. See g_object_add_toggle_ref().
*/
/**
- * GUnixSocketAddressType:
- * @G_UNIX_SOCKET_ADDRESS_INVALID: invalid
- * @G_UNIX_SOCKET_ADDRESS_ANONYMOUS: anonymous
- * @G_UNIX_SOCKET_ADDRESS_PATH: a filesystem path
- * @G_UNIX_SOCKET_ADDRESS_ABSTRACT: an abstract name
- * @G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED: an abstract name, 0-padded to the full length of a unix socket name
+ * GTranslateFunc:
+ * @str: the untranslated string
+ * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func()
*
- * The type of name used by a #GUnixSocketAddress.
- * %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain
- * socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS
- * indicates a socket not bound to any name (eg, a client-side socket,
- * or a socket created with socketpair()).
- * For abstract sockets, there are two incompatible ways of naming
- * them; the man pages suggest using the entire <literal>struct
- * sockaddr_un</literal> as the name, padding the unused parts of the
- * %sun_path field with zeroes; this corresponds to
- * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs
- * instead just use a portion of %sun_path, and pass an appropriate
- * smaller length to bind() or connect(). This is
- * %G_UNIX_SOCKET_ADDRESS_ABSTRACT.
+ * The type of functions which are used to translate user-visible
+ * strings, for <option>--help</option> output.
+ * The returned string is owned by GLib and must not be freed.
*
- * Since: 2.26
+ * Returns: a translation of the string for the current locale.
*/
/**
- * GUserDirectory:
- * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory
- * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory
- * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory
- * @G_USER_DIRECTORY_MUSIC: the user's Music directory
- * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory
- * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory
- * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory
- * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory
- * @G_USER_N_DIRECTORIES: the number of enum values
- *
- * These are logical ids for special directories which are defined
- * depending on the platform used. You should use g_get_user_special_dir()
- * to retrieve the full path associated to the logical id.
- * The #GUserDirectory enumeration can be extended at later date. Not
- * every platform has a directory for every logical id in this
- * enumeration.
+ * GType:
*
- * Since: 2.14
+ * A numerical value which represents the unique identifier of a registered
+ * type.
*/
/**
- * GValue:
- *
- * An opaque structure used to hold different types of values.
- * to functions within a #GTypeValueTable structure, or implementations of
- * the g_value_*() API. That is, code portions which implement new fundamental
- * types.
- * #GValue users cannot make any assumptions about how data is stored
- * within the 2 element @data union, and the @g_type member should
- * only be accessed through the G_VALUE_TYPE() macro.
+ * GTypeClass:
*
- * The data within the structure has protected scope: it is accessible only
+ * An opaque structure used as the base of all classes.
*/
/**
- * GValueArray:
- * @n_values: number of values contained in the array
- * @values: array of values
+ * GTypeClassCacheFunc:
+ * @cache_data: data that was given to the g_type_add_class_cache_func() call
+ * @g_class: The #GTypeClass structure which is unreferenced
*
- * A #GValueArray contains an array of #GValue elements.
- */
-
-
-/**
- * GValueTransform:
- * @src_value: Source value.
- * @dest_value: Target value.
+ * A callback function which is called when the reference count of a class
+ * drops to zero. It may use g_type_class_ref() to prevent the class from
+ * being freed. You should not call g_type_class_unref() from a
+ * #GTypeClassCacheFunc function to prevent infinite recursion, use
+ * g_type_class_unref_uncached() instead.
+ * The functions have to check the class id passed in to figure
+ * whether they actually want to cache the class of this type, since all
+ * classes are routed through the same #GTypeClassCacheFunc chain.
+ * called, %FALSE to continue.
*
- * The type of value transformation functions which can be registered with
- * g_value_register_transform_func().
+ * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
*/
/**
- * GVariantType:
+ * GTypeDebugFlags:
+ * @G_TYPE_DEBUG_NONE: Print no messages.
+ * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
+ * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
+ * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
*
- * A type in the GVariant type system.
- * Two types may not be compared by value; use g_variant_type_equal() or
- * g_variant_type_is_subtype_of(). May be copied using
- * g_variant_type_copy() and freed using g_variant_type_free().
+ * The <type>GTypeDebugFlags</type> enumeration values can be passed to
+ * g_type_init_with_debug_flags() to trigger debugging messages during runtime.
+ * Note that the messages can also be triggered by setting the
+ * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of
+ * "objects" and "signals".
*/
/**
- * GVfs:
+ * GTypeFlags:
+ * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type.
+ * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init().
*
- * Virtual File System object.
+ * Bit masks used to check or determine characteristics of a type.
*/
/**
- * GVolume:
+ * GTypeFundamentalFlags:
+ * @G_TYPE_FLAG_CLASSED: Indicates a classed type.
+ * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
+ * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
+ * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
*
- * Opaque mountable volume object.
+ * Bit masks used to check or determine specific characteristics of a
+ * fundamental type.
*/
/**
- * GVolume::changed:
+ * GTypeFundamentalInfo:
+ * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
*
- * Emitted when the volume has been changed.
+ * A structure that provides information to the type system which is
+ * used specifically for managing fundamental types.
*/
/**
- * GVolume::removed:
+ * GTypeInfo:
+ * @class_size: Size of the class structure (required for interface, classed and instantiatable types).
+ * @base_init: Location of the base initialization function (optional).
+ * @base_finalize: Location of the base finalization function (optional).
+ * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties.
+ * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional)
+ * @class_data: User-supplied data passed to the class init/finalize functions.
+ * @instance_size: Size of the instance (object) structure (required for instantiatable types only).
+ * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now.
+ * @instance_init: Location of the instance initialization function (optional, for instantiatable types only).
+ * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types).
*
- * This 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.
+ * This structure is used to provide the type system with the information
+ * required to initialize and destruct (finalize) a type's class and
+ * its instances.
+ * The initialized structure is passed to the g_type_register_static() function
+ * (or is copied into the provided #GTypeInfo structure in the
+ * g_type_plugin_complete_type_info()). The type system will perform a deep
+ * copy of this structure, so its memory does not need to be persistent
+ * across invocation of g_type_register_static().
*/
/**
- * GVolumeIface:
- * @g_iface: The parent interface.
- * @changed: Changed signal that is emitted when the volume's state has changed.
- * @removed: The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.
- * @get_name: Gets a string containing the name of the #GVolume.
- * @get_icon: Gets a #GIcon for the #GVolume.
- * @get_uuid: Gets the UUID for the #GVolume. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
- * @get_drive: Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive.
- * @get_mount: Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted.
- * @can_mount: Returns %TRUE if the #GVolume can be mounted.
- * @can_eject: Checks if a #GVolume can be ejected.
- * @mount_fn: Mounts a given #GVolume. #GVolume implementations must emit the #GMountOperation::aborted signal before completing a mount operation that is aborted while awaiting input from the user through a #GMountOperation instance.
- * @mount_finish: Finishes a mount operation.
- * @eject: Ejects a given #GVolume.
- * @eject_finish: Finishes an eject operation.
- * @get_identifier: Returns the <link linkend="volume-identifier">identifier</link> of the given kind, or %NULL if the #GVolume doesn't have one.
- * @enumerate_identifiers: Returns an array strings listing the kinds of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
- * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
- * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if it is not known.
- * @eject_with_operation: Starts ejecting a #GVolume using a #GMountOperation. Since 2.22.
- * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
+ * GTypeInstance:
*
- * Interface for implementing operations for mountable volumes.
+ * An opaque structure used as the base of all type instances.
*/
/**
- * GVolumeMonitor:
+ * GTypeInterface:
*
- * A Volume Monitor that watches for volume events.
+ * An opaque structure used as the base of all interface types.
*/
/**
- * GVolumeMonitor::drive-changed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: the drive that changed
+ * GTypeInterfaceCheckFunc:
+ * @check_data: data passed to g_type_add_interface_check().
+ * @g_iface: the interface that has been initialized
*
- * Emitted when a drive changes.
+ * A callback called after an interface vtable is initialized.
+ * See g_type_add_interface_check().
+ *
+ * Since: 2.4
*/
/**
- * GVolumeMonitor::drive-connected:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: a #GDrive that was connected.
+ * GTypeModule:
+ * @name: the name of the module
*
- * Emitted when a drive is connected to the system.
+ * The members of the <structname>GTypeModule</structname> structure should not
+ * be accessed directly, except for the @name field.
*/
/**
- * GVolumeMonitor::drive-disconnected:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: a #GDrive that was disconnected.
+ * GTypeModuleClass:
+ * @parent_class: the parent class
+ * @load: loads the module and registers one or more types using g_type_module_register_type().
+ * @unload: unloads the module
*
- * Emitted when a drive is disconnected from the system.
+ * In order to implement dynamic loading of types based on #GTypeModule,
+ * the @load and @unload functions in #GTypeModuleClass must be implemented.
*/
/**
- * GVolumeMonitor::drive-eject-button:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: the drive where the eject button was pressed
- *
- * Emitted when the eject button is pressed on @drive.
+ * GTypePlugin:
*
- * Since: 2.18
+ * The <structname>GTypePlugin</structname> typedef is used as a placeholder
+ * for objects that implement the <structname>GTypePlugin</structname>
+ * interface.
*/
/**
- * GVolumeMonitor::drive-stop-button:
- * @volume_monitor: The volume monitor emitting the signal.
- * @drive: the drive where the stop button was pressed
- *
- * Emitted when the stop button is pressed on @drive.
+ * GTypePluginClass:
+ * @use_plugin: Increases the use count of the plugin.
+ * @unuse_plugin: Decreases the use count of the plugin.
+ * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function.
+ * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function.
*
- * Since: 2.22
+ * The #GTypePlugin interface is used by the type system in order to handle
+ * the lifecycle of dynamically loaded types.
*/
/**
- * GVolumeMonitor::mount-added:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that was added.
+ * GTypePluginCompleteInterfaceInfo:
+ * @plugin: the #GTypePlugin
+ * @instance_type: the #GType of an instantiable type to which the interface is added
+ * @interface_type: the #GType of the interface whose info is completed
+ * @info: the #GInterfaceInfo to fill in
*
- * Emitted when a mount is added.
+ * The type of the @complete_interface_info function of #GTypePluginClass.
*/
/**
- * GVolumeMonitor::mount-changed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that changed.
+ * GTypePluginCompleteTypeInfo:
+ * @plugin: the #GTypePlugin
+ * @g_type: the #GType whose info is completed
+ * @info: the #GTypeInfo struct to fill in
+ * @value_table: the #GTypeValueTable to fill in
*
- * Emitted when a mount changes.
+ * The type of the @complete_type_info function of #GTypePluginClass.
*/
/**
- * GVolumeMonitor::mount-pre-unmount:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that is being unmounted.
+ * GTypePluginUnuse:
+ * @plugin: the #GTypePlugin whose use count should be decreased
*
- * Emitted when a mount is about to be removed.
+ * The type of the @unuse_plugin function of #GTypePluginClass.
*/
/**
- * GVolumeMonitor::mount-removed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @mount: a #GMount that was removed.
+ * GTypePluginUse:
+ * @plugin: the #GTypePlugin whose use count should be increased
*
- * Emitted when a mount is removed.
+ * The type of the @use_plugin function of #GTypePluginClass, which gets called
+ * to increase the use count of @plugin.
*/
/**
- * GVolumeMonitor::volume-added:
- * @volume_monitor: The volume monitor emitting the signal.
- * @volume: a #GVolume that was added.
+ * GTypeQuery:
+ * @type: the #GType value of the type.
+ * @type_name: the name of the type.
+ * @class_size: the size of the class structure.
+ * @instance_size: the size of the instance structure.
*
- * Emitted when a mountable volume is added to the system.
+ * A structure holding information for a specific type. It is
+ * filled in by the g_type_query() function.
*/
/**
- * GVolumeMonitor::volume-changed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @volume: a #GVolume that changed.
+ * GTypeValueTable:
+ * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]|
+ * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]|
+ * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
+ * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]|
+ * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i
' needs to be used, and for collection of floats 'd'.
+ * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_p
ointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour i
s undefined.
+ * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
+ * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
*
- * Emitted when mountable volume is changed.
+ * The #GTypeValueTable provides the functions required by the #GValue implementation,
+ * to serve as a container for values of a type.
*/
/**
- * GVolumeMonitor::volume-removed:
- * @volume_monitor: The volume monitor emitting the signal.
- * @volume: a #GVolume that was removed.
+ * GUnixCredentialsMessage:credentials:
*
- * Emitted when a mountable volume is removed from the system.
+ * The credentials stored in the message.
+ *
+ * Since: 2.26
*/
/**
- * GWeakNotify:
- * @data: data that was provided when the weak reference was established
- * @where_the_object_was: the object being finalized
+ * GUnixInputStream:close-fd:
*
- * A #GWeakNotify function can be added to an object as a callback that gets
- * triggered when the object is finalized. Since the object is already being
- * finalized when the #GWeakNotify is called, there's not much you could do
- * with the object, apart from e.g. using its adress as hash-index or the like.
+ * Whether to close the file descriptor when the stream is closed.
+ *
+ * Since: 2.20
*/
/**
- * GWin32InputStream:
+ * GUnixInputStream:fd:
+ *
+ * The file descriptor that the stream reads from.
*
- * Implements #GInputStream for reading from selectable Windows file handles
+ * Since: 2.20
*/
/**
- * GWin32InputStream:close-handle:
+ * GUnixMountMonitor::mountpoints-changed:
+ * @monitor: the object on which the signal is emitted
*
- * Whether to close the file handle when the stream is closed.
+ * Emitted when the unix mount points have changed.
+ */
+
+
+/**
+ * GUnixMountMonitor::mounts-changed:
+ * @monitor: the object on which the signal is emitted
*
- * Since: 2.26
+ * Emitted when the unix mounts have changed.
*/
/**
- * GWin32InputStream:handle:
+ * GUnixOutputStream:close-fd:
*
- * The handle that the stream reads from.
+ * Whether to close the file descriptor when the stream is closed.
*
- * Since: 2.26
+ * Since: 2.20
*/
/**
- * GWin32Mount:
+ * GUnixOutputStream:fd:
*
- * Implementation of the #GMount interface for Win32 systems.
+ * The file descriptor that the stream writes to.
+ *
+ * Since: 2.20
*/
/**
- * GWin32OutputStream:
+ * GUnixSocketAddress:
*
- * Implements #GOutputStream for outputting to Windows file handles
+ * A UNIX-domain (local) socket address, corresponding to a
+ * <type>struct sockaddr_un</type>.
*/
/**
- * GWin32OutputStream:close-handle:
+ * GUnixSocketAddress:abstract:
*
- * Whether to close the file handle when the stream is closed.
+ * Whether or not this is an abstract address
+ * distinguishes between zero-padded and non-zero-padded
+ * abstract addresses.
*
- * Since: 2.26
+ * Deprecated: Use #GUnixSocketAddress:address-type, which
*/
/**
- * GWin32OutputStream:handle:
+ * GUnixSocketAddressType:
+ * @G_UNIX_SOCKET_ADDRESS_INVALID: invalid
+ * @G_UNIX_SOCKET_ADDRESS_ANONYMOUS: anonymous
+ * @G_UNIX_SOCKET_ADDRESS_PATH: a filesystem path
+ * @G_UNIX_SOCKET_ADDRESS_ABSTRACT: an abstract name
+ * @G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED: an abstract name, 0-padded to the full length of a unix socket name
*
- * The file handle that the stream writes to.
+ * The type of name used by a #GUnixSocketAddress.
+ * %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain
+ * socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS
+ * indicates a socket not bound to any name (eg, a client-side socket,
+ * or a socket created with socketpair()).
+ * For abstract sockets, there are two incompatible ways of naming
+ * them; the man pages suggest using the entire <literal>struct
+ * sockaddr_un</literal> as the name, padding the unused parts of the
+ * %sun_path field with zeroes; this corresponds to
+ * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs
+ * instead just use a portion of %sun_path, and pass an appropriate
+ * smaller length to bind() or connect(). This is
+ * %G_UNIX_SOCKET_ADDRESS_ABSTRACT.
*
* Since: 2.26
*/
/**
- * GZlibCompressor:
+ * GUserDirectory:
+ * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory
+ * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory
+ * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory
+ * @G_USER_DIRECTORY_MUSIC: the user's Music directory
+ * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory
+ * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory
+ * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory
+ * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory
+ * @G_USER_N_DIRECTORIES: the number of enum values
*
- * Zlib decompression
+ * These are logical ids for special directories which are defined
+ * depending on the platform used. You should use g_get_user_special_dir()
+ * to retrieve the full path associated to the logical id.
+ * The #GUserDirectory enumeration can be extended at later date. Not
+ * every platform has a directory for every logical id in this
+ * enumeration.
+ *
+ * Since: 2.14
*/
/**
- * GZlibCompressor:file-info:
+ * GValue:
*
- * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
- * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
- * and modification time from the file info to the the GZIP header.
+ * An opaque structure used to hold different types of values.
+ * to functions within a #GTypeValueTable structure, or implementations of
+ * the g_value_*() API. That is, code portions which implement new fundamental
+ * types.
+ * #GValue users cannot make any assumptions about how data is stored
+ * within the 2 element @data union, and the @g_type member should
+ * only be accessed through the G_VALUE_TYPE() macro.
*
- * Since: 2.26
+ * The data within the structure has protected scope: it is accessible only
*/
/**
- * GZlibCompressorFormat:
- * @G_ZLIB_COMPRESSOR_FORMAT_ZLIB: deflate compression with zlib header
- * @G_ZLIB_COMPRESSOR_FORMAT_GZIP: gzip file format
- * @G_ZLIB_COMPRESSOR_FORMAT_RAW: deflate compression with no header
- *
- * Used to select the type of data format to use for #GZlibDecompressor
- * and #GZlibCompressor.
+ * GValueArray:
+ * @n_values: number of values contained in the array
+ * @values: array of values
*
- * Since: 2.24
+ * A #GValueArray contains an array of #GValue elements.
*/
/**
- * GZlibDecompressor:
+ * GValueTransform:
+ * @src_value: Source value.
+ * @dest_value: Target value.
*
- * Zlib decompression
+ * The type of value transformation functions which can be registered with
+ * g_value_register_transform_func().
*/
/**
- * GZlibDecompressor:file-info:
- *
- * 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.
+ * GVariantType:
*
- * Since: 2.26
+ * A type in the GVariant type system.
+ * Two types may not be compared by value; use g_variant_type_equal() or
+ * g_variant_type_is_subtype_of(). May be copied using
+ * g_variant_type_copy() and freed using g_variant_type_free().
*/
/**
- * G_BOOKMARK_FILE_ERROR:
+ * GVfs:
*
- * Error domain for bookmark file parsing.
- * Errors in this domain will be from the #GBookmarkFileError
- * enumeration. See #GError for information on error domains.
+ * Virtual File System object.
*/
/**
- * G_CALLBACK:
- * @f: a function pointer.
+ * GVoidFunc:
*
- * Cast a function pointer to a #GCallback.
+ * Declares a type of function which takes no arguments
+ * and has no return value. It is used to specify the type
+ * function passed to g_atexit().
*/
/**
- * G_CCLOSURE_SWAP_DATA:
- * @cclosure: a #GCClosure
- *
- * Checks whether the user data of the #GCClosure should be passed as the
- * first parameter to the callback. See g_cclosure_new_swap().
+ * GVolume:
*
- * Returns: %TRUE if data has to be swapped.
+ * Opaque mountable volume object.
*/
/**
- * G_CLOSURE_NEEDS_MARSHAL:
- * @closure: a #GClosure
- *
- * Check if the closure still needs a marshaller. See g_closure_set_marshal().
+ * GVolume::changed:
*
- * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
+ * Emitted when the volume has been changed.
*/
/**
- * G_CLOSURE_N_NOTIFIERS:
- * @cl: a #GClosure
- *
- * Get the total number of notifiers connected with the closure @cl.
- * The count includes the meta marshaller, the finalize and invalidate notifiers
- * and the marshal guards. Note that each guard counts as two notifiers.
- * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
- * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().
+ * GVolume::removed:
*
- * Returns: number of notifiers
+ * 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.
*/
/**
- * G_CONVERT_ERROR:
+ * GVolumeIface:
+ * @g_iface: The parent interface.
+ * @changed: Changed signal that is emitted when the volume's state has changed.
+ * @removed: The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.
+ * @get_name: Gets a string containing the name of the #GVolume.
+ * @get_icon: Gets a #GIcon for the #GVolume.
+ * @get_uuid: Gets the UUID for the #GVolume. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
+ * @get_drive: Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive.
+ * @get_mount: Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted.
+ * @can_mount: Returns %TRUE if the #GVolume can be mounted.
+ * @can_eject: Checks if a #GVolume can be ejected.
+ * @mount_fn: Mounts a given #GVolume. #GVolume implementations must emit the #GMountOperation::aborted signal before completing a mount operation that is aborted while awaiting input from the user through a #GMountOperation instance.
+ * @mount_finish: Finishes a mount operation.
+ * @eject: Ejects a given #GVolume.
+ * @eject_finish: Finishes an eject operation.
+ * @get_identifier: Returns the <link linkend="volume-identifier">identifier</link> of the given kind, or %NULL if the #GVolume doesn't have one.
+ * @enumerate_identifiers: Returns an array strings listing the kinds of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
+ * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
+ * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if it is not known.
+ * @eject_with_operation: Starts ejecting a #GVolume using a #GMountOperation. Since 2.22.
+ * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
*
- * Error domain for character set conversions. Errors in this domain will
- * be from the #GConvertError enumeration. See #GError for information on
- * error domains.
+ * Interface for implementing operations for mountable volumes.
*/
/**
- * G_DATALIST_FLAGS_MASK:
+ * GVolumeMonitor:
*
- * A bitmask that restricts the possible flags passed to
- * g_datalist_set_flags(). Passing a flags value where
- * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.
+ * A Volume Monitor that watches for volume events.
*/
/**
- * G_DBUS_ERROR:
- *
- * Error domain for errors generated by a remote message bus. Errors
- * in this domain will be from the #GDBusError enumeration. See
- * #GError for more information on error domains.
- * Note that errors in this error domain is intended only for
- * returning errors from a remote message bus process. Errors
- * generated locally in-process by e.g. #GDBusConnection is from the
- * %G_IO_ERROR domain.
+ * GVolumeMonitor::drive-changed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: the drive that changed
*
- * Since: 2.26
+ * Emitted when a drive changes.
*/
/**
- * G_DEFINE_ABSTRACT_TYPE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
+ * GVolumeMonitor::drive-connected:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: a #GDrive that was connected.
*
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE(), but defines an abstract type.
- * See G_DEFINE_TYPE_EXTENDED() for an example.
+ * Emitted when a drive is connected to the system.
+ */
+
+
+/**
+ * GVolumeMonitor::drive-disconnected:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: a #GDrive that was disconnected.
*
- * Since: 2.4
+ * Emitted when a drive is disconnected from the system.
*/
/**
- * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
+ * GVolumeMonitor::drive-eject-button:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: the drive where the eject button was pressed
*
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to
- * insert custom code into the *_get_type() function, e.g. interface implementations
- * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
+ * Emitted when the eject button is pressed on @drive.
*
- * Since: 2.4
+ * Since: 2.18
*/
/**
- * G_DEFINE_BOXED_TYPE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @copy_func: the #GBoxedCopyFunc for the new type
- * @free_func: the #GBoxedFreeFunc for the new type
+ * GVolumeMonitor::drive-stop-button:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @drive: the drive where the stop button was pressed
*
- * A convenience macro for boxed type implementations, which defines a
- * type_name_get_type() function registering the boxed type.
+ * Emitted when the stop button is pressed on @drive.
*
- * Since: 2.26
+ * Since: 2.22
*/
/**
- * G_DEFINE_BOXED_TYPE_WITH_CODE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @copy_func: the #GBoxedCopyFunc for the new type
- * @free_func: the #GBoxedFreeFunc for the new type
- * @_C_: Custom code that gets inserted in the *_get_type() function.
- *
- * A convenience macro for boxed type implementations.
- * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
- * type_name_get_type() function, e.g. to register value transformations with
- * g_value_register_transform_func().
+ * GVolumeMonitor::mount-added:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that was added.
*
- * Since: 2.26
+ * Emitted when a mount is added.
*/
/**
- * G_DEFINE_DYNAMIC_TYPE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- *
- * A convenience macro for dynamic type implementations, which declares a
- * class initialization function, an instance initialization function (see
- * #GTypeInfo for information about these) and a static variable named
- * it defines a <function>*_get_type()</function> and a static
- * <function>*_register_type()</function> function for use in your
- * <function>module_init()</function>.
- * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
+ * GVolumeMonitor::mount-changed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that changed.
*
- * Since: 2.14
+ * Emitted when a mount changes.
*/
/**
- * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @TYPE_PARENT: The #GType of the parent type.
- * @flags: #GTypeFlags to pass to g_type_module_register_type()
- * @CODE: Custom code that gets inserted in the *_get_type() function.
- *
- * A more general version of G_DEFINE_DYNAMIC_TYPE() which
- * allows to specify #GTypeFlags and custom code.
- * |[
- * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_THING,
- * 0,
- * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
- * ]|
- * expands to
- * |[
- * static void gtk_gadget_init (GtkGadget *self);
- * static void gtk_gadget_class_init (GtkGadgetClass *klass);
- * static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
- * static gpointer gtk_gadget_parent_class = NULL;
- * static GType gtk_gadget_type_id = 0;
- * static void gtk_gadget_class_intern_init (gpointer klass)
- * {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
- * }
- * GType
- * gtk_gadget_get_type (void)
- * {
- * return gtk_gadget_type_id;
- * }
- * static void
- * gtk_gadget_register_type (GTypeModule *type_module)
- * {
- * const GTypeInfo g_define_type_info = {
- * sizeof (GtkGadgetClass),
- * (GBaseInitFunc) NULL,
- * (GBaseFinalizeFunc) NULL,
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * (GClassFinalizeFunc) gtk_gadget_class_finalize,
- * NULL, // class_data
- * sizeof (GtkGadget),
- * 0, // n_preallocs
- * (GInstanceInitFunc) gtk_gadget_init,
- * NULL // value_table
- * };
- * gtk_gadget_type_id = g_type_module_register_type (type_module,
- * GTK_TYPE_THING,
- * GtkGadget,
- * &g_define_type_info,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * }
- * ]|
+ * GVolumeMonitor::mount-pre-unmount:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that is being unmounted.
*
- * Since: 2.14
+ * Emitted when a mount is about to be removed.
*/
/**
- * G_DEFINE_INTERFACE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
- *
- * A convenience macro for #GTypeInterface definitions, which declares
- * a default vtable initialization function and defines a *_get_type()
- * function.
- * The macro expects the interface initialization function to have the
- * name <literal>t_n ## _default_init</literal>, and the interface
- * structure to have the name <literal>TN ## Interface</literal>.
+ * GVolumeMonitor::mount-removed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @mount: a #GMount that was removed.
*
- * Since: 2.24
+ * Emitted when a mount is removed.
*/
/**
- * G_DEFINE_INTERFACE_WITH_CODE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
- *
- * A convenience macro for #GTypeInterface definitions. Similar to
- * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
- * *_get_type() function, e.g. additional interface implementations
- * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
- * G_DEFINE_TYPE_EXTENDED() for a similar example using
- * G_DEFINE_TYPE_WITH_CODE().
+ * GVolumeMonitor::volume-added:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @volume: a #GVolume that was added.
*
- * Since: 2.24
+ * Emitted when a mountable volume is added to the system.
*/
/**
- * G_DEFINE_POINTER_TYPE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- *
- * A convenience macro for pointer type implementations, which defines a
- * type_name_get_type() function registering the pointer type.
+ * GVolumeMonitor::volume-changed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @volume: a #GVolume that changed.
*
- * Since: 2.26
+ * Emitted when mountable volume is changed.
*/
/**
- * G_DEFINE_POINTER_TYPE_WITH_CODE:
- * @TypeName: The name of the new type, in Camel case.
- * @type_name: The name of the new type, in lowercase, with words separated by '_'.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
- *
- * A convenience macro for pointer type implementations.
- * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the
- * type_name_get_type() function.
+ * GVolumeMonitor::volume-removed:
+ * @volume_monitor: The volume monitor emitting the signal.
+ * @volume: a #GVolume that was removed.
*
- * Since: 2.26
+ * Emitted when a mountable volume is removed from the system.
*/
/**
- * G_DEFINE_TYPE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- *
- * A convenience macro for type implementations, which declares a
- * class initialization function, an instance initialization function (see #GTypeInfo for information about
- * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
- * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
+ * GWeakNotify:
+ * @data: data that was provided when the weak reference was established
+ * @where_the_object_was: the object being finalized
*
- * Since: 2.4
+ * A #GWeakNotify function can be added to an object as a callback that gets
+ * triggered when the object is finalized. Since the object is already being
+ * finalized when the #GWeakNotify is called, there's not much you could do
+ * with the object, apart from e.g. using its adress as hash-index or the like.
*/
/**
- * G_DEFINE_TYPE_EXTENDED:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type, in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- * @_f_: #GTypeFlags to pass to g_type_register_static()
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ * GWin32InputStream:close-handle:
*
- * The most general convenience macro for type implementations, on which
- * G_DEFINE_TYPE(), etc are based.
- * |[
- * G_DEFINE_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_WIDGET,
- * 0,
- * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
- * ]|
- * expands to
- * |[
- * static void gtk_gadget_init (GtkGadget *self);
- * static void gtk_gadget_class_init (GtkGadgetClass *klass);
- * static gpointer gtk_gadget_parent_class = NULL;
- * static void gtk_gadget_class_intern_init (gpointer klass)
- * {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
- * }
- * GType
- * gtk_gadget_get_type (void)
- * {
- * static volatile gsize g_define_type_id__volatile = 0;
- * if (g_once_init_enter (&g_define_type_id__volatile))
- * {
- * GType g_define_type_id =
- * g_type_register_static_simple (GTK_TYPE_WIDGET,
- * g_intern_static_string ("GtkGadget"),
- * sizeof (GtkGadgetClass),
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * sizeof (GtkGadget),
- * (GInstanceInitFunc) gtk_gadget_init,
- * (GTypeFlags) flags);
- * {
- * static const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
- * }
- * return g_define_type_id__volatile;
- * }
- * ]|
- * The only pieces which have to be manually provided are the definitions of
- * the instance and class structure and the definitions of the instance and
- * class init functions.
+ * Whether to close the file handle when the stream is closed.
*
- * Since: 2.4
+ * Since: 2.26
*/
/**
- * G_DEFINE_TYPE_WITH_CODE:
- * @TN: The name of the new type, in Camel case.
- * @t_n: The name of the new type in lowercase, with words separated by '_'.
- * @T_P: The #GType of the parent type.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ * GWin32InputStream:handle:
*
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
- * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
- * See G_DEFINE_TYPE_EXTENDED() for an example.
+ * The handle that the stream reads from.
*
- * Since: 2.4
+ * Since: 2.26
*/
/**
- * G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME:
+ * GWin32OutputStream:close-handle:
+ *
+ * Whether to close the file handle when the stream is closed.
*
- * Extension point for default handler to URI association. See
- * <link linkend="extending-gio">Extending GIO</link>.
+ * Since: 2.26
*/
/**
- * G_ENUM_CLASS:
- * @class: a valid #GEnumClass
+ * GWin32OutputStream:handle:
*
- * Casts a derived #GEnumClass structure into a #GEnumClass structure.
+ * The file handle that the stream writes to.
+ *
+ * Since: 2.26
*/
/**
- * G_ENUM_CLASS_TYPE:
- * @class: a #GEnumClass
- *
- * Get the type identifier from a given #GEnumClass structure.
+ * GZlibCompressor:
*
- * Returns: the #GType
+ * Zlib decompression
*/
/**
- * G_ENUM_CLASS_TYPE_NAME:
- * @class: a #GEnumClass
+ * GZlibCompressor:file-info:
*
- * Get the static type name from a given #GEnumClass structure.
+ * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
+ * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
+ * and modification time from the file info to the the GZIP header.
*
- * Returns: the type name.
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
+ * GZlibCompressorFormat:
+ * @G_ZLIB_COMPRESSOR_FORMAT_ZLIB: deflate compression with zlib header
+ * @G_ZLIB_COMPRESSOR_FORMAT_GZIP: gzip file format
+ * @G_ZLIB_COMPRESSOR_FORMAT_RAW: deflate compression with no header
*
- * A key in the "access" namespace for checking deletion privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to delete the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
+ * Used to select the type of data format to use for #GZlibDecompressor
+ * and #GZlibCompressor.
*
- * A key in the "access" namespace for getting execution privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to execute the file.
+ * Since: 2.24
*/
/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
+ * GZlibDecompressor:
*
- * A key in the "access" namespace for getting read privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to read the file.
+ * Zlib decompression
*/
/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
+ * GZlibDecompressor:file-info:
*
- * A key in the "access" namespace for checking renaming privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to rename the file.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
+ * 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.
*
- * A key in the "access" namespace for checking trashing privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to move the file to
- * the trash.
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
+ * G_BOOKMARK_FILE_ERROR:
*
- * A key in the "access" namespace for getting write privileges.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This attribute will be %TRUE if the user is able to write to the file.
+ * Error domain for bookmark file parsing.
+ * Errors in this domain will be from the #GBookmarkFileError
+ * enumeration. See #GError for information on error domains.
*/
/**
- * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
+ * G_CALLBACK:
+ * @f: a function pointer.
*
- * A key in the "dos" namespace for checking if the file's archive flag
- * is set. This attribute is %TRUE if the archive flag is set. This attribute
- * is only available for DOS file systems. Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * Cast a function pointer to a #GCallback.
*/
/**
- * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
+ * G_CCLOSURE_SWAP_DATA:
+ * @cclosure: a #GCClosure
*
- * A key in the "dos" namespace for checking if the file's backup flag
- * is set. This attribute is %TRUE if the backup flag is set. This attribute
- * is only available for DOS file systems. Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ETAG_VALUE:
+ * Checks whether the user data of the #GCClosure should be passed as the
+ * first parameter to the callback. See g_cclosure_new_swap().
*
- * A key in the "etag" namespace for getting the value of the file's
- * entity tag. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * Returns: %TRUE if data has to be swapped.
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_FREE:
+ * G_CLOSURE_NEEDS_MARSHAL:
+ * @closure: a #GClosure
*
- * A key in the "filesystem" namespace for getting the number of bytes of free space left on the
- * file system. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT64.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_READONLY:
+ * Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
- * A key in the "filesystem" namespace for checking if the file system
- * is read only. Is set to %TRUE if the file system is read only.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE:
+ * G_CLOSURE_N_NOTIFIERS:
+ * @cl: a #GClosure
*
- * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system,
- * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_UINT64.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE:
+ * Get the total number of notifiers connected with the closure @cl.
+ * The count includes the meta marshaller, the finalize and invalidate notifiers
+ * and the marshal guards. Note that each guard counts as two notifiers.
+ * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
+ * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().
*
- * A key in the "filesystem" namespace for getting the file system's type.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * Returns: number of notifiers
*/
/**
- * G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW:
+ * G_CONVERT_ERROR:
*
- * A key in the "filesystem" namespace for hinting a file manager
- * application whether it should preview (e.g. thumbnail) files on the
- * file system. The value for this key contain a
- * #GFilesystemPreviewType.
+ * Error domain for character set conversions. Errors in this domain will
+ * be from the #GConvertError enumeration. See #GError for information on
+ * error domains.
*/
/**
- * G_FILE_ATTRIBUTE_GVFS_BACKEND:
+ * G_DATALIST_FLAGS_MASK:
*
- * A key in the "gvfs" namespace that gets the name of the current
- * GVFS backend in use. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A bitmask that restricts the possible flags passed to
+ * g_datalist_set_flags(). Passing a flags value where
+ * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.
*/
/**
- * G_FILE_ATTRIBUTE_ID_FILE:
+ * G_DBUS_ERROR:
*
- * A key in the "id" namespace for getting a file identifier.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- * An example use would be during listing files, to avoid recursive
- * directory scanning.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_ID_FILESYSTEM:
+ * Error domain for errors generated by a remote message bus. Errors
+ * in this domain will be from the #GDBusError enumeration. See
+ * #GError for more information on error domains.
+ * Note that errors in this error domain is intended only for
+ * returning errors from a remote message bus process. Errors
+ * generated locally in-process by e.g. #GDBusConnection is from the
+ * %G_IO_ERROR domain.
*
- * A key in the "id" namespace for getting the file system identifier.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- * An example use would be during drag and drop to see if the source
- * and target are on the same filesystem (default to move) or not (default
- * to copy).
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT:
+ * G_DEFINE_ABSTRACT_TYPE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
+ * A convenience macro for type implementations.
+ * Similar to G_DEFINE_TYPE(), but defines an abstract type.
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * Since: 2.4
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL:
+ * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A convenience macro for type implementations.
+ * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to
+ * insert custom code into the *_get_type() function, e.g. interface implementations
+ * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
*
- * Since: 2.22
+ * Since: 2.4
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START:
+ * G_DEFINE_BOXED_TYPE:
+ * @TypeName: The name of the new type, in Camel case.
+ * @type_name: The name of the new type, in lowercase, with words separated by '_'.
+ * @copy_func: the #GBoxedCopyFunc for the new type
+ * @free_func: the #GBoxedFreeFunc for the new type
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A convenience macro for boxed type implementations, which defines a
+ * type_name_get_type() function registering the boxed type.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED:
+ * G_DEFINE_BOXED_TYPE_WITH_CODE:
+ * @TypeName: The name of the new type, in Camel case.
+ * @type_name: The name of the new type, in lowercase, with words separated by '_'.
+ * @copy_func: the #GBoxedCopyFunc for the new type
+ * @free_func: the #GBoxedFreeFunc for the new type
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started
- * degraded.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A convenience macro for boxed type implementations.
+ * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
+ * type_name_get_type() function, e.g. to register value transformations with
+ * g_value_register_transform_func().
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP:
+ * G_DEFINE_DYNAMIC_TYPE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A convenience macro for dynamic type implementations, which declares a
+ * class initialization function, an instance initialization function (see
+ * #GTypeInfo for information about these) and a static variable named
+ * it defines a <function>*_get_type()</function> and a static
+ * <function>*_register_type()</function> function for use in your
+ * <function>module_init()</function>.
+ * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
*
- * Since: 2.22
+ * Since: 2.14
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT:
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
+ * @TypeName: The name of the new type, in Camel case.
+ * @type_name: The name of the new type, in lowercase, with words separated by '_'.
+ * @TYPE_PARENT: The #GType of the parent type.
+ * @flags: #GTypeFlags to pass to g_type_module_register_type()
+ * @CODE: Custom code that gets inserted in the *_get_type() function.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI:
+ * A more general version of G_DEFINE_DYNAMIC_TYPE() which
+ * allows to specify #GTypeFlags and custom code.
+ * |[
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
+ * gtk_gadget,
+ * GTK_TYPE_THING,
+ * 0,
+ * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
+ * ]|
+ * expands to
+ * |[
+ * static void gtk_gadget_init (GtkGadget *self);
+ * static void gtk_gadget_class_init (GtkGadgetClass *klass);
+ * static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
+ * static gpointer gtk_gadget_parent_class = NULL;
+ * static GType gtk_gadget_type_id = 0;
+ * static void gtk_gadget_class_intern_init (gpointer klass)
+ * {
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * }
+ * GType
+ * gtk_gadget_get_type (void)
+ * {
+ * return gtk_gadget_type_id;
+ * }
+ * static void
+ * gtk_gadget_register_type (GTypeModule *type_module)
+ * {
+ * const GTypeInfo g_define_type_info = {
+ * sizeof (GtkGadgetClass),
+ * (GBaseInitFunc) NULL,
+ * (GBaseFinalizeFunc) NULL,
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * (GClassFinalizeFunc) gtk_gadget_class_finalize,
+ * NULL, // class_data
+ * sizeof (GtkGadget),
+ * 0, // n_preallocs
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * NULL // value_table
+ * };
+ * gtk_gadget_type_id = g_type_module_register_type (type_module,
+ * GTK_TYPE_THING,
+ * GtkGadget,
+ * &g_define_type_info,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
+ * }
+ * ]|
*
- * A key in the "mountable" namespace for getting the HAL UDI for the mountable
- * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * Since: 2.14
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC:
+ * G_DEFINE_INTERFACE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
*
- * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE)
- * is automatically polled for media.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A convenience macro for #GTypeInterface definitions, which declares
+ * a default vtable initialization function and defines a *_get_type()
+ * function.
+ * The macro expects the interface initialization function to have the
+ * name <literal>t_n ## _default_init</literal>, and the interface
+ * structure to have the name <literal>TN ## Interface</literal>.
*
- * Since: 2.22
+ * Since: 2.24
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE:
+ * G_DEFINE_INTERFACE_WITH_CODE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
*
- * A key in the "mountable" namespace for getting the #GDriveStartStopType.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A convenience macro for #GTypeInterface definitions. Similar to
+ * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
+ * *_get_type() function, e.g. additional interface implementations
+ * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
+ * G_DEFINE_TYPE_EXTENDED() for a similar example using
+ * G_DEFINE_TYPE_WITH_CODE().
*
- * Since: 2.22
+ * Since: 2.24
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE:
+ * G_DEFINE_POINTER_TYPE:
+ * @TypeName: The name of the new type, in Camel case.
+ * @type_name: The name of the new type, in lowercase, with words separated by '_'.
*
- * A key in the "mountable" namespace for getting the unix device.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A convenience macro for pointer type implementations, which defines a
+ * type_name_get_type() function registering the pointer type.
+ *
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE:
+ * G_DEFINE_POINTER_TYPE_WITH_CODE:
+ * @TypeName: The name of the new type, in Camel case.
+ * @type_name: The name of the new type, in lowercase, with words separated by '_'.
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
*
- * A key in the "mountable" namespace for getting the unix device file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A convenience macro for pointer type implementations.
+ * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the
+ * type_name_get_type() function.
*
- * Since: 2.22
+ * Since: 2.26
*/
/**
- * G_FILE_ATTRIBUTE_OWNER_GROUP:
+ * G_DEFINE_TYPE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
*
- * A key in the "owner" namespace for getting the file owner's group.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A convenience macro for type implementations, which declares a
+ * class initialization function, an instance initialization function (see #GTypeInfo for information about
+ * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
+ * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Since: 2.4
*/
/**
- * G_FILE_ATTRIBUTE_OWNER_USER:
+ * G_DEFINE_TYPE_EXTENDED:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type, in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * @_f_: #GTypeFlags to pass to g_type_register_static()
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
*
- * A key in the "owner" namespace for getting the user name of the
- * file's owner. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * The most general convenience macro for type implementations, on which
+ * G_DEFINE_TYPE(), etc are based.
+ * |[
+ * G_DEFINE_TYPE_EXTENDED (GtkGadget,
+ * gtk_gadget,
+ * GTK_TYPE_WIDGET,
+ * 0,
+ * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
+ * ]|
+ * expands to
+ * |[
+ * static void gtk_gadget_init (GtkGadget *self);
+ * static void gtk_gadget_class_init (GtkGadgetClass *klass);
+ * static gpointer gtk_gadget_parent_class = NULL;
+ * static void gtk_gadget_class_intern_init (gpointer klass)
+ * {
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * }
+ * GType
+ * gtk_gadget_get_type (void)
+ * {
+ * static volatile gsize g_define_type_id__volatile = 0;
+ * if (g_once_init_enter (&g_define_type_id__volatile))
+ * {
+ * GType g_define_type_id =
+ * g_type_register_static_simple (GTK_TYPE_WIDGET,
+ * g_intern_static_string ("GtkGadget"),
+ * sizeof (GtkGadgetClass),
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * sizeof (GtkGadget),
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * (GTypeFlags) flags);
+ * {
+ * static const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
+ * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
+ * }
+ * return g_define_type_id__volatile;
+ * }
+ * ]|
+ * The only pieces which have to be manually provided are the definitions of
+ * the instance and class structure and the definitions of the instance and
+ * class init functions.
+ *
+ * Since: 2.4
*/
/**
- * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
+ * G_DEFINE_TYPE_WITH_CODE:
+ * @TN: The name of the new type, in Camel case.
+ * @t_n: The name of the new type in lowercase, with words separated by '_'.
+ * @T_P: The #GType of the parent type.
+ * @_C_: Custom code that gets inserted in the *_get_type() function.
*
- * A key in the "owner" namespace for getting the real name of the
- * user that owns the file. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A convenience macro for type implementations.
+ * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
+ * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
+ * Since: 2.4
*/
/**
- * G_FILE_ATTRIBUTE_PREVIEW_ICON:
- *
- * A key in the "preview" namespace for getting a #GIcon that can be
- * used to get preview of the file. For example, it may be a low
- * resolution thumbnail without metadata. Corresponding
- * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value
- * for this key should contain a #GIcon.
+ * G_ENUM_CLASS:
+ * @class: a valid #GEnumClass
*
- * Since: 2.20
+ * Casts a derived #GEnumClass structure into a #GEnumClass structure.
*/
/**
- * G_FILE_ATTRIBUTE_SELINUX_CONTEXT:
+ * G_ENUM_CLASS_TYPE:
+ * @class: a #GEnumClass
*
- * A key in the "selinux" namespace for getting the file's SELinux
- * context. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only
- * available if GLib has been built with SELinux support.
+ * Get the type identifier from a given #GEnumClass structure.
+ *
+ * Returns: the #GType
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE:
+ * G_ENUM_CLASS_TYPE_NAME:
+ * @class: a #GEnumClass
*
- * A key in the "standard" namespace for getting the amount of disk space
- * that is consumed by the file (in bytes). This will generally be larger
- * than the file size (due to block size overhead) but can occasionally be
- * smaller (for example, for sparse files).
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * Get the static type name from a given #GEnumClass structure.
*
- * Since: 2.20
+ * Returns: the type name.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE:
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
*
- * A key in the "standard" namespace for getting the content type of the file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
- * The value for this key should contain a valid content type.
+ * A key in the "access" namespace for checking deletion privileges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This attribute will be %TRUE if the user is able to delete the file.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME:
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
*
- * A key in the "standard" namespace for getting the copy name of the file.
- * The copy name is an optional version of the name. If available it's always
- * in UTF8, and corresponds directly to the original filename (only transcoded to
- * UTF8). This is useful if you want to copy the file to another filesystem that
- * might have a different encoding. If the filename is not a valid string in the
- * encoding selected for the filesystem it is in then the copy name will not be set.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "access" namespace for getting execution privileges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This attribute will be %TRUE if the user is able to execute the file.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION:
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
*
- * A key in the "standard" namespace for getting the description of the file.
- * The description is a utf8 string that describes the file, generally containing
- * the filename, but can also contain furter information. Example descriptions
- * could be "filename (on hostname)" for a remote file or "filename (in trash)"
- * for a file in the trash. This is useful for instance as the window title
- * when displaying a directory or for a bookmarks menu.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "access" namespace for getting read privileges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This attribute will be %TRUE if the user is able to read the file.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME:
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
*
- * A key in the "standard" namespace for getting the display name of the file.
- * A display name is guaranteed to be in UTF8 and can thus be displayed in
- * the UI.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "access" namespace for checking renaming privileges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This attribute will be %TRUE if the user is able to rename the file.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME:
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
*
- * A key in the "standard" namespace for edit name of the file.
- * An edit name is similar to the display name, but it is meant to be
- * used when you want to rename the file in the UI. The display name
- * might contain information you don't want in the new filename (such as
- * "(invalid unicode)" if the filename was in an invalid encoding).
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "access" namespace for checking trashing privileges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This attribute will be %TRUE if the user is able to move the file to
+ * the trash.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE:
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
*
- * A key in the "standard" namespace for getting the fast content type.
- * The fast content type isn't as reliable as the regular one, as it
- * only uses the filename to guess it, but it is faster to calculate than the
- * regular content type.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "access" namespace for getting write privileges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This attribute will be %TRUE if the user is able to write to the file.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_ICON:
+ * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
*
- * A key in the "standard" namespace for getting the icon for the file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
- * The value for this key should contain a #GIcon.
+ * A key in the "dos" namespace for checking if the file's archive flag
+ * is set. This attribute is %TRUE if the archive flag is set. This attribute
+ * is only available for DOS file systems. Corresponding #GFileAttributeType
+ * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP:
+ * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
*
- * A key in the "standard" namespace for checking if a file is a backup file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A key in the "dos" namespace for checking if the file's backup flag
+ * is set. This attribute is %TRUE if the backup flag is set. This attribute
+ * is only available for DOS file systems. Corresponding #GFileAttributeType
+ * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN:
+ * G_FILE_ATTRIBUTE_ETAG_VALUE:
*
- * A key in the "standard" namespace for checking if a file is hidden.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A key in the "etag" namespace for getting the value of the file's
+ * entity tag. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK:
+ * G_FILE_ATTRIBUTE_FILESYSTEM_FREE:
*
- * A key in the "standard" namespace for checking if the file is a symlink.
- * Typically the actual type is something else, if we followed the symlink
- * to get the type.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A key in the "filesystem" namespace for getting the number of bytes of free space left on the
+ * file system. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL:
+ * G_FILE_ATTRIBUTE_FILESYSTEM_READONLY:
*
- * A key in the "standard" namespace for checking if a file is virtual.
+ * A key in the "filesystem" namespace for checking if the file system
+ * is read only. Is set to %TRUE if the file system is read only.
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_NAME:
+ * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE:
*
- * A key in the "standard" namespace for getting the name of the file.
- * The name is the on-disk filename which may not be in any known encoding,
- * and can thus not be generally displayed as is.
- * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the
- * name in a user interface.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system,
+ * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType
+ * is %G_FILE_ATTRIBUTE_TYPE_UINT64.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_SIZE:
+ * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE:
*
- * A key in the "standard" namespace for getting the file's size (in bytes).
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * A key in the "filesystem" namespace for getting the file system's type.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER:
+ * G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW:
*
- * A key in the "standard" namespace for setting the sort order of a file.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
- * An example use would be in file managers, which would use this key
- * to set the order files are displayed. Files with smaller sort order
- * should be sorted first, and files without sort order as if sort order
- * was zero.
+ * A key in the "filesystem" namespace for hinting a file manager
+ * application whether it should preview (e.g. thumbnail) files on the
+ * file system. The value for this key contain a
+ * #GFilesystemPreviewType.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET:
+ * G_FILE_ATTRIBUTE_GVFS_BACKEND:
*
- * A key in the "standard" namespace for getting the symlink target, if the file
- * is a symlink. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ * A key in the "gvfs" namespace that gets the name of the current
+ * GVFS backend in use. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_TARGET_URI:
+ * G_FILE_ATTRIBUTE_ID_FILE:
*
- * A key in the "standard" namespace for getting the target URI for the file, in
- * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files.
+ * A key in the "id" namespace for getting a file identifier.
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * An example use would be during listing files, to avoid recursive
+ * directory scanning.
*/
/**
- * G_FILE_ATTRIBUTE_STANDARD_TYPE:
+ * G_FILE_ATTRIBUTE_ID_FILESYSTEM:
*
- * A key in the "standard" namespace for storing file types.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
- * The value for this key should contain a #GFileType.
+ * A key in the "id" namespace for getting the file system identifier.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * An example use would be during drag and drop to see if the source
+ * and target are on the same filesystem (default to move) or not (default
+ * to copy).
*/
/**
- * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT:
*
- * A key in the "thumbnail" namespace for checking if thumbnailing failed.
- * This attribute is %TRUE if thumbnailing failed. Corresponding
- * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
*
- * A key in the "thumbnail" namespace for getting the path to the thumbnail
- * image. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_FILE_ATTRIBUTE_TIME_ACCESS:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL:
*
- * A key in the "time" namespace for getting the time the file was last
- * accessed. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
- * file was last accessed.
- */
-
-
-/**
- * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
- * A key in the "time" namespace for getting the microseconds of the time
- * the file was last accessed. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TIME_CHANGED:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START:
*
- * A key in the "time" namespace for getting the time the file was last
- * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
- * and contains the UNIX time since the file was last changed.
- * This corresponds to the traditional UNIX ctime.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ *
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED:
*
- * A key in the "time" namespace for getting the microseconds of the time
- * the file was last changed. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started
+ * degraded.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ *
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TIME_CREATED:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP:
*
- * A key in the "time" namespace for getting the time the file was created.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
- * and contains the UNIX time since the file was created.
- * This corresponds to the NTFS ctime.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ *
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TIME_CREATED_USEC:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT:
*
- * A key in the "time" namespace for getting the microseconds of the time
- * the file was created. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_FILE_ATTRIBUTE_TIME_MODIFIED:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI:
*
- * A key in the "time" namespace for getting the time the file was last
- * modified. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
- * file was modified.
+ * A key in the "mountable" namespace for getting the HAL UDI for the mountable
+ * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC:
*
- * A key in the "time" namespace for getting the miliseconds of the time
- * the file was last modified. This should be used in conjunction with
- * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE)
+ * is automatically polled for media.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ *
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE:
*
- * A key in the "trash" namespace. When requested against
- * items in "trash:///", will return the date and time when the file
- * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "mountable" namespace for getting the #GDriveStartStopType.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*
- * Since: 2.24.
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE:
*
- * A key in the "trash" namespace. When requested against
- * "trash:///" returns the number of (toplevel) items in the trash folder.
+ * A key in the "mountable" namespace for getting the unix device.
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH:
+ * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE:
*
- * A key in the "trash" namespace. When requested against
- * items in "trash:///", will return the original path to the file before it
- * was trashed. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * A key in the "mountable" namespace for getting the unix device file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*
- * Since: 2.24.
+ * Since: 2.22
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
+ * G_FILE_ATTRIBUTE_OWNER_GROUP:
*
- * A key in the "unix" namespace for getting the number of blocks allocated
- * for the file. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * A key in the "owner" namespace for getting the file owner's group.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
+ * G_FILE_ATTRIBUTE_OWNER_USER:
*
- * A key in the "unix" namespace for getting the block size for the file
- * system. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "owner" namespace for getting the user name of the
+ * file's owner. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_DEVICE:
+ * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
*
- * A key in the "unix" namespace for getting the device id of the device the
- * file is located on (see stat() documentation). This attribute is only
- * available for UNIX file systems. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "owner" namespace for getting the real name of the
+ * user that owns the file. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_GID:
+ * G_FILE_ATTRIBUTE_PREVIEW_ICON:
*
- * A key in the "unix" namespace for getting the group ID for the file.
- * This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "preview" namespace for getting a #GIcon that can be
+ * used to get preview of the file. For example, it may be a low
+ * resolution thumbnail without metadata. Corresponding
+ * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value
+ * for this key should contain a #GIcon.
+ *
+ * Since: 2.20
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_INODE:
+ * G_FILE_ATTRIBUTE_SELINUX_CONTEXT:
*
- * A key in the "unix" namespace for getting the inode of the file.
- * This attribute is only available for UNIX file systems. Corresponding
- * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * A key in the "selinux" namespace for getting the file's SELinux
+ * context. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only
+ * available if GLib has been built with SELinux support.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
+ * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE:
*
- * A key in the "unix" namespace for checking if the file represents a
- * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount
- * point. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * A key in the "standard" namespace for getting the amount of disk space
+ * that is consumed by the file (in bytes). This will generally be larger
+ * than the file size (due to block size overhead) but can occasionally be
+ * smaller (for example, for sparse files).
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ *
+ * Since: 2.20
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_MODE:
+ * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE:
*
- * A key in the "unix" namespace for getting the mode of the file
- * (e.g. whether the file is a regular file, symlink, etc). See lstat()
- * documentation. This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "standard" namespace for getting the content type of the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * The value for this key should contain a valid content type.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_NLINK:
+ * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME:
*
- * A key in the "unix" namespace for getting the number of hard links
- * for a file. See lstat() documentation. This attribute is only available
- * for UNIX file systems. Corresponding #GFileAttributeType is
- * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "standard" namespace for getting the copy name of the file.
+ * The copy name is an optional version of the name. If available it's always
+ * in UTF8, and corresponds directly to the original filename (only transcoded to
+ * UTF8). This is useful if you want to copy the file to another filesystem that
+ * might have a different encoding. If the filename is not a valid string in the
+ * encoding selected for the filesystem it is in then the copy name will not be set.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_RDEV:
+ * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION:
*
- * A key in the "unix" namespace for getting the device ID for the file
- * (if it is a special file). See lstat() documentation. This attribute
- * is only available for UNIX file systems. Corresponding #GFileAttributeType
- * is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "standard" namespace for getting the description of the file.
+ * The description is a utf8 string that describes the file, generally containing
+ * the filename, but can also contain furter information. Example descriptions
+ * could be "filename (on hostname)" for a remote file or "filename (in trash)"
+ * for a file in the trash. This is useful for instance as the window title
+ * when displaying a directory or for a bookmarks menu.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FILE_ATTRIBUTE_UNIX_UID:
+ * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME:
*
- * A key in the "unix" namespace for getting the user ID for the file.
- * This attribute is only available for UNIX file systems.
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * A key in the "standard" namespace for getting the display name of the file.
+ * A display name is guaranteed to be in UTF8 and can thus be displayed in
+ * the UI.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FLAGS_CLASS:
- * @class: a valid #GFlagsClass
+ * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME:
*
- * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
+ * A key in the "standard" namespace for edit name of the file.
+ * An edit name is similar to the display name, but it is meant to be
+ * used when you want to rename the file in the UI. The display name
+ * might contain information you don't want in the new filename (such as
+ * "(invalid unicode)" if the filename was in an invalid encoding).
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FLAGS_CLASS_TYPE:
- * @class: a #GFlagsClass
- *
- * Get the type identifier from a given #GFlagsClass structure.
+ * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE:
*
- * Returns: the #GType
+ * A key in the "standard" namespace for getting the fast content type.
+ * The fast content type isn't as reliable as the regular one, as it
+ * only uses the filename to guess it, but it is faster to calculate than the
+ * regular content type.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_FLAGS_CLASS_TYPE_NAME:
- * @class: a #GFlagsClass
- *
- * Get the static type name from a given #GFlagsClass structure.
+ * G_FILE_ATTRIBUTE_STANDARD_ICON:
*
- * Returns: the type name.
+ * A key in the "standard" namespace for getting the icon for the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
+ * The value for this key should contain a #GIcon.
*/
/**
- * G_IMPLEMENT_INTERFACE:
- * @TYPE_IFACE: The #GType of the interface to add
- * @iface_init: The interface init function
- *
- * A convenience macro to ease interface addition in the @_C_ section
- * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
- * See G_DEFINE_TYPE_EXTENDED() for an example.
- * Note that this macro can only be used together with the G_DEFINE_TYPE_*
- * macros, since it depends on variable names from those macros.
+ * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP:
*
- * Since: 2.4
+ * A key in the "standard" namespace for checking if a file is a backup file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_IMPLEMENT_INTERFACE_DYNAMIC:
- * @TYPE_IFACE: The #GType of the interface to add
- * @iface_init: The interface init function
- *
- * A convenience macro to ease interface addition in the @_C_ section
- * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
- * for an example.
- * Note that this macro can only be used together with the
- * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
- * names from that macro.
+ * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN:
*
- * Since: 2.24
+ * A key in the "standard" namespace for checking if a file is hidden.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_INITIALLY_UNOWNED:
- * @object: Object which is subject to casting.
+ * G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK:
*
- * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*)
- * pointer. Depending on the current debugging level, this function may invoke
- * certain runtime checks to identify invalid casts.
+ * A key in the "standard" namespace for checking if the file is a symlink.
+ * Typically the actual type is something else, if we followed the symlink
+ * to get the type.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_INITIALLY_UNOWNED_CLASS:
- * @class: a valid #GInitiallyUnownedClass
+ * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL:
*
- * Casts a derived #GInitiallyUnownedClass structure into a
- * #GInitiallyUnownedClass structure.
+ * A key in the "standard" namespace for checking if a file is virtual.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_INITIALLY_UNOWNED_GET_CLASS:
- * @object: a #GInitiallyUnowned instance.
- *
- * Get the class structure associated to a #GInitiallyUnowned instance.
+ * G_FILE_ATTRIBUTE_STANDARD_NAME:
*
- * Returns: pointer to object class structure.
+ * A key in the "standard" namespace for getting the name of the file.
+ * The name is the on-disk filename which may not be in any known encoding,
+ * and can thus not be generally displayed as is.
+ * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the
+ * name in a user interface.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
*/
/**
- * G_IO_ERROR:
+ * G_FILE_ATTRIBUTE_STANDARD_SIZE:
*
- * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration.
- * See #GError for more information on error domains.
+ * A key in the "standard" namespace for getting the file's size (in bytes).
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
*/
/**
- * G_IS_ENUM_CLASS:
- * @class: a #GEnumClass
+ * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER:
*
- * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
- * or derived.
+ * A key in the "standard" namespace for setting the sort order of a file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
+ * An example use would be in file managers, which would use this key
+ * to set the order files are displayed. Files with smaller sort order
+ * should be sorted first, and files without sort order as if sort order
+ * was zero.
*/
/**
- * G_IS_FLAGS_CLASS:
- * @class: a #GFlagsClass
+ * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET:
*
- * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
- * or derived.
+ * A key in the "standard" namespace for getting the symlink target, if the file
+ * is a symlink. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
*/
/**
- * G_IS_INITIALLY_UNOWNED:
- * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.
+ * G_FILE_ATTRIBUTE_STANDARD_TARGET_URI:
*
- * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.
+ * A key in the "standard" namespace for getting the target URI for the file, in
+ * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
/**
- * G_IS_INITIALLY_UNOWNED_CLASS:
- * @class: a #GInitiallyUnownedClass
+ * G_FILE_ATTRIBUTE_STANDARD_TYPE:
*
- * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type
- * %G_TYPE_INITIALLY_UNOWNED or derived.
+ * A key in the "standard" namespace for storing file types.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * The value for this key should contain a #GFileType.
*/
/**
- * G_IS_OBJECT:
- * @object: Instance to check for being a %G_TYPE_OBJECT.
+ * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED:
*
- * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
+ * A key in the "thumbnail" namespace for checking if thumbnailing failed.
+ * This attribute is %TRUE if thumbnailing failed. Corresponding
+ * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_IS_OBJECT_CLASS:
- * @class: a #GObjectClass
+ * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
*
- * Checks whether @class "is a" valid #GObjectClass structure of type
- * %G_TYPE_OBJECT or derived.
+ * A key in the "thumbnail" namespace for getting the path to the thumbnail
+ * image. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
*/
/**
- * G_IS_PARAM_SPEC:
- * @pspec: a #GParamSpec
+ * G_FILE_ATTRIBUTE_TIME_ACCESS:
*
- * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
- * or derived.
+ * A key in the "time" namespace for getting the time the file was last
+ * accessed. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
+ * file was last accessed.
*/
/**
- * G_IS_PARAM_SPEC_BOOLEAN:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.
+ * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
*
- * Returns: %TRUE on success.
+ * A key in the "time" namespace for getting the microseconds of the time
+ * the file was last accessed. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_BOXED:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.
+ * G_FILE_ATTRIBUTE_TIME_CHANGED:
*
- * Returns: %TRUE on success.
+ * A key in the "time" namespace for getting the time the file was last
+ * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
+ * and contains the UNIX time since the file was last changed.
+ * This corresponds to the traditional UNIX ctime.
*/
/**
- * G_IS_PARAM_SPEC_CHAR:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.
+ * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
*
- * Returns: %TRUE on success.
+ * A key in the "time" namespace for getting the microseconds of the time
+ * the file was last changed. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_CLASS:
- * @pclass: a #GParamSpecClass
+ * G_FILE_ATTRIBUTE_TIME_CREATED:
*
- * Checks whether @pclass "is a" valid #GParamSpecClass structure of type
- * %G_TYPE_PARAM or derived.
+ * A key in the "time" namespace for getting the time the file was created.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
+ * and contains the UNIX time since the file was created.
+ * This corresponds to the NTFS ctime.
*/
/**
- * G_IS_PARAM_SPEC_DOUBLE:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.
+ * G_FILE_ATTRIBUTE_TIME_CREATED_USEC:
*
- * Returns: %TRUE on success.
+ * A key in the "time" namespace for getting the microseconds of the time
+ * the file was created. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_ENUM:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.
+ * G_FILE_ATTRIBUTE_TIME_MODIFIED:
*
- * Returns: %TRUE on success.
+ * A key in the "time" namespace for getting the time the file was last
+ * modified. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
+ * file was modified.
*/
/**
- * G_IS_PARAM_SPEC_FLAGS:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.
+ * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC:
*
- * Returns: %TRUE on success.
+ * A key in the "time" namespace for getting the miliseconds of the time
+ * the file was last modified. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_FLOAT:
- * @pspec: a valid #GParamSpec instance
+ * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE:
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.
+ * A key in the "trash" namespace. When requested against
+ * items in "trash:///", will return the date and time when the file
+ * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*
- * Returns: %TRUE on success.
+ * Since: 2.24.
*/
/**
- * G_IS_PARAM_SPEC_GTYPE:
- * @pspec: a #GParamSpec
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.
+ * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT:
*
- * Since: 2.10
- * Returns: %TRUE on success.
+ * A key in the "trash" namespace. When requested against
+ * "trash:///" returns the number of (toplevel) items in the trash folder.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_INT:
- * @pspec: a valid #GParamSpec instance
+ * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH:
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.
+ * A key in the "trash" namespace. When requested against
+ * items in "trash:///", will return the original path to the file before it
+ * was trashed. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
*
- * Returns: %TRUE on success.
+ * Since: 2.24.
*/
/**
- * G_IS_PARAM_SPEC_INT64:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.
+ * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the number of blocks allocated
+ * for the file. This attribute is only available for UNIX file systems.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
*/
/**
- * G_IS_PARAM_SPEC_LONG:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.
+ * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the block size for the file
+ * system. This attribute is only available for UNIX file systems.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_OBJECT:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
+ * G_FILE_ATTRIBUTE_UNIX_DEVICE:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the device id of the device the
+ * file is located on (see stat() documentation). This attribute is only
+ * available for UNIX file systems. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_OVERRIDE:
- * @pspec: a #GParamSpec
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.
+ * G_FILE_ATTRIBUTE_UNIX_GID:
*
- * Since: 2.4
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the group ID for the file.
+ * This attribute is only available for UNIX file systems.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_PARAM:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.
+ * G_FILE_ATTRIBUTE_UNIX_INODE:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the inode of the file.
+ * This attribute is only available for UNIX file systems. Corresponding
+ * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
*/
/**
- * G_IS_PARAM_SPEC_POINTER:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.
+ * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for checking if the file represents a
+ * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount
+ * point. This attribute is only available for UNIX file systems.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*/
/**
- * G_IS_PARAM_SPEC_STRING:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.
+ * G_FILE_ATTRIBUTE_UNIX_MODE:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the mode of the file
+ * (e.g. whether the file is a regular file, symlink, etc). See lstat()
+ * documentation. This attribute is only available for UNIX file systems.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_UCHAR:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.
+ * G_FILE_ATTRIBUTE_UNIX_NLINK:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the number of hard links
+ * for a file. See lstat() documentation. This attribute is only available
+ * for UNIX file systems. Corresponding #GFileAttributeType is
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_UINT:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.
+ * G_FILE_ATTRIBUTE_UNIX_RDEV:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the device ID for the file
+ * (if it is a special file). See lstat() documentation. This attribute
+ * is only available for UNIX file systems. Corresponding #GFileAttributeType
+ * is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_UINT64:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.
+ * G_FILE_ATTRIBUTE_UNIX_UID:
*
- * Returns: %TRUE on success.
+ * A key in the "unix" namespace for getting the user ID for the file.
+ * This attribute is only available for UNIX file systems.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*/
/**
- * G_IS_PARAM_SPEC_ULONG:
- * @pspec: a valid #GParamSpec instance
- *
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.
+ * G_FLAGS_CLASS:
+ * @class: a valid #GFlagsClass
*
- * Returns: %TRUE on success.
+ * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
*/
/**
- * G_IS_PARAM_SPEC_UNICHAR:
- * @pspec: a valid #GParamSpec instance
+ * G_FLAGS_CLASS_TYPE:
+ * @class: a #GFlagsClass
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.
+ * Get the type identifier from a given #GFlagsClass structure.
*
- * Returns: %TRUE on success.
+ * Returns: the #GType
*/
/**
- * G_IS_PARAM_SPEC_VALUE_ARRAY:
- * @pspec: a valid #GParamSpec instance
+ * G_FLAGS_CLASS_TYPE_NAME:
+ * @class: a #GFlagsClass
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
+ * Get the static type name from a given #GFlagsClass structure.
*
- * Returns: %TRUE on success.
+ * Returns: the type name.
*/
/**
- * G_IS_PARAM_SPEC_VARIANT:
- * @pspec: a #GParamSpec
+ * G_IMPLEMENT_INTERFACE:
+ * @TYPE_IFACE: The #GType of the interface to add
+ * @iface_init: The interface init function
*
- * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT.
+ * A convenience macro to ease interface addition in the @_C_ section
+ * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
+ * Note that this macro can only be used together with the G_DEFINE_TYPE_*
+ * macros, since it depends on variable names from those macros.
*
- * Returns: %TRUE on success
- * Since: 2.26
+ * Since: 2.4
*/
/**
- * G_IS_VALUE:
- * @value: A #GValue structure.
+ * G_IMPLEMENT_INTERFACE_DYNAMIC:
+ * @TYPE_IFACE: The #GType of the interface to add
+ * @iface_init: The interface init function
*
- * Checks if @value is a valid and initialized #GValue structure.
+ * A convenience macro to ease interface addition in the @_C_ section
+ * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
+ * for an example.
+ * Note that this macro can only be used together with the
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
+ * names from that macro.
*
- * Returns: %TRUE on success.
+ * Since: 2.24
*/
/**
- * G_MARKUP_ERROR:
+ * G_INITIALLY_UNOWNED:
+ * @object: Object which is subject to casting.
*
- * Error domain for markup parsing.
- * Errors in this domain will be from the #GMarkupError enumeration.
- * See #GError for information on error domains.
+ * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*)
+ * pointer. Depending on the current debugging level, this function may invoke
+ * certain runtime checks to identify invalid casts.
*/
/**
- * G_NODE_IS_LEAF:
- * @node: a #GNode
- *
- * Returns %TRUE if a #GNode is a leaf node.
- * (i.e. it has no children)
+ * G_INITIALLY_UNOWNED_CLASS:
+ * @class: a valid #GInitiallyUnownedClass
*
- * Returns: %TRUE if the #GNode is a leaf node
+ * Casts a derived #GInitiallyUnownedClass structure into a
+ * #GInitiallyUnownedClass structure.
*/
/**
- * G_NODE_IS_ROOT:
- * @node: a #GNode
+ * G_INITIALLY_UNOWNED_GET_CLASS:
+ * @object: a #GInitiallyUnowned instance.
*
- * Returns %TRUE if a #GNode is the root of a tree.
- * (i.e. it has no parent or siblings)
+ * Get the class structure associated to a #GInitiallyUnowned instance.
*
- * Returns: %TRUE if the #GNode is the root of a tree
+ * Returns: pointer to object class structure.
*/
/**
- * G_OBJECT:
- * @object: Object which is subject to casting.
+ * G_IO_ERROR:
*
- * Casts a #GObject or derived pointer into a (GObject*) pointer.
- * Depending on the current debugging level, this function may invoke
- * certain runtime checks to identify invalid casts.
+ * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration.
+ * See #GError for more information on error domains.
*/
/**
- * G_OBJECT_CLASS:
- * @class: a valid #GObjectClass
+ * G_IS_ENUM_CLASS:
+ * @class: a #GEnumClass
*
- * Casts a derived #GObjectClass structure into a #GObjectClass structure.
+ * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
+ * or derived.
*/
/**
- * G_OBJECT_CLASS_NAME:
- * @class: a valid #GObjectClass
- *
- * Return the name of a class structure's type.
- * should not be freed.
+ * G_IS_FLAGS_CLASS:
+ * @class: a #GFlagsClass
*
- * Returns: Type name of @class. The string is owned by the type system and
+ * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
+ * or derived.
*/
/**
- * G_OBJECT_CLASS_TYPE:
- * @class: a valid #GObjectClass
- *
- * Get the type id of a class structure.
+ * G_IS_INITIALLY_UNOWNED:
+ * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.
*
- * Returns: Type id of @class.
+ * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.
*/
/**
- * G_OBJECT_GET_CLASS:
- * @object: a #GObject instance.
- *
- * Get the class structure associated to a #GObject instance.
+ * G_IS_INITIALLY_UNOWNED_CLASS:
+ * @class: a #GInitiallyUnownedClass
*
- * Returns: pointer to object class structure.
+ * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type
+ * %G_TYPE_INITIALLY_UNOWNED or derived.
*/
/**
- * G_OBJECT_TYPE:
- * @object: Object to return the type id for.
- *
- * Get the type id of an object.
+ * G_IS_OBJECT:
+ * @object: Instance to check for being a %G_TYPE_OBJECT.
*
- * Returns: Type id of @object.
+ * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
*/
/**
- * G_OBJECT_TYPE_NAME:
- * @object: Object to return the type name for.
- *
- * Get the name of an object's type.
- * should not be freed.
+ * G_IS_OBJECT_CLASS:
+ * @class: a #GObjectClass
*
- * Returns: Type name of @object. The string is owned by the type system and
+ * Checks whether @class "is a" valid #GObjectClass structure of type
+ * %G_TYPE_OBJECT or derived.
*/
/**
- * G_OBJECT_WARN_INVALID_PROPERTY_ID:
- * @object: the #GObject on which set_property() or get_property() was called
- * @property_id: the numeric id of the property
- * @pspec: the #GParamSpec of the property
+ * G_IS_PARAM_SPEC:
+ * @pspec: a #GParamSpec
*
- * This macro should be used to emit a standard warning about unexpected
- * properties in set_property() and get_property() implementations.
+ * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
+ * or derived.
*/
/**
- * G_OPTION_ERROR:
+ * G_IS_PARAM_SPEC_BOOLEAN:
+ * @pspec: a valid #GParamSpec instance
*
- * Error domain for option parsing. Errors in this domain will
- * be from the #GOptionError enumeration. See #GError for information on
- * error domains.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_OPTION_REMAINING:
+ * G_IS_PARAM_SPEC_BOXED:
+ * @pspec: a valid #GParamSpec instance
*
- * If a long option in the main group has this name, it is not treated as a
- * regular option. Instead it collects all non-option arguments which would
- * otherwise be left in <literal>argv</literal>. The option must be of type
- * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
- * or %G_OPTION_ARG_FILENAME_ARRAY.
- * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
- * for leftover arguments has the advantage that GOption takes care of
- * necessary encoding conversions for strings or filenames.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.
*
- * Since: 2.6
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_MASK:
+ * G_IS_PARAM_SPEC_CHAR:
+ * @pspec: a valid #GParamSpec instance
*
- * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_READWRITE:
+ * G_IS_PARAM_SPEC_CLASS:
+ * @pclass: a #GParamSpecClass
*
- * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
+ * Checks whether @pclass "is a" valid #GParamSpecClass structure of type
+ * %G_TYPE_PARAM or derived.
*/
/**
- * G_PARAM_SPEC:
- * @pspec: a valid #GParamSpec
+ * G_IS_PARAM_SPEC_DOUBLE:
+ * @pspec: a valid #GParamSpec instance
*
- * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
- * a #GParamSpec object.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_BOOLEAN:
+ * G_IS_PARAM_SPEC_ENUM:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecBoolean.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_BOXED:
+ * G_IS_PARAM_SPEC_FLAGS:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecBoxed.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_CHAR:
+ * G_IS_PARAM_SPEC_FLOAT:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecChar.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_CLASS:
- * @pclass: a valid #GParamSpecClass
+ * G_IS_PARAM_SPEC_GTYPE:
+ * @pspec: a #GParamSpec
*
- * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.
+ *
+ * Since: 2.10
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_DOUBLE:
+ * G_IS_PARAM_SPEC_INT:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecDouble.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_ENUM:
+ * G_IS_PARAM_SPEC_INT64:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecEnum.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_FLAGS:
+ * G_IS_PARAM_SPEC_LONG:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecFlags.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_FLOAT:
+ * G_IS_PARAM_SPEC_OBJECT:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecFloat.
- */
-
-
-/**
- * G_PARAM_SPEC_GET_CLASS:
- * @pspec: a valid #GParamSpec
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
*
- * Retrieves the #GParamSpecClass of a #GParamSpec.
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_GTYPE:
+ * G_IS_PARAM_SPEC_OVERRIDE:
* @pspec: a #GParamSpec
*
- * Casts a #GParamSpec into a #GParamSpecGType.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.
*
- * Since: 2.10
+ * Since: 2.4
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_INT:
+ * G_IS_PARAM_SPEC_PARAM:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecInt.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_INT64:
+ * G_IS_PARAM_SPEC_POINTER:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecInt64.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_LONG:
+ * G_IS_PARAM_SPEC_STRING:
* @pspec: a valid #GParamSpec instance
*
- * Cast a #GParamSpec instance into a #GParamSpecLong.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_OBJECT:
+ * G_IS_PARAM_SPEC_UCHAR:
* @pspec: a valid #GParamSpec instance
*
- * Casts a #GParamSpec instance into a #GParamSpecObject.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_OVERRIDE:
- * @pspec: a #GParamSpec
+ * G_IS_PARAM_SPEC_UINT:
+ * @pspec: a valid #GParamSpec instance
*
- * Casts a #GParamSpec into a #GParamSpecOverride.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.
*
- * Since: 2.4
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_PARAM:
+ * G_IS_PARAM_SPEC_UINT64:
* @pspec: a valid #GParamSpec instance
*
- * Casts a #GParamSpec instance into a #GParamSpecParam.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_POINTER:
+ * G_IS_PARAM_SPEC_ULONG:
* @pspec: a valid #GParamSpec instance
*
- * Casts a #GParamSpec instance into a #GParamSpecPointer.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_STRING:
+ * G_IS_PARAM_SPEC_UNICHAR:
* @pspec: a valid #GParamSpec instance
*
- * Casts a #GParamSpec instance into a #GParamSpecString.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_TYPE:
- * @pspec: a valid #GParamSpec
+ * G_IS_PARAM_SPEC_VALUE_ARRAY:
+ * @pspec: a valid #GParamSpec instance
*
- * Retrieves the #GType of this @pspec.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_TYPE_NAME:
- * @pspec: a valid #GParamSpec
+ * G_IS_PARAM_SPEC_VARIANT:
+ * @pspec: a #GParamSpec
*
- * Retrieves the #GType name of this @pspec.
+ * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT.
+ *
+ * Returns: %TRUE on success
+ * Since: 2.26
*/
/**
- * G_PARAM_SPEC_UCHAR:
- * @pspec: a valid #GParamSpec instance
+ * G_IS_VALUE:
+ * @value: A #GValue structure.
*
- * Cast a #GParamSpec instance into a #GParamSpecUChar.
+ * Checks if @value is a valid and initialized #GValue structure.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_PARAM_SPEC_UINT:
- * @pspec: a valid #GParamSpec instance
+ * G_MARKUP_ERROR:
*
- * Cast a #GParamSpec instance into a #GParamSpecUInt.
+ * Error domain for markup parsing.
+ * Errors in this domain will be from the #GMarkupError enumeration.
+ * See #GError for information on error domains.
*/
/**
- * G_PARAM_SPEC_UINT64:
- * @pspec: a valid #GParamSpec instance
+ * G_NODE_IS_LEAF:
+ * @node: a #GNode
*
- * Cast a #GParamSpec instance into a #GParamSpecUInt64.
+ * Returns %TRUE if a #GNode is a leaf node.
+ * (i.e. it has no children)
+ *
+ * Returns: %TRUE if the #GNode is a leaf node
*/
/**
- * G_PARAM_SPEC_ULONG:
- * @pspec: a valid #GParamSpec instance
+ * G_NODE_IS_ROOT:
+ * @node: a #GNode
*
- * Cast a #GParamSpec instance into a #GParamSpecULong.
+ * Returns %TRUE if a #GNode is the root of a tree.
+ * (i.e. it has no parent or siblings)
+ *
+ * Returns: %TRUE if the #GNode is the root of a tree
*/
/**
- * G_PARAM_SPEC_UNICHAR:
- * @pspec: a valid #GParamSpec instance
+ * G_OBJECT:
+ * @object: Object which is subject to casting.
*
- * Cast a #GParamSpec instance into a #GParamSpecUnichar.
+ * Casts a #GObject or derived pointer into a (GObject*) pointer.
+ * Depending on the current debugging level, this function may invoke
+ * certain runtime checks to identify invalid casts.
*/
/**
- * G_PARAM_SPEC_VALUE_ARRAY:
- * @pspec: a valid #GParamSpec instance
+ * G_OBJECT_CLASS:
+ * @class: a valid #GObjectClass
*
- * Cast a #GParamSpec instance into a #GParamSpecValueArray.
+ * Casts a derived #GObjectClass structure into a #GObjectClass structure.
*/
/**
- * G_PARAM_SPEC_VALUE_TYPE:
- * @pspec: a valid #GParamSpec
+ * G_OBJECT_CLASS_NAME:
+ * @class: a valid #GObjectClass
*
- * Retrieves the #GType to initialize a #GValue for this parameter.
+ * Return the name of a class structure's type.
+ * should not be freed.
+ *
+ * Returns: Type name of @class. The string is owned by the type system and
*/
/**
- * G_PARAM_SPEC_VARIANT:
- * @pspec: a #GParamSpec
+ * G_OBJECT_CLASS_TYPE:
+ * @class: a valid #GObjectClass
*
- * Casts a #GParamSpec into a #GParamSpecVariant.
+ * Get the type id of a class structure.
*
- * Since: 2.26
+ * Returns: Type id of @class.
*/
/**
- * G_PARAM_STATIC_STRINGS:
+ * G_OBJECT_GET_CLASS:
+ * @object: a #GObject instance.
*
- * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
- * Since 2.13.0
+ * Get the class structure associated to a #GObject instance.
+ *
+ * Returns: pointer to object class structure.
*/
/**
- * G_PARAM_USER_SHIFT:
+ * G_OBJECT_TYPE:
+ * @object: Object to return the type id for.
*
- * Minimum shift count to be used for user defined flags, to be stored in
- * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT.
+ * Get the type id of an object.
+ *
+ * Returns: Type id of @object.
*/
/**
- * G_PRIORITY_DEFAULT:
+ * G_OBJECT_TYPE_NAME:
+ * @object: Object to return the type name for.
*
- * Use this for default priority event sources.
- * In GLib this priority is used when adding timeout functions
- * with g_timeout_add(). In GDK this priority is used for events
- * from the X server.
+ * Get the name of an object's type.
+ * should not be freed.
+ *
+ * Returns: Type name of @object. The string is owned by the type system and
*/
/**
- * G_PRIORITY_DEFAULT_IDLE:
+ * G_OBJECT_WARN_INVALID_PROPERTY_ID:
+ * @object: the #GObject on which set_property() or get_property() was called
+ * @property_id: the numeric id of the property
+ * @pspec: the #GParamSpec of the property
*
- * Use this for default priority idle functions.
- * In GLib this priority is used when adding idle functions with
- * g_idle_add().
+ * This macro should be used to emit a standard warning about unexpected
+ * properties in set_property() and get_property() implementations.
*/
/**
- * G_PRIORITY_HIGH:
+ * G_OPTION_ERROR:
*
- * Use this for high priority event sources.
- * It is not used within GLib or GTK+.
+ * Error domain for option parsing. Errors in this domain will
+ * be from the #GOptionError enumeration. See #GError for information on
+ * error domains.
*/
/**
- * G_PRIORITY_HIGH_IDLE:
+ * G_OPTION_REMAINING:
*
- * Use this for high priority idle functions.
- * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
- * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
- * done to ensure that any pending resizes are processed before any
- * pending redraws, so that widgets are not redrawn twice unnecessarily.)
+ * If a long option in the main group has this name, it is not treated as a
+ * regular option. Instead it collects all non-option arguments which would
+ * otherwise be left in <literal>argv</literal>. The option must be of type
+ * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
+ * or %G_OPTION_ARG_FILENAME_ARRAY.
+ * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
+ * for leftover arguments has the advantage that GOption takes care of
+ * necessary encoding conversions for strings or filenames.
+ *
+ * Since: 2.6
*/
/**
- * G_PRIORITY_LOW:
+ * G_PARAM_MASK:
*
- * Use this for very low priority background tasks.
- * It is not used within GLib or GTK+.
+ * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
*/
/**
- * G_PROXY_EXTENSION_POINT_NAME:
- *
- * Extension point for proxy functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * G_PARAM_READWRITE:
*
- * Since: 2.26
+ * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
*/
/**
- * G_PROXY_RESOLVER_EXTENSION_POINT_NAME:
+ * G_PARAM_SPEC:
+ * @pspec: a valid #GParamSpec
*
- * Extension point for proxy resolving functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
+ * a #GParamSpec object.
*/
/**
- * G_REGEX_ERROR:
- *
- * Error domain for regular expressions. Errors in this domain will be
- * from the #GRegexError enumeration. See #GError for information on
- * error domains.
+ * G_PARAM_SPEC_BOOLEAN:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.14
+ * Cast a #GParamSpec instance into a #GParamSpecBoolean.
*/
/**
- * G_RESOLVER_ERROR:
+ * G_PARAM_SPEC_BOXED:
+ * @pspec: a valid #GParamSpec instance
*
- * Error domain for #GResolver. Errors in this domain will be from the
- * #GResolverError enumeration. See #GError for more information on
- * error domains.
+ * Cast a #GParamSpec instance into a #GParamSpecBoxed.
*/
/**
- * G_SETTINGS_BACKEND_EXTENSION_POINT_NAME:
+ * G_PARAM_SPEC_CHAR:
+ * @pspec: a valid #GParamSpec instance
*
- * Extension point for #GSettingsBackend functionality.
+ * Cast a #GParamSpec instance into a #GParamSpecChar.
*/
/**
- * G_SIGNAL_FLAGS_MASK:
+ * G_PARAM_SPEC_CLASS:
+ * @pclass: a valid #GParamSpecClass
*
- * A mask for all #GSignalFlags bits.
+ * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
*/
/**
- * G_SIGNAL_MATCH_MASK:
+ * G_PARAM_SPEC_DOUBLE:
+ * @pspec: a valid #GParamSpec instance
*
- * A mask for all #GSignalMatchType bits.
+ * Cast a #GParamSpec instance into a #GParamSpecDouble.
*/
/**
- * G_SIGNAL_TYPE_STATIC_SCOPE:
+ * G_PARAM_SPEC_ENUM:
+ * @pspec: a valid #GParamSpec instance
*
- * This macro flags signal argument types for which the signal system may
- * assume that instances thereof remain persistent across all signal emissions
- * they are used in. This is only useful for non ref-counted, value-copy types.
- * To flag a signal argument in this way, add
- * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
- * of g_signal_new().
- * |[
- * g_signal_new ("size_request",
- * G_TYPE_FROM_CLASS (gobject_class),
- * G_SIGNAL_RUN_FIRST,
- * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
- * NULL, NULL,
- * _gtk_marshal_VOID__BOXED,
- * G_TYPE_NONE, 1,
- * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
- * ]|
+ * Cast a #GParamSpec instance into a #GParamSpecEnum.
*/
/**
- * G_TIME_SPAN_DAY:
- *
- * Evaluates to a time span of one day.
+ * G_PARAM_SPEC_FLAGS:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.26
+ * Cast a #GParamSpec instance into a #GParamSpecFlags.
*/
/**
- * G_TIME_SPAN_HOUR:
- *
- * Evaluates to a time span of one hour.
+ * G_PARAM_SPEC_FLOAT:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.26
+ * Cast a #GParamSpec instance into a #GParamSpecFloat.
*/
/**
- * G_TIME_SPAN_MILLISECOND:
- *
- * Evaluates to a time span of one millisecond.
+ * G_PARAM_SPEC_GET_CLASS:
+ * @pspec: a valid #GParamSpec
*
- * Since: 2.26
+ * Retrieves the #GParamSpecClass of a #GParamSpec.
*/
/**
- * G_TIME_SPAN_MINUTE:
+ * G_PARAM_SPEC_GTYPE:
+ * @pspec: a #GParamSpec
*
- * Evaluates to a time span of one minute.
+ * Casts a #GParamSpec into a #GParamSpecGType.
*
- * Since: 2.26
+ * Since: 2.10
*/
/**
- * G_TIME_SPAN_SECOND:
- *
- * Evaluates to a time span of one second.
+ * G_PARAM_SPEC_INT:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.26
+ * Cast a #GParamSpec instance into a #GParamSpecInt.
*/
/**
- * G_TLS_BACKEND_EXTENSION_POINT_NAME:
+ * G_PARAM_SPEC_INT64:
+ * @pspec: a valid #GParamSpec instance
*
- * Extension point for TLS functionality via #GTlsBackend.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * Cast a #GParamSpec instance into a #GParamSpecInt64.
*/
/**
- * G_TLS_ERROR:
+ * G_PARAM_SPEC_LONG:
+ * @pspec: a valid #GParamSpec instance
*
- * Error domain for TLS. Errors in this domain will be from the
- * #GTlsError enumeration. See #GError for more information on error
- * domains.
+ * Cast a #GParamSpec instance into a #GParamSpecLong.
*/
/**
- * G_TYPE_ARRAY:
- *
- * The #GType for a boxed type holding a #GArray reference.
+ * G_PARAM_SPEC_OBJECT:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.22
+ * Casts a #GParamSpec instance into a #GParamSpecObject.
*/
/**
- * G_TYPE_BOOLEAN:
+ * G_PARAM_SPEC_OVERRIDE:
+ * @pspec: a #GParamSpec
*
- * The fundamental type corresponding to #gboolean.
+ * Casts a #GParamSpec into a #GParamSpecOverride.
+ *
+ * Since: 2.4
*/
/**
- * G_TYPE_BOXED:
+ * G_PARAM_SPEC_PARAM:
+ * @pspec: a valid #GParamSpec instance
*
- * The fundamental type from which all boxed types are derived.
+ * Casts a #GParamSpec instance into a #GParamSpecParam.
*/
/**
- * G_TYPE_BYTE_ARRAY:
- *
- * The #GType for a boxed type holding a #GByteArray reference.
+ * G_PARAM_SPEC_POINTER:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.22
+ * Casts a #GParamSpec instance into a #GParamSpecPointer.
*/
/**
- * G_TYPE_CHAR:
+ * G_PARAM_SPEC_STRING:
+ * @pspec: a valid #GParamSpec instance
*
- * The fundamental type corresponding to #gchar.
- * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
- * This may or may not be the same type a the C type "gchar".
+ * Casts a #GParamSpec instance into a #GParamSpecString.
*/
/**
- * G_TYPE_CHECK_CLASS_CAST:
- * @g_class: Location of a #GTypeClass structure.
- * @g_type: The type to be returned.
- * @c_type: The corresponding C type of class structure of @g_type.
+ * G_PARAM_SPEC_TYPE:
+ * @pspec: a valid #GParamSpec
*
- * Checks that @g_class is a class structure of the type identified by @g_type
- * and issues a warning if this is not the case. Returns @g_class casted
- * to a pointer to @c_type.
- * This macro should only be used in type implementations.
+ * Retrieves the #GType of this @pspec.
*/
/**
- * G_TYPE_CHECK_CLASS_TYPE:
- * @g_class: Location of a #GTypeClass structure.
- * @g_type: The type to be checked.
- *
- * Checks if @g_class is a class structure of the type identified by
- * This macro should only be used in type implementations.
+ * G_PARAM_SPEC_TYPE_NAME:
+ * @pspec: a valid #GParamSpec
*
- * Returns: %TRUE on success.
+ * Retrieves the #GType name of this @pspec.
*/
/**
- * G_TYPE_CHECK_INSTANCE:
- * @instance: Location of a #GTypeInstance structure.
- *
- * Checks if @instance is a valid #GTypeInstance structure,
- * otherwise issues a warning and returns %FALSE.
- * This macro should only be used in type implementations.
+ * G_PARAM_SPEC_UCHAR:
+ * @pspec: a valid #GParamSpec instance
*
- * Returns: %TRUE on success.
+ * Cast a #GParamSpec instance into a #GParamSpecUChar.
*/
/**
- * G_TYPE_CHECK_INSTANCE_CAST:
- * @instance: Location of a #GTypeInstance structure.
- * @g_type: The type to be returned.
- * @c_type: The corresponding C type of @g_type.
+ * G_PARAM_SPEC_UINT:
+ * @pspec: a valid #GParamSpec instance
*
- * Checks that @instance is an instance of the type identified by @g_type
- * and issues a warning if this is not the case. Returns @instance casted
- * to a pointer to @c_type.
- * This macro should only be used in type implementations.
+ * Cast a #GParamSpec instance into a #GParamSpecUInt.
*/
/**
- * G_TYPE_CHECK_INSTANCE_TYPE:
- * @instance: Location of a #GTypeInstance structure.
- * @g_type: The type to be checked
- *
- * Checks if @instance is an instance of the type identified by @g_type.
- * This macro should only be used in type implementations.
+ * G_PARAM_SPEC_UINT64:
+ * @pspec: a valid #GParamSpec instance
*
- * Returns: %TRUE on success.
+ * Cast a #GParamSpec instance into a #GParamSpecUInt64.
*/
/**
- * G_TYPE_CHECK_VALUE:
- * @value: a #GValue
- *
- * Checks if @value has been initialized to hold values
- * of a value type.
- * This macro should only be used in type implementations.
+ * G_PARAM_SPEC_ULONG:
+ * @pspec: a valid #GParamSpec instance
*
- * Returns: %TRUE on success.
+ * Cast a #GParamSpec instance into a #GParamSpecULong.
*/
/**
- * G_TYPE_CHECK_VALUE_TYPE:
- * @value: a #GValue
- * @g_type: The type to be checked.
- *
- * Checks if @value has been initialized to hold values
- * of type @g_type.
- * This macro should only be used in type implementations.
+ * G_PARAM_SPEC_UNICHAR:
+ * @pspec: a valid #GParamSpec instance
*
- * Returns: %TRUE on success.
+ * Cast a #GParamSpec instance into a #GParamSpecUnichar.
*/
/**
- * G_TYPE_CLASS_GET_PRIVATE:
- * @klass: the class of a type deriving from @private_type.
- * @g_type: the type identifying which private data to retrieve.
- * @c_type: The C type for the private structure.
- *
- * Gets the private class structure for a particular type.
- * The private structure must have been registered in the
- * get_type() function with g_type_add_class_private().
- * This macro should only be used in type implementations.
+ * G_PARAM_SPEC_VALUE_ARRAY:
+ * @pspec: a valid #GParamSpec instance
*
- * Since: 2.24
- * Returns: a pointer to the private data structure.
+ * Cast a #GParamSpec instance into a #GParamSpecValueArray.
*/
/**
- * G_TYPE_CLOSURE:
+ * G_PARAM_SPEC_VALUE_TYPE:
+ * @pspec: a valid #GParamSpec
*
- * The #GType for #GClosure.
+ * Retrieves the #GType to initialize a #GValue for this parameter.
*/
/**
- * G_TYPE_DATE:
+ * G_PARAM_SPEC_VARIANT:
+ * @pspec: a #GParamSpec
*
- * The #GType for #GDate.
+ * Casts a #GParamSpec into a #GParamSpecVariant.
+ *
+ * Since: 2.26
*/
/**
- * G_TYPE_DATE_TIME:
- *
- * The #GType for a boxed type holding a #GDateTime.
+ * G_PARAM_STATIC_STRINGS:
*
- * Since: 2.26
+ * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+ * Since 2.13.0
*/
/**
- * G_TYPE_DBUS_ANNOTATION_INFO:
- *
- * The #GType for a boxed type holding a #GDBusAnnotationInfo.
+ * G_PARAM_USER_SHIFT:
*
- * Since: 2.26
+ * Minimum shift count to be used for user defined flags, to be stored in
+ * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT.
*/
/**
- * G_TYPE_DBUS_ARG_INFO:
- *
- * The #GType for a boxed type holding a #GDBusArgInfo.
+ * G_PRIORITY_DEFAULT:
*
- * Since: 2.26
+ * Use this for default priority event sources.
+ * In GLib this priority is used when adding timeout functions
+ * with g_timeout_add(). In GDK this priority is used for events
+ * from the X server.
*/
/**
- * G_TYPE_DBUS_INTERFACE_INFO:
- *
- * The #GType for a boxed type holding a #GDBusInterfaceInfo.
+ * G_PRIORITY_DEFAULT_IDLE:
*
- * Since: 2.26
+ * Use this for default priority idle functions.
+ * In GLib this priority is used when adding idle functions with
+ * g_idle_add().
*/
/**
- * G_TYPE_DBUS_METHOD_INFO:
- *
- * The #GType for a boxed type holding a #GDBusMethodInfo.
+ * G_PRIORITY_HIGH:
*
- * Since: 2.26
+ * Use this for high priority event sources.
+ * It is not used within GLib or GTK+.
*/
/**
- * G_TYPE_DBUS_NODE_INFO:
- *
- * The #GType for a boxed type holding a #GDBusNodeInfo.
+ * G_PRIORITY_HIGH_IDLE:
*
- * Since: 2.26
+ * Use this for high priority idle functions.
+ * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
+ * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
+ * done to ensure that any pending resizes are processed before any
+ * pending redraws, so that widgets are not redrawn twice unnecessarily.)
*/
/**
- * G_TYPE_DBUS_PROPERTY_INFO:
- *
- * The #GType for a boxed type holding a #GDBusPropertyInfo.
+ * G_PRIORITY_LOW:
*
- * Since: 2.26
+ * Use this for very low priority background tasks.
+ * It is not used within GLib or GTK+.
*/
/**
- * G_TYPE_DBUS_SIGNAL_INFO:
+ * G_PROXY_EXTENSION_POINT_NAME:
*
- * The #GType for a boxed type holding a #GDBusSignalInfo.
+ * Extension point for proxy functionality.
+ * See <link linkend="extending-gio">Extending GIO</link>.
*
* Since: 2.26
*/
/**
- * G_TYPE_DOUBLE:
+ * G_PROXY_RESOLVER_EXTENSION_POINT_NAME:
*
- * The fundamental type corresponding to #gdouble.
+ * Extension point for proxy resolving functionality.
+ * See <link linkend="extending-gio">Extending GIO</link>.
*/
/**
- * G_TYPE_ENUM:
+ * G_REGEX_ERROR:
*
- * The fundamental type from which all enumeration types are derived.
+ * Error domain for regular expressions. Errors in this domain will be
+ * from the #GRegexError enumeration. See #GError for information on
+ * error domains.
+ *
+ * Since: 2.14
*/
/**
- * G_TYPE_ERROR:
+ * G_RESOLVER_ERROR:
*
- * The #GType for a boxed type holding a #GError.
+ * Error domain for #GResolver. Errors in this domain will be from the
+ * #GResolverError enumeration. See #GError for more information on
+ * error domains.
+ */
+
+
+/**
+ * G_SETTINGS_BACKEND_EXTENSION_POINT_NAME:
*
- * Since: 2.26
+ * Extension point for #GSettingsBackend functionality.
*/
/**
- * G_TYPE_FLAGS:
+ * G_SIGNAL_FLAGS_MASK:
*
- * The fundamental type from which all flags types are derived.
+ * A mask for all #GSignalFlags bits.
*/
/**
- * G_TYPE_FLAG_RESERVED_ID_BIT:
+ * G_SIGNAL_MATCH_MASK:
*
- * A bit in the type number that's supposed to be left untouched.
+ * A mask for all #GSignalMatchType bits.
*/
/**
- * G_TYPE_FLOAT:
+ * G_SIGNAL_TYPE_STATIC_SCOPE:
*
- * The fundamental type corresponding to #gfloat.
+ * This macro flags signal argument types for which the signal system may
+ * assume that instances thereof remain persistent across all signal emissions
+ * they are used in. This is only useful for non ref-counted, value-copy types.
+ * To flag a signal argument in this way, add
+ * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
+ * of g_signal_new().
+ * |[
+ * g_signal_new ("size_request",
+ * G_TYPE_FROM_CLASS (gobject_class),
+ * G_SIGNAL_RUN_FIRST,
+ * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
+ * NULL, NULL,
+ * _gtk_marshal_VOID__BOXED,
+ * G_TYPE_NONE, 1,
+ * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+ * ]|
*/
/**
- * G_TYPE_FROM_CLASS:
- * @g_class: Location of a valid #GTypeClass structure.
+ * G_TIME_SPAN_DAY:
*
- * Get the type identifier from a given @class structure.
- * This macro should only be used in type implementations.
+ * Evaluates to a time span of one day.
*
- * Returns: the #GType
+ * Since: 2.26
*/
/**
- * G_TYPE_FROM_INSTANCE:
- * @instance: Location of a valid #GTypeInstance structure.
+ * G_TIME_SPAN_HOUR:
*
- * Get the type identifier from a given @instance structure.
- * This macro should only be used in type implementations.
+ * Evaluates to a time span of one hour.
*
- * Returns: the #GType
+ * Since: 2.26
*/
/**
- * G_TYPE_FROM_INTERFACE:
- * @g_iface: Location of a valid #GTypeInterface structure.
+ * G_TIME_SPAN_MILLISECOND:
*
- * Get the type identifier from a given @interface structure.
- * This macro should only be used in type implementations.
+ * Evaluates to a time span of one millisecond.
*
- * Returns: the #GType
+ * Since: 2.26
*/
/**
- * G_TYPE_FUNDAMENTAL:
- * @type: A #GType value.
+ * G_TIME_SPAN_MINUTE:
*
- * The fundamental type which is the ancestor of @type.
- * Fundamental types are types that serve as ultimate bases for the derived types,
- * thus they are the roots of distinct inheritance hierarchies.
+ * Evaluates to a time span of one minute.
+ *
+ * Since: 2.26
*/
/**
- * G_TYPE_FUNDAMENTAL_MAX:
+ * G_TIME_SPAN_SECOND:
*
- * An integer constant that represents the number of identifiers reserved
- * for types that are assigned at compile-time.
+ * Evaluates to a time span of one second.
+ *
+ * Since: 2.26
*/
/**
- * G_TYPE_FUNDAMENTAL_SHIFT:
+ * G_TLS_BACKEND_EXTENSION_POINT_NAME:
*
- * Shift value used in converting numbers to type IDs.
+ * Extension point for TLS functionality via #GTlsBackend.
+ * See <link linkend="extending-gio">Extending GIO</link>.
*/
/**
- * G_TYPE_GSTRING:
+ * G_TLS_ERROR:
*
- * The #GType for #GString.
+ * Error domain for TLS. Errors in this domain will be from the
+ * #GTlsError enumeration. See #GError for more information on error
+ * domains.
*/
/**
- * G_TYPE_GTYPE:
+ * G_TYPE_ARRAY:
*
- * The type for #GType.
+ * The #GType for a boxed type holding a #GArray reference.
+ *
+ * Since: 2.22
*/
/**
- * G_TYPE_HASH_TABLE:
+ * G_TYPE_BOOLEAN:
*
- * The #GType for a boxed type holding a #GHashTable reference.
+ * The fundamental type corresponding to #gboolean.
+ */
+
+
+/**
+ * G_TYPE_BOXED:
*
- * Since: 2.10
+ * The fundamental type from which all boxed types are derived.
*/
/**
- * G_TYPE_HAS_VALUE_TABLE:
- * @type: A #GType value.
+ * G_TYPE_BYTE_ARRAY:
*
- * Checks if @type has a #GTypeValueTable.
+ * The #GType for a boxed type holding a #GByteArray reference.
*
- * Returns: %TRUE on success.
+ * Since: 2.22
*/
/**
- * G_TYPE_INITIALLY_UNOWNED:
+ * G_TYPE_CHAR:
*
- * The type for #GInitiallyUnowned.
+ * The fundamental type corresponding to #gchar.
+ * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
+ * This may or may not be the same type a the C type "gchar".
*/
/**
- * G_TYPE_INSTANCE_GET_CLASS:
- * @instance: Location of the #GTypeInstance structure.
- * @g_type: The #GType of the class to be returned.
- * @c_type: The C type of the class structure.
+ * G_TYPE_CHECK_CLASS_CAST:
+ * @g_class: Location of a #GTypeClass structure.
+ * @g_type: The type to be returned.
+ * @c_type: The corresponding C type of class structure of @g_type.
*
- * Get the class structure of a given @instance, casted
- * to a specified ancestor type @g_type of the instance.
- * Note that while calling a GInstanceInitFunc(), the class pointer gets
- * modified, so it might not always return the expected pointer.
+ * Checks that @g_class is a class structure of the type identified by @g_type
+ * and issues a warning if this is not the case. Returns @g_class casted
+ * to a pointer to @c_type.
* This macro should only be used in type implementations.
- *
- * Returns: a pointer to the class structure
*/
/**
- * G_TYPE_INSTANCE_GET_INTERFACE:
- * @instance: Location of the #GTypeInstance structure.
- * @g_type: The #GType of the interface to be returned.
- * @c_type: The C type of the interface structure.
+ * G_TYPE_CHECK_CLASS_TYPE:
+ * @g_class: Location of a #GTypeClass structure.
+ * @g_type: The type to be checked.
*
- * Get the interface structure for interface @g_type of a given @instance.
+ * Checks if @g_class is a class structure of the type identified by
* This macro should only be used in type implementations.
*
- * Returns: a pointer to the interface structure
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_INSTANCE_GET_PRIVATE:
- * @instance: the instance of a type deriving from @private_type.
- * @g_type: the type identifying which private data to retrieve.
- * @c_type: The C type for the private structure.
+ * G_TYPE_CHECK_INSTANCE:
+ * @instance: Location of a #GTypeInstance structure.
*
- * Gets the private structure for a particular type.
- * The private structure must have been registered in the
- * class_init function with g_type_class_add_private().
+ * Checks if @instance is a valid #GTypeInstance structure,
+ * otherwise issues a warning and returns %FALSE.
* This macro should only be used in type implementations.
*
- * Since: 2.4
- * Returns: a pointer to the private data structure.
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_INT:
+ * G_TYPE_CHECK_INSTANCE_CAST:
+ * @instance: Location of a #GTypeInstance structure.
+ * @g_type: The type to be returned.
+ * @c_type: The corresponding C type of @g_type.
*
- * The fundamental type corresponding to #gint.
+ * Checks that @instance is an instance of the type identified by @g_type
+ * and issues a warning if this is not the case. Returns @instance casted
+ * to a pointer to @c_type.
+ * This macro should only be used in type implementations.
*/
/**
- * G_TYPE_INT64:
+ * G_TYPE_CHECK_INSTANCE_TYPE:
+ * @instance: Location of a #GTypeInstance structure.
+ * @g_type: The type to be checked
*
- * The fundamental type corresponding to #gint64.
+ * Checks if @instance is an instance of the type identified by @g_type.
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_INTERFACE:
+ * G_TYPE_CHECK_VALUE:
+ * @value: a #GValue
*
- * The fundamental type from which all interfaces are derived.
+ * Checks if @value has been initialized to hold values
+ * of a value type.
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_INVALID:
+ * G_TYPE_CHECK_VALUE_TYPE:
+ * @value: a #GValue
+ * @g_type: The type to be checked.
*
- * An invalid #GType used as error return value in some functions which return
- * a #GType.
+ * Checks if @value has been initialized to hold values
+ * of type @g_type.
+ * This macro should only be used in type implementations.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_IO_CHANNEL:
+ * G_TYPE_CLASS_GET_PRIVATE:
+ * @klass: the class of a type deriving from @private_type.
+ * @g_type: the type identifying which private data to retrieve.
+ * @c_type: The C type for the private structure.
*
- * The #GType for #GIOChannel.
+ * Gets the private class structure for a particular type.
+ * The private structure must have been registered in the
+ * get_type() function with g_type_add_class_private().
+ * This macro should only be used in type implementations.
+ *
+ * Since: 2.24
+ * Returns: a pointer to the private data structure.
*/
/**
- * G_TYPE_IO_CONDITION:
+ * G_TYPE_CLOSURE:
*
- * The #GType for #GIOCondition.
+ * The #GType for #GClosure.
*/
/**
- * G_TYPE_IS_ABSTRACT:
- * @type: A #GType value.
- *
- * Checks if @type is an abstract type. An abstract type cannot be
- * instantiated and is normally used as an abstract base class for
- * derived classes.
+ * G_TYPE_DATE:
*
- * Returns: %TRUE on success.
+ * The #GType for #GDate.
*/
/**
- * G_TYPE_IS_CLASSED:
- * @type: A #GType value.
+ * G_TYPE_DATE_TIME:
*
- * Checks if @type is a classed type.
+ * The #GType for a boxed type holding a #GDateTime.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_DEEP_DERIVABLE:
- * @type: A #GType value.
+ * G_TYPE_DBUS_ANNOTATION_INFO:
*
- * Checks if @type is a deep derivable type. A deep derivable type
- * can be used as the base class of a deep (multi-level) class hierarchy.
+ * The #GType for a boxed type holding a #GDBusAnnotationInfo.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_DERIVABLE:
- * @type: A #GType value.
+ * G_TYPE_DBUS_ARG_INFO:
*
- * Checks if @type is a derivable type. A derivable type can
- * be used as the base class of a flat (single-level) class hierarchy.
+ * The #GType for a boxed type holding a #GDBusArgInfo.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_DERIVED:
- * @type: A #GType value.
+ * G_TYPE_DBUS_INTERFACE_INFO:
*
- * Checks if @type is derived (or in object-oriented terminology:
- * inherited) from another type (this holds true for all non-fundamental
- * types).
+ * The #GType for a boxed type holding a #GDBusInterfaceInfo.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_ENUM:
- * @type: a #GType ID.
+ * G_TYPE_DBUS_METHOD_INFO:
*
- * Checks whether @type "is a" %G_TYPE_ENUM.
+ * The #GType for a boxed type holding a #GDBusMethodInfo.
*
- * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_FLAGS:
- * @type: a #GType ID.
+ * G_TYPE_DBUS_NODE_INFO:
*
- * Checks whether @type "is a" %G_TYPE_FLAGS.
+ * The #GType for a boxed type holding a #GDBusNodeInfo.
*
- * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_FUNDAMENTAL:
- * @type: A #GType value.
+ * G_TYPE_DBUS_PROPERTY_INFO:
*
- * Checks if @type is a fundamental type.
+ * The #GType for a boxed type holding a #GDBusPropertyInfo.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_INSTANTIATABLE:
- * @type: A #GType value.
+ * G_TYPE_DBUS_SIGNAL_INFO:
*
- * Checks if @type can be instantiated. Instantiation is the
- * process of creating an instance (object) of this type.
+ * The #GType for a boxed type holding a #GDBusSignalInfo.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_INTERFACE:
- * @type: A #GType value.
+ * G_TYPE_DOUBLE:
*
- * Checks if @type is an interface type.
- * An interface type provides a pure API, the implementation
- * of which is provided by another type (which is then said to conform
- * to the interface). GLib interfaces are somewhat analogous to Java
- * interfaces and C++ classes containing only pure virtual functions,
- * with the difference that GType interfaces are not derivable (but see
- * g_type_interface_add_prerequisite() for an alternative).
+ * The fundamental type corresponding to #gdouble.
+ */
+
+
+/**
+ * G_TYPE_ENUM:
*
- * Returns: %TRUE on success.
+ * The fundamental type from which all enumeration types are derived.
*/
/**
- * G_TYPE_IS_OBJECT:
- * @type: Type id to check
+ * G_TYPE_ERROR:
*
- * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.
+ * The #GType for a boxed type holding a #GError.
*
- * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
+ * Since: 2.26
*/
/**
- * G_TYPE_IS_PARAM:
- * @type: a #GType ID
+ * G_TYPE_FLAGS:
*
- * Checks whether @type "is a" %G_TYPE_PARAM.
+ * The fundamental type from which all flags types are derived.
*/
/**
- * G_TYPE_IS_VALUE:
- * @type: A #GType value.
+ * G_TYPE_FLAG_RESERVED_ID_BIT:
*
- * Checks whether the passed in type ID can be used for g_value_init().
- * That is, this macro checks whether this type provides an implementation
- * of the #GTypeValueTable functions required for a type to create a #GValue of.
- *
- * Returns: Whether @type is suitable as a #GValue type.
+ * A bit in the type number that's supposed to be left untouched.
*/
/**
- * G_TYPE_IS_VALUE_ABSTRACT:
- * @type: A #GType value.
- *
- * Checks if @type is an abstract value type. An abstract value type introduces
- * a value table, but can't be used for g_value_init() and is normally used as
- * an abstract base type for derived value types.
+ * G_TYPE_FLOAT:
*
- * Returns: %TRUE on success.
+ * The fundamental type corresponding to #gfloat.
*/
/**
- * G_TYPE_IS_VALUE_TYPE:
- * @type: A #GType value.
+ * G_TYPE_FROM_CLASS:
+ * @g_class: Location of a valid #GTypeClass structure.
*
- * Checks if @type is a value type and can be used with g_value_init().
+ * Get the type identifier from a given @class structure.
+ * This macro should only be used in type implementations.
*
- * Returns: %TRUE on success.
+ * Returns: the #GType
*/
/**
- * G_TYPE_LONG:
+ * G_TYPE_FROM_INSTANCE:
+ * @instance: Location of a valid #GTypeInstance structure.
*
- * The fundamental type corresponding to #glong.
+ * Get the type identifier from a given @instance structure.
+ * This macro should only be used in type implementations.
+ *
+ * Returns: the #GType
*/
/**
- * G_TYPE_MAKE_FUNDAMENTAL:
- * @x: the fundamental type number.
+ * G_TYPE_FROM_INTERFACE:
+ * @g_iface: Location of a valid #GTypeInterface structure.
*
- * Get the type ID for the fundamental type number @x.
- * Use g_type_fundamental_next() instead of this macro to create new fundamental
- * types.
+ * Get the type identifier from a given @interface structure.
+ * This macro should only be used in type implementations.
*
- * Returns: the GType
+ * Returns: the #GType
*/
/**
- * G_TYPE_NONE:
+ * G_TYPE_FUNDAMENTAL:
+ * @type: A #GType value.
*
- * A fundamental type which is used as a replacement for the C
- * <literal>void</literal> return type.
+ * The fundamental type which is the ancestor of @type.
+ * Fundamental types are types that serve as ultimate bases for the derived types,
+ * thus they are the roots of distinct inheritance hierarchies.
*/
/**
- * G_TYPE_OBJECT:
+ * G_TYPE_FUNDAMENTAL_MAX:
*
- * The fundamental type for #GObject.
+ * An integer constant that represents the number of identifiers reserved
+ * for types that are assigned at compile-time.
*/
/**
- * G_TYPE_PARAM:
+ * G_TYPE_FUNDAMENTAL_SHIFT:
*
- * The fundamental type from which all #GParamSpec types are derived.
+ * Shift value used in converting numbers to type IDs.
*/
/**
- * G_TYPE_PARAM_BOOLEAN:
+ * G_TYPE_GSTRING:
*
- * The #GType of #GParamSpecBoolean.
+ * The #GType for #GString.
*/
/**
- * G_TYPE_PARAM_BOXED:
+ * G_TYPE_GTYPE:
*
- * The #GType of #GParamSpecBoxed.
+ * The type for #GType.
*/
/**
- * G_TYPE_PARAM_CHAR:
+ * G_TYPE_HASH_TABLE:
*
- * The #GType of #GParamSpecChar.
+ * The #GType for a boxed type holding a #GHashTable reference.
+ *
+ * Since: 2.10
*/
/**
- * G_TYPE_PARAM_DOUBLE:
+ * G_TYPE_HAS_VALUE_TABLE:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecDouble.
+ * Checks if @type has a #GTypeValueTable.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_ENUM:
+ * G_TYPE_INITIALLY_UNOWNED:
*
- * The #GType of #GParamSpecEnum.
+ * The type for #GInitiallyUnowned.
*/
/**
- * G_TYPE_PARAM_FLAGS:
+ * G_TYPE_INSTANCE_GET_CLASS:
+ * @instance: Location of the #GTypeInstance structure.
+ * @g_type: The #GType of the class to be returned.
+ * @c_type: The C type of the class structure.
*
- * The #GType of #GParamSpecFlags.
+ * Get the class structure of a given @instance, casted
+ * to a specified ancestor type @g_type of the instance.
+ * Note that while calling a GInstanceInitFunc(), the class pointer gets
+ * modified, so it might not always return the expected pointer.
+ * This macro should only be used in type implementations.
+ *
+ * Returns: a pointer to the class structure
*/
/**
- * G_TYPE_PARAM_FLOAT:
+ * G_TYPE_INSTANCE_GET_INTERFACE:
+ * @instance: Location of the #GTypeInstance structure.
+ * @g_type: The #GType of the interface to be returned.
+ * @c_type: The C type of the interface structure.
*
- * The #GType of #GParamSpecFloat.
+ * Get the interface structure for interface @g_type of a given @instance.
+ * This macro should only be used in type implementations.
+ *
+ * Returns: a pointer to the interface structure
*/
/**
- * G_TYPE_PARAM_GTYPE:
+ * G_TYPE_INSTANCE_GET_PRIVATE:
+ * @instance: the instance of a type deriving from @private_type.
+ * @g_type: the type identifying which private data to retrieve.
+ * @c_type: The C type for the private structure.
*
- * The #GType of #GParamSpecGType.
+ * Gets the private structure for a particular type.
+ * The private structure must have been registered in the
+ * class_init function with g_type_class_add_private().
+ * This macro should only be used in type implementations.
*
- * Since: 2.10
+ * Since: 2.4
+ * Returns: a pointer to the private data structure.
*/
/**
- * G_TYPE_PARAM_INT:
+ * G_TYPE_INT:
*
- * The #GType of #GParamSpecInt.
+ * The fundamental type corresponding to #gint.
*/
/**
- * G_TYPE_PARAM_INT64:
+ * G_TYPE_INT64:
*
- * The #GType of #GParamSpecInt64.
+ * The fundamental type corresponding to #gint64.
*/
/**
- * G_TYPE_PARAM_LONG:
+ * G_TYPE_INTERFACE:
*
- * The #GType of #GParamSpecLong.
+ * The fundamental type from which all interfaces are derived.
*/
/**
- * G_TYPE_PARAM_OBJECT:
+ * G_TYPE_INVALID:
*
- * The #GType of #GParamSpecObject.
+ * An invalid #GType used as error return value in some functions which return
+ * a #GType.
*/
/**
- * G_TYPE_PARAM_OVERRIDE:
- *
- * The #GType of #GParamSpecOverride.
+ * G_TYPE_IO_CHANNEL:
*
- * Since: 2.4
+ * The #GType for #GIOChannel.
*/
/**
- * G_TYPE_PARAM_PARAM:
+ * G_TYPE_IO_CONDITION:
*
- * The #GType of #GParamSpecParam.
+ * The #GType for #GIOCondition.
*/
/**
- * G_TYPE_PARAM_POINTER:
+ * G_TYPE_IS_ABSTRACT:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecPointer.
+ * Checks if @type is an abstract type. An abstract type cannot be
+ * instantiated and is normally used as an abstract base class for
+ * derived classes.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_STRING:
+ * G_TYPE_IS_CLASSED:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecString.
+ * Checks if @type is a classed type.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_UCHAR:
+ * G_TYPE_IS_DEEP_DERIVABLE:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecUChar.
+ * Checks if @type is a deep derivable type. A deep derivable type
+ * can be used as the base class of a deep (multi-level) class hierarchy.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_UINT:
+ * G_TYPE_IS_DERIVABLE:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecUInt.
+ * Checks if @type is a derivable type. A derivable type can
+ * be used as the base class of a flat (single-level) class hierarchy.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_UINT64:
+ * G_TYPE_IS_DERIVED:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecUInt64.
+ * Checks if @type is derived (or in object-oriented terminology:
+ * inherited) from another type (this holds true for all non-fundamental
+ * types).
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_ULONG:
+ * G_TYPE_IS_ENUM:
+ * @type: a #GType ID.
*
- * The #GType of #GParamSpecULong.
+ * Checks whether @type "is a" %G_TYPE_ENUM.
+ *
+ * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.
*/
/**
- * G_TYPE_PARAM_UNICHAR:
+ * G_TYPE_IS_FLAGS:
+ * @type: a #GType ID.
*
- * The #GType of #GParamSpecUnichar.
+ * Checks whether @type "is a" %G_TYPE_FLAGS.
+ *
+ * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.
*/
/**
- * G_TYPE_PARAM_VALUE_ARRAY:
+ * G_TYPE_IS_FUNDAMENTAL:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecValueArray.
+ * Checks if @type is a fundamental type.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PARAM_VARIANT:
+ * G_TYPE_IS_INSTANTIATABLE:
+ * @type: A #GType value.
*
- * The #GType of #GParamSpecVariant.
+ * Checks if @type can be instantiated. Instantiation is the
+ * process of creating an instance (object) of this type.
*
- * Since: 2.26
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_POINTER:
+ * G_TYPE_IS_INTERFACE:
+ * @type: A #GType value.
*
- * The fundamental type corresponding to #gpointer.
+ * Checks if @type is an interface type.
+ * An interface type provides a pure API, the implementation
+ * of which is provided by another type (which is then said to conform
+ * to the interface). GLib interfaces are somewhat analogous to Java
+ * interfaces and C++ classes containing only pure virtual functions,
+ * with the difference that GType interfaces are not derivable (but see
+ * g_type_interface_add_prerequisite() for an alternative).
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_PTR_ARRAY:
+ * G_TYPE_IS_OBJECT:
+ * @type: Type id to check
*
- * The #GType for a boxed type holding a #GPtrArray reference.
+ * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.
*
- * Since: 2.22
+ * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
*/
/**
- * G_TYPE_REGEX:
- *
- * The #GType for a boxed type holding a #GRegex reference.
+ * G_TYPE_IS_PARAM:
+ * @type: a #GType ID
*
- * Since: 2.14
+ * Checks whether @type "is a" %G_TYPE_PARAM.
*/
/**
- * G_TYPE_RESERVED_BSE_FIRST:
+ * G_TYPE_IS_VALUE:
+ * @type: A #GType value.
*
- * First fundamental type number to create a new fundamental type id with
- * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
+ * Checks whether the passed in type ID can be used for g_value_init().
+ * That is, this macro checks whether this type provides an implementation
+ * of the #GTypeValueTable functions required for a type to create a #GValue of.
+ *
+ * Returns: Whether @type is suitable as a #GValue type.
*/
/**
- * G_TYPE_RESERVED_BSE_LAST:
+ * G_TYPE_IS_VALUE_ABSTRACT:
+ * @type: A #GType value.
*
- * Last fundamental type number reserved for BSE.
+ * Checks if @type is an abstract value type. An abstract value type introduces
+ * a value table, but can't be used for g_value_init() and is normally used as
+ * an abstract base type for derived value types.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_RESERVED_GLIB_FIRST:
+ * G_TYPE_IS_VALUE_TYPE:
+ * @type: A #GType value.
*
- * First fundamental type number to create a new fundamental type id with
- * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
+ * Checks if @type is a value type and can be used with g_value_init().
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_TYPE_RESERVED_GLIB_LAST:
+ * G_TYPE_LONG:
*
- * Last fundamental type number reserved for GLib.
+ * The fundamental type corresponding to #glong.
*/
/**
- * G_TYPE_RESERVED_USER_FIRST:
+ * G_TYPE_MAKE_FUNDAMENTAL:
+ * @x: the fundamental type number.
*
- * First available fundamental type number to create new fundamental
- * type id with G_TYPE_MAKE_FUNDAMENTAL().
+ * Get the type ID for the fundamental type number @x.
+ * Use g_type_fundamental_next() instead of this macro to create new fundamental
+ * types.
+ *
+ * Returns: the GType
*/
/**
- * G_TYPE_STRING:
+ * G_TYPE_NONE:
*
- * The fundamental type corresponding to nul-terminated C strings.
+ * A fundamental type which is used as a replacement for the C
+ * <literal>void</literal> return type.
*/
/**
- * G_TYPE_STRV:
- *
- * The #GType for a boxed type holding a %NULL-terminated array of strings.
- * The code fragments in the following example show the use of a property of
- * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
- * and g_object_get().
- * |[
- * g_object_class_install_property (object_class,
- * PROP_AUTHORS,
- * g_param_spec_boxed ("authors",
- * _("Authors"),
- * _("List of authors"),
- * G_TYPE_STRV,
- * G_PARAM_READWRITE));
- * gchar *authors[] = { "Owen", "Tim", NULL };
- * g_object_set (obj, "authors", authors, NULL);
- * gchar *writers[];
- * g_object_get (obj, "authors", &writers, NULL);
- * /* do something with writers */
- * g_strfreev (writers);
- * ]|
+ * G_TYPE_OBJECT:
*
- * Since: 2.4
+ * The fundamental type for #GObject.
*/
/**
- * G_TYPE_UCHAR:
+ * G_TYPE_PARAM:
*
- * The fundamental type corresponding to #guchar.
+ * The fundamental type from which all #GParamSpec types are derived.
*/
/**
- * G_TYPE_UINT:
+ * G_TYPE_PARAM_BOOLEAN:
*
- * The fundamental type corresponding to #guint.
+ * The #GType of #GParamSpecBoolean.
*/
/**
- * G_TYPE_UINT64:
+ * G_TYPE_PARAM_BOXED:
*
- * The fundamental type corresponding to #guint64.
+ * The #GType of #GParamSpecBoxed.
*/
/**
- * G_TYPE_ULONG:
+ * G_TYPE_PARAM_CHAR:
*
- * The fundamental type corresponding to #gulong.
+ * The #GType of #GParamSpecChar.
*/
/**
- * G_TYPE_VALUE:
+ * G_TYPE_PARAM_DOUBLE:
*
- * The type ID of the "GValue" type which is a boxed type,
- * used to pass around pointers to GValues.
+ * The #GType of #GParamSpecDouble.
*/
/**
- * G_TYPE_VALUE_ARRAY:
+ * G_TYPE_PARAM_ENUM:
*
- * The type ID of the "GValueArray" type which is a boxed type,
- * used to pass around pointers to GValueArrays.
+ * The #GType of #GParamSpecEnum.
*/
/**
- * G_TYPE_VARIANT:
- *
- * The fundamental type corresponding to #GVariant.
- * All floating #GVariant instances passed through the #GType system are
- * consumed.
- * Note that callbacks in closures, and signal handlers
- * for signals of return type %G_TYPE_VARIANT, must never return floating
- * variants.
- * with this fundamental type in 2.26.
+ * G_TYPE_PARAM_FLAGS:
*
- * Note: GLib 2.24 did include a boxed type with this name. It was replaced
- * Since: 2.26
+ * The #GType of #GParamSpecFlags.
*/
/**
- * G_TYPE_VARIANT_TYPE:
- *
- * The #GType for a boxed type holding a #GVariantType.
+ * G_TYPE_PARAM_FLOAT:
*
- * Since: 2.24
+ * The #GType of #GParamSpecFloat.
*/
/**
- * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
+ * G_TYPE_PARAM_GTYPE:
*
- * Allowed characters in a path. Includes "!$&'()*+,;=:@/".
+ * The #GType of #GParamSpecGType.
+ *
+ * Since: 2.10
*/
/**
- * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
+ * G_TYPE_PARAM_INT:
*
- * Allowed characters in path elements. Includes "!$&'()*+,;=:@".
+ * The #GType of #GParamSpecInt.
*/
/**
- * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
+ * G_TYPE_PARAM_INT64:
*
- * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:".
+ * The #GType of #GParamSpecInt64.
*/
/**
- * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
+ * G_TYPE_PARAM_LONG:
*
- * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@".
+ * The #GType of #GParamSpecLong.
*/
/**
- * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
+ * G_TYPE_PARAM_OBJECT:
*
- * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=".
+ * The #GType of #GParamSpecObject.
*/
/**
- * G_VALUE_HOLDS:
- * @value: A #GValue structure.
- * @type: A #GType value.
+ * G_TYPE_PARAM_OVERRIDE:
*
- * Checks if @value holds (or contains) a value of @type.
- * This macro will also check for @value != %NULL and issue a
- * warning if the check fails.
+ * The #GType of #GParamSpecOverride.
*
- * Returns: %TRUE if @value holds the @type.
+ * Since: 2.4
*/
/**
- * G_VALUE_HOLDS_BOOLEAN:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.
+ * G_TYPE_PARAM_PARAM:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecParam.
*/
/**
- * G_VALUE_HOLDS_BOXED:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values derived
- * from type %G_TYPE_BOXED.
+ * G_TYPE_PARAM_POINTER:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecPointer.
*/
/**
- * G_VALUE_HOLDS_CHAR:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.
+ * G_TYPE_PARAM_STRING:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecString.
*/
/**
- * G_VALUE_HOLDS_DOUBLE:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.
+ * G_TYPE_PARAM_UCHAR:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecUChar.
*/
/**
- * G_VALUE_HOLDS_ENUM:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
+ * G_TYPE_PARAM_UINT:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecUInt.
*/
/**
- * G_VALUE_HOLDS_FLAGS:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
+ * G_TYPE_PARAM_UINT64:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecUInt64.
*/
/**
- * G_VALUE_HOLDS_FLOAT:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.
+ * G_TYPE_PARAM_ULONG:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecULong.
*/
/**
- * G_VALUE_HOLDS_GTYPE:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.
+ * G_TYPE_PARAM_UNICHAR:
*
- * Since: 2.12
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecUnichar.
*/
/**
- * G_VALUE_HOLDS_INT:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_INT.
+ * G_TYPE_PARAM_VALUE_ARRAY:
*
- * Returns: %TRUE on success.
+ * The #GType of #GParamSpecValueArray.
*/
/**
- * G_VALUE_HOLDS_INT64:
- * @value: a valid #GValue structure
+ * G_TYPE_PARAM_VARIANT:
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_INT64.
+ * The #GType of #GParamSpecVariant.
*
- * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_VALUE_HOLDS_LONG:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_LONG.
+ * G_TYPE_POINTER:
*
- * Returns: %TRUE on success.
+ * The fundamental type corresponding to #gpointer.
*/
/**
- * G_VALUE_HOLDS_OBJECT:
- * @value: a valid #GValue structure
+ * G_TYPE_PTR_ARRAY:
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
+ * The #GType for a boxed type holding a #GPtrArray reference.
*
- * Returns: %TRUE on success.
+ * Since: 2.22
*/
/**
- * G_VALUE_HOLDS_PARAM:
- * @value: a valid #GValue structure
+ * G_TYPE_REGEX:
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
+ * The #GType for a boxed type holding a #GRegex reference.
*
- * Returns: %TRUE on success.
+ * Since: 2.14
*/
/**
- * G_VALUE_HOLDS_POINTER:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.
+ * G_TYPE_RESERVED_BSE_FIRST:
*
- * Returns: %TRUE on success.
+ * First fundamental type number to create a new fundamental type id with
+ * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
*/
/**
- * G_VALUE_HOLDS_STRING:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_STRING.
+ * G_TYPE_RESERVED_BSE_LAST:
*
- * Returns: %TRUE on success.
+ * Last fundamental type number reserved for BSE.
*/
/**
- * G_VALUE_HOLDS_UCHAR:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.
+ * G_TYPE_RESERVED_GLIB_FIRST:
*
- * Returns: %TRUE on success.
+ * First fundamental type number to create a new fundamental type id with
+ * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
*/
/**
- * G_VALUE_HOLDS_UINT:
- * @value: a valid #GValue structure
+ * G_TYPE_RESERVED_GLIB_LAST:
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_UINT.
- *
- * Returns: %TRUE on success.
+ * Last fundamental type number reserved for GLib.
*/
/**
- * G_VALUE_HOLDS_UINT64:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.
+ * G_TYPE_RESERVED_USER_FIRST:
*
- * Returns: %TRUE on success.
+ * First available fundamental type number to create new fundamental
+ * type id with G_TYPE_MAKE_FUNDAMENTAL().
*/
/**
- * G_VALUE_HOLDS_ULONG:
- * @value: a valid #GValue structure
- *
- * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.
+ * G_TYPE_STRING:
*
- * Returns: %TRUE on success.
+ * The fundamental type corresponding to nul-terminated C strings.
*/
/**
- * G_VALUE_HOLDS_VARIANT:
- * @value: a valid #GValue structure
+ * G_TYPE_STRV:
*
- * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT.
+ * The #GType for a boxed type holding a %NULL-terminated array of strings.
+ * The code fragments in the following example show the use of a property of
+ * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
+ * and g_object_get().
+ * |[
+ * g_object_class_install_property (object_class,
+ * PROP_AUTHORS,
+ * g_param_spec_boxed ("authors",
+ * _("Authors"),
+ * _("List of authors"),
+ * G_TYPE_STRV,
+ * G_PARAM_READWRITE));
+ * gchar *authors[] = { "Owen", "Tim", NULL };
+ * g_object_set (obj, "authors", authors, NULL);
+ * gchar *writers[];
+ * g_object_get (obj, "authors", &writers, NULL);
+ * /* do something with writers */
+ * g_strfreev (writers);
+ * ]|
*
- * Returns: %TRUE on success.
- * Since: 2.26
+ * Since: 2.4
*/
/**
- * G_VALUE_NOCOPY_CONTENTS:
+ * G_TYPE_UCHAR:
*
- * If passed to G_VALUE_COLLECT(), allocated data won't be copied
- * but used verbatim. This does not affect ref-counted types like
- * objects. For more details, see the #GValueTable documentation.
+ * The fundamental type corresponding to #guchar.
*/
/**
- * G_VALUE_TYPE:
- * @value: A #GValue structure.
- *
- * Get the type identifier of @value.
+ * G_TYPE_UINT:
*
- * Returns: the #GType.
+ * The fundamental type corresponding to #guint.
*/
/**
- * G_VALUE_TYPE_NAME:
- * @value: A #GValue structure.
- *
- * Gets the the type name of @value.
+ * G_TYPE_UINT64:
*
- * Returns: the type name.
+ * The fundamental type corresponding to #guint64.
*/
/**
- * G_VARIANT_TYPE:
- * @type_string: a well-formed #GVariantType type string
+ * G_TYPE_ULONG:
*
- * Converts a string to a const #GVariantType. Depending on the
- * current debugging level, this function may perform a runtime check
- * to ensure that @string is a valid GVariant type string.
- * It is always a programmer error to use this macro with an invalid
- * type string.
- * Since 2.24
+ * The fundamental type corresponding to #gulong.
*/
/**
- * G_VARIANT_TYPE_ANY:
+ * G_TYPE_VALUE:
*
- * An indefinite type that is a supertype of every type (including
- * itself).
+ * The type ID of the "GValue" type which is a boxed type,
+ * used to pass around pointers to GValues.
*/
/**
- * G_VARIANT_TYPE_ARRAY:
+ * G_TYPE_VALUE_ARRAY:
*
- * An indefinite type that is a supertype of every array type.
+ * The type ID of the "GValueArray" type which is a boxed type,
+ * used to pass around pointers to GValueArrays.
*/
/**
- * G_VARIANT_TYPE_BASIC:
+ * G_TYPE_VARIANT:
*
- * An indefinite type that is a supertype of every basic (ie:
- * non-container) type.
+ * The fundamental type corresponding to #GVariant.
+ * All floating #GVariant instances passed through the #GType system are
+ * consumed.
+ * Note that callbacks in closures, and signal handlers
+ * for signals of return type %G_TYPE_VARIANT, must never return floating
+ * variants.
+ * with this fundamental type in 2.26.
+ *
+ * Note: GLib 2.24 did include a boxed type with this name. It was replaced
+ * Since: 2.26
*/
/**
- * G_VARIANT_TYPE_BOOLEAN:
+ * G_TYPE_VARIANT_BUILDER:
*
- * The type of a value that can be either %TRUE or %FALSE.
+ * The #GType for a boxed type holding a #GVariantBuilder.
+ *
+ * Since: 2.30
*/
/**
- * G_VARIANT_TYPE_BYTE:
+ * G_TYPE_VARIANT_TYPE:
*
- * The type of an integer value that can range from 0 to 255.
+ * The #GType for a boxed type holding a #GVariantType.
+ *
+ * Since: 2.24
*/
/**
- * G_VARIANT_TYPE_BYTESTRING:
+ * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
*
- * The type of an array of bytes. This type is commonly used to pass
- * around strings that may not be valid utf8. In that case, the
- * convention is that the nul terminator character should be included as
- * the last character in the array.
+ * Allowed characters in a path. Includes "!$&'()*+,;=:@/".
*/
/**
- * G_VARIANT_TYPE_BYTESTRING_ARRAY:
+ * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
*
- * The type of an array of byte strings (an array of arrays of bytes).
+ * Allowed characters in path elements. Includes "!$&'()*+,;=:@".
*/
/**
- * G_VARIANT_TYPE_DICTIONARY:
+ * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
*
- * An indefinite type that is a supertype of every dictionary type --
- * that is, any array type that has an element type equal to any
- * dictionary entry type.
+ * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:".
*/
/**
- * G_VARIANT_TYPE_DICT_ENTRY:
+ * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
*
- * An indefinite type that is a supertype of every dictionary entry
- * type.
+ * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@".
*/
/**
- * G_VARIANT_TYPE_DOUBLE:
+ * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
*
- * The type of a double precision IEEE754 floating point number.
- * These guys go up to about 1.80e308 (plus and minus) but miss out on
- * some numbers in between. In any case, that's far greater than the
- * estimated number of fundamental particles in the observable
- * universe.
+ * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=".
*/
/**
- * G_VARIANT_TYPE_HANDLE:
+ * G_VALUE_HOLDS:
+ * @value: A #GValue structure.
+ * @type: A #GType value.
*
- * The type of a 32bit signed integer value, that by convention, is used
- * as an index into an array of file descriptors that are sent alongside
- * a DBus message.
- * If you are not interacting with DBus, then there is no reason to make
- * use of this type.
+ * Checks if @value holds (or contains) a value of @type.
+ * This macro will also check for @value != %NULL and issue a
+ * warning if the check fails.
+ *
+ * Returns: %TRUE if @value holds the @type.
*/
/**
- * G_VARIANT_TYPE_INT16:
+ * G_VALUE_HOLDS_BOOLEAN:
+ * @value: a valid #GValue structure
*
- * The type of an integer value that can range from -32768 to 32767.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_INT32:
+ * G_VALUE_HOLDS_BOXED:
+ * @value: a valid #GValue structure
*
- * The type of an integer value that can range from -2147483648 to
- * 2147483647.
+ * Checks whether the given #GValue can hold values derived
+ * from type %G_TYPE_BOXED.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_INT64:
+ * G_VALUE_HOLDS_CHAR:
+ * @value: a valid #GValue structure
*
- * The type of an integer value that can range from
- * -9223372036854775808 to 9223372036854775807.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_MAYBE:
+ * G_VALUE_HOLDS_DOUBLE:
+ * @value: a valid #GValue structure
*
- * An indefinite type that is a supertype of every maybe type.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_OBJECT_PATH:
+ * G_VALUE_HOLDS_ENUM:
+ * @value: a valid #GValue structure
*
- * The type of a DBus object reference. These are strings of a
- * specific format used to identify objects at a given destination on
- * the bus.
- * If you are not interacting with DBus, then there is no reason to make
- * use of this type. If you are, then the DBus specification contains a
- * precise description of valid object paths.
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_SIGNATURE:
+ * G_VALUE_HOLDS_FLAGS:
+ * @value: a valid #GValue structure
*
- * The type of a DBus type signature. These are strings of a specific
- * format used as type signatures for DBus methods and messages.
- * If you are not interacting with DBus, then there is no reason to make
- * use of this type. If you are, then the DBus specification contains a
- * precise description of valid signature strings.
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_STRING:
+ * G_VALUE_HOLDS_FLOAT:
+ * @value: a valid #GValue structure
*
- * The type of a string. "" is a string. %NULL is not a string.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_STRING_ARRAY:
+ * G_VALUE_HOLDS_GTYPE:
+ * @value: a valid #GValue structure
*
- * The type of an array of strings.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.
+ *
+ * Since: 2.12
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_TUPLE:
+ * G_VALUE_HOLDS_INT:
+ * @value: a valid #GValue structure
*
- * An indefinite type that is a supertype of every tuple type,
- * regardless of the number of items in the tuple.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_INT.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_UINT16:
+ * G_VALUE_HOLDS_INT64:
+ * @value: a valid #GValue structure
*
- * The type of an integer value that can range from 0 to 65535.
- * There were about this many people living in Toronto in the 1870s.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_INT64.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_UINT32:
+ * G_VALUE_HOLDS_LONG:
+ * @value: a valid #GValue structure
*
- * The type of an integer value that can range from 0 to 4294967295.
- * That's one number for everyone who was around in the late 1970s.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_LONG.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_UINT64:
+ * G_VALUE_HOLDS_OBJECT:
+ * @value: a valid #GValue structure
*
- * The type of an integer value that can range from 0 to
- * 18446744073709551616. That's a really big number, but a Rubik's
- * cube can have a bit more than twice as many possible positions.
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_UNIT:
+ * G_VALUE_HOLDS_PARAM:
+ * @value: a valid #GValue structure
*
- * The empty tuple type. Has only one instance. Known also as "triv"
- * or "void".
+ * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_VARDICT:
- *
- * The type of a dictionary mapping strings to variants (the ubiquitous
- * "a{sv}" type).
+ * G_VALUE_HOLDS_POINTER:
+ * @value: a valid #GValue structure
+ *
+ * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VARIANT_TYPE_VARIANT:
+ * G_VALUE_HOLDS_STRING:
+ * @value: a valid #GValue structure
*
- * The type of a box that contains any other value (including another
- * variant).
+ * Checks whether the given #GValue can hold values of type %G_TYPE_STRING.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VFS_EXTENSION_POINT_NAME:
+ * G_VALUE_HOLDS_UCHAR:
+ * @value: a valid #GValue structure
*
- * Extension point for #GVfs functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
+ * G_VALUE_HOLDS_UINT:
+ * @value: a valid #GValue structure
*
- * The string used to obtain a Hal UDI with g_volume_get_identifier().
+ * Checks whether the given #GValue can hold values of type %G_TYPE_UINT.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_LABEL:
+ * G_VALUE_HOLDS_UINT64:
+ * @value: a valid #GValue structure
*
- * The string used to obtain a filesystem label with g_volume_get_identifier().
+ * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
+ * G_VALUE_HOLDS_ULONG:
+ * @value: a valid #GValue structure
*
- * The string used to obtain a NFS mount with g_volume_get_identifier().
+ * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.
+ *
+ * Returns: %TRUE on success.
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
+ * G_VALUE_HOLDS_VARIANT:
+ * @value: a valid #GValue structure
*
- * The string used to obtain a Unix device path with g_volume_get_identifier().
+ * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT.
+ *
+ * Returns: %TRUE on success.
+ * Since: 2.26
*/
/**
- * G_VOLUME_IDENTIFIER_KIND_UUID:
+ * G_VALUE_NOCOPY_CONTENTS:
*
- * The string used to obtain a UUID with g_volume_get_identifier().
+ * If passed to G_VALUE_COLLECT(), allocated data won't be copied
+ * but used verbatim. This does not affect ref-counted types like
+ * objects. For more details, see the #GValueTable documentation.
*/
/**
- * G_VOLUME_MONITOR_EXTENSION_POINT_NAME:
+ * G_VALUE_TYPE:
+ * @value: A #GValue structure.
*
- * Extension point for volume monitor functionality.
- * See <link linkend="extending-gio">Extending GIO</link>.
+ * Get the type identifier of @value.
+ *
+ * Returns: the #GType.
*/
/**
- * SECTION:extensionpoints
- * @short_description: Extension Points
- * @include: gio.h
- * @see_also: <link linkend="extending-gio">Extending GIO</link>
+ * G_VALUE_TYPE_NAME:
+ * @value: A #GValue structure.
*
- * #GIOExtensionPoint provides a mechanism for modules to extend the
- * functionality of the library or application that loaded it in an
- * organized fashion.
- * An extension point is identified by a name, and it may optionally
- * require that any implementation must by of a certain type (or derived
- * thereof). Use g_io_extension_point_register() to register an
- * extension point, and g_io_extension_point_set_required_type() to
- * set a required type.
- * A module can implement an extension point by specifying the #GType
- * that implements the functionality. Additionally, each implementation
- * of an extension point has a name, and a priority. Use
- * g_io_extension_point_implement() to implement an extension point.
- * |[
- * GIOExtensionPoint *ep;
- * /* Register an extension point */
- * ep = g_io_extension_point_register ("my-extension-point");
- * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
- * ]|
- * |[
- * /* Implement an extension point */
- * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
- * g_io_extension_point_implement ("my-extension-point",
- * my_example_impl_get_type (),
- * "my-example",
- * 10);
- * ]|
- * It is up to the code that registered the extension point how
- * it uses the implementations that have been associated with it.
- * Depending on the use case, it may use all implementations, or
- * only the one with the highest priority, or pick a specific
- * one by name.
- * To avoid opening all modules just to find out what extension
- * points they implement, GIO makes use of a caching mechanism,
- * see <link linkend="gio-querymodules">gio-querymodules</link>.
- * You are expected to run this command after installing a
- * GIO module.
+ * Gets the the type name of @value.
+ *
+ * Returns: the type name.
*/
/**
- * SECTION:gaction
- * @title: GAction
- * @short_description: An action
+ * G_VARIANT_TYPE:
+ * @type_string: a well-formed #GVariantType type string
*
- * #GAction represents a single named action.
- * The main interface to an action is that it can be activated with
- * g_action_activate(). This results in the 'activate' signal being
- * emitted. An activation has a #GVariant parameter (which may be
- * %NULL). The correct type for the parameter is determined by a static
- * parameter type (which is given at construction time).
- * An action may optionally have a state, in which case the state may be
- * set with g_action_set_state(). This call takes a #GVariant. The
- * correct type for the state is determined by a static state type
- * (which is given at construction time).
- * The state may have a hint associated with it, specifying its valid
- * range.
- * #GAction is merely the interface to the concept of an action, as
- * described above. Various implementations of actions exist, including
- * #GSimpleAction and #GtkAction.
- * In all cases, the implementing class is responsible for storing the
- * name of the action, the parameter type, the enabled state, the
- * optional state type and the state and emitting the appropriate
- * signals when these change. The implementor responsible for filtering
- * calls to g_action_activate() and g_action_set_state() for type safety
- * and for the state being enabled.
- * Probably the only useful thing to do with a #GAction is to put it
- * inside of a #GSimpleActionGroup.
+ * Converts a string to a const #GVariantType. Depending on the
+ * current debugging level, this function may perform a runtime check
+ * to ensure that @string is a valid GVariant type string.
+ * It is always a programmer error to use this macro with an invalid
+ * type string.
+ * Since 2.24
*/
/**
- * SECTION:gactiongroup
- * @title: GActionGroup
- * @short_description: A group of actions
+ * G_VARIANT_TYPE_ANY:
*
- * #GActionGroup represents a group of actions.
- * Each action in the group has a unique name (which is a string). All
- * method calls, except g_action_group_list_actions() take the name of
- * an action as an argument.
- * The #GActionGroup API is meant to be the 'public' API to the action
- * group. The calls here are exactly the interaction that 'external
- * the action group implementation) are found on subclasses. This is
- * why you will find -- for example -- g_action_group_get_enabled() but
- * not an equivalent <function>set()</function> call.
- * Signals are emitted on the action group in response to state changes
- * on individual actions.
+ * An indefinite type that is a supertype of every type (including
+ * itself).
+ */
+
+
+/**
+ * G_VARIANT_TYPE_ARRAY:
*
- * Forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
- * With actions. 'internal' apis (ie: ones meant only to be accessed by
+ * An indefinite type that is a supertype of every array type.
*/
/**
- * SECTION:gappinfo
- * @short_description: Application information and launch contexts
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_BASIC:
*
- * #GAppInfo and #GAppLaunchContext are used for describing and launching
- * applications installed on the system.
- * As of GLib 2.20, URIs will always be converted to POSIX paths
- * (using g_file_get_path()) when using g_app_info_launch() even if
- * the application requested an URI and not a POSIX path. For example
- * for an desktop-file based application with Exec key <literal>totem
- * %%U</literal> and a single URI,
- * <literal>sftp://foo/file.avi</literal>, then
- * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
- * passed. This will only work if a set of suitable GIO extensions
- * (such as gvfs 2.26 compiled with FUSE support), is available and
- * operational; if this is not the case, the URI will be passed
- * unmodified to the application. Some URIs, such as
- * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
- * path (in gvfs there's no FUSE mount for it); such URIs will be
- * passed unmodified to the application.
- * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
- * back to the GIO URI in the #GFile constructors (since gvfs
- * implements the #GVfs extension point). As such, if the application
- * needs to examine the URI, it needs to use g_file_get_uri() or
- * similar on #GFile. In other words, an application cannot assume
- * that the URI passed to e.g. g_file_new_for_commandline_arg() is
- * equal to the result of g_file_get_uri(). The following snippet
- * illustrates this:
- * <programlisting>
- * GFile *f;
- * char *uri;
- * file = g_file_new_for_commandline_arg (uri_from_commandline);
- * uri = g_file_get_uri (file);
- * strcmp (uri, uri_from_commandline) == 0; // FALSE
- * g_free (uri);
- * if (g_file_has_uri_scheme (file, "cdda"))
- * {
- * // do something special with uri
- * }
- * g_object_unref (file);
- * </programlisting>
- * This code will work when both <literal>cdda://sr0/Track
- * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
- * 1.wav</literal> is passed to the application. It should be noted
- * that it's generally not safe for applications to rely on the format
- * of a particular URIs. Different launcher applications (e.g. file
- * managers) may have different ideas of what a given URI means.
+ * An indefinite type that is a supertype of every basic (ie:
+ * non-container) type.
*/
/**
- * SECTION:gapplication
- * @title: GApplication
- * @short_description: Core application class
+ * G_VARIANT_TYPE_BOOLEAN:
*
- * A #GApplication is the foundation of an application, unique for a
- * given application identifier. The GApplication class wraps some
- * low-level platform-specific services and is intended to act as the
- * foundation for higher-level application classes such as
- * #GtkApplication or #MxApplication. In general, you should not use
- * this class outside of a higher level framework.
- * One of the core features that GApplication provides is process
- * uniqueness, in the context of a "session". The session concept is
- * platform-dependent, but corresponds roughly to a graphical desktop
- * login. When your application is launched again, its arguments
- * are passed through platform communication to the already running
- * program. The already running instance of the program is called the
- * <firstterm>primary instance</firstterm>.
- * Before using GApplication, you must choose an "application identifier".
- * The expected form of an application identifier is very close to that of
- * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface";>DBus bus name</ulink>.
- * For details on valid application identifiers, see
- * g_application_id_is_valid().
- * The application identifier is claimed by the application as a
- * well-known bus name on the user's session bus. This means that the
- * uniqueness of your application is scoped to the current session. It
- * also means that your application may provide additional services
- * (through registration of other object paths) at that bus name.
- * The registration of these object paths should be done with the shared
- * GDBus session bus. Note that due to the internal architecture of
- * GDBus, method calls can be dispatched at any time (even if a main
- * loop is not running). For this reason, you must ensure that any
- * object paths that you wish to register are registered before
- * #GApplication attempts to acquire the bus name of your application
- * (which happens in g_application_register()). Unfortunately, this
- * means that you cannot use g_application_get_is_remote() to decide if
- * you want to register object paths.
- * GApplication provides convenient life cycle management by maintaining
- * a <firstterm>use count</firstterm> for the primary application instance.
- * The use count can be changed using g_application_hold() and
- * g_application_release(). If it drops to zero, the application exits.
- * GApplication also implements the #GActionGroup interface and lets you
- * easily export actions by adding them with g_application_set_action_group().
- * When invoking an action by calling g_action_group_activate_action() on
- * the application, it is always invoked in the primary instance.
- * There is a number of different entry points into a #GApplication:
- * <itemizedlist>
- * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
- * <listitem>via 'Open' (i.e. opening some files)</listitem>
- * <listitem>by handling a command-line</listitem>
- * <listitem>via activating an action</listitem>
- * </itemizedlist>
- * The #GApplication::startup signal lets you handle the application
- * initialization for all of these in a single place.
- * Regardless of which of these entry points is used to start the application,
- * GApplication passes some <firstterm id="platform-data">platform
- * data</firstterm> from the launching instance to the primary instance,
- * in the form of a #GVariant dictionary mapping strings to variants.
- * To use platform data, override the @before_emit or @after_emit virtual
- * functions in your #GApplication subclass. When dealing with
- * #GApplicationCommandline objects, the platform data is directly
- * available via g_application_command_line_get_cwd(),
- * g_application_command_line_get_environ() and
- * g_application_command_line_get_platform_data().
- * As the name indicates, the platform data may vary depending on the
- * operating system, but it always includes the current directory (key
- * "cwd"), and optionally the environment (ie the set of environment
- * variables and their values) of the calling process (key "environ").
- * The environment is only added to the platform data if the
- * #G_APPLICATION_SEND_ENVIONMENT flag is set. GApplication subclasses
- * can add their own platform data by overriding the @add_platform_data
- * virtual function. For instance, #GtkApplication adds startup notification
- * data in this way.
- * To parse commandline arguments you may handle the
- * #GApplication::command-line signal or override the local_command_line()
- * vfunc, to parse them in either the primary instance or the local instance,
- * respectively.
- * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-open.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * The type of a value that can be either %TRUE or %FALSE.
+ */
+
+
+/**
+ * G_VARIANT_TYPE_BYTE:
*
- * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
+ * The type of an integer value that can range from 0 to 255.
*/
/**
- * SECTION:gapplicationcommandline
- * @title: GApplicationCommandLine
- * @short_description: A command-line invocation of an application
- * @see_also: #GApplication
+ * G_VARIANT_TYPE_BYTESTRING:
*
- * #GApplicationCommandLine represents a command-line invocation of
- * an application. It is created by #GApplication and emitted
- * in the #GApplication::command-line signal and virtual function.
- * The class contains the list of arguments that the program was invoked
- * with. It is also possible to query if the commandline invocation was
- * commandline to this process).
- * The GApplicationCommandLine object can provide the @argc and @argv
- * parameters for use with the #GOptionContext command-line parsing API,
- * with the g_application_command_line_get_arguments() function. See
- * <xref linkend="gapplication-example-cmdline3"/> for an example.
- * The exit status of the originally-invoked process may be set and
- * messages can be printed to stdout or stderr of that process. The
- * lifecycle of the originally-invoked process is tied to the lifecycle
- * dropped).
- * The main use for #GApplicationCommandline (and the
- * #GApplication::command-line signal) is 'Emacs server' like use cases:
- * You can set the <envar>EDITOR</envar> environment variable to have
- * e.g. git use your favourite editor to edit commit messages, and if you
- * already have an instance of the editor running, the editing will happen
- * in the running instance, instead of opening a new one. An important
- * aspect of this use case is that the process that gets started by git
- * does not return until the editing is done.
- * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
- * <para>
- * A simple example where the commandline is completely handled
- * in the #GApplication::command-line handler. The launching instance exits
- * once the signal handler in the primary instance has returned, and the
- * return value of the signal handler becomes the exit status of the launching
- * instance.
- * </para>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
- * <para>
- * An example of split commandline handling. Options that start with
- * <literal>--local-</literal> are handled locally, all other options are
- * passed to the #GApplication::command-line handler which runs in the primary
- * instance.
- * </para>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
- * <para>
- * An example of deferred commandline handling. Here, the commandline is
- * not completely handled before the #GApplication::command-line handler
- * returns. Instead, we keep a reference to the GApplicationCommandline
- * object and handle it later(in this example, in an idle). Note that it
- * is necessary to hold the application until you are done with the
- * commandline.
- * </para>
- * <para>
- * This example also shows how to use #GOptionContext for parsing the
- * commandline arguments.
- * </para>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * The type of an array of bytes. This type is commonly used to pass
+ * around strings that may not be valid utf8. In that case, the
+ * convention is that the nul terminator character should be included as
+ * the last character in the array.
+ */
+
+
+/**
+ * G_VARIANT_TYPE_BYTESTRING_ARRAY:
*
- * Local (ie: the current process is running in direct response to the
- * Invocation) or remote (ie: some other process forwarded the
- * Of this object (ie: the process exits when the last reference is
+ * The type of an array of byte strings (an array of arrays of bytes).
*/
/**
- * SECTION:gasynchelper
- * @short_description: Asynchronous Helper Functions
- * @include: gio/gio.h
- * @see_also: #GAsyncReady
+ * G_VARIANT_TYPE_DICTIONARY:
*
- * Provides helper functions for asynchronous operations.
+ * An indefinite type that is a supertype of every dictionary type --
+ * that is, any array type that has an element type equal to any
+ * dictionary entry type.
*/
/**
- * SECTION:gasyncinitable
- * @short_description: Asynchronously failable object initialization interface
- * @include: gio/gio.h
- * @see_also: #GInitable
+ * G_VARIANT_TYPE_DICT_ENTRY:
*
- * This is the asynchronous version of #GInitable; it behaves the same
- * in all ways except that initialization is asynchronous. For more details
- * see the descriptions on #GInitable.
- * A class may implement both the #GInitable and #GAsyncInitable interfaces.
- * Users of objects implementing this are not intended to use the interface
- * method directly; instead it will be used automatically in various ways.
- * For C applications you generally just call g_async_initable_new_async()
- * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
- * g_async_initable_init_async() under the cover, calling back with %NULL and
- * a set %GError on failure.
- * A typical implementation might look something like this:
- * |[
- * enum {
- * NOT_INITIALIZED,
- * INITIALIZING,
- * INITIALIZED
- * };
- * static void
- * _foo_ready_cb (Foo *self)
- * {
- * GList *l;
- * self->priv->state = INITIALIZED;
- * for (l = self->priv->init_results; l != NULL; l = l->next)
- * {
- * GSimpleAsyncResult *simple = l->data;
- * if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
- * g_simple_async_result_complete (simple);
- * g_object_unref (simple);
- * }
- * g_list_free (self->priv->init_results);
- * self->priv->init_results = NULL;
- * }
- * static void
- * foo_init_async (GAsyncInitable *initable,
- * int io_priority,
- * GCancellable *cancellable,
- * GAsyncReadyCallback callback,
- * gpointer user_data)
- * {
- * Foo *self = FOO (initable);
- * GSimpleAsyncResult *simple;
- * simple = g_simple_async_result_new (G_OBJECT (initable)
- * callback,
- * user_data,
- * foo_init_async);
- * switch (self->priv->state)
- * {
- * case NOT_INITIALIZED:
- * _foo_get_ready (self);
- * self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
- * self->priv->state = INITIALIZING;
- * break;
- * case INITIALIZING:
- * self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
- * break;
- * case INITIALIZED:
- * if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
- * g_simple_async_result_complete_in_idle (simple);
- * g_object_unref (simple);
- * break;
- * }
- * }
- * static gboolean
- * foo_init_finish (GAsyncInitable *initable,
- * GAsyncResult *result,
- * GError **error)
- * {
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (initable), foo_init_async), FALSE);
- * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
- * error))
- * return FALSE;
- * return TRUE;
- * }
- * static void
- * foo_async_initable_iface_init (gpointer g_iface,
- * gpointer data)
- * {
- * GAsyncInitableIface *iface = g_iface;
- * iface->init_async = foo_init_async;
- * iface->init_finish = foo_init_finish;
- * }
- * ]|
+ * An indefinite type that is a supertype of every dictionary entry
+ * type.
*/
/**
- * SECTION:gasyncresult
- * @short_description: Asynchronous Function Results
- * @include: gio/gio.h
- * @see_also: #GSimpleAsyncResult
+ * G_VARIANT_TYPE_DOUBLE:
*
- * Provides a base class for implementing asynchronous function results.
- * Asynchronous operations are broken up into two separate operations
- * which are chained together by a #GAsyncReadyCallback. To begin
- * an asynchronous operation, provide a #GAsyncReadyCallback to the
- * asynchronous function. This callback will be triggered when the
- * operation has completed, and will be passed a #GAsyncResult instance
- * filled with the details of the operation's success or failure, the
- * object the asynchronous function was started for and any error codes
- * returned. The asynchronous callback function is then expected to call
- * the corresponding "_finish()" function, passing the object the
- * function was called for, the #GAsyncResult instance, and (optionally)
- * an @error to grab any error conditions that may have occurred.
- * The "_finish()" function for an operation takes the generic result
- * (of type #GAsyncResult) and returns the specific result that the
- * operation in question yields (e.g. a #GFileEnumerator for a
- * "enumerate children" operation). If the result or error status of the
- * operation is not needed, there is no need to call the "_finish()"
- * function; GIO will take care of cleaning up the result and error
- * information after the #GAsyncReadyCallback returns. Applications may
- * also take a reference to the #GAsyncResult and call "_finish()"
- * later; however, the "_finish()" function may be called at most once.
- * Example of a typical asynchronous operation flow:
- * |[
- * void _theoretical_frobnitz_async (Theoretical *t,
- * GCancellable *c,
- * GAsyncReadyCallback *cb,
- * gpointer u);
- * gboolean _theoretical_frobnitz_finish (Theoretical *t,
- * GAsyncResult *res,
- * GError **e);
- * static void
- * frobnitz_result_func (GObject *source_object,
- * GAsyncResult *res,
- * gpointer user_data)
- * {
- * gboolean success = FALSE;
- * success = _theoretical_frobnitz_finish (source_object, res, NULL);
- * if (success)
- * g_printf ("Hurray!\n");
- * else
- * g_printf ("Uh oh!\n");
- * /<!-- -->* ... *<!-- -->/
- * }
- * int main (int argc, void *argv[])
- * {
- * /<!-- -->* ... *<!-- -->/
- * _theoretical_frobnitz_async (theoretical_data,
- * NULL,
- * frobnitz_result_func,
- * NULL);
- * /<!-- -->* ... *<!-- -->/
- * }
- * ]|
- * The callback for an asynchronous operation is called only once, and is
- * always called, even in the case of a cancelled operation. On cancellation
- * the result is a %G_IO_ERROR_CANCELLED error.
- * Some asynchronous operations are implemented using synchronous calls.
- * These are run in a separate thread, if #GThread has been initialized, but
- * otherwise they are sent to the Main Event Loop and processed in an idle
- * function. So, if you truly need asynchronous operations, make sure to
- * initialize #GThread.
+ * The type of a double precision IEEE754 floating point number.
+ * These guys go up to about 1.80e308 (plus and minus) but miss out on
+ * some numbers in between. In any case, that's far greater than the
+ * estimated number of fundamental particles in the observable
+ * universe.
*/
/**
- * SECTION:gbufferedinputstream
- * @short_description: Buffered Input Stream
- * @include: gio/gio.h
- * @see_also: #GFilterInputStream, #GInputStream
+ * G_VARIANT_TYPE_HANDLE:
*
- * Buffered input stream implements #GFilterInputStream and provides
- * for buffered reads.
- * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
- * To create a buffered input stream, use g_buffered_input_stream_new(),
- * or g_buffered_input_stream_new_sized() to specify the buffer's size at
- * construction.
- * To get the size of a buffer within a buffered input stream, use
- * g_buffered_input_stream_get_buffer_size(). To change the size of a
- * buffered input stream's buffer, use
- * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
- * cannot be reduced below the size of the data within the buffer.
+ * The type of a 32bit signed integer value, that by convention, is used
+ * as an index into an array of file descriptors that are sent alongside
+ * a D-Bus message.
+ * If you are not interacting with D-Bus, then there is no reason to make
+ * use of this type.
*/
/**
- * SECTION:gbufferedoutputstream
- * @short_description: Buffered Output Stream
- * @include: gio/gio.h
- * @see_also: #GFilterOutputStream, #GOutputStream
+ * G_VARIANT_TYPE_INT16:
*
- * Buffered output stream implements #GFilterOutputStream and provides
- * for buffered writes.
- * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
- * To create a buffered output stream, use g_buffered_output_stream_new(),
- * or g_buffered_output_stream_new_sized() to specify the buffer's size
- * at construction.
- * To get the size of a buffer within a buffered input stream, use
- * g_buffered_output_stream_get_buffer_size(). To change the size of a
- * buffered output stream's buffer, use
- * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
- * size cannot be reduced below the size of the data within the buffer.
+ * The type of an integer value that can range from -32768 to 32767.
*/
/**
- * SECTION:gcancellable
- * @short_description: Thread-safe Operation Cancellation Stack
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_INT32:
*
- * GCancellable is a thread-safe operation cancellation stack used
- * throughout GIO to allow for cancellation of synchronous and
- * asynchronous operations.
+ * The type of an integer value that can range from -2147483648 to
+ * 2147483647.
*/
/**
- * SECTION:gcharsetconverter
- * @short_description: Convert between charsets
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_INT64:
*
- * #GCharsetConverter is an implementation of #GConverter based on
- * GIConv.
+ * The type of an integer value that can range from
+ * -9223372036854775808 to 9223372036854775807.
*/
/**
- * SECTION:gcontenttype
- * @short_description: Platform-specific content typing
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_MAYBE:
*
- * A content type is a platform specific string that defines the type
- * of a file. On unix it is a mime type, on win32 it is an extension string
- * like ".doc", ".txt" or a percieved string like "audio". Such strings
- * can be looked up in the registry at HKEY_CLASSES_ROOT.
+ * An indefinite type that is a supertype of every maybe type.
*/
/**
- * SECTION:gconverter
- * @short_description: Data conversion interface
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
- *
- * #GConverter is implemented by objects that convert
- * binary data in various ways. The conversion can be
- * stateful and may fail at any place.
- * compression, decompression and regular expression
- * replace.
+ * G_VARIANT_TYPE_OBJECT_PATH:
*
- * Some example conversions are: character set conversion,
- * Since: 2.24
+ * The type of a D-Bus object reference. These are strings of a
+ * specific format used to identify objects at a given destination on
+ * the bus.
+ * If you are not interacting with D-Bus, then there is no reason to make
+ * use of this type. If you are, then the D-Bus specification contains a
+ * precise description of valid object paths.
*/
/**
- * SECTION:gconverterinputstream
- * @short_description: Converter Input Stream
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GConverter
+ * G_VARIANT_TYPE_SIGNATURE:
*
- * Converter input stream implements #GInputStream and allows
- * conversion of data of various types during reading.
+ * The type of a D-Bus type signature. These are strings of a specific
+ * format used as type signatures for D-Bus methods and messages.
+ * If you are not interacting with D-Bus, then there is no reason to make
+ * use of this type. If you are, then the D-Bus specification contains a
+ * precise description of valid signature strings.
*/
/**
- * SECTION:gconverteroutputstream
- * @short_description: Converter Output Stream
- * @include: gio/gio.h
- * @see_also: #GOutputStream, #GConverter
+ * G_VARIANT_TYPE_STRING:
*
- * Converter output stream implements #GOutputStream and allows
- * conversion of data of various types during reading.
+ * The type of a string. "" is a string. %NULL is not a string.
*/
/**
- * SECTION:gcredentials
- * @short_description: An object containing credentials
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_STRING_ARRAY:
*
- * The #GCredentials type is a reference-counted wrapper for native
- * credentials. This information is typically used for identifying,
- * authenticating and authorizing other processes.
- * Some operating systems supports looking up the credentials of the
- * remote peer of a communication endpoint - see e.g.
- * g_socket_get_credentials().
- * Some operating systems supports securely sending and receiving
- * credentials over a Unix Domain Socket, see
- * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
- * g_unix_connection_receive_credentials() for details.
- * On Linux, the native credential type is a <type>struct ucred</type>
- * - see the
- * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- * man page for details. This corresponds to
- * %G_CREDENTIALS_TYPE_LINUX_UCRED.
- * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>.
- * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
+ * The type of an array of strings.
*/
/**
- * SECTION:gdatainputstream
- * @short_description: Data Input Stream
- * @include: gio/gio.h
- * @see_also: #GInputStream
+ * G_VARIANT_TYPE_TUPLE:
*
- * Data input stream implements #GInputStream and includes functions for
- * reading structured data directly from a binary input stream.
+ * An indefinite type that is a supertype of every tuple type,
+ * regardless of the number of items in the tuple.
*/
/**
- * SECTION:gdataoutputstream
- * @short_description: Data Output Stream
- * @include: gio/gio.h
- * @see_also: #GOutputStream
+ * G_VARIANT_TYPE_UINT16:
*
- * Data output stream implements #GOutputStream and includes functions for
- * writing data directly to an output stream.
+ * The type of an integer value that can range from 0 to 65535.
+ * There were about this many people living in Toronto in the 1870s.
*/
/**
- * SECTION:gdbusaddress
- * @title: D-Bus Addresses
- * @short_description: D-Bus connection endpoints
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_UINT32:
*
- * Routines for working with D-Bus addresses. A D-Bus address is a string
- * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
- * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses";>D-Bus specification</link>.
+ * The type of an integer value that can range from 0 to 4294967295.
+ * That's one number for everyone who was around in the late 1970s.
*/
/**
- * SECTION:gdbusauthobserver
- * @short_description: Object used for authenticating connections
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_UINT64:
*
- * The #GDBusAuthObserver type provides a mechanism for participating
- * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
- * peers. Simply instantiate a #GDBusAuthObserver and connect to the
- * signals you are interested in. Note that new signals may be added
- * in the future
- * For example, if you only want to allow D-Bus connections from
- * processes owned by the same uid as the server, you would use a
- * signal handler like the following:
- * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
- * static gboolean
- * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
- * GIOStream *stream,
- * GCredentials *credentials,
- * gpointer user_data)
- * {
- * gboolean authorized;
- * authorized = FALSE;
- * if (credentials != NULL)
- * {
- * GCredentials *own_credentials;
- * own_credentials = g_credentials_new ();
- * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
- * authorized = TRUE;
- * g_object_unref (own_credentials);
- * }
- * return authorized;
- * }
- * </programlisting></example>
+ * The type of an integer value that can range from 0 to
+ * 18446744073709551616. That's a really big number, but a Rubik's
+ * cube can have a bit more than twice as many possible positions.
*/
/**
- * SECTION:gdbusconnection
- * @short_description: D-Bus Connections
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_UNIT:
*
- * The #GDBusConnection type is used for D-Bus connections to remote
- * peers such as a message buses. It is a low-level API that offers a
- * lot of flexibility. For instance, it lets you establish a connection
- * over any transport that can by represented as an #GIOStream.
- * This class is rarely used directly in D-Bus clients. If you are writing
- * an D-Bus client, it is often easier to use the g_bus_own_name(),
- * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
- * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
- * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
- * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
- * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * The empty tuple type. Has only one instance. Known also as "triv"
+ * or "void".
*/
/**
- * SECTION:gdbuserror
- * @title: GDBusError
- * @short_description: Mapping D-Bus errors to and from GError
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_VARDICT:
*
- * All facilities that return errors from remote methods (such as
- * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
- * errors (e.g. errors returned from the other peer) and locally
- * in-process generated errors.
- * To check if a returned #GError is an error from a remote peer, use
- * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
- * use g_dbus_error_get_remote_error(). Before presenting an error,
- * always use g_dbus_error_strip_remote_error().
- * In addition, facilities used to return errors to a remote peer also
- * use #GError. See g_dbus_method_invocation_return_error() for
- * discussion about how the D-Bus error name is set.
- * Applications can associate a #GError error domain with a set of D-Bus errors in order to
- * automatically map from D-Bus errors to #GError and back. This
- * is typically done in the function returning the #GQuark for the
- * error domain:
- * <example id="error-registration"><title>Error Registration</title><programlisting>
- * /<!-- -->* foo-bar-error.h: *<!-- -->/
- * #define FOO_BAR_ERROR (foo_bar_error_quark ())
- * GQuark foo_bar_error_quark (void);
- * typedef enum
- * {
- * FOO_BAR_ERROR_FAILED,
- * FOO_BAR_ERROR_ANOTHER_ERROR,
- * FOO_BAR_ERROR_SOME_THIRD_ERROR,
- * } FooBarError;
- * /<!-- -->* foo-bar-error.c: *<!-- -->/
- * static const GDBusErrorEntry foo_bar_error_entries[] =
- * {
- * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
- * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
- * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
- * };
- * GQuark
- * foo_bar_error_quark (void)
- * {
- * static volatile gsize quark_volatile = 0;
- * g_dbus_error_register_error_domain ("foo-bar-error-quark",
- * &quark_volatile,
- * foo_bar_error_entries,
- * G_N_ELEMENTS (foo_bar_error_entries));
- * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR);
- * return (GQuark) quark_volatile;
- * }
- * </programlisting></example>
- * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
- * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>.
- * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
- * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
- * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
- * Note that errors in the %G_DBUS_ERROR error domain is intended only
- * for returning errors from a remote message bus process. Errors
- * generated locally in-process by e.g. #GDBusConnection is from the
- * %G_IO_ERROR domain.
+ * The type of a dictionary mapping strings to variants (the ubiquitous
+ * "a{sv}" type).
+ *
+ * Since: 2.30
*/
/**
- * SECTION:gdbusintrospection
- * @title: D-Bus Introspection Data
- * @short_description: Node and interface description data structures
- * @include: gio/gio.h
+ * G_VARIANT_TYPE_VARIANT:
*
- * Various data structures and convenience routines to parse and
- * generate D-Bus introspection XML. Introspection information is
- * used when registering objects with g_dbus_connection_register_object().
- * The format of D-Bus introspection XML is specified in the
- * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format";>D-Bus specification</link>.
+ * The type of a box that contains any other value (including another
+ * variant).
*/
/**
- * SECTION:gdbusmessage
- * @short_description: D-Bus Message
- * @include: gio/gio.h
+ * G_VFS_EXTENSION_POINT_NAME:
*
- * A type for representing D-Bus messages that can be sent or received
- * on a #GDBusConnection.
+ * Extension point for #GVfs functionality.
+ * See <link linkend="extending-gio">Extending GIO</link>.
*/
/**
- * SECTION:gdbusmethodinvocation
- * @short_description: Object for handling remote calls
- * @include: gio/gio.h
+ * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
*
- * Instances of the #GDBusMethodInvocation class are used when
- * handling D-Bus method calls. It provides a way to asynchronously
- * return results and errors.
- * The normal way to obtain a #GDBusMethodInvocation object is to receive
- * it as an argument to the handle_method_call() function in a
- * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
+ * The string used to obtain a Hal UDI with g_volume_get_identifier().
*/
/**
- * SECTION:gdbusnameowning
- * @title: Owning Bus Names
- * @short_description: Simple API for owning bus names
- * @include: gio/gio.h
+ * G_VOLUME_IDENTIFIER_KIND_LABEL:
*
- * Convenience API for owning bus names.
- * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * The string used to obtain a filesystem label with g_volume_get_identifier().
*/
/**
- * SECTION:gdbusnamewatching
- * @title: Watching Bus Names
- * @short_description: Simple API for watching bus names
- * @include: gio/gio.h
+ * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
*
- * Convenience API for watching bus names.
- * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * The string used to obtain a NFS mount with g_volume_get_identifier().
*/
/**
- * SECTION:gdbusproxy
- * @short_description: Client-side proxies
- * @include: gio/gio.h
+ * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
*
- * #GDBusProxy is a base class used for proxies to access a D-Bus
- * interface on a remote object. A #GDBusProxy can be constructed for
- * both well-known and unique names.
- * By default, #GDBusProxy will cache all properties (and listen to
- * changes) of the remote object, and proxy all signals that gets
- * emitted. This behaviour can be changed by passing suitable
- * #GDBusProxyFlags when the proxy is created. If the proxy is for a
- * well-known name, the property cache is flushed when the name owner
- * vanishes and reloaded when a name owner appears.
- * If a #GDBusProxy is used for a well-known name, the owner of the
- * name is tracked and can be read from
- * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
- * get notified of changes. Additionally, only signals and property
- * changes emitted from the current name owner are considered and
- * calls are always sent to the current name owner. This avoids a
- * number of race conditions when the name is lost by one owner and
- * claimed by another. However, if no name owner currently exists,
- * then calls will be sent to the well-known name which may result in
- * the message bus launching an owner (unless
- * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
- * The generic #GDBusProxy::g-properties-changed and #GDBusProxy::g-signal
- * signals are not very convenient to work with. Therefore, the recommended
- * way of working with proxies is to subclass #GDBusProxy, and have
- * more natural properties and signals in your derived class.
- * See <xref linkend="gdbus-example-proxy-subclass"/> for an example.
- * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * The string used to obtain a Unix device path with g_volume_get_identifier().
*/
/**
- * SECTION:gdbusserver
- * @short_description: Helper for accepting connections
- * @include: gio/gio.h
+ * G_VOLUME_IDENTIFIER_KIND_UUID:
*
- * #GDBusServer is a helper for listening to and accepting D-Bus
- * connections.
- * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * The string used to obtain a UUID with g_volume_get_identifier().
*/
/**
- * SECTION:gdbusutils
- * @title: D-Bus Utilities
- * @short_description: Various utilities related to D-Bus.
- * @include: gio/gio.h
+ * G_VOLUME_MONITOR_EXTENSION_POINT_NAME:
*
- * Various utility routines related to D-Bus.
+ * Extension point for volume monitor functionality.
+ * See <link linkend="extending-gio">Extending GIO</link>.
*/
/**
- * SECTION:gdesktopappinfo
- * @title: GDesktopAppInfo
- * @short_description: Application information from desktop files
- * @include: gio/gdesktopappinfo.h
+ * SECTION:extensionpoints
+ * @short_description: Extension Points
+ * @include: gio.h
+ * @see_also: <link linkend="extending-gio">Extending GIO</link>
*
- * #GDesktopAppInfo is an implementation of #GAppInfo based on
- * desktop files.
- * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * #GIOExtensionPoint provides a mechanism for modules to extend the
+ * functionality of the library or application that loaded it in an
+ * organized fashion.
+ * An extension point is identified by a name, and it may optionally
+ * require that any implementation must by of a certain type (or derived
+ * thereof). Use g_io_extension_point_register() to register an
+ * extension point, and g_io_extension_point_set_required_type() to
+ * set a required type.
+ * A module can implement an extension point by specifying the #GType
+ * that implements the functionality. Additionally, each implementation
+ * of an extension point has a name, and a priority. Use
+ * g_io_extension_point_implement() to implement an extension point.
+ * |[
+ * GIOExtensionPoint *ep;
+ * /* Register an extension point */
+ * ep = g_io_extension_point_register ("my-extension-point");
+ * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
+ * ]|
+ * |[
+ * /* Implement an extension point */
+ * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
+ * g_io_extension_point_implement ("my-extension-point",
+ * my_example_impl_get_type (),
+ * "my-example",
+ * 10);
+ * ]|
+ * It is up to the code that registered the extension point how
+ * it uses the implementations that have been associated with it.
+ * Depending on the use case, it may use all implementations, or
+ * only the one with the highest priority, or pick a specific
+ * one by name.
+ * To avoid opening all modules just to find out what extension
+ * points they implement, GIO makes use of a caching mechanism,
+ * see <link linkend="gio-querymodules">gio-querymodules</link>.
+ * You are expected to run this command after installing a
+ * GIO module.
*/
/**
- * SECTION:gdrive
- * @short_description: Drive management
- * @include: gio/gio.h
+ * SECTION:gaction
+ * @title: GAction
+ * @short_description: An action
*
- * #GDrive - this represent a piece of hardware connected to the machine.
- * It's generally only created for removable hardware or hardware with
- * removable media.
- * #GDrive is a container class for #GVolume objects that stem from
- * the same piece of media. As such, #GDrive abstracts a drive with
- * (or without) removable media and provides operations for querying
- * whether media is available, determing whether media change is
- * automatically detected and ejecting the media.
- * If the #GDrive reports that media isn't automatically detected, one
- * can poll for media; typically one should not do this periodically
- * as a poll for media operation is potententially expensive and may
- * spin up the drive creating noise.
- * #GDrive supports starting and stopping drives with authentication
- * support for the former. This can be used to support a diverse set
- * of use cases including connecting/disconnecting iSCSI devices,
- * powering down external disk enclosures and starting/stopping
- * multi-disk devices such as RAID devices. Note that the actual
- * semantics and side-effects of starting/stopping a #GDrive may vary
- * according to implementation. To choose the correct verbs in e.g. a
- * file manager, use g_drive_get_start_stop_type().
- * For porting from GnomeVFS note that there is no equivalent of
- * #GDrive in that API.
+ * #GAction represents a single named action.
+ * The main interface to an action is that it can be activated with
+ * g_action_activate(). This results in the 'activate' signal being
+ * emitted. An activation has a #GVariant parameter (which may be
+ * %NULL). The correct type for the parameter is determined by a static
+ * parameter type (which is given at construction time).
+ * An action may optionally have a state, in which case the state may be
+ * set with g_action_set_state(). This call takes a #GVariant. The
+ * correct type for the state is determined by a static state type
+ * (which is given at construction time).
+ * The state may have a hint associated with it, specifying its valid
+ * range.
+ * #GAction is merely the interface to the concept of an action, as
+ * described above. Various implementations of actions exist, including
+ * #GSimpleAction and #GtkAction.
+ * In all cases, the implementing class is responsible for storing the
+ * name of the action, the parameter type, the enabled state, the
+ * optional state type and the state and emitting the appropriate
+ * signals when these change. The implementor responsible for filtering
+ * calls to g_action_activate() and g_action_set_state() for type safety
+ * and for the state being enabled.
+ * Probably the only useful thing to do with a #GAction is to put it
+ * inside of a #GSimpleActionGroup.
*/
/**
- * SECTION:gemblem
- * @short_description: An object for emblems
- * @include: gio/gio.h
- * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
+ * SECTION:gactiongroup
+ * @title: GActionGroup
+ * @short_description: A group of actions
*
- * #GEmblem is an implementation of #GIcon that supports
- * having an emblem, which is an icon with additional properties.
- * It can than be added to a #GEmblemedIcon.
- * Currently, only metainformation about the emblem's origin is
- * supported. More may be added in the future.
+ * #GActionGroup represents a group of actions.
+ * Each action in the group has a unique name (which is a string). All
+ * method calls, except g_action_group_list_actions() take the name of
+ * an action as an argument.
+ * The #GActionGroup API is meant to be the 'public' API to the action
+ * group. The calls here are exactly the interaction that 'external
+ * the action group implementation) are found on subclasses. This is
+ * why you will find -- for example -- g_action_group_get_action_enabled()
+ * but not an equivalent <function>set()</function> call.
+ * Signals are emitted on the action group in response to state changes
+ * on individual actions.
+ *
+ * Forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
+ * With actions. 'internal' apis (ie: ones meant only to be accessed by
*/
/**
- * SECTION:gemblemedicon
- * @short_description: Icon with emblems
+ * SECTION:gappinfo
+ * @short_description: Application information and launch contexts
* @include: gio/gio.h
- * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
*
- * #GEmblemedIcon is an implementation of #GIcon that supports
- * adding an emblem to an icon. Adding multiple emblems to an
- * icon is ensured via g_emblemed_icon_add_emblem().
- * Note that #GEmblemedIcon allows no control over the position
- * of the emblems. See also #GEmblem for more information.
+ * #GAppInfo and #GAppLaunchContext are used for describing and launching
+ * applications installed on the system.
+ * As of GLib 2.20, URIs will always be converted to POSIX paths
+ * (using g_file_get_path()) when using g_app_info_launch() even if
+ * the application requested an URI and not a POSIX path. For example
+ * for an desktop-file based application with Exec key <literal>totem
+ * %U</literal> and a single URI,
+ * <literal>sftp://foo/file.avi</literal>, then
+ * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
+ * passed. This will only work if a set of suitable GIO extensions
+ * (such as gvfs 2.26 compiled with FUSE support), is available and
+ * operational; if this is not the case, the URI will be passed
+ * unmodified to the application. Some URIs, such as
+ * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
+ * path (in gvfs there's no FUSE mount for it); such URIs will be
+ * passed unmodified to the application.
+ * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
+ * back to the GIO URI in the #GFile constructors (since gvfs
+ * implements the #GVfs extension point). As such, if the application
+ * needs to examine the URI, it needs to use g_file_get_uri() or
+ * similar on #GFile. In other words, an application cannot assume
+ * that the URI passed to e.g. g_file_new_for_commandline_arg() is
+ * equal to the result of g_file_get_uri(). The following snippet
+ * illustrates this:
+ * <programlisting>
+ * GFile *f;
+ * char *uri;
+ * file = g_file_new_for_commandline_arg (uri_from_commandline);
+ * uri = g_file_get_uri (file);
+ * strcmp (uri, uri_from_commandline) == 0; // FALSE
+ * g_free (uri);
+ * if (g_file_has_uri_scheme (file, "cdda"))
+ * {
+ * // do something special with uri
+ * }
+ * g_object_unref (file);
+ * </programlisting>
+ * This code will work when both <literal>cdda://sr0/Track
+ * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
+ * 1.wav</literal> is passed to the application. It should be noted
+ * that it's generally not safe for applications to rely on the format
+ * of a particular URIs. Different launcher applications (e.g. file
+ * managers) may have different ideas of what a given URI means.
*/
/**
- * SECTION:gfile
- * @short_description: File and Directory Handling
- * @include: gio/gio.h
- * @see_also: #GFileInfo, #GFileEnumerator
+ * SECTION:gapplication
+ * @title: GApplication
+ * @short_description: Core application class
*
- * #GFile is a high level abstraction for manipulating files on a
- * virtual file system. #GFile<!-- -->s are lightweight, immutable
- * objects that do no I/O upon creation. It is necessary to understand that
- * #GFile objects do not represent files, merely an identifier for a file. All
- * file content I/O is implemented as streaming operations (see #GInputStream and
- * #GOutputStream).
- * g_file_new_for_path() if you have a path.
- * g_file_new_for_uri() if you have a URI.
- * g_file_new_for_commandline_arg() for a command line argument.
- * g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name().
- * One way to think of a #GFile is as an abstraction of a pathname. For normal
- * files the system pathname is what is stored internally, but as #GFile<!-- -->s
- * are extensible it could also be something else that corresponds to a pathname
- * in a userspace implementation of a filesystem.
- * #GFile<!-- -->s make up hierarchies of directories and files that correspond to the
- * files on a filesystem. You can move through the file system with #GFile using
- * g_file_get_parent() to get an identifier for the parent directory, g_file_get_child()
- * to get a child within a directory, g_file_resolve_relative_path() to resolve a relative
- * path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not
- * end up at the same root if you repeatedly call g_file_get_parent() on two different
- * files.
- * All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names
- * are byte strings that are used to identify the file on the filesystem (relative to
- * its parent directory) and there is no guarantees that they have any particular charset
- * encoding or even make any sense at all. If you want to use filenames in a user
- * interface you should use the display name that you can get by requesting the
- * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
- * This is guaranteed to be in utf8 and can be used in a user interface. But always
- * store the real basename or the #GFile to use to actually access the file, because
- * there is no way to go from a display name to the actual name.
- * Using #GFile as an identifier has the same weaknesses as using a path in that
- * there may be multiple aliases for the same file. For instance, hard or
- * soft links may cause two different #GFile<!-- -->s to refer to the same file.
- * and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if
- * two #GFile<!-- -->s point to the same file you can query for the
- * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
- * canonicalization of pathnames passed in, so that trivial differences in the
- * path string used at creation (duplicated slashes, slash at end of path, "."
- * or ".." path segments, etc) does not create different #GFile<!-- -->s.
- * Many #GFile operations have both synchronous and asynchronous versions
- * to suit your application. Asynchronous versions of synchronous functions
- * simply have _async() appended to their function names. The asynchronous
- * I/O functions call a #GAsyncReadyCallback which is then used to finalize
- * the operation, producing a GAsyncResult which is then passed to the
- * function's matching _finish() operation.
- * Some #GFile operations do not have synchronous analogs, as they may
- * take a very long time to finish, and blocking may leave an application
- * unusable. Notable cases include:
- * g_file_mount_mountable() to mount a mountable file.
- * g_file_unmount_mountable_with_operation() to unmount a mountable file.
- * g_file_eject_mountable_with_operation() to eject a mountable file.
- * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
- * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for
- * short. Entity tags are somewhat like a more abstract version of the
- * traditional mtime, and can be used to quickly determine if the file has
- * been modified from the version on the file system. See the HTTP 1.1
- * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html";>specification</ulink>
- * for HTTP Etag headers, which are a very similar concept.
- * </para>
+ * A #GApplication is the foundation of an application, unique for a
+ * given application identifier. The GApplication class wraps some
+ * low-level platform-specific services and is intended to act as the
+ * foundation for higher-level application classes such as
+ * #GtkApplication or #MxApplication. In general, you should not use
+ * this class outside of a higher level framework.
+ * One of the core features that GApplication provides is process
+ * uniqueness, in the context of a "session". The session concept is
+ * platform-dependent, but corresponds roughly to a graphical desktop
+ * login. When your application is launched again, its arguments
+ * are passed through platform communication to the already running
+ * program. The already running instance of the program is called the
+ * <firstterm>primary instance</firstterm>.
+ * Before using GApplication, you must choose an "application identifier".
+ * The expected form of an application identifier is very close to that of
+ * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface";>DBus bus name</ulink>.
+ * For details on valid application identifiers, see
+ * g_application_id_is_valid().
+ * The application identifier is claimed by the application as a
+ * well-known bus name on the user's session bus. This means that the
+ * uniqueness of your application is scoped to the current session. It
+ * also means that your application may provide additional services
+ * (through registration of other object paths) at that bus name.
+ * The registration of these object paths should be done with the shared
+ * GDBus session bus. Note that due to the internal architecture of
+ * GDBus, method calls can be dispatched at any time (even if a main
+ * loop is not running). For this reason, you must ensure that any
+ * object paths that you wish to register are registered before
+ * #GApplication attempts to acquire the bus name of your application
+ * (which happens in g_application_register()). Unfortunately, this
+ * means that you cannot use g_application_get_is_remote() to decide if
+ * you want to register object paths.
+ * GApplication provides convenient life cycle management by maintaining
+ * a <firstterm>use count</firstterm> for the primary application instance.
+ * The use count can be changed using g_application_hold() and
+ * g_application_release(). If it drops to zero, the application exits.
+ * GApplication also implements the #GActionGroup interface and lets you
+ * easily export actions by adding them with g_application_set_action_group().
+ * When invoking an action by calling g_action_group_activate_action() on
+ * the application, it is always invoked in the primary instance.
+ * There is a number of different entry points into a #GApplication:
+ * <itemizedlist>
+ * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
+ * <listitem>via 'Open' (i.e. opening some files)</listitem>
+ * <listitem>by handling a command-line</listitem>
+ * <listitem>via activating an action</listitem>
+ * </itemizedlist>
+ * The #GApplication::startup signal lets you handle the application
+ * initialization for all of these in a single place.
+ * Regardless of which of these entry points is used to start the application,
+ * GApplication passes some <firstterm id="platform-data">platform
+ * data</firstterm> from the launching instance to the primary instance,
+ * in the form of a #GVariant dictionary mapping strings to variants.
+ * To use platform data, override the @before_emit or @after_emit virtual
+ * functions in your #GApplication subclass. When dealing with
+ * #GApplicationCommandline objects, the platform data is directly
+ * available via g_application_command_line_get_cwd(),
+ * g_application_command_line_get_environ() and
+ * g_application_command_line_get_platform_data().
+ * As the name indicates, the platform data may vary depending on the
+ * operating system, but it always includes the current directory (key
+ * "cwd"), and optionally the environment (ie the set of environment
+ * variables and their values) of the calling process (key "environ").
+ * The environment is only added to the platform data if the
+ * #G_APPLICATION_SEND_ENVIONMENT flag is set. GApplication subclasses
+ * can add their own platform data by overriding the @add_platform_data
+ * virtual function. For instance, #GtkApplication adds startup notification
+ * data in this way.
+ * To parse commandline arguments you may handle the
+ * #GApplication::command-line signal or override the local_command_line()
+ * vfunc, to parse them in either the primary instance or the local instance,
+ * respectively.
+ * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-open.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
+ * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
*
- * To construct a #gfile, you can use:
- * Other possible causes for aliases are: case insensitive filesystems, short
+ * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
*/
/**
- * SECTION:gfileattribute
- * @short_description: Key-Value Paired File Attributes
- * @include: gio/gio.h
- * @see_also: #GFile, #GFileInfo
+ * SECTION:gapplicationcommandline
+ * @title: GApplicationCommandLine
+ * @short_description: A command-line invocation of an application
+ * @see_also: #GApplication
*
- * File attributes in GIO consist of a list of key-value pairs.
- * Keys are strings that contain a key namespace and a key name, separated
- * by a colon, e.g. "namespace:keyname". Namespaces are included to sort
- * key-value pairs by namespaces for relevance. Keys can be retrived
- * using wildcards, e.g. "standard::*" will return all of the keys in the
- * "standard" namespace.
- * Values are stored within the list in #GFileAttributeValue structures.
- * Values can store different types, listed in the enum #GFileAttributeType.
- * Upon creation of a #GFileAttributeValue, the type will be set to
- * %G_FILE_ATTRIBUTE_TYPE_INVALID.
- * The list of possible attributes for a filesystem (pointed to by a #GFile) is
- * availible as a #GFileAttributeInfoList. This list is queryable by key names
- * as indicated earlier.
- * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
- * install default keys and values for their given file system, architecture,
- * and other possible implementation details (e.g., on a UNIX system, a file
- * attribute key will be registered for the user id for a given file).
- * <para>
- * <table>
- * <title>GFileAttributes Default Namespaces</title>
- * <tgroup cols='2' align='left'><thead>
- * <row><entry>Namspace</entry><entry>Description</entry></row>
- * </thead>
- * <tbody>
- * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file
- * information that any application may need should be put in this namespace.
- * Examples include the file's name, type, and size.</entry></row>
- * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link>
- * namespace. Currently, the only key in this namespace is "value", which contains
- * the value of the current entity tag.</entry></row>
- * <row><entry>"id"</entry><entry>The "Identification" namespace. This
- * namespace is used by file managers and applications that list directories
- * to check for loops and to uniquely identify files.</entry></row>
- * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check
- * if a user has the proper privilidges to access files and perform
- * file operations. Keys in this namespace are made to be generic
- * and easily understood, e.g. the "can_read" key is %TRUE if
- * the current user has permission to read the file. UNIX permissions and
- * NTFS ACLs in Windows should be mapped to these values.</entry></row>
- * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
- * simple boolean keys for checking if a file or path supports mount operations, e.g.
- * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row>
- * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
- * access, changed, created times. </entry></row>
- * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
- * information and may not be available for all files. Examples include
- * the UNIX "UID", "GID", etc.</entry></row>
- * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific
- * information and may not be available for all files. Examples include
- * "is_system" for checking if a file is marked as a system file, and "is_archive"
- * for checking if a file is marked as an archive file.</entry></row>
- * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
- * about who owns a file. May not be available for all file systems. Examples include
- * "user" for getting the user name of the file owner. This information is often mapped from
- * some backend specific data such as a unix UID.</entry></row>
- * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
- * information about file thumbnails and their location within the file system. Exaples of
- * keys in this namespace include "path" to get the location of a thumbnail, and "failed"
- * to check if thumbnailing of the file failed.</entry></row>
- * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information
- * about the file system where a file is located, such as its type, how much
- * space is left available, and the overall size of the file system.</entry></row>
- * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
- * contain information about the current GVFS backend in use. </entry></row>
- * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information
- * about extended user attributes. See attr(5). The "user." prefix of the
- * extended user attribute name is stripped away when constructing keys in
- * this namespace, e.g. "xattr::mime_type" for the extended attribute with
- * the name "user.mime_type". Note that this information is only available
- * if GLib has been built with extended attribute support.</entry></row>
- * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace.
- * Gets information about extended attributes which are not user-specific.
- * See attr(5). Note that this information is only available if GLib
- * has been built with extended attribute support.</entry></row>
- * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes
- * information about the SELinux context of files. Note that this information
- * is only available if GLib has been built with SELinux support.</entry></row>
- * </tbody>
- * </tgroup>
- * </table>
+ * #GApplicationCommandLine represents a command-line invocation of
+ * an application. It is created by #GApplication and emitted
+ * in the #GApplication::command-line signal and virtual function.
+ * The class contains the list of arguments that the program was invoked
+ * with. It is also possible to query if the commandline invocation was
+ * commandline to this process).
+ * The GApplicationCommandLine object can provide the @argc and @argv
+ * parameters for use with the #GOptionContext command-line parsing API,
+ * with the g_application_command_line_get_arguments() function. See
+ * <xref linkend="gapplication-example-cmdline3"/> for an example.
+ * The exit status of the originally-invoked process may be set and
+ * messages can be printed to stdout or stderr of that process. The
+ * lifecycle of the originally-invoked process is tied to the lifecycle
+ * dropped).
+ * The main use for #GApplicationCommandline (and the
+ * #GApplication::command-line signal) is 'Emacs server' like use cases:
+ * You can set the <envar>EDITOR</envar> environment variable to have
+ * e.g. git use your favourite editor to edit commit messages, and if you
+ * already have an instance of the editor running, the editing will happen
+ * in the running instance, instead of opening a new one. An important
+ * aspect of this use case is that the process that gets started by git
+ * does not return until the editing is done.
+ * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
+ * <para>
+ * A simple example where the commandline is completely handled
+ * in the #GApplication::command-line handler. The launching instance exits
+ * once the signal handler in the primary instance has returned, and the
+ * return value of the signal handler becomes the exit status of the launching
+ * instance.
* </para>
- * Please note that these are not all of the possible namespaces.
- * More namespaces can be added from GIO modules or by individual applications.
- * For more information about writing GIO modules, see #GIOModule.
- * <!-- TODO: Implementation note about using extended attributes on supported
- * file systems -->
- * <para><table>
- * <title>GFileAttributes Built-in Keys and Value Types</title>
- * <tgroup cols='3' align='left'><thead>
- * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row>
- * </thead><tbody>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
- * </tbody></tgroup></table></para>
- * Note that there are no predefined keys in the "xattr" and "xattr-sys"
- * namespaces. Keys for the "xattr" namespace are constructed by stripping
- * away the "user." prefix from the extended user attribute, and prepending
- * "xattr::". Keys for the "xattr-sys" namespace are constructed by
- * concatenating "xattr-sys::" with the extended attribute name. All extended
- * attribute values are returned as hex-encoded strings in which bytes outside
- * the ASCII range are encoded as hexadecimal escape sequences of the form
- * \x<replaceable>nn</replaceable>.
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
+ * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
+ * <para>
+ * An example of split commandline handling. Options that start with
+ * <literal>--local-</literal> are handled locally, all other options are
+ * passed to the #GApplication::command-line handler which runs in the primary
+ * instance.
+ * </para>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
+ * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
+ * <para>
+ * An example of deferred commandline handling. Here, the commandline is
+ * not completely handled before the #GApplication::command-line handler
+ * returns. Instead, we keep a reference to the GApplicationCommandline
+ * object and handle it later(in this example, in an idle). Note that it
+ * is necessary to hold the application until you are done with the
+ * commandline.
+ * </para>
+ * <para>
+ * This example also shows how to use #GOptionContext for parsing the
+ * commandline arguments. Note that it is necessary to disable the
+ * built-in help-handling of #GOptionContext, since it calls exit()
+ * after printing help, which is not what you want to happen in
+ * the primary instance.
+ * </para>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
+ *
+ * Local (ie: the current process is running in direct response to the
+ * Invocation) or remote (ie: some other process forwarded the
+ * Of this object (ie: the process exits when the last reference is
*/
/**
- * SECTION:gfiledescriptorbased
- * @short_description: Interface for file descriptor based IO
- * @include: gio/gfiledescriptorbased.h
- * @see_also: #GInputStream, #GOutputStream
+ * SECTION:gasynchelper
+ * @short_description: Asynchronous Helper Functions
+ * @include: gio/gio.h
+ * @see_also: #GAsyncReady
*
- * #GFileDescriptorBased is implemented by streams (implementations of
- * #GInputStream or #GOutputStream) that are based on file descriptors.
- * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Provides helper functions for asynchronous operations.
+ */
+
+
+/**
+ * SECTION:gasyncinitable
+ * @short_description: Asynchronously failable object initialization interface
+ * @include: gio/gio.h
+ * @see_also: #GInitable
+ *
+ * This is the asynchronous version of #GInitable; it behaves the same
+ * in all ways except that initialization is asynchronous. For more details
+ * see the descriptions on #GInitable.
+ * A class may implement both the #GInitable and #GAsyncInitable interfaces.
+ * Users of objects implementing this are not intended to use the interface
+ * method directly; instead it will be used automatically in various ways.
+ * For C applications you generally just call g_async_initable_new_async()
+ * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
+ * g_async_initable_init_async() under the cover, calling back with %NULL and
+ * a set %GError on failure.
+ * A typical implementation might look something like this:
+ * |[
+ * enum {
+ * NOT_INITIALIZED,
+ * INITIALIZING,
+ * INITIALIZED
+ * };
+ * static void
+ * _foo_ready_cb (Foo *self)
+ * {
+ * GList *l;
+ * self->priv->state = INITIALIZED;
+ * for (l = self->priv->init_results; l != NULL; l = l->next)
+ * {
+ * GSimpleAsyncResult *simple = l->data;
+ * if (!self->priv->success)
+ * g_simple_async_result_set_error (simple, ...);
+ * g_simple_async_result_complete (simple);
+ * g_object_unref (simple);
+ * }
+ * g_list_free (self->priv->init_results);
+ * self->priv->init_results = NULL;
+ * }
+ * static void
+ * foo_init_async (GAsyncInitable *initable,
+ * int io_priority,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * Foo *self = FOO (initable);
+ * GSimpleAsyncResult *simple;
+ * simple = g_simple_async_result_new (G_OBJECT (initable)
+ * callback,
+ * user_data,
+ * foo_init_async);
+ * switch (self->priv->state)
+ * {
+ * case NOT_INITIALIZED:
+ * _foo_get_ready (self);
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * simple);
+ * self->priv->state = INITIALIZING;
+ * break;
+ * case INITIALIZING:
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * simple);
+ * break;
+ * case INITIALIZED:
+ * if (!self->priv->success)
+ * g_simple_async_result_set_error (simple, ...);
+ * g_simple_async_result_complete_in_idle (simple);
+ * g_object_unref (simple);
+ * break;
+ * }
+ * }
+ * static gboolean
+ * foo_init_finish (GAsyncInitable *initable,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ * G_OBJECT (initable), foo_init_async), FALSE);
+ * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
+ * error))
+ * return FALSE;
+ * return TRUE;
+ * }
+ * static void
+ * foo_async_initable_iface_init (gpointer g_iface,
+ * gpointer data)
+ * {
+ * GAsyncInitableIface *iface = g_iface;
+ * iface->init_async = foo_init_async;
+ * iface->init_finish = foo_init_finish;
+ * }
+ * ]|
+ */
+
+
+/**
+ * SECTION:gasyncresult
+ * @short_description: Asynchronous Function Results
+ * @include: gio/gio.h
+ * @see_also: #GSimpleAsyncResult
+ *
+ * Provides a base class for implementing asynchronous function results.
+ * Asynchronous operations are broken up into two separate operations
+ * which are chained together by a #GAsyncReadyCallback. To begin
+ * an asynchronous operation, provide a #GAsyncReadyCallback to the
+ * asynchronous function. This callback will be triggered when the
+ * operation has completed, and will be passed a #GAsyncResult instance
+ * filled with the details of the operation's success or failure, the
+ * object the asynchronous function was started for and any error codes
+ * returned. The asynchronous callback function is then expected to call
+ * the corresponding "_finish()" function, passing the object the
+ * function was called for, the #GAsyncResult instance, and (optionally)
+ * an @error to grab any error conditions that may have occurred.
+ * The "_finish()" function for an operation takes the generic result
+ * (of type #GAsyncResult) and returns the specific result that the
+ * operation in question yields (e.g. a #GFileEnumerator for a
+ * "enumerate children" operation). If the result or error status of the
+ * operation is not needed, there is no need to call the "_finish()"
+ * function; GIO will take care of cleaning up the result and error
+ * information after the #GAsyncReadyCallback returns. Applications may
+ * also take a reference to the #GAsyncResult and call "_finish()"
+ * later; however, the "_finish()" function may be called at most once.
+ * Example of a typical asynchronous operation flow:
+ * |[
+ * void _theoretical_frobnitz_async (Theoretical *t,
+ * GCancellable *c,
+ * GAsyncReadyCallback *cb,
+ * gpointer u);
+ * gboolean _theoretical_frobnitz_finish (Theoretical *t,
+ * GAsyncResult *res,
+ * GError **e);
+ * static void
+ * frobnitz_result_func (GObject *source_object,
+ * GAsyncResult *res,
+ * gpointer user_data)
+ * {
+ * gboolean success = FALSE;
+ * success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ * if (success)
+ * g_printf ("Hurray!\n");
+ * else
+ * g_printf ("Uh oh!\n");
+ * /<!-- -->* ... *<!-- -->/
+ * }
+ * int main (int argc, void *argv[])
+ * {
+ * /<!-- -->* ... *<!-- -->/
+ * _theoretical_frobnitz_async (theoretical_data,
+ * NULL,
+ * frobnitz_result_func,
+ * NULL);
+ * /<!-- -->* ... *<!-- -->/
+ * }
+ * ]|
+ * The callback for an asynchronous operation is called only once, and is
+ * always called, even in the case of a cancelled operation. On cancellation
+ * the result is a %G_IO_ERROR_CANCELLED error.
+ * Some asynchronous operations are implemented using synchronous calls.
+ * These are run in a separate thread, if #GThread has been initialized, but
+ * otherwise they are sent to the Main Event Loop and processed in an idle
+ * function. So, if you truly need asynchronous operations, make sure to
+ * initialize #GThread.
+ */
+
+
+/**
+ * SECTION:gbufferedinputstream
+ * @short_description: Buffered Input Stream
+ * @include: gio/gio.h
+ * @see_also: #GFilterInputStream, #GInputStream
+ *
+ * Buffered input stream implements #GFilterInputStream and provides
+ * for buffered reads.
+ * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
+ * To create a buffered input stream, use g_buffered_input_stream_new(),
+ * or g_buffered_input_stream_new_sized() to specify the buffer's size at
+ * construction.
+ * To get the size of a buffer within a buffered input stream, use
+ * g_buffered_input_stream_get_buffer_size(). To change the size of a
+ * buffered input stream's buffer, use
+ * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
+ * cannot be reduced below the size of the data within the buffer.
+ */
+
+
+/**
+ * SECTION:gbufferedoutputstream
+ * @short_description: Buffered Output Stream
+ * @include: gio/gio.h
+ * @see_also: #GFilterOutputStream, #GOutputStream
+ *
+ * Buffered output stream implements #GFilterOutputStream and provides
+ * for buffered writes.
+ * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
+ * To create a buffered output stream, use g_buffered_output_stream_new(),
+ * or g_buffered_output_stream_new_sized() to specify the buffer's size
+ * at construction.
+ * To get the size of a buffer within a buffered input stream, use
+ * g_buffered_output_stream_get_buffer_size(). To change the size of a
+ * buffered output stream's buffer, use
+ * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
+ * size cannot be reduced below the size of the data within the buffer.
+ */
+
+
+/**
+ * SECTION:gcancellable
+ * @short_description: Thread-safe Operation Cancellation Stack
+ * @include: gio/gio.h
+ *
+ * GCancellable is a thread-safe operation cancellation stack used
+ * throughout GIO to allow for cancellation of synchronous and
+ * asynchronous operations.
+ */
+
+
+/**
+ * SECTION:gcharsetconverter
+ * @short_description: Convert between charsets
+ * @include: gio/gio.h
+ *
+ * #GCharsetConverter is an implementation of #GConverter based on
+ * GIConv.
+ */
+
+
+/**
+ * SECTION:gcontenttype
+ * @short_description: Platform-specific content typing
+ * @include: gio/gio.h
+ *
+ * A content type is a platform specific string that defines the type
+ * of a file. On UNIX it is a <ulink url="http://www.wikipedia.org/wiki/Internet_media_type";>mime type</ulink> like "text/plain" or "image/png".
+ * On Win32 it is an extension string like ".doc", ".txt" or a perceived
+ * string like "audio". Such strings can be looked up in the registry at
+ * HKEY_CLASSES_ROOT.
+ */
+
+
+/**
+ * SECTION:gconverter
+ * @short_description: Data conversion interface
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
+ *
+ * #GConverter is implemented by objects that convert
+ * binary data in various ways. The conversion can be
+ * stateful and may fail at any place.
+ * compression, decompression and regular expression
+ * replace.
+ *
+ * Some example conversions are: character set conversion,
+ * Since: 2.24
+ */
+
+
+/**
+ * SECTION:gconverterinputstream
+ * @short_description: Converter Input Stream
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GConverter
+ *
+ * Converter input stream implements #GInputStream and allows
+ * conversion of data of various types during reading.
+ */
+
+
+/**
+ * SECTION:gconverteroutputstream
+ * @short_description: Converter Output Stream
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream, #GConverter
+ *
+ * Converter output stream implements #GOutputStream and allows
+ * conversion of data of various types during reading.
+ */
+
+
+/**
+ * SECTION:gcredentials
+ * @short_description: An object containing credentials
+ * @include: gio/gio.h
+ *
+ * The #GCredentials type is a reference-counted wrapper for native
+ * credentials. This information is typically used for identifying,
+ * authenticating and authorizing other processes.
+ * Some operating systems supports looking up the credentials of the
+ * remote peer of a communication endpoint - see e.g.
+ * g_socket_get_credentials().
+ * Some operating systems supports securely sending and receiving
+ * credentials over a Unix Domain Socket, see
+ * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
+ * g_unix_connection_receive_credentials() for details.
+ * On Linux, the native credential type is a <type>struct ucred</type>
+ * - see the
+ * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ * man page for details. This corresponds to
+ * %G_CREDENTIALS_TYPE_LINUX_UCRED.
+ * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>.
+ * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
+ * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
+ * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
+ */
+
+
+/**
+ * SECTION:gdatainputstream
+ * @short_description: Data Input Stream
+ * @include: gio/gio.h
+ * @see_also: #GInputStream
+ *
+ * Data input stream implements #GInputStream and includes functions for
+ * reading structured data directly from a binary input stream.
+ */
+
+
+/**
+ * SECTION:gdataoutputstream
+ * @short_description: Data Output Stream
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream
+ *
+ * Data output stream implements #GOutputStream and includes functions for
+ * writing data directly to an output stream.
+ */
+
+
+/**
+ * SECTION:gdbusaddress
+ * @title: D-Bus Addresses
+ * @short_description: D-Bus connection endpoints
+ * @include: gio/gio.h
+ *
+ * Routines for working with D-Bus addresses. A D-Bus address is a string
+ * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
+ * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses";>D-Bus specification</link>.
+ */
+
+
+/**
+ * SECTION:gdbusauthobserver
+ * @short_description: Object used for authenticating connections
+ * @include: gio/gio.h
+ *
+ * The #GDBusAuthObserver type provides a mechanism for participating
+ * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
+ * peers. Simply instantiate a #GDBusAuthObserver and connect to the
+ * signals you are interested in. Note that new signals may be added
+ * in the future
+ * For example, if you only want to allow D-Bus connections from
+ * processes owned by the same uid as the server, you would use a
+ * signal handler like the following:
+ * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
+ * static gboolean
+ * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
+ * GIOStream *stream,
+ * GCredentials *credentials,
+ * gpointer user_data)
+ * {
+ * gboolean authorized;
+ * authorized = FALSE;
+ * if (credentials != NULL)
+ * {
+ * GCredentials *own_credentials;
+ * own_credentials = g_credentials_new ();
+ * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
+ * authorized = TRUE;
+ * g_object_unref (own_credentials);
+ * }
+ * return authorized;
+ * }
+ * </programlisting></example>
+ */
+
+
+/**
+ * SECTION:gdbusconnection
+ * @short_description: D-Bus Connections
+ * @include: gio/gio.h
+ *
+ * The #GDBusConnection type is used for D-Bus connections to remote
+ * peers such as a message buses. It is a low-level API that offers a
+ * lot of flexibility. For instance, it lets you establish a connection
+ * over any transport that can by represented as an #GIOStream.
+ * This class is rarely used directly in D-Bus clients. If you are writing
+ * an D-Bus client, it is often easier to use the g_bus_own_name(),
+ * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
+ * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ */
+
+
+/**
+ * SECTION:gdbuserror
+ * @title: GDBusError
+ * @short_description: Mapping D-Bus errors to and from GError
+ * @include: gio/gio.h
+ *
+ * All facilities that return errors from remote methods (such as
+ * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
+ * errors (e.g. errors returned from the other peer) and locally
+ * in-process generated errors.
+ * To check if a returned #GError is an error from a remote peer, use
+ * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
+ * use g_dbus_error_get_remote_error(). Before presenting an error,
+ * always use g_dbus_error_strip_remote_error().
+ * In addition, facilities used to return errors to a remote peer also
+ * use #GError. See g_dbus_method_invocation_return_error() for
+ * discussion about how the D-Bus error name is set.
+ * Applications can associate a #GError error domain with a set of D-Bus errors in order to
+ * automatically map from D-Bus errors to #GError and back. This
+ * is typically done in the function returning the #GQuark for the
+ * error domain:
+ * <example id="error-registration"><title>Error Registration</title><programlisting>
+ * /<!-- -->* foo-bar-error.h: *<!-- -->/
+ * #define FOO_BAR_ERROR (foo_bar_error_quark ())
+ * GQuark foo_bar_error_quark (void);
+ * typedef enum
+ * {
+ * FOO_BAR_ERROR_FAILED,
+ * FOO_BAR_ERROR_ANOTHER_ERROR,
+ * FOO_BAR_ERROR_SOME_THIRD_ERROR,
+ * } FooBarError;
+ * /<!-- -->* foo-bar-error.c: *<!-- -->/
+ * static const GDBusErrorEntry foo_bar_error_entries[] =
+ * {
+ * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
+ * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
+ * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
+ * };
+ * GQuark
+ * foo_bar_error_quark (void)
+ * {
+ * static volatile gsize quark_volatile = 0;
+ * g_dbus_error_register_error_domain ("foo-bar-error-quark",
+ * &quark_volatile,
+ * foo_bar_error_entries,
+ * G_N_ELEMENTS (foo_bar_error_entries));
+ * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR);
+ * return (GQuark) quark_volatile;
+ * }
+ * </programlisting></example>
+ * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
+ * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>.
+ * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
+ * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
+ * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
+ * Note that errors in the %G_DBUS_ERROR error domain is intended only
+ * for returning errors from a remote message bus process. Errors
+ * generated locally in-process by e.g. #GDBusConnection is from the
+ * %G_IO_ERROR domain.
+ */
+
+
+/**
+ * SECTION:gdbusinterface
+ * @short_description: Base type for D-Bus interfaces
+ * @include: gio/gio.h
+ *
+ * The #GDBusInterface type is the base type for D-Bus interfaces both
+ * on the service side (see #GDBusInterfaceSkeleton) and client side
+ * (see #GDBusProxy).
+ */
+
+
+/**
+ * SECTION:gdbusinterfaceskeleton
+ * @short_description: Service-side D-Bus interface
+ * @include: gio/gio.h
+ *
+ * Abstract base class for D-Bus interfaces on the service side.
+ */
+
+
+/**
+ * SECTION:gdbusintrospection
+ * @title: D-Bus Introspection Data
+ * @short_description: Node and interface description data structures
+ * @include: gio/gio.h
+ *
+ * Various data structures and convenience routines to parse and
+ * generate D-Bus introspection XML. Introspection information is
+ * used when registering objects with g_dbus_connection_register_object().
+ * The format of D-Bus introspection XML is specified in the
+ * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format";>D-Bus specification</link>.
+ */
+
+
+/**
+ * SECTION:gdbusmessage
+ * @short_description: D-Bus Message
+ * @include: gio/gio.h
+ *
+ * A type for representing D-Bus messages that can be sent or received
+ * on a #GDBusConnection.
+ */
+
+
+/**
+ * SECTION:gdbusmethodinvocation
+ * @short_description: Object for handling remote calls
+ * @include: gio/gio.h
+ *
+ * Instances of the #GDBusMethodInvocation class are used when
+ * handling D-Bus method calls. It provides a way to asynchronously
+ * return results and errors.
+ * The normal way to obtain a #GDBusMethodInvocation object is to receive
+ * it as an argument to the handle_method_call() function in a
+ * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
+ */
+
+
+/**
+ * SECTION:gdbusnameowning
+ * @title: Owning Bus Names
+ * @short_description: Simple API for owning bus names
+ * @include: gio/gio.h
+ *
+ * Convenience API for owning bus names.
+ * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ */
+
+
+/**
+ * SECTION:gdbusnamewatching
+ * @title: Watching Bus Names
+ * @short_description: Simple API for watching bus names
+ * @include: gio/gio.h
+ *
+ * Convenience API for watching bus names.
+ * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ */
+
+
+/**
+ * SECTION:gdbusobject
+ * @short_description: Base type for D-Bus objects
+ * @include: gio/gio.h
+ *
+ * The #GDBusObject type is the base type for D-Bus objects on both
+ * the service side (see #GDBusObjectSkeleton) and the client side
+ * (see #GDBusObjectProxy). It is essentially just a container of
+ * interfaces.
+ */
+
+
+/**
+ * SECTION:gdbusobjectmanager
+ * @short_description: Base type for D-Bus object managers
+ * @include: gio/gio.h
+ *
+ * The #GDBusObjectManager type is the base type for service- and
+ * client-side implementations of the standardized <ulink
+ * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager";>org.freedesktop.DBus.ObjectManager</ulink>
+ * interface.
+ * See #GDBusObjectManagerClient for the client-side implementation
+ * and #GDBusObjectManagerServer for the service-side implementation.
+ */
+
+
+/**
+ * SECTION:gdbusobjectmanagerclient
+ * @short_description: Client-side object manager
+ * @include: gio/gio.h
+ *
+ * #GDBusObjectManagerClient is used to create, monitor and delete object
+ * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
+ * code implementing the <ulink
+ * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager";>org.freedesktop.DBus.ObjectManager</ulink>
+ * interface).
+ * Once an instance of this type has been created, you can connect to
+ * the #GDBusObjectManager::object-added and
+ * #GDBusObjectManager::object-removed signals and inspect the
+ * #GDBusObjectProxy objects returned by
+ * g_dbus_object_manager_get_objects().
+ * If the name for a #GDBusObjectManagerClient is not owned by anyone at
+ * object construction time, the default behavior is to request the
+ * message bus to launch an owner for the name. This behavior can be
+ * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
+ * flag. It's also worth noting that this only works if the name of
+ * interest is activatable in the first place. E.g. in some cases it
+ * is not possible to launch an owner for the requested name. In this
+ * case, #GDBusObjectManagerClient object construction still succeeds but
+ * there will be no object proxies
+ * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
+ * the #GDBusObjectManagerClient:name-owner property is %NULL.
+ * The owner of the requested name can come and go (for example
+ * consider a system service being restarted) â?? #GDBusObjectManagerClient
+ * handles this case too; simply connect to the #GObject::notify
+ * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
+ * property. When the name owner vanishes, the behavior is that
+ * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
+ * emission of the #GObject::notify signal) and then
+ * #GDBusObjectManager::object-removed signals are synthesized
+ * for all currently existing object proxies. Since
+ * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
+ * use this information to disambiguate a synthesized signal from a
+ * genuine signal caused by object removal on the remote
+ * #GDBusObjectManager. Similarly, when a new name owner appears,
+ * #GDBusObjectManager::object-added signals are synthesized
+ * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
+ * object proxies have been added, the #GDBusObjectManagerClient:name-owner
+ * is set to the new name owner (this includes emission of the
+ * #GObject::notify signal). Furthermore, you are guaranteed that
+ * #GDBusObjectManagerClient:name-owner will alternate between a name owner
+ * (e.g. <literal>:1.42</literal>) and %NULL even in the case where
+ * the name of interest is atomically replaced
+ * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
+ * instances. All signals (including the
+ * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
+ * signal) delivered to #GDBusProxy instances are guaranteed to
+ * originate from the name owner. This guarantee along with the
+ * behavior described above, means that certain race conditions
+ * including the <emphasis><quote>half the proxy is from the old owner
+ * and the other half is from the new owner</quote></emphasis> problem
+ * cannot happen.
+ * To avoid having the application connect to signals on the returned
+ * #GDBusObjectProxy and #GDBusProxy objects, the
+ * #GDBusObject::interface-added,
+ * #GDBusObject::interface-removed,
+ * #GDBusProxy::g-properties-changed and
+ * #GDBusProxy::g-signal signals
+ * are also emitted on the #GDBusObjectManagerClient instance managing these
+ * objects. The signals emitted are
+ * #GDBusObjectManager::interface-added,
+ * #GDBusObjectManager::interface-removed,
+ * #GDBusObjectManagerClient::interface-proxy-properties-changed and
+ * #GDBusObjectManagerClient::interface-proxy-signal.
+ * Note that all callbacks and signals are emitted in the
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * that the #GDBusObjectManagerClient object was constructed
+ * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
+ * originating from the #GDBusObjectManagerClient object will be created in
+ * the same context and, consequently, will deliver signals in the
+ * same main loop.
+ */
+
+
+/**
+ * SECTION:gdbusobjectmanagerserver
+ * @short_description: Service-side object manager
+ * @include: gio/gio.h
+ *
+ * #GDBusObjectManagerServer is used to export #GDBusObject instances using
+ * the standardized <ulink
+ * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager";>org.freedesktop.DBus.ObjectManager</ulink>
+ * interface. For example, remote D-Bus clients can get all objects
+ * and properties in a single call. Additionally, any change in the
+ * object hierarchy is broadcast using signals. This means that D-Bus
+ * clients can keep caches up to date by only listening to D-Bus
+ * signals.
+ * See #GDBusObjectManagerClient for the client-side code that is
+ * intended to be used with #GDBusObjectManagerServer or any D-Bus
+ * object implementing the org.freedesktop.DBus.ObjectManager
+ * interface.
+ */
+
+
+/**
+ * SECTION:gdbusobjectproxy
+ * @short_description: Client-side D-Bus object
+ * @include: gio/gio.h
+ *
+ * A #GDBusObjectProxy is an object used to represent a remote object
+ * with one or more D-Bus interfaces. Normally, you don't instantiate
+ * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
+ * is used to obtain it.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * SECTION:gdbusobjectskeleton
+ * @short_description: Service-side D-Bus object
+ * @include: gio/gio.h
+ *
+ * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
+ * interfaces. The set of exported interfaces on the object may be
+ * dynamic and change at runtime.
+ * This type is intended to be used with #GDBusObjectManager.
+ */
+
+
+/**
+ * SECTION:gdbusproxy
+ * @short_description: Client-side D-Bus interface proxy
+ * @include: gio/gio.h
+ *
+ * #GDBusProxy is a base class used for proxies to access a D-Bus
+ * interface on a remote object. A #GDBusProxy can be constructed for
+ * both well-known and unique names.
+ * By default, #GDBusProxy will cache all properties (and listen to
+ * changes) of the remote object, and proxy all signals that gets
+ * emitted. This behaviour can be changed by passing suitable
+ * #GDBusProxyFlags when the proxy is created. If the proxy is for a
+ * well-known name, the property cache is flushed when the name owner
+ * vanishes and reloaded when a name owner appears.
+ * If a #GDBusProxy is used for a well-known name, the owner of the
+ * name is tracked and can be read from
+ * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
+ * get notified of changes. Additionally, only signals and property
+ * changes emitted from the current name owner are considered and
+ * calls are always sent to the current name owner. This avoids a
+ * number of race conditions when the name is lost by one owner and
+ * claimed by another. However, if no name owner currently exists,
+ * then calls will be sent to the well-known name which may result in
+ * the message bus launching an owner (unless
+ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
+ * The generic #GDBusProxy::g-properties-changed and
+ * #GDBusProxy::g-signal signals are not very convenient to work
+ * with. Therefore, the recommended way of working with proxies is to
+ * subclass #GDBusProxy, and have more natural properties and signals
+ * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/>
+ * for how this can easily be done using the
+ * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command>
+ * tool.
+ * A #GDBusProxy instance can be used from multiple threads but note
+ * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
+ * and #GObject::notify) are emitted in the
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread where the instance was constructed.
+ * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ */
+
+
+/**
+ * SECTION:gdbusserver
+ * @short_description: Helper for accepting connections
+ * @include: gio/gio.h
+ *
+ * #GDBusServer is a helper for listening to and accepting D-Bus
+ * connections. This can be used to create a new D-Bus server, allowing two
+ * peers to use the D-Bus protocol for their own specialized communication.
+ * A server instance provided in this way will not perform message routing or
+ * implement the org.freedesktop.DBus interface.
+ * To just export an object on a well-known name on a message bus, such as the
+ * session or system bus, you should instead use g_bus_own_name().
+ * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ */
+
+
+/**
+ * SECTION:gdbusutils
+ * @title: D-Bus Utilities
+ * @short_description: Various utilities related to D-Bus.
+ * @include: gio/gio.h
+ *
+ * Various utility routines related to D-Bus.
+ */
+
+
+/**
+ * SECTION:gdesktopappinfo
+ * @title: GDesktopAppInfo
+ * @short_description: Application information from desktop files
+ * @include: gio/gdesktopappinfo.h
+ *
+ * #GDesktopAppInfo is an implementation of #GAppInfo based on
+ * desktop files.
+ * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to
+ * the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ */
+
+
+/**
+ * SECTION:gdrive
+ * @short_description: Drive management
+ * @include: gio/gio.h
+ *
+ * #GDrive - this represent a piece of hardware connected to the machine.
+ * It's generally only created for removable hardware or hardware with
+ * removable media.
+ * #GDrive is a container class for #GVolume objects that stem from
+ * the same piece of media. As such, #GDrive abstracts a drive with
+ * (or without) removable media and provides operations for querying
+ * whether media is available, determing whether media change is
+ * automatically detected and ejecting the media.
+ * If the #GDrive reports that media isn't automatically detected, one
+ * can poll for media; typically one should not do this periodically
+ * as a poll for media operation is potententially expensive and may
+ * spin up the drive creating noise.
+ * #GDrive supports starting and stopping drives with authentication
+ * support for the former. This can be used to support a diverse set
+ * of use cases including connecting/disconnecting iSCSI devices,
+ * powering down external disk enclosures and starting/stopping
+ * multi-disk devices such as RAID devices. Note that the actual
+ * semantics and side-effects of starting/stopping a #GDrive may vary
+ * according to implementation. To choose the correct verbs in e.g. a
+ * file manager, use g_drive_get_start_stop_type().
+ * For porting from GnomeVFS note that there is no equivalent of
+ * #GDrive in that API.
+ */
+
+
+/**
+ * SECTION:gemblem
+ * @short_description: An object for emblems
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
+ *
+ * #GEmblem is an implementation of #GIcon that supports
+ * having an emblem, which is an icon with additional properties.
+ * It can than be added to a #GEmblemedIcon.
+ * Currently, only metainformation about the emblem's origin is
+ * supported. More may be added in the future.
+ */
+
+
+/**
+ * SECTION:gemblemedicon
+ * @short_description: Icon with emblems
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
+ *
+ * #GEmblemedIcon is an implementation of #GIcon that supports
+ * adding an emblem to an icon. Adding multiple emblems to an
+ * icon is ensured via g_emblemed_icon_add_emblem().
+ * Note that #GEmblemedIcon allows no control over the position
+ * of the emblems. See also #GEmblem for more information.
+ */
+
+
+/**
+ * SECTION:gfile
+ * @short_description: File and Directory Handling
+ * @include: gio/gio.h
+ * @see_also: #GFileInfo, #GFileEnumerator
+ *
+ * #GFile is a high level abstraction for manipulating files on a
+ * virtual file system. #GFile<!-- -->s are lightweight, immutable
+ * objects that do no I/O upon creation. It is necessary to understand that
+ * #GFile objects do not represent files, merely an identifier for a file. All
+ * file content I/O is implemented as streaming operations (see #GInputStream and
+ * #GOutputStream).
+ * g_file_new_for_path() if you have a path.
+ * g_file_new_for_uri() if you have a URI.
+ * g_file_new_for_commandline_arg() for a command line argument.
+ * g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name().
+ * One way to think of a #GFile is as an abstraction of a pathname. For normal
+ * files the system pathname is what is stored internally, but as #GFile<!-- -->s
+ * are extensible it could also be something else that corresponds to a pathname
+ * in a userspace implementation of a filesystem.
+ * #GFile<!-- -->s make up hierarchies of directories and files that correspond to the
+ * files on a filesystem. You can move through the file system with #GFile using
+ * g_file_get_parent() to get an identifier for the parent directory, g_file_get_child()
+ * to get a child within a directory, g_file_resolve_relative_path() to resolve a relative
+ * path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not
+ * end up at the same root if you repeatedly call g_file_get_parent() on two different
+ * files.
+ * All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names
+ * are byte strings that are used to identify the file on the filesystem (relative to
+ * its parent directory) and there is no guarantees that they have any particular charset
+ * encoding or even make any sense at all. If you want to use filenames in a user
+ * interface you should use the display name that you can get by requesting the
+ * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
+ * This is guaranteed to be in utf8 and can be used in a user interface. But always
+ * store the real basename or the #GFile to use to actually access the file, because
+ * there is no way to go from a display name to the actual name.
+ * Using #GFile as an identifier has the same weaknesses as using a path in that
+ * there may be multiple aliases for the same file. For instance, hard or
+ * soft links may cause two different #GFile<!-- -->s to refer to the same file.
+ * and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if
+ * two #GFile<!-- -->s point to the same file you can query for the
+ * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
+ * canonicalization of pathnames passed in, so that trivial differences in the
+ * path string used at creation (duplicated slashes, slash at end of path, "."
+ * or ".." path segments, etc) does not create different #GFile<!-- -->s.
+ * Many #GFile operations have both synchronous and asynchronous versions
+ * to suit your application. Asynchronous versions of synchronous functions
+ * simply have _async() appended to their function names. The asynchronous
+ * I/O functions call a #GAsyncReadyCallback which is then used to finalize
+ * the operation, producing a GAsyncResult which is then passed to the
+ * function's matching _finish() operation.
+ * Some #GFile operations do not have synchronous analogs, as they may
+ * take a very long time to finish, and blocking may leave an application
+ * unusable. Notable cases include:
+ * g_file_mount_mountable() to mount a mountable file.
+ * g_file_unmount_mountable_with_operation() to unmount a mountable file.
+ * g_file_eject_mountable_with_operation() to eject a mountable file.
+ * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
+ * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for
+ * short. Entity tags are somewhat like a more abstract version of the
+ * traditional mtime, and can be used to quickly determine if the file has
+ * been modified from the version on the file system. See the HTTP 1.1
+ * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html";>specification</ulink>
+ * for HTTP Etag headers, which are a very similar concept.
+ * </para>
+ *
+ * To construct a #gfile, you can use:
+ * Other possible causes for aliases are: case insensitive filesystems, short
+ */
+
+
+/**
+ * SECTION:gfileattribute
+ * @short_description: Key-Value Paired File Attributes
+ * @include: gio/gio.h
+ * @see_also: #GFile, #GFileInfo
+ *
+ * File attributes in GIO consist of a list of key-value pairs.
+ * Keys are strings that contain a key namespace and a key name, separated
+ * by a colon, e.g. "namespace:keyname". Namespaces are included to sort
+ * key-value pairs by namespaces for relevance. Keys can be retrived
+ * using wildcards, e.g. "standard::*" will return all of the keys in the
+ * "standard" namespace.
+ * Values are stored within the list in #GFileAttributeValue structures.
+ * Values can store different types, listed in the enum #GFileAttributeType.
+ * Upon creation of a #GFileAttributeValue, the type will be set to
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ * The list of possible attributes for a filesystem (pointed to by a #GFile) is
+ * availible as a #GFileAttributeInfoList. This list is queryable by key names
+ * as indicated earlier.
+ * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
+ * install default keys and values for their given file system, architecture,
+ * and other possible implementation details (e.g., on a UNIX system, a file
+ * attribute key will be registered for the user id for a given file).
+ * <para>
+ * <table>
+ * <title>GFileAttributes Default Namespaces</title>
+ * <tgroup cols='2' align='left'><thead>
+ * <row><entry>Namspace</entry><entry>Description</entry></row>
+ * </thead>
+ * <tbody>
+ * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file
+ * information that any application may need should be put in this namespace.
+ * Examples include the file's name, type, and size.</entry></row>
+ * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link>
+ * namespace. Currently, the only key in this namespace is "value", which contains
+ * the value of the current entity tag.</entry></row>
+ * <row><entry>"id"</entry><entry>The "Identification" namespace. This
+ * namespace is used by file managers and applications that list directories
+ * to check for loops and to uniquely identify files.</entry></row>
+ * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check
+ * if a user has the proper privilidges to access files and perform
+ * file operations. Keys in this namespace are made to be generic
+ * and easily understood, e.g. the "can_read" key is %TRUE if
+ * the current user has permission to read the file. UNIX permissions and
+ * NTFS ACLs in Windows should be mapped to these values.</entry></row>
+ * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
+ * simple boolean keys for checking if a file or path supports mount operations, e.g.
+ * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row>
+ * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
+ * access, changed, created times. </entry></row>
+ * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
+ * information and may not be available for all files. Examples include
+ * the UNIX "UID", "GID", etc.</entry></row>
+ * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific
+ * information and may not be available for all files. Examples include
+ * "is_system" for checking if a file is marked as a system file, and "is_archive"
+ * for checking if a file is marked as an archive file.</entry></row>
+ * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
+ * about who owns a file. May not be available for all file systems. Examples include
+ * "user" for getting the user name of the file owner. This information is often mapped from
+ * some backend specific data such as a unix UID.</entry></row>
+ * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
+ * information about file thumbnails and their location within the file system. Exaples of
+ * keys in this namespace include "path" to get the location of a thumbnail, and "failed"
+ * to check if thumbnailing of the file failed.</entry></row>
+ * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information
+ * about the file system where a file is located, such as its type, how much
+ * space is left available, and the overall size of the file system.</entry></row>
+ * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
+ * contain information about the current GVFS backend in use. </entry></row>
+ * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information
+ * about extended user attributes. See attr(5). The "user." prefix of the
+ * extended user attribute name is stripped away when constructing keys in
+ * this namespace, e.g. "xattr::mime_type" for the extended attribute with
+ * the name "user.mime_type". Note that this information is only available
+ * if GLib has been built with extended attribute support.</entry></row>
+ * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace.
+ * Gets information about extended attributes which are not user-specific.
+ * See attr(5). Note that this information is only available if GLib
+ * has been built with extended attribute support.</entry></row>
+ * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes
+ * information about the SELinux context of files. Note that this information
+ * is only available if GLib has been built with SELinux support.</entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ * </para>
+ * Please note that these are not all of the possible namespaces.
+ * More namespaces can be added from GIO modules or by individual applications.
+ * For more information about writing GIO modules, see #GIOModule.
+ * <!-- TODO: Implementation note about using extended attributes on supported
+ * file systems -->
+ * <para><table>
+ * <title>GFileAttributes Built-in Keys and Value Types</title>
+ * <tgroup cols='3' align='left'><thead>
+ * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row>
+ * </thead><tbody>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
+ * </tbody></tgroup></table></para>
+ * Note that there are no predefined keys in the "xattr" and "xattr-sys"
+ * namespaces. Keys for the "xattr" namespace are constructed by stripping
+ * away the "user." prefix from the extended user attribute, and prepending
+ * "xattr::". Keys for the "xattr-sys" namespace are constructed by
+ * concatenating "xattr-sys::" with the extended attribute name. All extended
+ * attribute values are returned as hex-encoded strings in which bytes outside
+ * the ASCII range are encoded as hexadecimal escape sequences of the form
+ * \x<replaceable>nn</replaceable>.
+ */
+
+
+/**
+ * SECTION:gfiledescriptorbased
+ * @short_description: Interface for file descriptor based IO
+ * @include: gio/gfiledescriptorbased.h
+ * @see_also: #GInputStream, #GOutputStream
+ *
+ * #GFileDescriptorBased is implemented by streams (implementations of
+ * #GInputStream or #GOutputStream) that are based on file descriptors.
+ * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to
+ * the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ *
+ * Since: 2.24
+ */
+
+
+/**
+ * SECTION:gfileenumerator
+ * @short_description: Enumerated Files Routines
+ * @include: gio/gio.h
+ *
+ * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
+ * returning a #GFileInfo structure for each file enumerated (e.g.
+ * g_file_enumerate_children() will return a #GFileEnumerator for each
+ * of the children within a directory).
+ * To get the next file's information from a #GFileEnumerator, use
+ * g_file_enumerator_next_file() or its asynchronous version,
+ * g_file_enumerator_next_files_async(). Note that the asynchronous
+ * version will return a list of #GFileInfo<!---->s, whereas the
+ * synchronous will only return the next file in the enumerator.
+ * To close a #GFileEnumerator, use g_file_enumerator_close(), or
+ * its asynchronous version, g_file_enumerator_close_async(). Once
+ * a #GFileEnumerator is closed, no further actions may be performed
+ * on it, and it should be freed with g_object_unref().
+ */
+
+
+/**
+ * SECTION:gfileicon
+ * @short_description: Icons pointing to an image file
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon
+ *
+ * #GFileIcon specifies an icon by pointing to an image file
+ * to be used as icon.
+ */
+
+
+/**
+ * SECTION:gfileinfo
+ * @short_description: File Information and Attributes
+ * @include: gio/gio.h
+ * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
+ *
+ * Functionality for manipulating basic metadata for files. #GFileInfo
+ * implements methods for getting information that all files should
+ * contain, and allows for manipulation of extended attributes.
+ * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
+ * information on how GIO handles file attributes.
+ * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
+ * async variant). To obtain a #GFileInfo for a file input or output
+ * stream, use g_file_input_stream_query_info() or
+ * g_file_output_stream_query_info() (or their async variants).
+ * To change the actual attributes of a file, you should then set the
+ * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
+ * or g_file_set_attributes_async() on a GFile.
+ * However, not all attributes can be changed in the file. For instance,
+ * the actual size of a file cannot be changed via g_file_info_set_size().
+ * You may call g_file_query_settable_attributes() and
+ * g_file_query_writable_namespaces() to discover the settable attributes
+ * of a particular file at runtime.
+ * #GFileAttributeMatcher allows for searching through a #GFileInfo for
+ * attributes.
+ */
+
+
+/**
+ * SECTION:gfileinputstream
+ * @short_description: File input streaming operations
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GDataInputStream, #GSeekable
+ *
+ * GFileInputStream provides input streams that take their
+ * content from a file.
+ * GFileInputStream implements #GSeekable, which allows the input
+ * stream to jump to arbitrary positions in the file, provided the
+ * filesystem of the file allows it. To find the position of a file
+ * input stream, use g_seekable_tell(). To find out if a file input
+ * stream supports seeking, use g_seekable_stream_can_seek().
+ * To position a file input stream, use g_seekable_seek().
+ */
+
+
+/**
+ * SECTION:gfileiostream
+ * @short_description: File read and write streaming operations
+ * @include: gio/gio.h
+ * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
+ *
+ * GFileIOStream provides io streams that both read and write to the same
+ * file handle.
+ * GFileIOStream implements #GSeekable, which allows the io
+ * stream to jump to arbitrary positions in the file and to truncate
+ * the file, provided the filesystem of the file supports these
+ * operations.
+ * To find the position of a file io stream, use
+ * g_seekable_tell().
+ * To find out if a file io stream supports seeking, use g_seekable_can_seek().
+ * To position a file io stream, use g_seekable_seek().
+ * To find out if a file io stream supports truncating, use
+ * g_seekable_can_truncate(). To truncate a file io
+ * stream, use g_seekable_truncate().
+ * The default implementation of all the #GFileIOStream operations
+ * and the implementation of #GSeekable just call into the same operations
+ * on the output stream.
+ *
+ * Since: 2.22
+ */
+
+
+/**
+ * SECTION:gfilemonitor
+ * @short_description: File Monitor
+ * @include: gio/gio.h
+ *
+ * Monitors a file or directory for changes.
+ * To obtain a #GFileMonitor for a file or directory, use
+ * g_file_monitor(), g_file_monitor_file(), or
+ * g_file_monitor_directory().
+ * To get informed about changes to the file or directory you are
+ * monitoring, connect to the #GFileMonitor::changed signal. The
+ * signal will be emitted in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * context</link> of the thread that the monitor was created in
+ * (though if the global default main context is blocked, this may
+ * cause notifications to be blocked even if the thread-default
+ * context is still running).
+ */
+
+
+/**
+ * SECTION:gfilenamecompleter
+ * @short_description: Filename Completer
+ * @include: gio/gio.h
+ *
+ * Completes partial file and directory names given a partial string by
+ * looking in the file system for clues. Can return a list of possible
+ * completion strings for widget implementations.
+ */
+
+
+/**
+ * SECTION:gfileoutputstream
+ * @short_description: File output streaming operations
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
+ *
+ * GFileOutputStream provides output streams that write their
+ * content to a file.
+ * GFileOutputStream implements #GSeekable, which allows the output
+ * stream to jump to arbitrary positions in the file and to truncate
+ * the file, provided the filesystem of the file supports these
+ * operations.
+ * To find the position of a file output stream, use g_seekable_tell().
+ * To find out if a file output stream supports seeking, use
+ * g_seekable_can_seek().To position a file output stream, use
+ * g_seekable_seek(). To find out if a file output stream supports
+ * truncating, use g_seekable_can_truncate(). To truncate a file output
+ * stream, use g_seekable_truncate().
+ */
+
+
+/**
+ * SECTION:gfilterinputstream
+ * @short_description: Filter Input Stream
+ * @include: gio/gio.h
+ *
+ * Base class for input stream implementations that perform some
+ * kind of filtering operation on a base stream. Typical examples
+ * of filtering operations are character set conversion, compression
+ * and byte order flipping.
+ */
+
+
+/**
+ * SECTION:gfilteroutputstream
+ * @short_description: Filter Output Stream
+ * @include: gio/gio.h
+ *
+ * Base class for output stream implementations that perform some
+ * kind of filtering operation on a base stream. Typical examples
+ * of filtering operations are character set conversion, compression
+ * and byte order flipping.
+ */
+
+
+/**
+ * SECTION:gicon
+ * @short_description: Interface for icons
+ * @include: gio/gio.h
+ *
+ * #GIcon is a very minimal interface for icons. It provides functions
+ * for checking the equality of two icons, hashing of icons and
+ * serializing an icon to and from strings.
+ * #GIcon does not provide the actual pixmap for the icon as this is out
+ * of GIO's scope, however implementations of #GIcon may contain the name
+ * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
+ * To obtain a hash of a #GIcon, see g_icon_hash().
+ * To check if two #GIcons are equal, see g_icon_equal().
+ * For serializing a #GIcon, use g_icon_to_string() and
+ * g_icon_new_for_string().
+ * 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().
+ */
+
+
+/**
+ * SECTION:ginetaddress
+ * @short_description: An IPv4/IPv6 address
+ *
+ * #GInetAddress represents an IPv4 or IPv6 internet address. Use
+ * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
+ * look up the #GInetAddress for a hostname. Use
+ * g_resolver_lookup_by_address() or
+ * g_resolver_lookup_by_address_async() to look up the hostname for a
+ * #GInetAddress.
+ * To actually connect to a remote host, you will need a
+ * #GInetSocketAddress (which includes a #GInetAddress as well as a
+ * port number).
+ */
+
+
+/**
+ * SECTION:ginetsocketaddress
+ * @short_description: Internet GSocketAddress
+ *
+ * An IPv4 or IPv6 socket address; that is, the combination of a
+ * #GInetAddress and a port number.
+ */
+
+
+/**
+ * SECTION:ginitable
+ * @short_description: Failable object initialization interface
+ * @include: gio/gio.h
+ * @see_also: #GAsyncInitable
+ *
+ * #GInitable is implemented by objects that can fail during
+ * initialization. If an object implements this interface the
+ * g_initable_init() function must be called as the first thing
+ * after construction. If g_initable_init() is not called, or if
+ * it returns an error, all further operations on the object
+ * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error.
+ * Users of objects implementing this are not intended to use
+ * the interface method directly, instead it will be used automatically
+ * in various ways. For C applications you generally just call
+ * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
+ * This will call g_initable_init() under the cover, returning %NULL and
+ * setting a #GError on failure (at which point the instance is
+ * unreferenced).
+ * For bindings in languages where the native constructor supports
+ * exceptions the binding could check for objects implemention %GInitable
+ * during normal construction and automatically initialize them, throwing
+ * an exception on failure.
+ */
+
+
+/**
+ * SECTION:ginputstream
+ * @short_description: Base class for implementing streaming input
+ * @include: gio/gio.h
+ *
+ * GInputStream has functions to read from a stream (g_input_stream_read()),
+ * to close a stream (g_input_stream_close()) and to skip some content
+ * (g_input_stream_skip()).
+ * To copy the content of an input stream to an output stream without
+ * manually handling the reads and writes, use g_output_stream_splice().
+ * All of these functions have async variants too.
+ */
+
+
+/**
+ * SECTION:gioerror
+ * @short_description: Error helper functions
+ * @include: gio/gio.h
+ *
+ * Contains helper functions for reporting errors to the user.
+ */
+
+
+/**
+ * SECTION:giomodule
+ * @short_description: Loadable GIO Modules
+ * @include: gio/gio.h
+ *
+ * Provides an interface and default functions for loading and unloading
+ * modules. This is used internally to make GIO extensible, but can also
+ * be used by others to implement module loading.
+ */
+
+
+/**
+ * SECTION:gioscheduler
+ * @short_description: I/O Scheduler
+ * @include: gio/gio.h
+ *
+ * Schedules asynchronous I/O operations. #GIOScheduler integrates
+ * into the main event loop (#GMainLoop) and may use threads if they
+ * are available.
+ * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
+ * Each I/O operation has a priority, and the scheduler uses the priorities
+ * to determine the order in which operations are executed. They are
+ * <emphasis>not</emphasis> used to determine system-wide I/O scheduling.
+ * Priorities are integers, with lower numbers indicating higher priority.
+ * It is recommended to choose priorities between %G_PRIORITY_LOW and
+ * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.
+ * </para>
+ */
+
+
+/**
+ * SECTION:giostream
+ * @short_description: Base class for implementing read/write streams
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
+ *
+ * GIOStream represents an object that has both read and write streams.
+ * Generally the two streams acts as separate input and output streams,
+ * but they share some common resources and state. For instance, for
+ * seekable streams they may use the same position in both streams.
+ * Examples of #GIOStream objects are #GSocketConnection which represents
+ * a two-way network connection, and #GFileIOStream which represent a
+ * file handle opened in read-write mode.
+ * To do the actual reading and writing you need to get the substreams
+ * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
+ * The #GIOStream object owns the input and the output streams, not the other
+ * way around, so keeping the substreams alive will not keep the #GIOStream
+ * object alive. If the #GIOStream object is freed it will be closed, thus
+ * closing the substream, so even if the substreams stay alive they will
+ * always just return a %G_IO_ERROR_CLOSED for all operations.
+ * To close a stream use g_io_stream_close() which will close the common
+ * stream object and also the individual substreams. You can also close
+ * the substreams themselves. In most cases this only marks the
+ * substream as closed, so further I/O on it fails. However, some streams
+ * may support "half-closed" states where one direction of the stream
+ * is actually shut down.
+ *
+ * Since: 2.22
+ */
+
+
+/**
+ * SECTION:gloadableicon
+ * @short_description: Loadable Icons
+ * @include: gio/gio.h
+ * @see_also: #GIcon, #GThemedIcon
+ *
+ * Extends the #GIcon interface and adds the ability to
+ * load icons from streams.
+ */
+
+
+/**
+ * SECTION:gmemoryinputstream
+ * @short_description: Streaming input operations on memory chunks
+ * @include: gio/gio.h
+ * @see_also: #GMemoryOutputStream
+ *
+ * #GMemoryInputStream is a class for using arbitrary
+ * memory chunks as input for GIO streaming input operations.
+ */
+
+
+/**
+ * SECTION:gmemoryoutputstream
+ * @short_description: Streaming output operations on memory chunks
+ * @include: gio/gio.h
+ * @see_also: #GMemoryInputStream
+ *
+ * #GMemoryOutputStream is a class for using arbitrary
+ * memory chunks as output for GIO streaming output operations.
+ */
+
+
+/**
+ * SECTION:gmount
+ * @short_description: Mount management
+ * @include: gio/gio.h
+ * @see_also: GVolume, GUnixMount
+ *
+ * The #GMount interface represents user-visible mounts. Note, when
+ * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
+ * #GMount is a "mounted" filesystem that you can access. Mounted is in
+ * quotes because it's not the same as a unix mount, it might be a gvfs
+ * mount, but you can still access the files on it if you use GIO. Might or
+ * might not be related to a volume object.
+ * Unmounting a #GMount instance is an asynchronous operation. For
+ * more information about asynchronous operations, see #GAsyncReady
+ * and #GSimpleAsyncReady. To unmount a #GMount instance, first call
+ * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
+ * #GAsyncReadyCallback. The callback will be fired when the
+ * operation has resolved (either with success or failure), and a
+ * #GAsyncReady structure will be passed to the callback. That
+ * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
+ * and the #GAsyncReady data to see if the operation was completed
+ * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
+ * is called, then it will be filled with any error information.
+ */
+
+
+/**
+ * SECTION:gmountoperation
+ * @short_description: Object used for authentication and user interaction
+ * @include: gio/gio.h
+ *
+ * #GMountOperation provides a mechanism for interacting with the user.
+ * It can be used for authenticating mountable operations, such as loop
+ * mounting files, hard drive partitions or server locations. It can
+ * also be used to ask the user questions or show a list of applications
+ * preventing unmount or eject operations from completing.
+ * Note that #GMountOperation is used for more than just #GMount
+ * objects â?? for example it is also used in g_drive_start() and
+ * g_drive_stop().
+ * Users should instantiate a subclass of this that implements all the
+ * various callbacks to show the required dialogs, such as
+ * #GtkMountOperation. If no user interaction is desired (for example
+ * when automounting filesystems at login time), usually %NULL can be
+ * passed, see each method taking a #GMountOperation for details.
+ */
+
+
+/**
+ * SECTION:gnetworkaddress
+ * @short_description: A GSocketConnectable for resolving hostnames
+ * @include: gio/gio.h
+ *
+ * #GNetworkAddress provides an easy way to resolve a hostname and
+ * then attempt to connect to that host, handling the possibility of
+ * multiple IP addresses and multiple address families.
+ * See #GSocketConnectable for and example of using the connectable
+ * interface.
+ */
+
+
+/**
+ * SECTION:gnetworkservice
+ * @short_description: A GSocketConnectable for resolving SRV records
+ * @include: gio/gio.h
+ *
+ * Like #GNetworkAddress does with hostnames, #GNetworkService
+ * provides an easy way to resolve a SRV record, and then attempt to
+ * connect to one of the hosts that implements that service, handling
+ * service priority/weighting, multiple IP addresses, and multiple
+ * address families.
+ * See #GSrvTarget for more information about SRV records, and see
+ * #GSocketConnectable for and example of using the connectable
+ * interface.
+ */
+
+
+/**
+ * SECTION:goutputstream
+ * @short_description: Base class for implementing streaming output
+ * @include: gio/gio.h
+ *
+ * GOutputStream has functions to write to a stream (g_output_stream_write()),
+ * to close a stream (g_output_stream_close()) and to flush pending writes
+ * (g_output_stream_flush()).
+ * To copy the content of an input stream to an output stream without
+ * manually handling the reads and writes, use g_output_stream_splice().
+ * All of these functions have async variants too.
+ */
+
+
+/**
+ * SECTION:gpermission
+ * @title: GPermission
+ * @short_description: An object representing the permission to perform a certain action
+ *
+ * A #GPermission represents the status of the caller's permission to
+ * perform a certain action.
+ * You can query if the action is currently allowed and if it is
+ * possible to acquire the permission so that the action will be allowed
+ * in the future.
+ * There is also an API to actually acquire the permission and one to
+ * release it.
+ * As an example, a #GPermission might represent the ability for the
+ * user to write to a #GSettings object. This #GPermission object could
+ * then be used to decide if it is appropriate to show a "Click here to
+ * unlock" button in a dialog and to provide the mechanism to invoke
+ * when that button is clicked.
+ */
+
+
+/**
+ * SECTION:gpollableinputstream
+ * @short_description: Interface for pollable input streams
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
+ *
+ * #GPollableInputStream is implemented by #GInputStream<!-- -->s that
+ * can be polled for readiness to read. This can be used when
+ * interfacing with a non-GIO API that expects
+ * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
+ *
+ * Since: 2.28
+ */
+
+
+/**
+ * SECTION:gpollableoutputstream
+ * @short_description: Interface for pollable output streams
+ * @include: gio/gio.h
+ * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
+ *
+ * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
+ * can be polled for readiness to write. This can be used when
+ * interfacing with a non-GIO API that expects
+ * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
+ *
+ * Since: 2.28
+ */
+
+
+/**
+ * SECTION:gproxy
+ * @short_description: Interface for proxy handling
+ *
+ * A #GProxy handles connecting to a remote host via a given type of
+ * proxy server. It is implemented by the 'gio-proxy' extension point.
+ * The extensions are named after their proxy protocol name. As an
+ * example, a SOCKS5 proxy implementation can be retrieved with the
+ * name 'socks5' using the function
+ * g_io_extension_point_get_extension_by_name().
+ *
+ * Since: 2.26
+ */
+
+
+/**
+ * SECTION:gproxyaddress
+ * @short_description: An internet address with proxy information
+ *
+ * Support for proxied #GInetSocketAddress.
+ */
+
+
+/**
+ * SECTION:gproxyresolver
+ * @short_description: Asynchronous and cancellable network proxy resolver
+ * @include: gio/gio.h
+ *
+ * #GProxyResolver provides synchronous and asynchronous network proxy
+ * resolution. #GProxyResolver is used within #GSocketClient through
+ * the method g_socket_connectable_proxy_enumerate().
+ */
+
+
+/**
+ * SECTION:gresolver
+ * @short_description: Asynchronous and cancellable DNS resolver
+ * @include: gio/gio.h
+ *
+ * #GResolver provides cancellable synchronous and asynchronous DNS
+ * resolution, for hostnames (g_resolver_lookup_by_address(),
+ * g_resolver_lookup_by_name() and their async variants) and SRV
+ * (service) records (g_resolver_lookup_service()).
+ * #GNetworkAddress and #GNetworkService provide wrappers around
+ * #GResolver functionality that also implement #GSocketConnectable,
+ * making it easy to connect to a remote host/service.
+ */
+
+
+/**
+ * SECTION:gseekable
+ * @short_description: Stream seeking interface
+ * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
+ *
+ * #GSeekable is implemented by streams (implementations of
+ * #GInputStream or #GOutputStream) that support seeking.
+ */
+
+
+/**
+ * SECTION:gsettings
+ * @short_description: High-level API for application settings
+ *
+ * The #GSettings class provides a convenient API for storing and retrieving
+ * application settings.
+ * Reads and writes can be considered to be non-blocking. Reading
+ * approximately the same order of magnitude (but slower than) a
+ * #GHashTable lookup. Writing settings is also extremely fast in terms
+ * of time to return to your application, but can be extremely expensive
+ * for other threads and other processes. Many settings backends
+ * (including dconf) have lazy initialisation which means in the common
+ * case of the user using their computer without modifying any settings
+ * a lot of work can be avoided. For dconf, the D-Bus service doesn't
+ * even need to be started in this case. For this reason, you should
+ * only ever modify #GSettings keys in response to explicit user action.
+ * Particular care should be paid to ensure that modifications are not
+ * made during startup -- for example, when setting the initial value
+ * of preferences widgets. The built-in g_settings_bind() functionality
+ * is careful not to write settings in response to notify signals as a
+ * result of modifications that it makes to widgets.
+ * When creating a GSettings instance, you have to specify a schema
+ * that describes the keys in your settings and their types and default
+ * values, as well as some other information.
+ * Normally, a schema has as fixed path that determines where the settings
+ * are stored in the conceptual global tree of settings. However, schemas
+ * can also be 'relocatable', i.e. not equipped with a fixed path. This is
+ * useful e.g. when the schema describes an 'account', and you want to be
+ * able to store a arbitrary number of accounts.
+ * Unlike other configuration systems (like GConf), GSettings does not
+ * restrict keys to basic types like strings and numbers. GSettings stores
+ * values as #GVariant, and allows any #GVariantType for keys. Key names
+ * are restricted to lowercase characters, numbers and '-'. Furthermore,
+ * the names must begin with a lowercase character, must not end
+ * with a '-', and must not contain consecutive dashes. Key names can
+ * be up to 32 characters long.
+ * Similar to GConf, the default values in GSettings schemas can be
+ * localized, but the localized values are stored in gettext catalogs
+ * and looked up with the domain that is specified in the
+ * <tag class="attribute">gettext-domain</tag> attribute of the
+ * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
+ * elements and the category that is specified in the l10n attribute of the
+ * <tag class="starttag">key</tag> element.
+ * GSettings uses schemas in a compact binary form that is created
+ * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
+ * utility. The input is a schema description in an XML format that can be
+ * described by the following DTD:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
+ * At runtime, schemas are identified by their id (as specified
+ * in the <tag class="attribute">id</tag> attribute of the
+ * <tag class="starttag">schema</tag> element). The
+ * convention for schema ids is to use a dotted name, similar in
+ * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
+ * if the settings are for a specific service that owns a D-Bus bus name,
+ * the D-Bus bus name and schema id should match. For schemas which deal
+ * with settings not associated with one named application, the id should
+ * not use StudlyCaps, e.g. "org.gnome.font-rendering".
+ * In addition to #GVariant types, keys can have types that have enumerated
+ * types. These can be described by a <tag class="starttag">choice</tag>,
+ * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
+ * <xref linkend="schema-enumerated"/>. The underlying type of
+ * such a key is string, but you can use g_settings_get_enum(),
+ * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
+ * access the numeric values corresponding to the string value of enum
+ * and flags keys.
+ * <example id="schema-default-values"><title>Default values</title>
+ * <programlisting><![CDATA[
+ * <schemalist>
+ * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
+ * <key name="greeting" type="s">
+ * <default l10n="messages">"Hello, earthlings"</default>
+ * <summary>A greeting</summary>
+ * <description>
+ * Greeting of the invading martians
+ * </description>
+ * </key>
+ * <key name="box" type="(ii)">
+ * <default>(20,30)</default>
+ * </key>
+ * </schema>
+ * </schemalist>
+ * ]]></programlisting></example>
+ * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
+ * <programlisting><![CDATA[
+ * <schemalist>
+ * <enum id="org.gtk.Test.myenum">
+ * <value nick="first" value="1"/>
+ * <value nick="second" value="2"/>
+ * </enum>
+ * <flags id="org.gtk.Test.myflags">
+ * <value nick="flag1" value="1"/>
+ * <value nick="flag2" value="2"/>
+ * <value nick="flag3" value="4"/>
+ * </flags>
+ * <schema id="org.gtk.Test">
+ * <key name="key-with-range" type="i">
+ * <range min="1" max="100"/>
+ * <default>10</default>
+ * </key>
+ * <key name="key-with-choices" type="s">
+ * <choices>
+ * <choice value='Elisabeth'/>
+ * <choice value='Annabeth'/>
+ * <choice value='Joe'/>
+ * </choices>
+ * <aliases>
+ * <alias value='Anna' target='Annabeth'/>
+ * <alias value='Beth' target='Elisabeth'/>
+ * </aliases>
+ * <default>'Joe'</default>
+ * </key>
+ * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
+ * <default>'first'</default>
+ * </key>
+ * <key name='flags-key' flags='org.gtk.Test.myflags'>
+ * <default>["flag1",flag2"]</default>
+ * </key>
+ * </schema>
+ * </schemalist>
+ * ]]></programlisting></example>
+ * <refsect2>
+ * <title>Vendor overrides</title>
+ * <para>
+ * Default values are defined in the schemas that get installed by
+ * an application. Sometimes, it is necessary for a vendor or distributor
+ * to adjust these defaults. Since patching the XML source for the schema
+ * is inconvenient and error-prone,
+ * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
+ * so-called 'vendor override' files. These are keyfiles in the same
+ * directory as the XML schema sources which can override default values.
+ * The schema id serves as the group name in the key file, and the values
+ * are expected in serialized GVariant form, as in the following example:
+ * <informalexample><programlisting>
+ * [org.gtk.Example]
+ * key1='string'
+ * key2=1.5
+ * </programlisting></informalexample>
+ * </para>
+ * <para>
+ * glib-compile-schemas expects schema files to have the extension
+ * <filename>.gschema.override</filename>
+ * </para>
+ * </refsect2>
+ * <refsect2>
+ * <title>Binding</title>
+ * <para>
+ * A very convenient feature of GSettings lets you bind #GObject properties
+ * directly to settings, using g_settings_bind(). Once a GObject property
+ * has been bound to a setting, changes on either side are automatically
+ * propagated to the other side. GSettings handles details like
+ * mapping between GObject and GVariant types, and preventing infinite
+ * cycles.
+ * </para>
+ * <para>
+ * This makes it very easy to hook up a preferences dialog to the
+ * underlying settings. To make this even more convenient, GSettings
+ * looks for a boolean property with the name "sensitivity" and
+ * automatically binds it to the writability of the bound setting.
+ * If this 'magic' gets in the way, it can be suppressed with the
+ * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
+ * </para>
+ * </refsect2>
+ *
+ * Settings with #gsettings is typically extremely fast: on
+ */
+
+
+/**
+ * SECTION:gsettingsbackend
+ * @title: GSettingsBackend
+ * @short_description: Interface for settings backend implementations
+ * @include: gio/gsettingsbackend.h
+ * @see_also: #GSettings, #GIOExtensionPoint
+ *
+ * The #GSettingsBackend interface defines a generic interface for
+ * non-strictly-typed data that is stored in a hierarchy. To implement
+ * an alternative storage backend for #GSettings, you need to implement
+ * the #GSettingsBackend interface and then make it implement the
+ * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
+ * The interface defines methods for reading and writing values, a
+ * method for determining if writing of certain values will fail
+ * (lockdown) and a change notification mechanism.
+ * The semantics of the interface are very precisely defined and
+ * implementations must carefully adhere to the expectations of
+ * callers that are documented on each of the interface methods.
+ * Some of the GSettingsBackend functions accept or return a #GTree.
+ * These trees always have strings as keys and #GVariant as values.
+ * g_settings_backend_create_tree() is a convenience function to create
+ * suitable trees.
+ * <note><para>
+ * The #GSettingsBackend API is exported to allow third-party
+ * implementations, but does not carry the same stability guarantees
+ * as the public GIO API. For this reason, you have to define the
+ * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
+ * <filename>gio/gsettingsbackend.h</filename>
+ * </para></note>
+ */
+
+
+/**
+ * SECTION:gsimpleaction
+ * @title: GSimpleAction
+ * @short_description: A simple GSimpleAction
+ *
+ * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction
+ * interface. This is the easiest way to create an action for purposes of
+ * adding it to a #GSimpleActionGroup.
+ * See also #GtkAction.
+ */
+
+
+/**
+ * SECTION:gsimpleactiongroup
+ * @title: GSimpleActionGroup
+ * @short_description: A simple GActionGroup implementation
+ *
+ * #GSimpleActionGroup is a hash table filled with #GAction objects,
+ * implementing the #GActionGroup interface.
+ */
+
+
+/**
+ * SECTION:gsimpleasyncresult
+ * @short_description: Simple asynchronous results implementation
+ * @include: gio/gio.h
+ * @see_also: #GAsyncResult
+ *
+ * Implements #GAsyncResult for simple cases. Most of the time, this
+ * will be all an application needs, and will be used transparently.
+ * Because of this, #GSimpleAsyncResult is used throughout GIO for
+ * handling asynchronous functions.
+ * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
+ * reporting, operation cancellation and the final state of an operation,
+ * completely transparent to the application. Results can be returned
+ * as a pointer e.g. for functions that return data that is collected
+ * asynchronously, a boolean value for checking the success or failure
+ * of an operation, or a #gssize for operations which return the number
+ * of bytes modified by the operation; all of the simple return cases
+ * are covered.
+ * Most of the time, an application will not need to know of the details
+ * of this API; it is handled transparently, and any necessary operations
+ * are handled by #GAsyncResult's interface. However, if implementing a
+ * new GIO module, for writing language bindings, or for complex
+ * applications that need better control of how asynchronous operations
+ * are completed, it is important to understand this functionality.
+ * GSimpleAsyncResults are tagged with the calling function to ensure
+ * that asynchronous functions and their finishing functions are used
+ * together correctly.
+ * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
+ * If the result needs to be created for a #GError, use
+ * g_simple_async_result_new_from_error() or
+ * g_simple_async_result_new_take_error(). If a #GError is not available
+ * (e.g. the asynchronous operation's doesn't take a #GError argument),
+ * but the result still needs to be created for an error condition, use
+ * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
+ * if your application or binding requires passing a variable argument list
+ * directly), and the error can then be propagated through the use of
+ * g_simple_async_result_propagate_error().
+ * An asynchronous operation can be made to ignore a cancellation event by
+ * calling g_simple_async_result_set_handle_cancellation() with a
+ * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
+ * operations that are dangerous to cancel, such as close (which would
+ * cause a leak if cancelled before being run).
+ * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
+ * or it can use #GThread<!-- -->s if available.
+ * g_simple_async_result_complete() will finish an I/O task directly
+ * from the point where it is called. g_simple_async_result_complete_in_idle()
+ * will finish it from an idle handler in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * context</link>. g_simple_async_result_run_in_thread() will run the
+ * job in a separate thread and then deliver the result to the
+ * thread-default main context.
+ * To set the results of an asynchronous function,
+ * g_simple_async_result_set_op_res_gpointer(),
+ * g_simple_async_result_set_op_res_gboolean(), and
+ * g_simple_async_result_set_op_res_gssize()
+ * are provided, setting the operation's result to a gpointer, gboolean, or
+ * gssize, respectively.
+ * Likewise, to get the result of an asynchronous function,
+ * g_simple_async_result_get_op_res_gpointer(),
+ * g_simple_async_result_get_op_res_gboolean(), and
+ * g_simple_async_result_get_op_res_gssize() are
+ * provided, getting the operation's result as a gpointer, gboolean, and
+ * gssize, respectively.
+ * For the details of the requirements implementations must respect, see
+ * #GAsyncResult. A typical implementation of an asynchronous operation
+ * using GSimpleAsyncResult looks something like this:
+ * |[
+ * static void
+ * baked_cb (Cake *cake,
+ * gpointer user_data)
+ * {
+ * /* In this example, this callback is not given a reference to the cake, so
+ * * the GSimpleAsyncResult has to take a reference to it.
+ * */
+ * GSimpleAsyncResult *result = user_data;
+ * if (cake == NULL)
+ * g_simple_async_result_set_error (result,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_NO_FLOUR,
+ * "Go to the supermarket");
+ * else
+ * g_simple_async_result_set_op_res_gpointer (result,
+ * g_object_ref (cake),
+ * g_object_unref);
+ * /* In this example, we assume that baked_cb is called as a callback from
+ * * the mainloop, so it's safe to complete the operation synchronously here.
+ * * If, however, _baker_prepare_cake () might call its callback without
+ * * first returning to the mainloop â?? inadvisable, but some APIs do so â??
+ * * we would need to use g_simple_async_result_complete_in_idle().
+ * */
+ * g_simple_async_result_complete (result);
+ * g_object_unref (result);
+ * }
+ * void
+ * baker_bake_cake_async (Baker *self,
+ * guint radius,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
+ * {
+ * GSimpleAsyncResult *simple;
+ * Cake *cake;
+ * if (radius < 3)
+ * {
+ * g_simple_async_report_error_in_idle (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_TOO_SMALL,
+ * "%ucm radius cakes are silly",
+ * radius);
+ * return;
+ * }
+ * simple = g_simple_async_result_new (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * baker_bake_cake_async);
+ * cake = _baker_get_cached_cake (self, radius);
+ * if (cake != NULL)
+ * {
+ * g_simple_async_result_set_op_res_gpointer (simple,
+ * g_object_ref (cake),
+ * g_object_unref);
+ * g_simple_async_result_complete_in_idle (simple);
+ * g_object_unref (simple);
+ * /* Drop the reference returned by _baker_get_cached_cake(); the
+ * * GSimpleAsyncResult has taken its own reference.
+ * */
+ * g_object_unref (cake);
+ * return;
+ * }
+ * _baker_prepare_cake (self, radius, baked_cb, simple);
+ * }
+ * Cake *
+ * baker_bake_cake_finish (Baker *self,
+ * GAsyncResult *result,
+ * GError **error)
+ * {
+ * GSimpleAsyncResult *simple;
+ * Cake *cake;
+ * g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ * G_OBJECT (self),
+ * baker_bake_cake_async),
+ * NULL);
+ * simple = (GSimpleAsyncResult *) result;
+ * if (g_simple_async_result_propagate_error (simple, error))
+ * return NULL;
+ * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
+ * return g_object_ref (cake);
+ * }
+ * ]|
+ */
+
+
+/**
+ * SECTION:gsimplepermission
+ * @title: GSimplePermission
+ * @short_description: A GPermission that doesn't change value
+ *
+ * #GSimplePermission is a trivial implementation of #GPermission that
+ * represents a permission that is either always or never allowed. The
+ * value is given at constuction and doesn't change.
+ * Calling request or release will result in errors.
+ */
+
+
+/**
+ * SECTION:gsocket
+ * @short_description: Low-level socket object
+ * @include: gio/gio.h
+ * @see_also: #GInitable
+ *
+ * A #GSocket is a low-level networking primitive. It is a more or less
+ * direct mapping of the BSD socket API in a portable GObject based API.
+ * It supports both the UNIX socket implementations and winsock2 on Windows.
+ * #GSocket is the platform independent base upon which the higher level
+ * network primitives are based. Applications are not typically meant to
+ * use it directly, but rather through classes like #GSocketClient,
+ * #GSocketService and #GSocketConnection. However there may be cases where
+ * direct use of #GSocket is useful.
+ * #GSocket implements the #GInitable interface, so if it is manually constructed
+ * by e.g. g_object_new() you must call g_initable_init() and check the
+ * results before using the object. This is done automatically in
+ * g_socket_new() and g_socket_new_from_fd(), so these functions can return
+ * %NULL.
+ * Sockets operate in two general modes, blocking or non-blocking. When
+ * in blocking mode all operations block until the requested operation
+ * is finished or there is an error. In non-blocking mode all calls that
+ * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
+ * To know when a call would successfully run you can call g_socket_condition_check(),
+ * or g_socket_condition_wait(). You can also use g_socket_create_source() and
+ * attach it to a #GMainContext to get callbacks when I/O is possible.
+ * Note that all sockets are always set to non blocking mode in the system, and
+ * blocking mode is emulated in GSocket.
+ * When working in non-blocking mode applications should always be able to
+ * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
+ * function said that I/O was possible. This can easily happen in case
+ * of a race condition in the application, but it can also happen for other
+ * reasons. For instance, on Windows a socket is always seen as writable
+ * until a write returns %G_IO_ERROR_WOULD_BLOCK.
+ * #GSocket<!-- -->s can be either connection oriented or datagram based.
+ * For connection oriented types you must first establish a connection by
+ * either connecting to an address or accepting a connection from another
+ * address. For connectionless socket types the target/source address is
+ * specified or received in each I/O operation.
+ * All socket file descriptors are set to be close-on-exec.
+ * Note that creating a #GSocket causes the signal %SIGPIPE to be
+ * ignored for the remainder of the program. If you are writing a
+ * command-line utility that uses #GSocket, you may need to take into
+ * account the fact that your program will not automatically be killed
+ * if it tries to write to %stdout after it has been closed.
*
- * Since: 2.24
+ * Since: 2.22
*/
/**
- * SECTION:gfileenumerator
- * @short_description: Enumerated Files Routines
- * @include: gio/gio.h
+ * SECTION:gsocketaddress
+ * @short_description: Abstract base class representing endpoints for socket communication
*
- * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
- * returning a #GFileInfo structure for each file enumerated (e.g.
- * g_file_enumerate_children() will return a #GFileEnumerator for each
- * of the children within a directory).
- * To get the next file's information from a #GFileEnumerator, use
- * g_file_enumerator_next_file() or its asynchronous version,
- * g_file_enumerator_next_files_async(). Note that the asynchronous
- * version will return a list of #GFileInfo<!---->s, whereas the
- * synchronous will only return the next file in the enumerator.
- * To close a #GFileEnumerator, use g_file_enumerator_close(), or
- * its asynchronous version, g_file_enumerator_close_async(). Once
- * a #GFileEnumerator is closed, no further actions may be performed
- * on it, and it should be freed with g_object_unref().
+ * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
+ * in the BSD sockets API. This is an abstract class; use
+ * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
+ * for UNIX domain sockets.
*/
/**
- * SECTION:gfileicon
- * @short_description: Icons pointing to an image file
+ * SECTION:gsocketclient
+ * @short_description: Helper for connecting to a network service
* @include: gio/gio.h
- * @see_also: #GIcon, #GLoadableIcon
+ * @see_also: #GSocketConnection, #GSocketListener
*
- * #GFileIcon specifies an icon by pointing to an image file
- * to be used as icon.
+ * #GSocketClient is a high-level utility class for connecting to a
+ * network host using a connection oriented socket type.
+ * You create a #GSocketClient object, set any options you want, and then
+ * call a sync or async connect operation, which returns a #GSocketConnection
+ * subclass on success.
+ * The type of the #GSocketConnection object returned depends on the type of
+ * the underlying socket that is in use. For instance, for a TCP/IP connection
+ * it will be a #GTcpConnection.
+ *
+ * Since: 2.22
*/
/**
- * SECTION:gfileinfo
- * @short_description: File Information and Attributes
- * @include: gio/gio.h
- * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
+ * SECTION:gsocketconnectable
+ * @short_description: Interface for potential socket endpoints
*
- * Functionality for manipulating basic metadata for files. #GFileInfo
- * implements methods for getting information that all files should
- * contain, and allows for manipulation of extended attributes.
- * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
- * information on how GIO handles file attributes.
- * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
- * async variant). To obtain a #GFileInfo for a file input or output
- * stream, use g_file_input_stream_query_info() or
- * g_file_output_stream_query_info() (or their async variants).
- * To change the actual attributes of a file, you should then set the
- * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
- * or g_file_set_attributes_async() on a GFile.
- * However, not all attributes can be changed in the file. For instance,
- * the actual size of a file cannot be changed via g_file_info_set_size().
- * You may call g_file_query_settable_attributes() and
- * g_file_query_writable_namespaces() to discover the settable attributes
- * of a particular file at runtime.
- * #GFileAttributeMatcher allows for searching through a #GFileInfo for
- * attributes.
+ * Objects that describe one or more potential socket endpoints
+ * implement #GSocketConnectable. Callers can then use
+ * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
+ * to try out each socket address in turn until one succeeds, as shown
+ * in the sample code below.
+ * |[
+ * MyConnectionType *
+ * connect_to_host (const char *hostname,
+ * guint16 port,
+ * GCancellable *cancellable,
+ * GError **error)
+ * {
+ * MyConnection *conn = NULL;
+ * GSocketConnectable *addr;
+ * GSocketAddressEnumerator *enumerator;
+ * GSocketAddress *sockaddr;
+ * GError *conn_error = NULL;
+ * addr = g_network_address_new ("www.gnome.org", 80);
+ * enumerator = g_socket_connectable_enumerate (addr);
+ * g_object_unref (addr);
+ * /<!-- -->* Try each sockaddr until we succeed. Record the first
+ * * connection error, but not any further ones (since they'll probably
+ * * be basically the same as the first).
+ * *<!-- -->/
+ * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
+ * {
+ * g_object_unref (sockaddr);
+ * }
+ * g_object_unref (enumerator);
+ * if (conn)
+ * {
+ * if (conn_error)
+ * {
+ * /<!-- -->* We couldn't connect to the first address, but we succeeded
+ * * in connecting to a later address.
+ * *<!-- -->/
+ * g_error_free (conn_error);
+ * }
+ * return conn;
+ * }
+ * else if (error)
+ * {
+ * /<!-- -->* Either the initial lookup failed, or else the caller
+ * * cancelled us.
+ * *<!-- -->/
+ * if (conn_error)
+ * g_error_free (conn_error);
+ * return NULL;
+ * }
+ * else
+ * {
+ * g_error_propagate (error, conn_error);
+ * return NULL;
+ * }
+ * }
+ * ]|
+ *
+ * Conn = connect_to_sockaddr (sockaddr, conn_error ? null : &conn_error);
*/
/**
- * SECTION:gfileinputstream
- * @short_description: File input streaming operations
+ * SECTION:gsocketconnection
+ * @short_description: A socket connection
* @include: gio/gio.h
- * @see_also: #GInputStream, #GDataInputStream, #GSeekable
+ * @see_also: #GIOStream, #GSocketClient, #GSocketListener
*
- * GFileInputStream provides input streams that take their
- * content from a file.
- * GFileInputStream implements #GSeekable, which allows the input
- * stream to jump to arbitrary positions in the file, provided the
- * filesystem of the file allows it. To find the position of a file
- * input stream, use g_seekable_tell(). To find out if a file input
- * stream supports seeking, use g_seekable_stream_can_seek().
- * To position a file input stream, use g_seekable_seek().
+ * #GSocketConnection is a #GIOStream for a connected socket. They
+ * can be created either by #GSocketClient when connecting to a host,
+ * or by #GSocketListener when accepting a new client.
+ * The type of the #GSocketConnection object returned from these calls
+ * depends on the type of the underlying socket that is in use. For
+ * instance, for a TCP/IP connection it will be a #GTcpConnection.
+ * Choosing what type of object to construct is done with the socket
+ * connection factory, and it is possible for 3rd parties to register
+ * custom socket connection types for specific combination of socket
+ * family/type/protocol using g_socket_connection_factory_register_type().
+ *
+ * Since: 2.22
*/
/**
- * SECTION:gfileiostream
- * @short_description: File read and write streaming operations
- * @include: gio/gio.h
- * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
+ * SECTION:gsocketcontrolmessage
+ * @title: GSocketControlMessage
+ * @short_description: A GSocket control message
+ * @see_also: #GSocket.
*
- * GFileIOStream provides io streams that both read and write to the same
- * file handle.
- * GFileIOStream implements #GSeekable, which allows the io
- * stream to jump to arbitrary positions in the file and to truncate
- * the file, provided the filesystem of the file supports these
- * operations.
- * To find the position of a file io stream, use
- * g_seekable_tell().
- * To find out if a file io stream supports seeking, use g_seekable_can_seek().
- * To position a file io stream, use g_seekable_seek().
- * To find out if a file io stream supports truncating, use
- * g_seekable_can_truncate(). To truncate a file io
- * stream, use g_seekable_truncate().
- * The default implementation of all the #GFileIOStream operations
- * and the implementation of #GSeekable just call into the same operations
- * on the output stream.
+ * A #GSocketControlMessage is a special-purpose utility message that
+ * can be sent to or received from a #GSocket. These types of
+ * messages are often called "ancillary data".
+ * The message can represent some sort of special instruction to or
+ * information from the socket or can represent a special kind of
+ * transfer to the peer (for example, sending a file description over
+ * a UNIX socket).
+ * These messages are sent with g_socket_send_message() and received
+ * with g_socket_receive_message().
+ * To extend the set of control message that can be sent, subclass this
+ * class and override the get_size, get_level, get_type and serialize
+ * methods.
+ * To extend the set of control messages that can be received, subclass
+ * this class and implement the deserialize method. Also, make sure your
+ * class is registered with the GType typesystem before calling
+ * g_socket_receive_message() to read such a message.
*
* Since: 2.22
*/
/**
- * SECTION:gfilemonitor
- * @short_description: File Monitor
- * @include: gio/gio.h
+ * SECTION:gsocketlistener
+ * @title: GSocketListener
+ * @short_description: Helper for accepting network client connections
+ * @see_also: #GThreadedSocketService, #GSocketService.
*
- * Monitors a file or directory for changes.
- * To obtain a #GFileMonitor for a file or directory, use
- * g_file_monitor(), g_file_monitor_file(), or
- * g_file_monitor_directory().
- * To get informed about changes to the file or directory you are
- * monitoring, connect to the #GFileMonitor::changed signal. The
- * signal will be emitted in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link> of the thread that the monitor was created in
- * (though if the global default main context is blocked, this may
- * cause notifications to be blocked even if the thread-default
- * context is still running).
+ * A #GSocketListener is an object that keeps track of a set
+ * of server sockets and helps you accept sockets from any of the
+ * socket, either sync or async.
+ * If you want to implement a network server, also look at #GSocketService
+ * and #GThreadedSocketService which are subclass of #GSocketListener
+ * that makes this even easier.
+ *
+ * Since: 2.22
*/
/**
- * SECTION:gfilenamecompleter
- * @short_description: Filename Completer
- * @include: gio/gio.h
+ * SECTION:gsocketservice
+ * @title: GSocketService
+ * @short_description: Make it easy to implement a network service
+ * @see_also: #GThreadedSocketService, #GSocketListener.
+ *
+ * A #GSocketService is an object that represents a service that
+ * is provided to the network or over local sockets. When a new
+ * connection is made to the service the #GSocketService::incoming
+ * signal is emitted.
+ * A #GSocketService is a subclass of #GSocketListener and you need
+ * to add the addresses you want to accept connections on with the
+ * #GSocketListener APIs.
+ * There are two options for implementing a network service based on
+ * #GSocketService. The first is to create the service using
+ * g_socket_service_new() and to connect to the #GSocketService::incoming
+ * signal. The second is to subclass #GSocketService and override the
+ * default signal handler implementation.
+ * In either case, the handler must immediately return, or else it
+ * will block additional incoming connections from being serviced.
+ * If you are interested in writing connection handlers that contain
+ * blocking code then see #GThreadedSocketService.
+ * The socket service runs on the main loop in the main thread, and is
+ * not threadsafe in general. However, the calls to start and stop
+ * the service are threadsafe so these can be used from threads that
+ * handle incoming clients.
*
- * Completes partial file and directory names given a partial string by
- * looking in the file system for clues. Can return a list of possible
- * completion strings for widget implementations.
+ * Since: 2.22
*/
/**
- * SECTION:gfileoutputstream
- * @short_description: File output streaming operations
+ * SECTION:gsrvtarget
+ * @short_description: DNS SRV record target
* @include: gio/gio.h
- * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
*
- * GFileOutputStream provides output streams that write their
- * content to a file.
- * GFileOutputStream implements #GSeekable, which allows the output
- * stream to jump to arbitrary positions in the file and to truncate
- * the file, provided the filesystem of the file supports these
- * operations.
- * To find the position of a file output stream, use g_seekable_tell().
- * To find out if a file output stream supports seeking, use
- * g_seekable_can_seek().To position a file output stream, use
- * g_seekable_seek(). To find out if a file output stream supports
- * truncating, use g_seekable_can_truncate(). To truncate a file output
- * stream, use g_seekable_truncate().
+ * SRV (service) records are used by some network protocols to provide
+ * service-specific aliasing and load-balancing. For example, XMPP
+ * (Jabber) uses SRV records to locate the XMPP server for a domain;
+ * rather than connecting directly to "example.com" or assuming a
+ * specific server hostname like "xmpp.example.com", an XMPP client
+ * would look up the "xmpp-client" SRV record for "example.com", and
+ * then connect to whatever host was pointed to by that record.
+ * You can use g_resolver_lookup_service() or
+ * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
+ * for a given service. However, if you are simply planning to connect
+ * to the remote service, you can use #GNetworkService's
+ * #GSocketConnectable interface and not need to worry about
+ * #GSrvTarget at all.
*/
/**
- * SECTION:gfilterinputstream
- * @short_description: Filter Input Stream
- * @include: gio/gio.h
+ * SECTION:gtcpconnection
+ * @title: GTcpConnection
+ * @short_description: A TCP GSocketConnection
+ * @see_also: #GSocketConnection.
*
- * Base class for input stream implementations that perform some
- * kind of filtering operation on a base stream. Typical examples
- * of filtering operations are character set conversion, compression
- * and byte order flipping.
+ * This is the subclass of #GSocketConnection that is created
+ * for TCP/IP sockets.
+ *
+ * Since: 2.22
*/
/**
- * SECTION:gfilteroutputstream
- * @short_description: Filter Output Stream
- * @include: gio/gio.h
+ * SECTION:gtcpwrapperconnection
+ * @title: GTcpWrapperConnection
+ * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
+ * @see_also: #GSocketConnection.
*
- * Base class for output stream implementations that perform some
- * kind of filtering operation on a base stream. Typical examples
- * of filtering operations are character set conversion, compression
- * and byte order flipping.
+ * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
+ * based on a #GSocket, but which is not actually a
+ * #GSocketConnection. This is used by #GSocketClient so that it can
+ * always return a #GSocketConnection, even when the connection it has
+ * actually created is not directly a #GSocketConnection.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gicon
- * @short_description: Interface for icons
+ * SECTION:gthemedicon
+ * @short_description: Icon theming support
* @include: gio/gio.h
+ * @see_also: #GIcon, #GLoadableIcon
*
- * #GIcon is a very minimal interface for icons. It provides functions
- * for checking the equality of two icons, hashing of icons and
- * serializing an icon to and from strings.
- * #GIcon does not provide the actual pixmap for the icon as this is out
- * of GIO's scope, however implementations of #GIcon may contain the name
- * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
- * To obtain a hash of a #GIcon, see g_icon_hash().
- * To check if two #GIcons are equal, see g_icon_equal().
- * For serializing a #GIcon, use g_icon_to_string() and
- * g_icon_new_for_string().
- * 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().
+ * #GThemedIcon is an implementation of #GIcon that supports icon themes.
+ * #GThemedIcon contains a list of all of the icons present in an icon
+ * theme, so that icons can be looked up quickly. #GThemedIcon does
+ * not provide actual pixmaps for icons, just the icon names.
+ * Ideally something like gtk_icon_theme_choose_icon() should be used to
+ * resolve the list of names so that fallback icons work nicely with
+ * themes that inherit other themes.
*/
/**
- * SECTION:ginetaddress
- * @short_description: An IPv4/IPv6 address
+ * SECTION:gthreadedsocketservice
+ * @title: GThreadedSocketService
+ * @short_description: A threaded GSocketService
+ * @see_also: #GSocketService.
*
- * #GInetAddress represents an IPv4 or IPv6 internet address. Use
- * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
- * look up the #GInetAddress for a hostname. Use
- * g_resolver_lookup_by_address() or
- * g_resolver_lookup_by_address_async() to look up the hostname for a
- * #GInetAddress.
- * To actually connect to a remote host, you will need a
- * #GInetSocketAddress (which includes a #GInetAddress as well as a
- * port number).
+ * A #GThreadedSocketService is a simple subclass of #GSocketService
+ * that handles incoming connections by creating a worker thread and
+ * dispatching the connection to it by emitting the
+ * #GThreadedSocketService::run signal in the new thread.
+ * The signal handler may perform blocking IO and need not return
+ * until the connection is closed.
+ * The service is implemented using a thread pool, so there is a
+ * limited amount of threads available to serve incoming requests.
+ * The service automatically stops the #GSocketService from accepting
+ * new connections when all threads are busy.
+ * As with #GSocketService, you may connect to #GThreadedSocketService::run,
+ * or subclass and override the default handler.
*/
/**
- * SECTION:ginetsocketaddress
- * @short_description: Internet GSocketAddress
+ * SECTION:gtimezonemonitor
+ * @title: GTimeZoneMonitor
+ * @short_description: Monitor the local timezone
*
- * An IPv4 or IPv6 socket address; that is, the combination of a
- * #GInetAddress and a port number.
- */
-
-
-/**
- * SECTION:ginitable
- * @short_description: Failable object initialization interface
- * @include: gio/gio.h
- * @see_also: #GAsyncInitable
+ * #GTimeZoneMonitor is a utility class to monitor the local timezone for
+ * to that of a different locale).
+ * You must use this class in order for your program to notice changes
+ * to the local timezone. It works by monitoring the /etc/localtime
+ * file. When the timezone is found to have changed,
+ * g_time_zone_refresh_local() is called and the "changed" signal is
+ * emitted on the #GTimeZoneMonitor (in that order).
+ * Windows support is not presently working.
*
- * #GInitable is implemented by objects that can fail during
- * initialization. If an object implements this interface the
- * g_initable_init() function must be called as the first thing
- * after construction. If g_initable_init() is not called, or if
- * it returns an error, all further operations on the object
- * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error.
- * Users of objects implementing this are not intended to use
- * the interface method directly, instead it will be used automatically
- * in various ways. For C applications you generally just call
- * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
- * This will call g_initable_init() under the cover, returning %NULL and
- * setting a #GError on failure (at which point the instance is
- * unreferenced).
- * For bindings in languages where the native constructor supports
- * exceptions the binding could check for objects implemention %GInitable
- * during normal construction and automatically initialize them, throwing
- * an exception on failure.
+ * Changes (ie: in response to the user manually changing the timezone
*/
/**
- * SECTION:ginputstream
- * @short_description: Base class for implementing streaming input
+ * SECTION:gtls
+ * @title: TLS Overview
+ * @short_description: TLS (aka SSL) support for GSocketConnection
* @include: gio/gio.h
*
- * GInputStream has functions to read from a stream (g_input_stream_read()),
- * to close a stream (g_input_stream_close()) and to skip some content
- * (g_input_stream_skip()).
- * To copy the content of an input stream to an output stream without
- * manually handling the reads and writes, use g_output_stream_splice().
- * All of these functions have async variants too.
+ * #GTlsConnection and related classes provide TLS (Transport Layer
+ * Security, previously known as SSL, Secure Sockets Layer) support for
+ * gio-based network streams.
+ * In the simplest case, for a client connection, you can just set the
+ * #GSocketClient:tls flag on a #GSocketClient, and then any
+ * connections created by that client will have TLS negotiated
+ * automatically, using appropriate default settings, and rejecting
+ * any invalid or self-signed certificates (unless you change that
+ * default by setting the #GSocketClient:tls-validation-flags
+ * property). The returned object will be a #GTcpWrapperConnection,
+ * which wraps the underlying #GTlsClientConnection.
+ * For greater control, you can create your own #GTlsClientConnection,
+ * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
+ * pollable input and output streams) and then connect to its signals,
+ * such as #GTlsConnection::accept-certificate, before starting the
+ * handshake.
+ * Server-side TLS is similar, using #GTlsServerConnection. At the
+ * moment, there is no support for automatically wrapping server-side
+ * connections in the way #GSocketClient does for client-side
+ * connections.
*/
/**
- * SECTION:gioerror
- * @short_description: Error helper functions
+ * SECTION:gtlsbackend
+ * @title: GTlsBackend
+ * @short_description: TLS backend implementation
* @include: gio/gio.h
*
- * Contains helper functions for reporting errors to the user.
+ *
*/
/**
- * SECTION:giomodule
- * @short_description: Loadable GIO Modules
- * @include: gio/gio.h
+ * SECTION:gtlscertificate
+ * @title: GTlsCertificate
+ * @short_description: TLS certificate
+ * @see_also: #GTlsConnection
*
- * Provides an interface and default functions for loading and unloading
- * modules. This is used internally to make GIO extensible, but can also
- * be used by others to implement module loading.
+ * A certificate used for TLS authentication and encryption.
+ * This can represent either a public key only (eg, the certificate
+ * received by a client from a server), or the combination of
+ * a public key and a private key (which is needed when acting as a
+ * #GTlsServerConnection).
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gioscheduler
- * @short_description: I/O Scheduler
+ * SECTION:gtlsclientconnection
+ * @short_description: TLS client-side connection
* @include: gio/gio.h
*
- * Schedules asynchronous I/O operations. #GIOScheduler integrates
- * into the main event loop (#GMainLoop) and may use threads if they
- * are available.
- * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
- * Each I/O operation has a priority, and the scheduler uses the priorities
- * to determine the order in which operations are executed. They are
- * <emphasis>not</emphasis> used to determine system-wide I/O scheduling.
- * Priorities are integers, with lower numbers indicating higher priority.
- * It is recommended to choose priorities between %G_PRIORITY_LOW and
- * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.
- * </para>
+ * #GTlsClientConnection is the client-side subclass of
+ * #GTlsConnection, representing a client-side TLS connection.
*/
/**
- * SECTION:giostream
- * @short_description: Base class for implementing read/write streams
+ * SECTION:gtlsconnection
+ * @short_description: TLS connection type
* @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
*
- * GIOStream represents an object that has both read and write streams.
- * Generally the two streams acts as separate input and output streams,
- * but they share some common resources and state. For instance, for
- * seekable streams they may use the same position in both streams.
- * Examples of #GIOStream objects are #GSocketConnection which represents
- * a two-way network connection, and #GFileIOStream which represent a
- * file handle opened in read-write mode.
- * To do the actual reading and writing you need to get the substreams
- * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
- * The #GIOStream object owns the input and the output streams, not the other
- * way around, so keeping the substreams alive will not keep the #GIOStream
- * object alive. If the #GIOStream object is freed it will be closed, thus
- * closing the substream, so even if the substreams stay alive they will
- * always just return a %G_IO_ERROR_CLOSED for all operations.
- * To close a stream use g_io_stream_close() which will close the common
- * stream object and also the individual substreams. You can also close
- * the substreams themselves. In most cases this only marks the
- * substream as closed, so further I/O on it fails. However, some streams
- * may support "half-closed" states where one direction of the stream
- * is actually shut down.
+ * #GTlsConnection is the base TLS connection class type, which wraps
+ * a #GIOStream and provides TLS encryption on top of it. Its
+ * subclasses, #GTlsClientConnection and #GTlsServerConnection,
+ * implement client-side and server-side TLS, respectively.
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * SECTION:gloadableicon
- * @short_description: Loadable Icons
+ * SECTION:gtlsserverconnection
+ * @short_description: TLS server-side connection
* @include: gio/gio.h
- * @see_also: #GIcon, #GThemedIcon
*
- * Extends the #GIcon interface and adds the ability to
- * load icons from streams.
+ * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
+ * representing a server-side TLS connection.
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gmemoryinputstream
- * @short_description: Streaming input operations on memory chunks
- * @include: gio/gio.h
- * @see_also: #GMemoryOutputStream
+ * SECTION:gunixconnection
+ * @title: GUnixConnection
+ * @short_description: A UNIX domain GSocketConnection
+ * @include: gio/gunixconnection.h
+ * @see_also: #GSocketConnection.
*
- * #GMemoryInputStream is a class for using arbitrary
- * memory chunks as input for GIO streaming input operations.
+ * This is the subclass of #GSocketConnection that is created
+ * for UNIX domain sockets.
+ * It contains functions to do some of the UNIX socket specific
+ * functionality like passing file descriptors.
+ * Note that <filename><gio/gunixconnection.h></filename> belongs to
+ * the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ *
+ * Since: 2.22
*/
/**
- * SECTION:gmemoryoutputstream
- * @short_description: Streaming output operations on memory chunks
- * @include: gio/gio.h
- * @see_also: #GMemoryInputStream
+ * SECTION:gunixcredentialsmessage
+ * @title: GUnixCredentialsMessage
+ * @short_description: A GSocketControlMessage containing credentials
+ * @include: gio/gunixcredentialsmessage.h
+ * @see_also: #GUnixConnection, #GSocketControlMessage
*
- * #GMemoryOutputStream is a class for using arbitrary
- * memory chunks as output for GIO streaming output operations.
+ * This #GSocketControlMessage contains a #GCredentials instance. It
+ * may be sent using g_socket_send_message() and received using
+ * %G_SOCKET_FAMILY_UNIX family).
+ * For an easier way to send and receive credentials over
+ * stream-oriented UNIX sockets, see
+ * g_unix_connection_send_credentials() and
+ * g_unix_connection_receive_credentials(). To receive credentials of
+ * a foreign process connected to a socket, use
+ * g_socket_get_credentials().
+ *
+ * G_socket_receive_message() over unix sockets (ie: sockets in the
*/
/**
- * SECTION:gmount
- * @short_description: Mount management
- * @include: gio/gio.h
- * @see_also: GVolume, GUnixMount
+ * SECTION:gunixfdlist
+ * @title: GUnixFDList
+ * @short_description: An object containing a set of UNIX file descriptors
+ * @include: gio/gunixfdlist.h
+ * @see_also: #GUnixFDMessage
*
- * The #GMount interface represents user-visible mounts. Note, when
- * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
- * #GMount is a "mounted" filesystem that you can access. Mounted is in
- * quotes because it's not the same as a unix mount, it might be a gvfs
- * mount, but you can still access the files on it if you use GIO. Might or
- * might not be related to a volume object.
- * Unmounting a #GMount instance is an asynchronous operation. For
- * more information about asynchronous operations, see #GAsyncReady
- * and #GSimpleAsyncReady. To unmount a #GMount instance, first call
- * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
- * #GAsyncReadyCallback. The callback will be fired when the
- * operation has resolved (either with success or failure), and a
- * #GAsyncReady structure will be passed to the callback. That
- * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
- * and the #GAsyncReady data to see if the operation was completed
- * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
- * is called, then it will be filled with any error information.
+ * A #GUnixFDList contains a list of file descriptors. It owns the file
+ * descriptors that it contains, closing them when finalized.
+ * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
+ * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
+ * and received using g_socket_receive_message().
+ * Note that <filename><gio/gunixfdlist.h></filename> belongs to
+ * the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:gmountoperation
- * @short_description: Object used for authentication and user interaction
- * @include: gio/gio.h
+ * SECTION:gunixfdmessage
+ * @title: GUnixFDMessage
+ * @short_description: A GSocketControlMessage containing a GUnixFDList
+ * @include: gio/gunixfdmessage.h
+ * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
*
- * #GMountOperation provides a mechanism for interacting with the user.
- * It can be used for authenticating mountable operations, such as loop
- * mounting files, hard drive partitions or server locations. It can
- * also be used to ask the user questions or show a list of applications
- * preventing unmount or eject operations from completing.
- * Note that #GMountOperation is used for more than just #GMount
- * objects â?? for example it is also used in g_drive_start() and
- * g_drive_stop().
- * Users should instantiate a subclass of this that implements all the
- * various callbacks to show the required dialogs, such as
- * #GtkMountOperation. If no user interaction is desired (for example
- * when automounting filesystems at login time), usually %NULL can be
- * passed, see each method taking a #GMountOperation for details.
+ * This #GSocketControlMessage contains a #GUnixFDList.
+ * It may be sent using g_socket_send_message() and received using
+ * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
+ * between processes by the kernel.
+ * For an easier way to send and receive file descriptors over
+ * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
+ * g_unix_connection_receive_fd().
+ * Note that <filename><gio/gunixfdmessage.h></filename> belongs to
+ * the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ *
+ * G_socket_receive_message() over unix sockets (ie: sockets in the
*/
/**
- * SECTION:gnetworkaddress
- * @short_description: A GSocketConnectable for resolving hostnames
- * @include: gio/gio.h
+ * SECTION:gunixinputstream
+ * @short_description: Streaming input operations for UNIX file descriptors
+ * @include: gio/gunixinputstream.h
+ * @see_also: #GInputStream
*
- * #GNetworkAddress provides an easy way to resolve a hostname and
- * then attempt to connect to that host, handling the possibility of
- * multiple IP addresses and multiple address families.
- * See #GSocketConnectable for and example of using the connectable
- * interface.
+ * #GUnixInputStream implements #GInputStream for reading from a
+ * UNIX file descriptor, including asynchronous operations. The file
+ * descriptor must be selectable, so it doesn't work with opened files.
+ * Note that <filename><gio/gunixinputstream.h></filename> belongs
+ * to the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:gnetworkservice
- * @short_description: A GSocketConnectable for resolving SRV records
- * @include: gio/gio.h
+ * SECTION:gunixmounts
+ * @include: gio/gunixmounts.h
+ * @short_description: UNIX mounts
*
- * Like #GNetworkAddress does with hostnames, #GNetworkService
- * provides an easy way to resolve a SRV record, and then attempt to
- * connect to one of the hosts that implements that service, handling
- * service priority/weighting, multiple IP addresses, and multiple
- * address families.
- * See #GSrvTarget for more information about SRV records, and see
- * #GSocketConnectable for and example of using the connectable
- * interface.
+ * Routines for managing mounted UNIX mount points and paths.
+ * Note that <filename><gio/gunixmounts.h></filename> belongs to the
+ * UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:goutputstream
- * @short_description: Base class for implementing streaming output
- * @include: gio/gio.h
+ * SECTION:gunixoutputstream
+ * @short_description: Streaming output operations for UNIX file descriptors
+ * @include: gio/gunixoutputstream.h
+ * @see_also: #GOutputStream
*
- * GOutputStream has functions to write to a stream (g_output_stream_write()),
- * to close a stream (g_output_stream_close()) and to flush pending writes
- * (g_output_stream_flush()).
- * To copy the content of an input stream to an output stream without
- * manually handling the reads and writes, use g_output_stream_splice().
- * All of these functions have async variants too.
+ * #GUnixOutputStream implements #GOutputStream for writing to a
+ * UNIX file descriptor, including asynchronous operations. The file
+ * descriptor must be selectable, so it doesn't work with opened files.
+ * Note that <filename><gio/gunixoutputstream.h></filename> belongs
+ * to the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:gpermission
- * @title: GPermission
- * @short_description: An object representing the permission to perform a certain action
+ * SECTION:gunixsocketaddress
+ * @short_description: UNIX GSocketAddress
+ * @include: gio/gunixsocketaddress.h
*
- * A #GPermission represents the status of the caller's permission to
- * perform a certain action.
- * You can query if the action is currently allowed and if it is
- * possible to acquire the permission so that the action will be allowed
- * in the future.
- * There is also an API to actually acquire the permission and one to
- * release it.
- * As an example, a #GPermission might represent the ability for the
- * user to write to a #GSettings object. This #GPermission object could
- * then be used to decide if it is appropriate to show a "Click here to
- * unlock" button in a dialog and to provide the mechanism to invoke
- * when that button is clicked.
+ * Support for UNIX-domain (also known as local) sockets.
+ * UNIX domain sockets are generally visible in the filesystem.
+ * However, some systems support abstract socket names which are not
+ * visible in the filesystem and not affected by the filesystem
+ * permissions, visibility, etc. Currently this is only supported
+ * under Linux. If you attempt to use abstract sockets on other
+ * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
+ * errors. You can use g_unix_socket_address_abstract_names_supported()
+ * to see if abstract names are supported.
+ * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to
+ * the UNIX-specific GIO interfaces, thus you have to use the
+ * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:gpollableinputstream
- * @short_description: Interface for pollable input streams
+ * SECTION:gvfs
+ * @short_description: Virtual File System
* @include: gio/gio.h
- * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
- *
- * #GPollableInputStream is implemented by #GInputStream<!-- -->s that
- * can be polled for readiness to read. This can be used when
- * interfacing with a non-GIO API that expects
- * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
*
- * Since: 2.28
+ * Entry point for using GIO functionality.
*/
/**
- * SECTION:gpollableoutputstream
- * @short_description: Interface for pollable output streams
+ * SECTION:gvolume
+ * @short_description: Volume management
* @include: gio/gio.h
- * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
*
- * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
- * can be polled for readiness to write. This can be used when
- * interfacing with a non-GIO API that expects
- * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
+ * The #GVolume interface represents user-visible objects that can be
+ * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
+ * equivalent of #GnomeVFSDrive.
+ * Mounting a #GVolume instance is an asynchronous operation. For more
+ * information about asynchronous operations, see #GAsyncReady and
+ * #GSimpleAsyncReady. To mount a #GVolume, first call
+ * g_volume_mount() with (at least) the #GVolume instance, optionally
+ * a #GMountOperation object and a #GAsyncReadyCallback.
+ * Typically, one will only want to pass %NULL for the
+ * #GMountOperation if automounting all volumes when a desktop session
+ * starts since it's not desirable to put up a lot of dialogs asking
+ * for credentials.
+ * The callback will be fired when the operation has resolved (either
+ * with success or failure), and a #GAsyncReady structure will be
+ * passed to the callback. That callback should then call
+ * g_volume_mount_finish() with the #GVolume instance and the
+ * #GAsyncReady data to see if the operation was completed
+ * successfully. If an @error is present when g_volume_mount_finish()
+ * is called, then it will be filled with any error information.
+ * <para id="volume-identifier">
+ * It is sometimes necessary to directly access the underlying
+ * operating system object behind a volume (e.g. for passing a volume
+ * to an application via the commandline). For this purpose, GIO
+ * allows to obtain an 'identifier' for the volume. There can be
+ * different kinds of identifiers, such as Hal UDIs, filesystem labels,
+ * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
+ * uuids. GIO uses predefind strings as names for the different kinds
+ * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
+ * to obtain an identifier for a volume.
+ * </para>
+ * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
+ * when the gvfs hal volume monitor is in use. Other volume monitors
+ * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
+ * identifier, which can be used to obtain a hal device by means of
+ * libhal_manger_find_device_string_match().
*
- * Since: 2.28
+ * Of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
*/
/**
- * SECTION:gproxy
- * @short_description: Interface for proxy handling
- *
- * A #GProxy handles connecting to a remote host via a given type of
- * proxy server. It is implemented by the 'gio-proxy' extension point.
- * The extensions are named after their proxy protocol name. As an
- * example, a SOCKS5 proxy implementation can be retrieved with the
- * name 'socks5' using the function
- * g_io_extension_point_get_extension_by_name().
+ * SECTION:gvolumemonitor
+ * @short_description: Volume Monitor
+ * @include: gio/gio.h
+ * @see_also: #GFileMonitor
*
- * Since: 2.26
+ * #GVolumeMonitor is for listing the user interesting devices and volumes
+ * on the computer. In other words, what a file selector or file manager
+ * would show in a sidebar.
+ * #GVolumeMonitor is not <link
+ * linkend="g-main-context-push-thread-default">thread-default-context
+ * aware</link>, and so should not be used other than from the main
+ * thread, with no thread-default-context active.
*/
/**
- * SECTION:gproxyaddress
- * @short_description: An internet address with proxy information
+ * SECTION:gwin32inputstream
+ * @short_description: Streaming input operations for Windows file handles
+ * @include: gio/gwin32inputstream.h
+ * @see_also: #GInputStream
*
- * Support for proxied #GInetSocketAddress.
+ * #GWin32InputStream implements #GInputStream for reading from a
+ * Windows file handle.
+ * Note that <filename><gio/gwin32inputstream.h></filename> belongs
+ * to the Windows-specific GIO interfaces, thus you have to use the
+ * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:gproxyresolver
- * @short_description: Asynchronous and cancellable network proxy resolver
- * @include: gio/gio.h
+ * SECTION:gwin32outputstream
+ * @short_description: Streaming output operations for Windows file handles
+ * @include: gio/gwin32outputstream.h
+ * @see_also: #GOutputStream
*
- * #GProxyResolver provides synchronous and asynchronous network proxy
- * resolution. #GProxyResolver is used within #GClientSocket through
- * the method g_socket_connectable_proxy_enumerate().
+ * #GWin32OutputStream implements #GOutputStream for writing to a
+ * Windows file handle.
+ * Note that <filename><gio/gwin32outputstream.h></filename> belongs
+ * to the Windows-specific GIO interfaces, thus you have to use the
+ * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
*/
/**
- * SECTION:gresolver
- * @short_description: Asynchronous and cancellable DNS resolver
+ * SECTION:gzcompressor
+ * @short_description: Zlib compressor
* @include: gio/gio.h
*
- * #GResolver provides cancellable synchronous and asynchronous DNS
- * resolution, for hostnames (g_resolver_lookup_by_address(),
- * g_resolver_lookup_by_name() and their async variants) and SRV
- * (service) records (g_resolver_lookup_service()).
- * #GNetworkAddress and #GNetworkService provide wrappers around
- * #GResolver functionality that also implement #GSocketConnectable,
- * making it easy to connect to a remote host/service.
+ * #GZlibCompressor is an implementation of #GConverter that
+ * compresses data using zlib.
*/
/**
- * SECTION:gseekable
- * @short_description: Stream seeking interface
+ * SECTION:gzdecompressor
+ * @short_description: Zlib decompressor
* @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
*
- * #GSeekable is implemented by streams (implementations of
- * #GInputStream or #GOutputStream) that support seeking.
+ * #GZlibDecompressor is an implementation of #GConverter that
+ * decompresses data compressed with zlib.
*/
/**
- * SECTION:gsettings
- * @short_description: High-level API for application settings
+ * The string info map is an efficient data structure designed to be:
*
- * The #GSettings class provides a convenient API for storing and retrieving
- * application settings.
- * Reads and writes can be considered to be non-blocking. Reading
- * approximately the same order of magnitude (but slower than) a
- * #GHashTable lookup. Writing settings is also extremely fast in terms
- * of time to return to your application, but can be extremely expensive
- * for other threads and other processes. Many settings backends
- * (including dconf) have lazy initialisation which means in the common
- * case of the user using their computer without modifying any settings
- * a lot of work can be avoided. For dconf, the D-Bus service doesn't
- * even need to be started in this case. For this reason, you should
- * only ever modify #GSettings keys in response to explicit user action.
- * Particular care should be paid to ensure that modifications are not
- * made during startup -- for example, when settings the initial value
- * of preferences widgets. The built-in g_settings_bind() functionality
- * is careful not to write settings in response to notify signals as a
- * result of modifications that it makes to widgets.
- * When creating a GSettings instance, you have to specify a schema
- * that describes the keys in your settings and their types and default
- * values, as well as some other information.
- * Normally, a schema has as fixed path that determines where the settings
- * are stored in the conceptual global tree of settings. However, schemas
- * can also be 'relocatable', i.e. not equipped with a fixed path. This is
- * useful e.g. when the schema describes an 'account', and you want to be
- * able to store a arbitrary number of accounts.
- * Unlike other configuration systems (like GConf), GSettings does not
- * restrict keys to basic types like strings and numbers. GSettings stores
- * values as #GVariant, and allows any #GVariantType for keys. Key names
- * are restricted to lowercase characters, numbers and '-'. Furthermore,
- * the names must begin with a lowercase character, must not end
- * with a '-', and must not contain consecutive dashes. Key names can
- * be up to 32 characters long.
- * Similar to GConf, the default values in GSettings schemas can be
- * localized, but the localized values are stored in gettext catalogs
- * and looked up with the domain that is specified in the
- * <tag class="attribute">gettext-domain</tag> attribute of the
- * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
- * elements and the category that is specified in the l10n attribute of the
- * <tag class="starttag">key</tag> element.
- * GSettings uses schemas in a compact binary form that is created
- * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
- * utility. The input is a schema description in an XML format that can be
- * described by the following DTD:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
- * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
- * At runtime, schemas are identified by their id (as specified
- * in the <tag class="attribute">id</tag> attribute of the
- * <tag class="starttag">schema</tag> element). The
- * convention for schema ids is to use a dotted name, similar in
- * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
- * if the settings are for a specific service that owns a D-Bus bus name,
- * the D-Bus bus name and schema id should match. For schemas which deal
- * with settings not associated with one named application, the id should
- * not use StudlyCaps, e.g. "org.gnome.font-rendering".
- * In addition to #GVariant types, keys can have types that have enumerated
- * types. These can be described by a <tag class="starttag">choice</tag>,
- * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
- * <xref linkend="schema-enumerated"/>. The underlying type of
- * such a key is string, but you can use g_settings_get_enum(),
- * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
- * access the numeric values corresponding to the string value of enum
- * and flags keys.
- * <example id="schema-default-values"><title>Default values</title>
- * <programlisting><![CDATA[
- * <schemalist>
- * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
- * <key name="greeting" type="s">
- * <default l10n="messages">"Hello, earthlings"</default>
- * <summary>A greeting</summary>
- * <description>
- * Greeting of the invading martians
- * </description>
- * </key>
- * <key name="box" type="(ii)">
- * <default>(20,30)</default>
- * </key>
- * </schema>
- * </schemalist>
- * ]]></programlisting></example>
- * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
- * <programlisting><![CDATA[
- * <schemalist>
- * <enum id="myenum">
- * <value nick="first" value="1"/>
- * <value nick="second" value="2"/>
- * </enum>
- * <enum id="myflags">
- * <value nick="flag1" value="1"/>
- * <value nick="flag2" value="2"/>
- * <value nick="flag3" value="4"/>
- * </enum>
- * <schema id="org.gtk.Test">
- * <key name="key-with-range" type="i">
- * <range min="1" max="100"/>
- * <default>10</default>
- * </key>
- * <key name="key-with-choices" type="s">
- * <choices>
- * <choice value='Elisabeth'/>
- * <choice value='Annabeth'/>
- * <choice value='Joe'/>
- * </choices>
- * <aliases>
- * <alias value='Anna' target='Annabeth'/>
- * <alias value='Beth' target='Elisabeth'/>
- * </aliases>
- * <default>'Joe'</default>
- * </key>
- * <key name='enumerated-key' enum='myenum'>
- * <default>'first'</default>
- * </key>
- * <key name='flags-key' flags='myflags'>
- * <default>["flag1",flag2"]</default>
- * </key>
- * </schema>
- * </schemalist>
- * ]]></programlisting></example>
- * <refsect2>
- * <title>Vendor overrides</title>
- * <para>
- * Default values are defined in the schemas that get installed by
- * an application. Sometimes, it is necessary for a vendor or distributor
- * to adjust these defaults. Since patching the XML source for the schema
- * is inconvenient and error-prone,
- * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
- * so-called 'vendor override' files. These are keyfiles in the same
- * directory as the XML schema sources which can override default values.
- * The schema id serves as the group name in the key file, and the values
- * are expected in serialized GVariant form, as in the following example:
- * <informalexample><programlisting>
- * [org.gtk.Example]
- * key1='string'
- * key2=1.5
- * </programlisting></informalexample>
- * </para>
- * <para>
- * glib-compile-schemas expects schema files to have the extension
- * <filename>.gschema.override</filename>
- * </para>
- * </refsect2>
- * <refsect2>
- * <title>Binding</title>
- * <para>
- * A very convenient feature of GSettings lets you bind #GObject properties
- * directly to settings, using g_settings_bind(). Once a GObject property
- * has been bound to a setting, changes on either side are automatically
- * propagated to the other side. GSettings handles details like
- * mapping between GObject and GVariant types, and preventing infinite
- * cycles.
- * </para>
- * <para>
- * This makes it very easy to hook up a preferences dialog to the
- * underlying settings. To make this even more convenient, GSettings
- * looks for a boolean property with the name "sensitivity" and
- * automatically binds it to the writability of the bound setting.
- * If this 'magic' gets in the way, it can be suppressed with the
- * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
- * </para>
- * </refsect2>
+ * used with a small set of items. It is used by GSettings schemas for
+ * three purposes:
+ * 1) Implement <choices> with a list of valid strings
+ * 2) Implement <alias> by mapping one string to another
+ * 3) Implement enumerated types by mapping strings to integer values
+ * (and back).
+ * The map is made out of an array of uint32s. Each entry in the array
+ * is an integer value, followed by a specially formatted string value:
+ * The string starts with the byte 0xff or 0xfe, followed by the
+ * content of the string, followed by a nul byte, followed by
+ * additional nul bytes for padding, followed by a 0xff byte.
+ * Padding is added so that the entire formatted string takes up a
+ * multiple of 4 bytes, and not less than 8 bytes. The requirement
+ * for a string to take up 8 bytes is so that the scanner doesn't lose
+ * synch and mistake a string for an integer value.
+ * The first byte of the formatted string depends on if the integer is
+ * an enum value (0xff) or an alias (0xfe). If it is an alias then the
+ * number refers to the word offset within the info map at which the
+ * integer corresponding to the "target" value is stored.
+ * For example, consider the case of the string info map representing an
+ * enumerated type of 'foo' (value 1) and 'bar' (value 2) and 'baz'
+ * (alias for 'bar'). Note that string info maps are always little
+ * endian.
+ * x01 x00 x00 x00 xff 'f' 'o' 'o' x00 x00 x00 xff x02 x00 x00 x00
+ * xff 'b' 'a' 'r' x00 x00 x00 xff x03 x00 x00 x00 xfe 'b' 'a' 'z'
+ * x00 x00 x00 xff
+ * The operations that someone may want to perform with the map:
+ * - lookup if a string is valid (and not an alias)
+ * - lookup the integer value for a enum 'nick'
+ * - lookup the integer value for the target of an alias
+ * - lookup an alias and convert it to its target string
+ * - lookup the enum nick for a given value
+ * In order to lookup if a string is valid, it is padded on either side
+ * (as described) and scanned for in the array. For example, you might
+ * look for "foo":
+ * xff 'f' 'o' 'o' x00 x00 x00 xff
+ * In order to lookup the integer value for a nick, the string is padded
+ * on either side and scanned for in the array, as above. Instead of
+ * merely succeeding, we look at the integer value to the left of the
+ * match. This is the enum value.
+ * In order to lookup an alias and convert it to its target enum value,
+ * the string is padded on either side (as described, with 0xfe) and
+ * scanned for. For example, you might look for "baz":
+ * xfe 'b' 'a' 'z' x00 x00 x00 xff
+ * The integer immediately preceeding the match then contains the offset
+ * of the integer value of the target. In our example, that's '3'.
+ * This index is dereferenced to find the enum value of '2'.
+ * To convert the alias to its target string, 5 bytes just need to be
+ * added past the start of the integer value to find the start of the
+ * string.
+ * To lookup the enum nick for a given value, the value is searched for
+ * in the array. To ensure that the value isn't matching the inside of a
+ * string, we must check that it is either the first item in the array or
+ * immediately preceeded by the byte 0xff. It must also be immediately
+ * followed by the byte 0xff.
+ * Because strings always take up a minimum of 2 words, because 0xff or
+ * 0xfe never appear inside of a utf-8 string and because no two integer
+ * values ever appear in sequence, the only way we can have the
+ * sequence:
+ * xff __ __ __ __ xff (or 0xfe)
+ * is in the event of an integer nested between two strings.
+ * For implementation simplicity/efficiency, strings may not be more
+ * the value of each choice is set to zero and ignored.
*
- * Settings with #gsettings is typically extremely fast: on
+ * Than 65 characters in length (ie: 17 32bit words after padding).
+ * In the event that we are doing <choices> (ie: not an enum type) then
*/
/**
- * SECTION:gsettingsbackend
- * @title: GSettingsBackend
- * @short_description: Interface for settings backend implementations
- * @include: gio/gsettingsbackend.h
- * @see_also: #GSettings, #GIOExtensionPoint
+ * g_action_activate:
+ * @action: a #GAction
+ * @parameter: (allow-none): the parameter to the activation
*
- * The #GSettingsBackend interface defines a generic interface for
- * non-strictly-typed data that is stored in a hierarchy. To implement
- * an alternative storage backend for #GSettings, you need to implement
- * the #GSettingsBackend interface and then make it implement the
- * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
- * The interface defines methods for reading and writing values, a
- * method for determining if writing of certain values will fail
- * (lockdown) and a change notification mechanism.
- * The semantics of the interface are very precisely defined and
- * implementations must carefully adhere to the expectations of
- * callers that are documented on each of the interface methods.
- * Some of the GSettingsBackend functions accept or return a #GTree.
- * These trees always have strings as keys and #GVariant as values.
- * g_settings_backend_create_tree() is a convenience function to create
- * suitable trees.
- * <note><para>
- * The #GSettingsBackend API is exported to allow third-party
- * implementations, but does not carry the same stability guarantees
- * as the public GIO API. For this reason, you have to define the
- * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
- * <filename>gio/gsettingsbackend.h</filename>
- * </para></note>
- */
-
-
-/**
- * SECTION:gsimpleaction
- * @title: GSimpleAction
- * @short_description: A simple GSimpleAction
+ * Activates the action.
+ * the parameter type given at construction time). If the parameter
+ * type was %NULL then @parameter must also be %NULL.
*
- * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction
- * interface. This is the easiest way to create an action for purposes of
- * adding it to a #GSimpleActionGroup.
- * See also #GtkAction.
+ * Since: 2.28
*/
/**
- * SECTION:gsimpleactiongroup
- * @title: GSimpleActionGroup
- * @short_description: A simple GActionGroup implementation
+ * g_action_get_enabled:
+ * @action: a #GAction
*
- * #GSimpleActionGroup is a hash table filled with #GAction objects,
- * implementing the #GActionGroup interface.
+ * 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.
+ *
+ * Returns: whether the action is enabled
+ * Since: 2.28
*/
/**
- * SECTION:gsimpleasyncresult
- * @short_description: Simple asynchronous results implementation
- * @include: gio/gio.h
- * @see_also: #GAsyncResult
- *
- * Implements #GAsyncResult for simple cases. Most of the time, this
- * will be all an application needs, and will be used transparently.
- * Because of this, #GSimpleAsyncResult is used throughout GIO for
- * handling asynchronous functions.
- * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
- * reporting, operation cancellation and the final state of an operation,
- * completely transparent to the application. Results can be returned
- * as a pointer e.g. for functions that return data that is collected
- * asynchronously, a boolean value for checking the success or failure
- * of an operation, or a #gssize for operations which return the number
- * of bytes modified by the operation; all of the simple return cases
- * are covered.
- * Most of the time, an application will not need to know of the details
- * of this API; it is handled transparently, and any necessary operations
- * are handled by #GAsyncResult's interface. However, if implementing a
- * new GIO module, for writing language bindings, or for complex
- * applications that need better control of how asynchronous operations
- * are completed, it is important to understand this functionality.
- * GSimpleAsyncResults are tagged with the calling function to ensure
- * that asynchronous functions and their finishing functions are used
- * together correctly.
- * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
- * If the result needs to be created for a #GError, use
- * g_simple_async_result_new_from_error() or
- * g_simple_async_result_new_take_error(). If a #GError is not available
- * (e.g. the asynchronous operation's doesn't take a #GError argument),
- * but the result still needs to be created for an error condition, use
- * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
- * if your application or binding requires passing a variable argument list
- * directly), and the error can then be propagated through the use of
- * g_simple_async_result_propagate_error().
- * An asynchronous operation can be made to ignore a cancellation event by
- * calling g_simple_async_result_set_handle_cancellation() with a
- * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
- * operations that are dangerous to cancel, such as close (which would
- * cause a leak if cancelled before being run).
- * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
- * or it can use #GThread<!-- -->s if available.
- * g_simple_async_result_complete() will finish an I/O task directly
- * from the point where it is called. g_simple_async_result_complete_in_idle()
- * will finish it from an idle handler in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link>. g_simple_async_result_run_in_thread() will run the
- * job in a separate thread and then deliver the result to the
- * thread-default main context.
- * To set the results of an asynchronous function,
- * g_simple_async_result_set_op_res_gpointer(),
- * g_simple_async_result_set_op_res_gboolean(), and
- * g_simple_async_result_set_op_res_gssize()
- * are provided, setting the operation's result to a gpointer, gboolean, or
- * gssize, respectively.
- * Likewise, to get the result of an asynchronous function,
- * g_simple_async_result_get_op_res_gpointer(),
- * g_simple_async_result_get_op_res_gboolean(), and
- * g_simple_async_result_get_op_res_gssize() are
- * provided, getting the operation's result as a gpointer, gboolean, and
- * gssize, respectively.
- * For the details of the requirements implementations must respect, see
- * #GAsyncResult. A typical implementation of an asynchronous operation
- * using GSimpleAsyncResult looks something like this:
- * |[
- * static void
- * baked_cb (Cake *cake,
- * gpointer user_data)
- * {
- * /* In this example, this callback is not given a reference to the cake, so
- * * the GSimpleAsyncResult has to take a reference to it.
- * */
- * GSimpleAsyncResult *result = user_data;
- * if (cake == NULL)
- * g_simple_async_result_set_error (result,
- * BAKER_ERRORS,
- * BAKER_ERROR_NO_FLOUR,
- * "Go to the supermarket");
- * else
- * g_simple_async_result_set_op_res_gpointer (result,
- * g_object_ref (cake),
- * g_object_unref);
- * /* In this example, we assume that baked_cb is called as a callback from
- * * the mainloop, so it's safe to complete the operation synchronously here.
- * * If, however, _baker_prepare_cake () might call its callback without
- * * first returning to the mainloop â?? inadvisable, but some APIs do so â??
- * * we would need to use g_simple_async_result_complete_in_idle().
- * */
- * g_simple_async_result_complete (result);
- * g_object_unref (result);
- * }
- * void
- * baker_bake_cake_async (Baker *self,
- * guint radius,
- * GAsyncReadyCallback callback,
- * gpointer user_data)
- * {
- * GSimpleAsyncResult *simple;
- * Cake *cake;
- * if (radius < 3)
- * {
- * g_simple_async_report_error_in_idle (G_OBJECT (self),
- * callback,
- * user_data,
- * BAKER_ERRORS,
- * BAKER_ERROR_TOO_SMALL,
- * "%ucm radius cakes are silly",
- * radius);
- * return;
- * }
- * simple = g_simple_async_result_new (G_OBJECT (self),
- * callback,
- * user_data,
- * baker_bake_cake_async);
- * cake = _baker_get_cached_cake (self, radius);
- * if (cake != NULL)
- * {
- * g_simple_async_result_set_op_res_gpointer (simple,
- * g_object_ref (cake),
- * g_object_unref);
- * g_simple_async_result_complete_in_idle (simple);
- * g_object_unref (simple);
- * /* Drop the reference returned by _baker_get_cached_cake(); the
- * * GSimpleAsyncResult has taken its own reference.
- * */
- * g_object_unref (cake);
- * return;
- * }
- * _baker_prepare_cake (self, radius, baked_cb, simple);
- * }
- * Cake *
- * baker_bake_cake_finish (Baker *self,
- * GAsyncResult *result,
- * GError **error)
- * {
- * GSimpleAsyncResult *simple;
- * Cake *cake;
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (self),
- * baker_bake_cake_async),
- * NULL);
- * simple = (GSimpleAsyncResult *) result;
- * if (g_simple_async_result_propagate_error (simple, error))
- * return NULL;
- * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
- * return g_object_ref (cake);
- * }
- * ]|
+ * g_action_get_name:
+ * @action: a #GAction
+ *
+ * Queries the name of @action.
+ *
+ * Returns: the name of the action
+ * Since: 2.28
*/
/**
- * SECTION:gsimplepermission
- * @title: GSimplePermission
- * @short_description: A GPermission that doesn't change value
+ * g_action_get_parameter_type:
+ * @action: a #GAction
*
- * #GSimplePermission is a trivial implementation of #GPermission that
- * represents a permission that is either always or never allowed. The
- * value is given at constuction and doesn't change.
- * Calling request or release will result in errors.
+ * Queries the type of the parameter that must be given when activating
+ * When activating the action using g_action_activate(), the #GVariant
+ * given to that function must be of the type returned by this function.
+ * In the case that this function returns %NULL, you must not give any
+ * #GVariant, but %NULL instead.
+ *
+ * Returns: (allow-none): the parameter type
+ * Since: 2.28
*/
/**
- * SECTION:gsocket
- * @short_description: Low-level socket object
- * @include: gio/gio.h
- * @see_also: #GInitable
+ * g_action_get_state:
+ * @action: a #GAction
*
- * A #GSocket is a low-level networking primitive. It is a more or less
- * direct mapping of the BSD socket API in a portable GObject based API.
- * It supports both the UNIX socket implementations and winsock2 on Windows.
- * #GSocket is the platform independent base upon which the higher level
- * network primitives are based. Applications are not typically meant to
- * use it directly, but rather through classes like #GSocketClient,
- * #GSocketService and #GSocketConnection. However there may be cases where
- * direct use of #GSocket is useful.
- * #GSocket implements the #GInitable interface, so if it is manually constructed
- * by e.g. g_object_new() you must call g_initable_init() and check the
- * results before using the object. This is done automatically in
- * g_socket_new() and g_socket_new_from_fd(), so these functions can return
- * %NULL.
- * Sockets operate in two general modes, blocking or non-blocking. When
- * in blocking mode all operations block until the requested operation
- * is finished or there is an error. In non-blocking mode all calls that
- * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
- * To know when a call would successfully run you can call g_socket_condition_check(),
- * or g_socket_condition_wait(). You can also use g_socket_create_source() and
- * attach it to a #GMainContext to get callbacks when I/O is possible.
- * Note that all sockets are always set to non blocking mode in the system, and
- * blocking mode is emulated in GSocket.
- * When working in non-blocking mode applications should always be able to
- * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
- * function said that I/O was possible. This can easily happen in case
- * of a race condition in the application, but it can also happen for other
- * reasons. For instance, on Windows a socket is always seen as writable
- * until a write returns %G_IO_ERROR_WOULD_BLOCK.
- * #GSocket<!-- -->s can be either connection oriented or datagram based.
- * For connection oriented types you must first establish a connection by
- * either connecting to an address or accepting a connection from another
- * address. For connectionless socket types the target/source address is
- * specified or received in each I/O operation.
- * All socket file descriptors are set to be close-on-exec.
- * Note that creating a #GSocket causes the signal %SIGPIPE to be
- * ignored for the remainder of the program. If you are writing a
- * command-line utility that uses #GSocket, you may need to take into
- * account the fact that your program will not automatically be killed
- * if it tries to write to %stdout after it has been closed.
+ * 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.22
+ * Returns: (transfer full): the current state of the action
+ * Since: 2.28
*/
/**
- * SECTION:gsocketaddress
- * @short_description: Abstract base class representing endpoints for socket communication
+ * g_action_get_state_hint:
+ * @action: a #GAction
*
- * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
- * in the BSD sockets API. This is an abstract class; use
- * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
- * for UNIX domain sockets.
+ * Requests a hint about the valid range of values for the state of
+ * 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
+ * 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.
+ *
+ * Possible value for the state. if a #gvariant pair (ie: two-tuple) is
+ * Returns: (transfer full): the state range hint
+ * Since: 2.28
*/
/**
- * SECTION:gsocketclient
- * @short_description: Helper for connecting to a network service
- * @include: gio/gio.h
- * @see_also: #GSocketConnection, #GSocketListener
+ * g_action_get_state_type:
+ * @action: a #GAction
*
- * #GSocketClient is a high-level utility class for connecting to a
- * network host using a connection oriented socket type.
- * You create a #GSocketClient object, set any options you want, then
- * call a sync or async connect operation, which returns a #GSocketConnection
- * subclass on success.
- * The type of the #GSocketConnection object returned depends on the type of
- * the underlying socket that is in use. For instance, for a TCP/IP connection
- * it will be a #GTcpConnection.
+ * 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_set_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_set_state().
*
- * Since: 2.22
+ * Returns: (allow-none): the state type, if the action is stateful
+ * Since: 2.28
*/
/**
- * SECTION:gsocketconnectable
- * @short_description: Interface for potential socket endpoints
+ * g_action_group_action_added:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
*
- * Objects that describe one or more potential socket endpoints
- * implement #GSocketConnectable. Callers can then use
- * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
- * to try out each socket address in turn until one succeeds, as shown
- * in the sample code below.
- * |[
- * MyConnectionType *
- * connect_to_host (const char *hostname,
- * guint16 port,
- * GCancellable *cancellable,
- * GError **error)
- * {
- * MyConnection *conn = NULL;
- * GSocketConnectable *addr;
- * GSocketAddressEnumerator *enumerator;
- * GSocketAddress *sockaddr;
- * GError *conn_error = NULL;
- * addr = g_network_address_new ("www.gnome.org", 80);
- * enumerator = g_socket_connectable_enumerate (addr);
- * g_object_unref (addr);
- * /<!-- -->* Try each sockaddr until we succeed. Record the first
- * * connection error, but not any further ones (since they'll probably
- * * be basically the same as the first).
- * *<!-- -->/
- * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
- * {
- * g_object_unref (sockaddr);
- * }
- * g_object_unref (enumerator);
- * if (conn)
- * {
- * if (conn_error)
- * {
- * /<!-- -->* We couldn't connect to the first address, but we succeeded
- * * in connecting to a later address.
- * *<!-- -->/
- * g_error_free (conn_error);
- * }
- * return conn;
- * }
- * else if (error)
- * {
- * /<!-- -->* Either the initial lookup failed, or else the caller
- * * cancelled us.
- * *<!-- -->/
- * if (conn_error)
- * g_error_free (conn_error);
- * return NULL;
- * }
- * else
- * {
- * g_error_propagate (error, conn_error);
- * return NULL;
- * }
- * }
- * ]|
+ * Emits the #GActionGroup::action-added signal on @action_group.
+ * This function should only be called by #GActionGroup implementations.
*
- * Conn = connect_to_sockaddr (sockaddr, conn_error ? null : &conn_error);
+ * Since: 2.28
*/
/**
- * SECTION:gsocketconnection
- * @short_description: A socket connection
- * @include: gio/gio.h
- * @see_also: #GIOStream, #GSocketClient, #GSocketListener
+ * g_action_group_action_enabled_changed:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
+ * @enabled: whether or not the action is now enabled
*
- * #GSocketConnection is a #GIOStream for a connected socket. They
- * can be created either by #GSocketClient when connecting to a host,
- * or by #GSocketListener when accepting a new client.
- * The type of the #GSocketConnection object returned from these calls
- * depends on the type of the underlying socket that is in use. For
- * instance, for a TCP/IP connection it will be a #GTcpConnection.
- * Chosing what type of object to construct is done with the socket
- * connection factory, and it is possible for 3rd parties to register
- * custom socket connection types for specific combination of socket
- * family/type/protocol using g_socket_connection_factory_register_type().
+ * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
+ * This function should only be called by #GActionGroup implementations.
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * SECTION:gsocketcontrolmessage
- * @title: GSocketControlMessage
- * @short_description: A GSocket control message
- * @see_also: #GSocket.
+ * g_action_group_action_removed:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
*
- * A #GSocketControlMessage is a special-purpose utility message that
- * can be sent to or received from a #GSocket. These types of
- * messages are often called "ancillary data".
- * The message can represent some sort of special instruction to or
- * information from the socket or can represent a special kind of
- * transfer to the peer (for example, sending a file description over
- * a UNIX socket).
- * These messages are sent with g_socket_send_message() and received
- * with g_socket_receive_message().
- * To extend the set of control message that can be sent, subclass this
- * class and override the get_size, get_level, get_type and serialize
- * methods.
- * To extend the set of control messages that can be received, subclass
- * this class and implement the deserialize method. Also, make sure your
- * class is registered with the GType typesystem before calling
- * g_socket_receive_message() to read such a message.
+ * Emits the #GActionGroup::action-removed signal on @action_group.
+ * This function should only be called by #GActionGroup implementations.
*
- * Since: 2.22
+ * Since: 2.28
*/
/**
- * SECTION:gsocketlistener
- * @title: GSocketListener
- * @short_description: Helper for accepting network client connections
- * @see_also: #GThreadedSocketService, #GSocketService.
+ * g_action_group_action_state_changed:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of an action in the group
+ * @state: the new state of the named action
*
- * A #GSocketListener is an object that keeps track of a set
- * of server sockets and helps you accept sockets from any of the
- * socket, either sync or async.
- * If you want to implement a network server, also look at #GSocketService
- * and #GThreadedSocketService which are subclass of #GSocketListener
- * that makes this even easier.
+ * Emits the #GActionGroup::action-state-changed signal on @action_group.
+ * This function should only be called by #GActionGroup implementations.
+ *
+ * Since: 2.28
+ */
+
+
+/**
+ * g_action_group_activate_action:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to activate
+ * @parameter: (allow-none): parameters to the activation
*
- * Since: 2.22
+ * Activate the named action within @action_group.
+ * If the action is expecting a parameter, then the correct type of
+ * parameter must be given as @parameter. If the action is expecting no
+ * parameters then @parameter must be %NULL. See
+ * g_action_group_get_action_parameter_type().
+ *
+ * Since: 2.28
*/
/**
- * SECTION:gsocketservice
- * @title: GSocketService
- * @short_description: Make it easy to implement a network service
- * @see_also: #GThreadedSocketService, #GSocketListener.
+ * g_action_group_change_action_state:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to request the change on
+ * @value: the new state
*
- * A #GSocketService is an object that represents a service that is
- * provided to the network or over local sockets. When a new
- * connection is made to the service the #GSocketService:incoming
- * signal is emitted.
- * A #GSocketService is a subclass of #GSocketListener and you need
- * to add the addresses you want to accept connections on to the
- * with the #GSocketListener APIs.
- * There are two options for implementing a network service based on
- * #GSocketService. The first is to create the service using
- * g_socket_service_new() and to connect to the #GSocketService:incoming
- * signal. The second is to subclass #GSocketService and override the
- * default signal handler implementation.
- * In either case, the handler must immediately return, or else it
- * will block additional incoming connections from being serviced.
- * If you are interested in writing connection handlers that contain
- * blocking code then see #GThreadedSocketService.
- * The socket service runs on the main loop in the main thread, and is
- * not threadsafe in general. However, the calls to start and stop
- * the service are threadsafe so these can be used from threads that
- * handle incoming clients.
+ * 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.22
+ * Since: 2.28
*/
/**
- * SECTION:gsrvtarget
- * @short_description: DNS SRV record target
- * @include: gio/gio.h
+ * g_action_group_get_action_enabled:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * SRV (service) records are used by some network protocols to provide
- * service-specific aliasing and load-balancing. For example, XMPP
- * (Jabber) uses SRV records to locate the XMPP server for a domain;
- * rather than connecting directly to "example.com" or assuming a
- * specific server hostname like "xmpp.example.com", an XMPP client
- * would look up the "xmpp-client" SRV record for "example.com", and
- * then connect to whatever host was pointed to by that record.
- * You can use g_resolver_lookup_service() or
- * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
- * for a given service. However, if you are simply planning to connect
- * to the remote service, you can use #GNetworkService's
- * #GSocketConnectable interface and not need to worry about
- * #GSrvTarget at all.
+ * 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.
+ *
+ * Returns: whether or not the action is currently enabled
+ * Since: 2.28
*/
/**
- * SECTION:gtcpconnection
- * @title: GTcpConnection
- * @short_description: A TCP GSocketConnection
- * @see_also: #GSocketConnection.
+ * g_action_group_get_action_parameter_type:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * This is the subclass of #GSocketConnection that is created
- * for TCP/IP sockets.
+ * 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.22
+ * Returns: the parameter type
+ * Since: 2.28
*/
/**
- * SECTION:gtcpwrapperconnection
- * @title: GTcpWrapperConnection
- * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
- * @see_also: #GSocketConnection.
+ * g_action_group_get_action_state:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
- * based on a #GSocket, but which is not actually a
- * #GSocketConnection. This is used by #GSocketClient so that it can
- * always return a #GSocketConnection, even when the connection it has
- * actually created is not directly a #GSocketConnection.
+ * Queries the current state of the named action within @action_group.
+ * If the action is not stateful then %NULL will be returned. If the
+ * action is stateful then the type of the return value is the type
+ * given by g_action_group_get_action_state_type().
+ * The return value (if non-%NULL) should be freed with
+ * g_variant_unref() when it is no longer required.
*
+ * Returns: (allow-none): the current state of the action
* Since: 2.28
*/
/**
- * SECTION:gthemedicon
- * @short_description: Icon theming support
- * @include: gio/gio.h
- * @see_also: #GIcon, #GLoadableIcon
+ * g_action_group_get_action_state_hint:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * #GThemedIcon is an implementation of #GIcon that supports icon themes.
- * #GThemedIcon contains a list of all of the icons present in an icon
- * theme, so that icons can be looked up quickly. #GThemedIcon does
- * not provide actual pixmaps for icons, just the icon names.
- * Ideally something like gtk_icon_theme_choose_icon() should be used to
- * resolve the list of names so that fallback icons work nicely with
- * themes that inherit other themes.
+ * 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
+ * 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.
+ *
+ * Possible value for the state. if a #gvariant pair (ie: two-tuple) is
+ * Returns: (transfer full): the state range hint
+ * Since: 2.28
*/
/**
- * SECTION:gthreadedsocketservice
- * @title: GThreadedSocketService
- * @short_description: A threaded GSocketService
- * @see_also: #GSocketService.
+ * g_action_group_get_action_state_type:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to query
*
- * A #GThreadedSocketService is a simple subclass of #GSocketService
- * that handles incoming connections by creating a worker thread and
- * dispatching the connection to it by emitting the ::run signal in
- * the new thread.
- * The signal handler may perform blocking IO and need not return
- * until the connection is closed.
- * The service is implemented using a thread pool, so there is a
- * limited amount of threads availible to serve incomming requests.
- * The service automatically stops the #GSocketService from accepting
- * new connections when all threads are busy.
- * As with #GSocketService, you may connect to #GThreadedSocketService:run,
- * or subclass and override the default handler.
+ * Queries the type of the state of the named action within
+ * 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.
+ *
+ * Returns: (transfer full): the state type, if the action is stateful
+ * Since: 2.28
*/
/**
- * SECTION:gtls
- * @title: TLS Overview
- * @short_description: TLS (aka SSL) support for GSocketConnection
- * @include: gio/gio.h
+ * g_action_group_has_action:
+ * @action_group: a #GActionGroup
+ * @action_name: the name of the action to check for
*
- * #GTlsConnection and related classes provide TLS (Transport Layer
- * Security, previously known as SSL, Secure Sockets Layer) support for
- * gio-based network streams.
- * In the simplest case, for a client connection, you can just set the
- * #GSocketClient:tls flag on a #GSocketClient, and then any
- * connections created by that client will have TLS negotiated
- * automatically, using appropriate default settings, and rejecting
- * any invalid or self-signed certificates (unless you change that
- * default by setting the #GSocketClient:tls-validation-flags
- * property). The returned object will be a #GTcpWrapperConnection,
- * which wraps the underlying #GTlsClientConnection.
- * For greater control, you can create your own #GTlsClientConnection,
- * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
- * pollable input and output streams) and then connect to its signals,
- * such as #GTlsConnection::accept-certificate, before starting the
- * handshake.
- * Server-side TLS is similar, using #GTlsServerConnection. At the
- * moment, there is no support for automatically wrapping server-side
- * connections in the way #GSocketClient does for client-side
- * connections.
+ * Checks if the named action exists within @action_group.
+ *
+ * Returns: whether the named action exists
+ * Since: 2.28
*/
/**
- * SECTION:gtlsbackend
- * @title: GTlsBackend
- * @short_description: TLS backend implementation
- * @include: gio/gio.h
+ * g_action_group_list_actions:
+ * @action_group: a #GActionGroup
*
+ * Lists the actions contained within @action_group.
+ * The caller is responsible for freeing the list with g_strfreev() when
+ * it is no longer required.
+ * actions in the groupb
*
+ * Returns: (transfer full): a %NULL-terminated array of the names of the
+ * Since: 2.28
*/
/**
- * SECTION:gtlscertificate
- * @title: GTlsCertificate
- * @short_description: TLS certificate
- * @see_also: #GTlsConnection
+ * g_action_set_state:
+ * @action: a #GAction
+ * @value: the new state
*
- * A certificate used for TLS authentication and encryption.
- * This can represent either a public key only (eg, the certificate
- * received by a client from a server), or the combination of
- * a public key and a private key (which is needed when acting as a
- * #GTlsServerConnection).
+ * 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.28
*/
/**
- * SECTION:gtlsclientconnection
- * @short_description: TLS client-side connection
- * @include: gio/gio.h
+ * g_alloca:
+ * @size: number of bytes to allocate.
*
- * #GTlsClientConnection is the client-side subclass of
- * #GTlsConnection, representing a client-side TLS connection.
+ * Allocates @size bytes on the stack; these bytes will be freed when the current
+ * stack frame is cleaned up. This macro essentially just wraps the alloca()
+ * function present on most UNIX variants.
+ * Thus it provides the same advantages and pitfalls as alloca():
+ * <variablelist>
+ * <varlistentry><term></term><listitem><para>
+ * + alloca() is very fast, as on most systems it's implemented by just adjusting
+ * the stack pointer register.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
+ * blocks just build up and are released together at function end.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation sizes have to fit into the current stack frame. For instance in a
+ * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+ * so be sparse with alloca() uses.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation failure due to insufficient stack space is not indicated with a %NULL
+ * return like e.g. with malloc(). Instead, most systems probably handle it the same
+ * way as out of stack space situations from infinite function recursion, i.e.
+ * with a segmentation fault.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
+ * Stack space allocated with alloca() in the same scope as a variable sized array
+ * will be freed together with the variable sized array upon exit of that scope, and
+ * not upon exit of the enclosing function scope.
+ * </para></listitem></varlistentry>
+ * </variablelist>
+ *
+ * Returns: space for @size bytes, allocated on the stack
*/
/**
- * SECTION:gtlsconnection
- * @short_description: TLS connection type
- * @include: gio/gio.h
+ * g_app_info_add_supports_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: a string.
+ * @error: a #GError.
*
- * #GTlsConnection is the base TLS connection class type, which wraps
- * a #GIOStream and provides TLS encryption on top of it. Its
- * subclasses, #GTlsClientConnection and #GTlsServerConnection,
- * implement client-side and server-side TLS, respectively.
+ * Adds a content type to the application information to indicate the
+ * application is capable of opening files with the given content type.
*
- * Since: 2.28
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * SECTION:gtlsserverconnection
- * @short_description: TLS server-side connection
- * @include: gio/gio.h
+ * g_app_info_can_delete:
+ * @appinfo: a #GAppInfo
*
- * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
- * representing a server-side TLS connection.
+ * Obtains the information whether the #GAppInfo can be deleted.
+ * See g_app_info_delete().
*
- * Since: 2.28
+ * Returns: %TRUE if @appinfo can be deleted
+ * Since: 2.20
*/
/**
- * SECTION:gunixconnection
- * @title: GUnixConnection
- * @short_description: A UNIX domain GSocketConnection
- * @include: gio/gunixconnection.h
- * @see_also: #GSocketConnection.
+ * g_app_info_can_remove_supports_type:
+ * @appinfo: a #GAppInfo.
*
- * This is the subclass of #GSocketConnection that is created
- * for UNIX domain sockets.
- * It contains functions to do some of the UNIX socket specific
- * functionality like passing file descriptors.
- * Note that <filename><gio/gunixconnection.h></filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Checks if a supported content type can be removed from an application.
+ * content types from a given @appinfo, %FALSE if not.
*
- * Since: 2.22
+ * Returns: %TRUE if it is possible to remove supported
*/
/**
- * SECTION:gunixcredentialsmessage
- * @title: GUnixCredentialsMessage
- * @short_description: A GSocketControlMessage containing credentials
- * @include: gio/gunixcredentialsmessage.h
- * @see_also: #GUnixConnection, #GSocketControlMessage
+ * g_app_info_create_from_commandline:
+ * @commandline: the commandline to use
+ * @application_name: (allow-none): the application name, or %NULL to use @commandline
+ * @flags: flags that can specify details of the created #GAppInfo
+ * @error: a #GError location to store the error occuring, %NULL to ignore.
*
- * This #GSocketControlMessage contains a #GCredentials instance. It
- * may be sent using g_socket_send_message() and received using
- * %G_SOCKET_FAMILY_UNIX family).
- * For an easier way to send and receive credentials over
- * stream-oriented UNIX sockets, see
- * g_unix_connection_send_credentials() and
- * g_unix_connection_receive_credentials(). To receive credentials of
- * a foreign process connected to a socket, use
- * g_socket_get_credentials().
+ * Creates a new #GAppInfo from the given information.
*
- * G_socket_receive_message() over unix sockets (ie: sockets in the
+ * Returns: (transfer full): new #GAppInfo for given command.
*/
/**
- * SECTION:gunixfdlist
- * @title: GUnixFDList
- * @short_description: An object containing a set of UNIX file descriptors
- * @include: gio/gunixfdlist.h
- * @see_also: #GUnixFDMessage
+ * g_app_info_delete:
+ * @appinfo: a #GAppInfo
*
- * A #GUnixFDList contains a list of file descriptors. It owns the file
- * descriptors that it contains, closing them when finalized.
- * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
- * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
- * and received using g_socket_receive_message().
- * Note that <filename><gio/gunixfdlist.h></filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Tries to delete a #GAppInfo.
+ * On some platforms, there may be a difference between user-defined
+ * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
+ * cannot. See g_app_info_can_delete().
+ *
+ * Virtual: do_delete
+ * Returns: %TRUE if @appinfo has been deleted
+ * Since: 2.20
*/
/**
- * SECTION:gunixfdmessage
- * @title: GUnixFDMessage
- * @short_description: A GSocketControlMessage containing a GUnixFDList
- * @include: gio/gunixfdmessage.h
- * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
+ * g_app_info_dup:
+ * @appinfo: a #GAppInfo.
*
- * This #GSocketControlMessage contains a #GUnixFDList.
- * It may be sent using g_socket_send_message() and received using
- * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
- * between processes by the kernel.
- * For an easier way to send and receive file descriptors over
- * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
- * g_unix_connection_receive_fd().
- * Note that <filename><gio/gunixfdmessage.h></filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Creates a duplicate of a #GAppInfo.
*
- * G_socket_receive_message() over unix sockets (ie: sockets in the
+ * Returns: (transfer full): a duplicate of @appinfo.
*/
/**
- * SECTION:gunixinputstream
- * @short_description: Streaming input operations for UNIX file descriptors
- * @include: gio/gunixinputstream.h
- * @see_also: #GInputStream
+ * g_app_info_equal:
+ * @appinfo1: the first #GAppInfo.
+ * @appinfo2: the second #GAppInfo.
*
- * #GUnixInputStream implements #GInputStream for reading from a
- * UNIX file descriptor, including asynchronous operations. The file
- * descriptor must be selectable, so it doesn't work with opened files.
- * Note that <filename><gio/gunixinputstream.h></filename> belongs
- * to the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
- */
-
-
-/**
- * SECTION:gunixmounts
- * @include: gio/gunixmounts.h
- * @short_description: UNIX mounts
+ * Checks if two #GAppInfo<!-- -->s are equal.
*
- * Routines for managing mounted UNIX mount points and paths.
- * Note that <filename><gio/gunixmounts.h></filename> belongs to the
- * UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
*/
/**
- * SECTION:gunixoutputstream
- * @short_description: Streaming output operations for UNIX file descriptors
- * @include: gio/gunixoutputstream.h
- * @see_also: #GOutputStream
+ * g_app_info_get_all:
*
- * #GUnixOutputStream implements #GOutputStream for writing to a
- * UNIX file descriptor, including asynchronous operations. The file
- * descriptor must be selectable, so it doesn't work with opened files.
- * Note that <filename><gio/gunixoutputstream.h></filename> belongs
- * to the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Gets a list of all of the applications currently registered
+ * on this system.
+ * For desktop files, this includes applications that have
+ * <literal>NoDisplay=true</literal> set or are excluded from
+ * display by means of <literal>OnlyShowIn</literal> or
+ * <literal>NotShowIn</literal>. See g_app_info_should_show().
+ * The returned list does not include applications which have
+ * the <literal>Hidden</literal> key set.
+ *
+ * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
*/
/**
- * SECTION:gunixsocketaddress
- * @short_description: UNIX GSocketAddress
- * @include: gio/gunixsocketaddress.h
+ * g_app_info_get_all_for_type:
+ * @content_type: the content type to find a #GAppInfo for
*
- * Support for UNIX-domain (also known as local) sockets.
- * UNIX domain sockets are generally visible in the filesystem.
- * However, some systems support abstract socket names which are not
- * visible in the filesystem and not affected by the filesystem
- * permissions, visibility, etc. Currently this is only supported
- * under Linux. If you attempt to use abstract sockets on other
- * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
- * errors. You can use g_unix_socket_address_abstract_names_supported()
- * to see if abstract names are supported.
- * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Gets a list of all #GAppInfos for a given content type.
+ * for given @content_type or %NULL on error.
+ *
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
*/
/**
- * SECTION:gvfs
- * @short_description: Virtual File System
- * @include: gio/gio.h
+ * g_app_info_get_commandline:
+ * @appinfo: a #GAppInfo
*
- * Entry point for using GIO functionality.
+ * Gets the commandline with which the application will be
+ * started.
+ * or %NULL if this information is not available
+ *
+ * Returns: a string containing the @appinfo's commandline,
+ * Since: 2.20
*/
/**
- * SECTION:gvolume
- * @short_description: Volume management
- * @include: gio/gio.h
+ * g_app_info_get_default_for_type:
+ * @content_type: the content type to find a #GAppInfo for
+ * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs
*
- * The #GVolume interface represents user-visible objects that can be
- * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
- * equivalent of #GnomeVFSDrive.
- * Mounting a #GVolume instance is an asynchronous operation. For more
- * information about asynchronous operations, see #GAsyncReady and
- * #GSimpleAsyncReady. To mount a #GVolume, first call
- * g_volume_mount() with (at least) the #GVolume instance, optionally
- * a #GMountOperation object and a #GAsyncReadyCallback.
- * Typically, one will only want to pass %NULL for the
- * #GMountOperation if automounting all volumes when a desktop session
- * starts since it's not desirable to put up a lot of dialogs asking
- * for credentials.
- * The callback will be fired when the operation has resolved (either
- * with success or failure), and a #GAsyncReady structure will be
- * passed to the callback. That callback should then call
- * g_volume_mount_finish() with the #GVolume instance and the
- * #GAsyncReady data to see if the operation was completed
- * successfully. If an @error is present when g_volume_mount_finish()
- * is called, then it will be filled with any error information.
- * <para id="volume-identifier">
- * It is sometimes necessary to directly access the underlying
- * operating system object behind a volume (e.g. for passing a volume
- * to an application via the commandline). For this purpose, GIO
- * allows to obtain an 'identifier' for the volume. There can be
- * different kinds of identifiers, such as Hal UDIs, filesystem labels,
- * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
- * uuids. GIO uses predefind strings as names for the different kinds
- * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
- * to obtain an identifier for a volume.
- * </para>
- * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
- * when the gvfs hal volume monitor is in use. Other volume monitors
- * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
- * identifier, which can be used to obtain a hal device by means of
- * libhal_manger_find_device_string_match().
+ * Gets the #GAppInfo that corresponds to a given content type.
+ * %NULL on error.
*
- * Of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
+ * Returns: (transfer full): #GAppInfo for given @content_type or
*/
/**
- * SECTION:gvolumemonitor
- * @short_description: Volume Monitor
- * @include: gio/gio.h
- * @see_also: #GFileMonitor
+ * g_app_info_get_default_for_uri_scheme:
+ * @uri_scheme: a string containing a URI scheme.
*
- * #GVolumeMonitor is for listing the user interesting devices and volumes
- * on the computer. In other words, what a file selector or file manager
- * would show in a sidebar.
- * #GVolumeMonitor is not <link
- * linkend="g-main-context-push-thread-default">thread-default-context
- * aware</link>, and so should not be used other than from the main
- * thread, with no thread-default-context active.
+ * Gets the default application for launching applications
+ * using this URI scheme. A URI scheme is the initial part
+ * of the URI, up to but not including the ':', e.g. "http",
+ * "ftp" or "sip".
+ *
+ * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
*/
/**
- * SECTION:gwin32inputstream
- * @short_description: Streaming input operations for Windows file handles
- * @include: gio/gwin32inputstream.h
- * @see_also: #GInputStream
+ * g_app_info_get_description:
+ * @appinfo: a #GAppInfo.
*
- * #GWin32InputStream implements #GInputStream for reading from a
- * Windows file handle.
- * Note that <filename><gio/gwin32inputstream.h></filename> belongs
- * to the Windows-specific GIO interfaces, thus you have to use the
- * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
+ * Gets a human-readable description of an installed application.
+ * application @appinfo, or %NULL if none.
+ *
+ * Returns: a string containing a description of the
*/
/**
- * SECTION:gwin32outputstream
- * @short_description: Streaming output operations for Windows file handles
- * @include: gio/gwin32outputstream.h
- * @see_also: #GOutputStream
+ * g_app_info_get_display_name:
+ * @appinfo: a #GAppInfo.
*
- * #GWin32OutputStream implements #GOutputStream for writing to a
- * Windows file handle.
- * Note that <filename><gio/gwin32outputstream.h></filename> belongs
- * to the Windows-specific GIO interfaces, thus you have to use the
- * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
+ * Gets the display name of the application. The display name is often more
+ * descriptive to the user than the name itself.
+ * no display name is available.
+ *
+ * Returns: the display name of the application for @appinfo, or the name if
+ * Since: 2.24
*/
/**
- * SECTION:gzcompressor
- * @short_description: Zlib compressor
- * @include: gio/gio.h
+ * g_app_info_get_executable:
+ * @appinfo: a #GAppInfo
*
- * #GZlibCompressor is an implementation of #GConverter that
- * compresses data using zlib.
+ * Gets the executable's name for the installed application.
+ * binaries name
+ *
+ * Returns: a string containing the @appinfo's application
*/
/**
- * SECTION:gzdecompressor
- * @short_description: Zlib decompressor
- * @include: gio/gio.h
+ * g_app_info_get_fallback_for_type:
+ * @content_type: the content type to find a #GAppInfo for
*
- * #GZlibDecompressor is an implementation of #GConverter that
- * decompresses data compressed with zlib.
+ * 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.
+ * for given @content_type or %NULL on error.
+ *
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * Since: 2.28
*/
/**
- * The string info map is an efficient data structure designed to be:
+ * g_app_info_get_icon:
+ * @appinfo: a #GAppInfo.
*
- * used with a small set of items. It is used by GSettings schemas for
- * three purposes:
- * 1) Implement <choices> with a list of valid strings
- * 2) Implement <alias> by mapping one string to another
- * 3) Implement enumerated types by mapping strings to integer values
- * (and back).
- * The map is made out of an array of uint32s. Each entry in the array
- * is an integer value, followed by a specially formatted string value:
- * The string starts with the byte 0xff or 0xfe, followed by the
- * content of the string, followed by a nul byte, followed by
- * additional nul bytes for padding, followed by a 0xff byte.
- * Padding is added so that the entire formatted string takes up a
- * multiple of 4 bytes, and not less than 8 bytes. The requirement
- * for a string to take up 8 bytes is so that the scanner doesn't lose
- * synch and mistake a string for an integer value.
- * The first byte of the formatted string depends on if the integer is
- * an enum value (0xff) or an alias (0xfe). If it is an alias then the
- * number refers to the word offset within the info map at which the
- * integer corresponding to the "target" value is stored.
- * For example, consider the case of the string info map representing an
- * enumerated type of 'foo' (value 1) and 'bar' (value 2) and 'baz'
- * (alias for 'bar'). Note that string info maps are always little
- * endian.
- * x01 x00 x00 x00 xff 'f' 'o' 'o' x00 x00 x00 xff x02 x00 x00 x00
- * xff 'b' 'a' 'r' x00 x00 x00 xff x03 x00 x00 x00 xfe 'b' 'a' 'z'
- * x00 x00 x00 xff
- * The operations that someone may want to perform with the map:
- * - lookup if a string is valid (and not an alias)
- * - lookup the integer value for a enum 'nick'
- * - lookup the integer value for the target of an alias
- * - lookup an alias and convert it to its target string
- * - lookup the enum nick for a given value
- * In order to lookup if a string is valid, it is padded on either side
- * (as described) and scanned for in the array. For example, you might
- * look for "foo":
- * xff 'f' 'o' 'o' x00 x00 x00 xff
- * In order to lookup the integer value for a nick, the string is padded
- * on either side and scanned for in the array, as above. Instead of
- * merely succeeding, we look at the integer value to the left of the
- * match. This is the enum value.
- * In order to lookup an alias and convert it to its target enum value,
- * the string is padded on either side (as described, with 0xfe) and
- * scanned for. For example, you might look for "baz":
- * xfe 'b' 'a' 'z' x00 x00 x00 xff
- * The integer immediately preceeding the match then contains the offset
- * of the integer value of the target. In our example, that's '3'.
- * This index is dereferenced to find the enum value of '2'.
- * To convert the alias to its target string, 5 bytes just need to be
- * added past the start of the integer value to find the start of the
- * string.
- * To lookup the enum nick for a given value, the value is searched for
- * in the array. To ensure that the value isn't matching the inside of a
- * string, we must check that it is either the first item in the array or
- * immediately preceeded by the byte 0xff. It must also be immediately
- * followed by the byte 0xff.
- * Because strings always take up a minimum of 2 words, because 0xff or
- * 0xfe never appear inside of a utf-8 string and because no two integer
- * values ever appear in sequence, the only way we can have the
- * sequence:
- * xff __ __ __ __ xff (or 0xfe)
- * is in the event of an integer nested between two strings.
- * For implementation simplicity/efficiency, strings may not be more
- * the value of each choice is set to zero and ignored.
+ * Gets the icon for the application.
*
- * Than 65 characters in length (ie: 17 32bit words after padding).
- * In the event that we are doing <choices> (ie: not an enum type) then
+ * Returns: (transfer none): the default #GIcon for @appinfo.
*/
/**
- * g_action_activate:
- * @action: a #GAction
- * @parameter: (allow-none): the parameter to the activation
+ * g_app_info_get_id:
+ * @appinfo: a #GAppInfo.
*
- * Activates the action.
- * the parameter type given at construction time). If the parameter
- * type was %NULL then @parameter must also be %NULL.
+ * 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.
*
- * Since: 2.28
+ * Returns: a string containing the application's ID.
*/
/**
- * g_action_get_enabled:
- * @action: a #GAction
+ * g_app_info_get_name:
+ * @appinfo: a #GAppInfo.
*
- * 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.
+ * Gets the installed name of the application.
*
- * Returns: whether the action is enabled
- * Since: 2.28
+ * Returns: the name of the application for @appinfo.
*/
/**
- * g_action_get_name:
- * @action: a #GAction
+ * g_app_info_get_recommended_for_type:
+ * @content_type: the content type to find a #GAppInfo for
*
- * Queries the name of @action.
+ * 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.
+ * for given @content_type or %NULL on error.
*
- * Returns: the name of the action
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
* Since: 2.28
*/
/**
- * g_action_get_parameter_type:
- * @action: a #GAction
+ * g_app_info_launch:
+ * @appinfo: a #GAppInfo
+ * @files: (element-type GFile): a #GList of #GFile objects
+ * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
+ * @error: a #GError
*
- * Queries the type of the parameter that must be given when activating
- * 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.
+ * Launches the application. Passes @files to the launched application
+ * as arguments, using the optional @launch_context to get information
+ * about the details of the launcher (like what screen it is on).
+ * On error, @error will be set accordingly.
+ * To launch the application without arguments pass a %NULL @files list.
+ * Note that even if the launch is successful the application launched
+ * can fail to start if it runs into problems during startup. There is
+ * no way to detect this.
+ * 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.
+ * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
+ * environment variable with the path of the launched desktop file and
+ * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
+ * id of the launched process. This can be used to ignore
+ * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
+ * by further processes. The <envar>DISPLAY</envar> and
+ * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
+ * set, based on information provided in @launch_context.
*
- * Returns: (allow-none): the parameter type
- * Since: 2.28
+ * Returns: %TRUE on successful launch, %FALSE otherwise.
*/
/**
- * g_action_get_state:
- * @action: a #GAction
+ * g_app_info_launch_default_for_uri:
+ * @uri: the uri to show
+ * @launch_context: (allow-none): an optional #GAppLaunchContext.
+ * @error: a #GError.
*
- * 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.
+ * 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.
*
- * Returns: (transfer full): the current state of the action
- * Since: 2.28
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * g_action_get_state_hint:
- * @action: a #GAction
+ * g_app_info_launch_uris:
+ * @appinfo: a #GAppInfo
+ * @uris: (element-type utf8): a #GList containing URIs to launch.
+ * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
+ * @error: a #GError
*
- * Requests a hint about the valid range of values for the state of
- * 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
- * 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.
+ * Launches the application. Passes @uris to the launched application
+ * as arguments, using the optional @launch_context to get information
+ * about the details of the launcher (like what screen it is on).
+ * On error, @error will be set accordingly.
+ * To lauch 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.
+ *
+ * Returns: %TRUE on successful launch, %FALSE otherwise.
+ */
+
+
+/**
+ * g_app_info_remove_supports_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: a string.
+ * @error: a #GError.
*
- * Possible value for the state. if a #gvariant pair (ie: two-tuple) is
- * Returns: (transfer full): the state range hint
- * Since: 2.28
+ * Removes a supported type from an application, if possible.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * g_action_get_state_type:
- * @action: a #GAction
+ * g_app_info_reset_type_associations:
+ * @content_type: a content type
*
- * Queries the type of the state of @action.
- * g_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_set_state() must give a #GVariant of
- * this type and g_action_get_state() will return a #GVariant of the
- * same type.
- * this function will return %NULL. In that case, g_action_get_state()
- * will return %NULL and you must not call g_action_set_state().
+ * 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().
*
- * If the action is stateful (ie: was created with
- * If the action is not stateful (ie: created with g_action_new()) then
- * Returns: (allow-none): the state type, if the action is stateful
- * Since: 2.28
+ * Since: 2.20
*/
/**
- * g_action_group_action_added:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
+ * g_app_info_set_as_default_for_extension:
+ * @appinfo: a #GAppInfo.
+ * @extension: a string containing the file extension (without the dot).
+ * @error: a #GError.
*
- * Emits the #GActionGroup::action-added signal on @action_group.
- * This function should only be called by #GActionGroup implementations.
+ * Sets the application as the default handler for the given file extension.
*
- * Since: 2.28
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * g_action_group_action_enabled_changed:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
- * @enabled: whether or not the action is now enabled
+ * g_app_info_set_as_default_for_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: the content type.
+ * @error: a #GError.
*
- * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
- * This function should only be called by #GActionGroup implementations.
+ * Sets the application as the default handler for a given type.
*
- * Since: 2.28
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * g_action_group_action_removed:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
+ * g_app_info_set_as_last_used_for_type:
+ * @appinfo: a #GAppInfo.
+ * @content_type: the content type.
+ * @error: a #GError.
*
- * Emits the #GActionGroup::action-removed signal on @action_group.
- * This function should only be called by #GActionGroup implementations.
+ * 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.
*
- * Since: 2.28
+ * Returns: %TRUE on success, %FALSE on error.
*/
/**
- * g_action_group_action_state_changed:
- * @action_group: a #GActionGroup
- * @action_name: the name of an action in the group
- * @state: the new state of the named action
+ * g_app_info_should_show:
+ * @appinfo: a #GAppInfo.
*
- * Emits the #GActionGroup::action-state-changed signal on @action_group.
- * This function should only be called by #GActionGroup implementations.
+ * Checks if the application info should be shown in menus that
+ * list available applications.
*
- * Since: 2.28
+ * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
*/
/**
- * g_action_group_activate_action:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to activate
- * @parameter: (allow-none): parameters to the activation
+ * g_app_info_supports_files:
+ * @appinfo: a #GAppInfo.
*
- * 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_parameter_type().
+ * Checks if the application accepts files as arguments.
*
- * Since: 2.28
+ * Returns: %TRUE if the @appinfo supports files.
*/
/**
- * g_action_group_change_action_state:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to request the change on
- * @value: the new state
+ * g_app_info_supports_uris:
+ * @appinfo: a #GAppInfo.
*
- * 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_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_state_hint().
- * If the @value GVariant is floating, it is consumed.
+ * Checks if the application supports reading files and directories from URIs.
*
- * Since: 2.28
+ * Returns: %TRUE if the @appinfo supports URIs.
*/
/**
- * g_action_group_get_action_enabled:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
+ * g_app_launch_context_get_display:
+ * @context: a #GAppLaunchContext
+ * @info: a #GAppInfo
+ * @files: (element-type GFile): a #GList of #GFile objects
*
- * 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.
+ * Gets the display string for the @context. This is used to ensure new
+ * applications are started on the same display as the launching
+ * application, by setting the <envar>DISPLAY</envar> environment variable.
*
- * Returns: whether or not the action is currently enabled
- * Since: 2.28
+ * Returns: a display string for the display.
*/
/**
- * g_action_group_get_action_parameter_type:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
+ * g_app_launch_context_get_startup_notify_id:
+ * @context: a #GAppLaunchContext
+ * @info: a #GAppInfo
+ * @files: (element-type GFile): a #GList of of #GFile objects
*
- * 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(), 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.
+ * Initiates startup notification for the application and returns the
+ * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
+ * if supported.
+ * Startup notification IDs are defined in the <ulink
+ * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt";>
+ * FreeDesktop.Org Startup Notifications standard</ulink>.
+ * not supported.
*
- * Returns: the parameter type
- * Since: 2.28
+ * Returns: a startup notification ID for the application, or %NULL if
*/
/**
- * g_action_group_get_action_state:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
- *
- * Queries the current state of the named action within @action_group.
- * If the action is not stateful then %NULL will be returned. If the
- * action is stateful then the type of the return value is the type
- * given by g_action_group_get_state_type().
- * The return value (if non-%NULL) should be freed with
- * g_variant_unref() when it is no longer required.
+ * g_app_launch_context_launch_failed:
+ * @context: a #GAppLaunchContext.
+ * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
*
- * Returns: (allow-none): the current state of the action
- * Since: 2.28
+ * Called when an application has failed to launch, so that it can cancel
+ * the application startup notification started in g_app_launch_context_get_startup_notify_id().
*/
/**
- * g_action_group_get_action_state_hint:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
+ * g_app_launch_context_new:
*
- * 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
- * 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.
+ * Creates a new application launch context. This is not normally used,
+ * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
*
- * Possible value for the state. if a #gvariant pair (ie: two-tuple) is
- * Returns: (transfer full): the state range hint
- * Since: 2.28
+ * Returns: a #GAppLaunchContext.
*/
/**
- * g_action_group_get_action_state_type:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to query
+ * g_application_activate:
+ * @application: a #GApplication
*
- * Queries the type of the state of the named action within
- * If the action is stateful then this function returns the
- * #GVariantType of the state. All calls to g_action_group_set_state()
- * must give a #GVariant of this type and g_action_group_get_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_state() will return %NULL and you
- * must not call g_action_group_set_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.
+ * 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.
*
- * Returns: (transfer full): the state type, if the action is stateful
* Since: 2.28
*/
/**
- * g_action_group_has_action:
- * @action_group: a #GActionGroup
- * @action_name: the name of the action to check for
+ * g_application_command_line_get_arguments:
+ * @cmdline: a #GApplicationCommandLine
+ * @argc: (out): the length of the arguments array, or %NULL
*
- * Checks if the named action exists within @action_group.
+ * Gets the list of arguments that was passed on the command line.
+ * The strings in the array may contain non-utf8 data.
+ * The return value is %NULL-terminated and should be freed using
+ * g_strfreev().
+ * containing the arguments (the argv)
*
- * Returns: whether the named action exists
+ * Returns: (array length=argc) (transfer full): the string array
* Since: 2.28
*/
/**
- * g_action_group_list_actions:
- * @action_group: a #GActionGroup
+ * g_application_command_line_get_cwd:
+ * @cmdline: a #GApplicationCommandLine
*
- * Lists the actions contained within @action_group.
- * The caller is responsible for freeing the list with g_strfreev() when
- * it is no longer required.
- * actions in the groupb
+ * 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.
*
- * Returns: (transfer full): a %NULL-terminated array of the names of the
+ * Returns: the current directory, or %NULL
* Since: 2.28
*/
/**
- * g_action_set_state:
- * @action: a #GAction
- * @value: the new state
+ * g_application_command_line_get_environ:
+ * @cmdline: a #GApplicationCommandLine
*
- * 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.
+ * 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.
+ * strings, or %NULL if they were not sent
+ *
+ * Returns: (array zero-terminated=1) (transfer none): the environment
+ * Since: 2.28
+ */
+
+
+/**
+ * g_application_command_line_get_exit_status:
+ * @cmdline: a #GApplicationCommandLine
+ *
+ * Gets the exit status of @cmdline. See
+ * g_application_command_line_set_exit_status() for more information.
*
+ * Returns: the exit status
* Since: 2.28
*/
/**
- * g_alloca:
- * @size: number of bytes to allocate.
+ * g_application_command_line_get_is_remote:
+ * @cmdline: a #GApplicationCommandLine
*
- * Allocates @size bytes on the stack; these bytes will be freed when the current
- * stack frame is cleaned up. This macro essentially just wraps the alloca()
- * function present on most UNIX variants.
- * Thus it provides the same advantages and pitfalls as alloca():
- * <variablelist>
- * <varlistentry><term></term><listitem><para>
- * + alloca() is very fast, as on most systems it's implemented by just adjusting
- * the stack pointer register.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
- * blocks just build up and are released together at function end.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation sizes have to fit into the current stack frame. For instance in a
- * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
- * so be sparse with alloca() uses.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation failure due to insufficient stack space is not indicated with a %NULL
- * return like e.g. with malloc(). Instead, most systems probably handle it the same
- * way as out of stack space situations from infinite function recursion, i.e.
- * with a segmentation fault.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
- * Stack space allocated with alloca() in the same scope as a variable sized array
- * will be freed together with the variable sized array upon exit of that scope, and
- * not upon exit of the enclosing function scope.
- * </para></listitem></varlistentry>
- * </variablelist>
+ * Determines if @cmdline represents a remote invocation.
*
- * Returns: space for @size bytes, allocated on the stack
+ * Returns: %TRUE if the invocation was remote
+ * Since: 2.28
*/
/**
- * g_app_info_add_supports_type:
- * @appinfo: a #GAppInfo.
- * @content_type: a string.
- * @error: a #GError.
+ * g_application_command_line_get_platform_data:
+ * @cmdline: #GApplicationCommandLine
*
- * Adds a content type to the application information to indicate the
- * application is capable of opening files with the given content type.
+ * Gets the platform data associated with the invocation of @cmdline.
+ * This is a #GVariant dictionary containing information about the
+ * context in which the invocation occured. It typically contains
+ * information like the current working directory and the startup
+ * notification ID.
+ * For local invocation, it will be %NULL.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: the platform data, or %NULL
+ * Since: 2.28
*/
/**
- * g_app_info_can_delete:
- * @appinfo: a #GAppInfo
+ * g_application_command_line_getenv:
+ * @cmdline: a #GApplicationCommandLine
+ * @name: the environment variable to get
*
- * Obtains the information whether the #GAppInfo can be deleted.
- * See g_app_info_delete().
+ * 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.
*
- * Returns: %TRUE if @appinfo can be deleted
- * Since: 2.20
+ * Returns: the value of the variable, or %NULL if unset or unsent
+ * Since: 2.28
*/
/**
- * g_app_info_can_remove_supports_type:
- * @appinfo: a #GAppInfo.
+ * g_application_command_line_print:
+ * @cmdline: a #GApplicationCommandLine
+ * @format: a printf-style format string
+ * @...: arguments, as per @format
*
- * Checks if a supported content type can be removed from an application.
- * content types from a given @appinfo, %FALSE if not.
+ * 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.
*
- * Returns: %TRUE if it is possible to remove supported
+ * Since: 2.28
*/
/**
- * g_app_info_create_from_commandline:
- * @commandline: the commandline to use
- * @application_name: (allow-none): the application name, or %NULL to use @commandline
- * @flags: flags that can specify details of the created #GAppInfo
- * @error: a #GError location to store the error occuring, %NULL to ignore.
+ * g_application_command_line_printerr:
+ * @cmdline: a #GApplicationCommandLine
+ * @format: a printf-style format string
+ * @...: arguments, as per @format
*
- * Creates a new #GAppInfo from the given information.
+ * 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.
*
- * Returns: (transfer full): new #GAppInfo for given command.
+ * Since: 2.28
*/
/**
- * g_app_info_delete:
- * @appinfo: a #GAppInfo
+ * g_application_command_line_set_exit_status:
+ * @cmdline: a #GApplicationCommandLine
+ * @exit_status: the exit status
*
- * Tries to delete a #GAppInfo.
- * On some platforms, there may be a difference between user-defined
- * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
- * cannot. See g_app_info_can_delete().
+ * 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
+ * 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.
*
- * Virtual: do_delete
- * Returns: %TRUE if @appinfo has been deleted
- * Since: 2.20
+ * In the mainloop running (ie: because the use-count of the application
+ * Since: 2.28
*/
/**
- * g_app_info_dup:
- * @appinfo: a #GAppInfo.
+ * g_application_get_application_id:
+ * @application: a #GApplication
+ * @returns: the identifier for @application, owned by @application
*
- * Creates a duplicate of a #GAppInfo.
+ * Gets the unique identifier for @application.
*
- * Returns: (transfer full): a duplicate of @appinfo.
+ * Since: 2.28
*/
/**
- * g_app_info_equal:
- * @appinfo1: the first #GAppInfo.
- * @appinfo2: the second #GAppInfo.
+ * g_application_get_flags:
+ * @application: a #GApplication
+ * @returns: the flags for @application
*
- * Checks if two #GAppInfo<!-- -->s are equal.
+ * Gets the flags for @application.
+ * See #GApplicationFlags.
*
- * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
+ * Since: 2.28
*/
/**
- * g_app_info_get_all:
+ * g_application_get_inactivity_timeout:
+ * @application: a #GApplication
*
- * Gets a list of all of the applications currently registered
- * on this system.
- * For desktop files, this includes applications that have
- * <literal>NoDisplay=true</literal> set or are excluded from
- * display by means of <literal>OnlyShowIn</literal> or
- * <literal>NotShowIn</literal>. See g_app_info_should_show().
- * The returned list does not include applications which have
- * the <literal>Hidden</literal> key set.
+ * 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.
*
- * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
+ * Returns: the timeout, in milliseconds
+ * Since: 2.28
*/
/**
- * g_app_info_get_all_for_type:
- * @content_type: the content type to find a #GAppInfo for
+ * g_application_get_is_registered:
+ * @application: a #GApplication
+ * @returns: %TRUE if @application is registered
*
- * Gets a list of all #GAppInfos for a given content type.
- * for given @content_type or %NULL on error.
+ * Checks if @application is registered.
+ * An application is registered if g_application_register() has been
+ * successfully called.
*
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * Since: 2.28
*/
/**
- * g_app_info_get_commandline:
- * @appinfo: a #GAppInfo
+ * g_application_get_is_remote:
+ * @application: a #GApplication
+ * @returns: %TRUE if @application is remote
*
- * Gets the commandline with which the application will be
- * started.
- * or %NULL if this information is not available
+ * 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().
*
- * Returns: a string containing the @appinfo's commandline,
- * Since: 2.20
+ * Since: 2.28
*/
/**
- * g_app_info_get_default_for_type:
- * @content_type: the content type to find a #GAppInfo for
- * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs
- *
- * Gets the #GAppInfo that corresponds to a given content type.
- * %NULL on error.
+ * g_application_hold:
+ * @application: a #GApplication
*
- * Returns: (transfer full): #GAppInfo for given @content_type or
+ * Increases the use count of @application.
+ * Use this function to indicate that the application has a reason to
+ * continue to run. For example, g_application_hold() is called by GTK+
+ * when a toplevel window is on the screen.
+ * To cancel the hold, call g_application_release().
*/
/**
- * g_app_info_get_default_for_uri_scheme:
- * @uri_scheme: a string containing a URI scheme.
- *
- * Gets the default application for launching applications
- * using this URI scheme. A URI scheme is the initial part
- * of the URI, up to but not including the ':', e.g. "http",
- * "ftp" or "sip".
+ * g_application_id_is_valid:
+ * @application_id: a potential application identifier
+ * @returns: %TRUE if @application_id is valid
*
- * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
+ * Checks if @application_id is a valid application identifier.
+ * A valid ID is required for calls to g_application_new() and
+ * g_application_set_application_id().
+ * For convenience, the restrictions on application identifiers are
+ * reproduced here:
+ * <itemizedlist>
+ * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
+ * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
+ * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
+ * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
+ * <listitem>Application identifiers must not exceed 255 characters.</listitem>
+ * </itemizedlist>
*/
/**
- * g_app_info_get_description:
- * @appinfo: a #GAppInfo.
- *
- * Gets a human-readable description of an installed application.
- * application @appinfo, or %NULL if none.
+ * g_application_new:
+ * @application_id: the application id
+ * @flags: the application flags
+ * @returns: a new #GApplication instance
*
- * Returns: a string containing a description of the
+ * Creates a new #GApplication instance.
+ * This function calls g_type_init() for you.
+ * The application id must be valid. See g_application_id_is_valid().
*/
/**
- * g_app_info_get_display_name:
- * @appinfo: a #GAppInfo.
+ * g_application_open:
+ * @application: a #GApplication
+ * @files: (array length=n_files): an array of #GFiles to open
+ * @n_files: the length of the @files array
+ * @hint: a hint (or ""), but never %NULL
*
- * Gets the display name of the application. The display name is often more
- * descriptive to the user than the name itself.
- * no display name is available.
+ * Opens the given files.
+ * In essence, this results in the #GApplication::open signal being emitted
+ * in the primary instance.
+ * intended to be used by applications that have multiple modes for
+ * for this functionality, you should use "".
+ * The application must be registered before calling this function
+ * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
*
- * Returns: the display name of the application for @appinfo, or the name if
- * Since: 2.24
+ * Opening files (eg: "view" vs "edit", etc). Unless you have a need
+ * Since: 2.28
*/
/**
- * g_app_info_get_executable:
- * @appinfo: a #GAppInfo
+ * g_application_register:
+ * @application: a #GApplication
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a NULL #GError, or %NULL
+ * @returns: %TRUE if registration succeeded
*
- * Gets the executable's name for the installed application.
- * binaries name
+ * Attempts registration of the application.
+ * This is the point at which the application discovers if it is the
+ * primary instance or merely acting as a remote for an already-existing
+ * primary instance. This is implemented by attempting to acquire the
+ * application identifier as a unique bus name on the session bus using
+ * GDBus.
+ * Due to the internal architecture of GDBus, method calls can be
+ * dispatched at any time (even if a main loop is not running). For
+ * this reason, you must ensure that any object paths that you wish to
+ * register are registered before calling this function.
+ * 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.
+ * 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.
+ * instance is or is not the primary instance of the application. See
+ * g_application_get_is_remote() for that.
*
- * Returns: a string containing the @appinfo's application
+ * Note: the return value of this function is not an indicator that this
+ * Since: 2.28
*/
/**
- * g_app_info_get_fallback_for_type:
- * @content_type: the content type to find a #GAppInfo for
- *
- * 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.
- * for given @content_type or %NULL on error.
+ * g_application_release:
+ * @application: a #GApplication
*
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
- * Since: 2.28
+ * 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().
*/
/**
- * g_app_info_get_icon:
- * @appinfo: a #GAppInfo.
+ * g_application_run:
+ * @application: a #GApplication
+ * @argc: the argc from main() (or 0 if @argv is %NULL)
+ * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
+ * @returns: the exit status
*
- * Gets the icon for the application.
+ * 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.
+ * First, the local_command_line() virtual function is invoked.
+ * This function always runs on the local instance. It gets passed a pointer
+ * to a %NULL-terminated copy of @argv and is expected to remove the arguments
+ * that it handled (shifting up remaining arguments). See
+ * <xref linkend="gapplication-example-cmdline2"/> for an example of
+ * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
+ * after setting <literal>argc = g_strv_length (argv);</literal>.
+ * The last argument to local_command_line() is a pointer to the @status
+ * variable which can used to set the exit status that is returned from
+ * g_application_run().
+ * If local_command_line() returns %TRUE, the command line is expected
+ * to be completely handled, including possibly registering as the primary
+ * instance, calling g_application_activate() or g_application_open(), etc.
+ * If local_command_line() returns %FALSE then the application is registered
+ * and the #GApplication::command-line signal is emitted in the primary
+ * instance (which may or may not be this instance). The signal handler
+ * gets passed a #GApplicationCommandline object that (among other things)
+ * contains the remaining commandline arguments that have not been handled
+ * by local_command_line().
+ * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
+ * flag set then the default implementation of local_command_line()
+ * always returns %FALSE immediately, resulting in the commandline
+ * always being handled in the primary instance.
+ * Otherwise, the default implementation of local_command_line() tries
+ * to do a couple of things that are probably reasonable for most
+ * applications. First, g_application_register() is called to attempt
+ * to register the application. If that works, then the command line
+ * arguments are inspected. If no commandline arguments are given, then
+ * g_application_activate() is called. If commandline arguments are
+ * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
+ * are assumed to be filenames and g_application_open() is called.
+ * If you need to handle commandline arguments that are not filenames,
+ * and you don't mind commandline handling to happen in the primary
+ * instance, you should set %G_APPLICATION_HANDLED_COMMAND_LINE and
+ * process the commandline arguments in your #GApplication::command-line
+ * signal handler, either manually or using the #GOptionContext API.
+ * If you are interested in doing more complicated local handling of the
+ * commandline then you should implement your own #GApplication subclass
+ * and override local_command_line(). In this case, you most likely want
+ * to return %TRUE from your local_command_line() implementation to
+ * suppress the default handling. See
+ * <xref linkend="gapplication-example-cmdline2"/> for an example.
+ * 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 mainloop is run until the use count falls to zero,
+ * at which point 0 is returned.
+ * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
+ * around to provide its <emphasis>service</emphasis> to others).
*
- * Returns: (transfer none): the default #GIcon for @appinfo.
+ * Use count of zero is delayed for a while (ie: the instance stays
+ * Since: 2.28
*/
/**
- * g_app_info_get_id:
- * @appinfo: a #GAppInfo.
+ * g_application_set_action_group:
+ * @application: a #GApplication
+ * @action_group: (allow-none): a #GActionGroup, or %NULL
*
- * 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.
+ * Sets or unsets the group of actions associated with the application.
+ * These actions are the actions that can be remotely invoked.
+ * It is an error to call this function after the application has been
+ * registered.
*
- * Returns: a string containing the application's ID.
+ * Since: 2.28
*/
/**
- * g_app_info_get_name:
- * @appinfo: a #GAppInfo.
+ * g_application_set_application_id:
+ * @application: a #GApplication
+ * @application_id: the identifier for @application
*
- * Gets the installed name of the application.
+ * Sets the unique identifier for @application.
+ * The application id can only be modified if @application has not yet
+ * been registered.
+ * The application id must be valid. See g_application_id_is_valid().
*
- * Returns: the name of the application for @appinfo.
+ * Since: 2.28
*/
/**
- * g_app_info_get_recommended_for_type:
- * @content_type: the content type to find a #GAppInfo for
+ * g_application_set_flags:
+ * @application: a #GApplication
+ * @flags: the flags for @application
*
- * 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.
- * for given @content_type or %NULL on error.
+ * Sets the flags for @application.
+ * The flags can only be modified if @application has not yet been
+ * registered.
+ * See #GApplicationFlags.
*
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
* Since: 2.28
*/
/**
- * g_app_info_launch:
- * @appinfo: a #GAppInfo
- * @files: (element-type GFile): a #GList of #GFile objects
- * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
- * @error: a #GError
+ * g_application_set_inactivity_timeout:
+ * @application: a #GApplication
+ * @inactivity_timeout: the timeout, in milliseconds
*
- * Launches the application. Passes @files to the launched application
- * as arguments, using the optional @launch_context to get information
- * about the details of the launcher (like what screen it is on).
- * On error, @error will be set accordingly.
- * To launch the application without arguments pass a %NULL @files list.
- * Note that even if the launch is successful the application launched
- * can fail to start if it runs into problems during startup. There is
- * no way to detect this.
- * 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.
- * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
- * environment variable with the path of the launched desktop file and
- * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
- * id of the launched process. This can be used to ignore
- * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
- * by further processes. The <envar>DISPLAY</envar> and
- * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
- * set, based on information provided in @launch_context.
+ * 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.
*
- * Returns: %TRUE on successful launch, %FALSE otherwise.
+ * Returns: the timeout, in milliseconds
+ * Since: 2.28
*/
/**
- * g_app_info_launch_default_for_uri:
- * @uri: the uri to show
- * @launch_context: (allow-none): an optional #GAppLaunchContext.
- * @error: a #GError.
+ * g_async_initable_init_async:
+ * @initable: a #GAsyncInitable.
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
*
- * Utility function that launches the default application
- * registered to handle the specified uri. Synchronous I/O
- * is done on the uri to detect the type of the file if
- * required.
+ * 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.
+ * 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.
+ * If this function is not called, or returns with an error, then all
+ * operations on the object should fail, generally returning the
+ * error %G_IO_ERROR_NOT_INITIALIZED.
+ * to this function with the same argument should return the same results.
+ * Only the first call initializes the object; further calls return the result
+ * of the first call. This is so that it's safe to implement the singleton
+ * pattern in the GObject constructor function.
+ * For classes that also support the #GInitable interface, the default
+ * implementation of this method will run the g_initable_init() function
+ * in a thread, so if you want to support asynchronous initialization via
+ * threads, just implement the #GAsyncInitable interface without overriding
+ * any interface methods.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Implementations of this method must be idempotent: i.e. multiple calls
+ * Since: 2.22
*/
/**
- * g_app_info_launch_uris:
- * @appinfo: a #GAppInfo
- * @uris: (element-type utf8): a #GList containing URIs to launch.
- * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
- * @error: a #GError
+ * g_async_initable_init_finish:
+ * @initable: a #GAsyncInitable.
+ * @res: a #GAsyncResult.
+ * @error: a #GError location to store the error occuring, or %NULL to ignore.
*
- * Launches the application. Passes @uris to the launched application
- * as arguments, using the optional @launch_context to get information
- * about the details of the launcher (like what screen it is on).
- * On error, @error will be set accordingly.
- * To lauch 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.
+ * Finishes asynchronous initialization and returns the result.
+ * See g_async_initable_init_async().
+ * will return %FALSE and set @error appropriately if present.
*
- * Returns: %TRUE on successful launch, %FALSE otherwise.
+ * Returns: %TRUE if successful. If an error has occurred, this function
+ * Since: 2.22
*/
/**
- * g_app_info_remove_supports_type:
- * @appinfo: a #GAppInfo.
- * @content_type: a string.
- * @error: a #GError.
+ * g_async_initable_new_async:
+ * @object_type: a #GType supporting #GAsyncInitable.
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the initialization is finished
+ * @user_data: the data to pass to callback function
+ * @first_property_name: the name of the first property, or %NULL if no properties
+ * @...: the value of the first property, followed by other property value pairs, and ended by %NULL.
*
- * Removes a supported type from an application, if possible.
+ * 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.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.22
*/
/**
- * g_app_info_reset_type_associations:
- * @content_type: a content type
+ * g_async_initable_new_finish:
+ * @initable: the #GAsyncInitable from the callback
+ * @res: the #GAsyncResult from the callback
+ * @error: return location for errors, or %NULL to ignore
*
- * 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().
+ * Finishes the async construction for the various g_async_initable_new
+ * calls, returning the created object or %NULL on error.
+ * Free with g_object_unref().
*
- * Since: 2.20
+ * Returns: (transfer full): a newly created #GObject, or %NULL on error.
+ * Since: 2.22
*/
/**
- * g_app_info_set_as_default_for_extension:
- * @appinfo: a #GAppInfo.
- * @extension: a string containing the file extension (without the dot).
- * @error: a #GError.
+ * g_async_initable_new_valist_async:
+ * @object_type: a #GType supporting #GAsyncInitable.
+ * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL.
+ * @var_args: The var args list generated from @first_property_name.
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the initialization is finished
+ * @user_data: the data to pass to callback function
*
- * Sets the application as the default handler for the given file extension.
+ * 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.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.22
*/
/**
- * g_app_info_set_as_default_for_type:
- * @appinfo: a #GAppInfo.
- * @content_type: the content type.
- * @error: a #GError.
+ * g_async_initable_newv_async:
+ * @object_type: a #GType supporting #GAsyncInitable.
+ * @n_parameters: the number of parameters in @parameters
+ * @parameters: the parameters to use to construct the object
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the initialization is finished
+ * @user_data: the data to pass to callback function
*
- * Sets the application as the default handler for a given type.
+ * 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.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.22
*/
/**
- * g_app_info_set_as_last_used_for_type:
- * @appinfo: a #GAppInfo.
- * @content_type: the content type.
- * @error: a #GError.
+ * g_async_result_get_source_object:
+ * @res: a #GAsyncResult
*
- * Sets the application as the last used application for a given type.
- * This will make the application appear as first in the list returned by
- * #g_app_info_get_recommended_for_type, regardless of the default application
- * for that content type.
+ * Gets the source object from a #GAsyncResult.
+ * or %NULL if there is none.
*
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: (transfer full): a new reference to the source object for the @res,
*/
/**
- * g_app_info_should_show:
- * @appinfo: a #GAppInfo.
+ * g_async_result_get_user_data:
+ * @res: a #GAsyncResult.
*
- * Checks if the application info should be shown in menus that
- * list available applications.
+ * Gets the user data from a #GAsyncResult.
*
- * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
+ * Returns: (transfer full): the user data for @res.
*/
/**
- * g_app_info_supports_files:
- * @appinfo: a #GAppInfo.
+ * g_buffered_input_stream_fill:
+ * @stream: a #GBufferedInputStream
+ * @count: the number of bytes that will be read from the stream
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @error: location to store the error occuring, or %NULL to ignore
*
- * Checks if the application accepts files as arguments.
+ * 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().
+ * or -1 on error.
*
- * Returns: %TRUE if the @appinfo supports files.
+ * Returns: the number of bytes read into @stream's buffer, up to @count,
*/
/**
- * g_app_info_supports_uris:
- * @appinfo: a #GAppInfo.
- *
- * Checks if the application supports reading files and directories from URIs.
+ * g_buffered_input_stream_fill_async:
+ * @stream: a #GBufferedInputStream
+ * @count: the number of bytes that will be read from the stream
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
+ * @cancellable: (allow-none): optional #GCancellable object
+ * @callback: (scope async): a #GAsyncReadyCallback
+ * @user_data: (closure): a #gpointer
*
- * Returns: %TRUE if the @appinfo supports URIs.
+ * Reads data into @stream's buffer asynchronously, up to @count size.
+ * 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.
*/
/**
- * g_app_launch_context_get_display:
- * @context: a #GAppLaunchContext
- * @info: a #GAppInfo
- * @files: (element-type GFile): a #GList of #GFile objects
+ * g_buffered_input_stream_fill_finish:
+ * @stream: a #GBufferedInputStream
+ * @result: a #GAsyncResult
+ * @error: a #GError
*
- * Gets the display string for the @context. This is used to ensure new
- * applications are started on the same display as the launching
- * application, by setting the <envar>DISPLAY</envar> environment variable.
+ * Finishes an asynchronous read.
*
- * Returns: a display string for the display.
+ * Returns: a #gssize of the read stream, or %-1 on an error.
*/
/**
- * g_app_launch_context_get_startup_notify_id:
- * @context: a #GAppLaunchContext
- * @info: a #GAppInfo
- * @files: (element-type GFile): a #GList of of #GFile objects
+ * g_buffered_input_stream_get_available:
+ * @stream: #GBufferedInputStream
*
- * Initiates startup notification for the application and returns the
- * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
- * if supported.
- * Startup notification IDs are defined in the <ulink
- * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt";>
- * FreeDesktop.Org Startup Notifications standard</ulink>.
- * not supported.
+ * Gets the size of the available data within the stream.
*
- * Returns: a startup notification ID for the application, or %NULL if
+ * Returns: size of the available stream.
*/
/**
- * g_app_launch_context_launch_failed:
- * @context: a #GAppLaunchContext.
- * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
+ * g_buffered_input_stream_get_buffer_size:
+ * @stream: a #GBufferedInputStream
*
- * 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().
+ * Gets the size of the input buffer.
+ *
+ * Returns: the current buffer size.
*/
/**
- * g_app_launch_context_new:
+ * g_buffered_input_stream_new:
+ * @base_stream: a #GInputStream
*
- * Creates a new application launch context. This is not normally used,
- * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
+ * Creates a new #GInputStream from the given @base_stream, with
+ * a buffer set to the default size (4 kilobytes).
*
- * Returns: a #GAppLaunchContext.
+ * Returns: a #GInputStream for the given @base_stream.
*/
/**
- * g_application_activate:
- * @application: a #GApplication
+ * g_buffered_input_stream_new_sized:
+ * @base_stream: a #GInputStream
+ * @size: a #gsize
*
- * 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.
+ * Creates a new #GBufferedInputStream from the given @base_stream,
+ * with a buffer set to @size.
*
- * Since: 2.28
+ * Returns: a #GInputStream.
*/
/**
- * g_application_command_line_get_arguments:
- * @cmdline: a #GApplicationCommandLine
- * @argc: (out): the length of the arguments array, or %NULL
+ * g_buffered_input_stream_peek:
+ * @stream: a #GBufferedInputStream
+ * @buffer: a pointer to an allocated chunk of memory
+ * @offset: a #gsize
+ * @count: a #gsize
*
- * Gets the list of arguments that was passed on the command line.
- * The strings in the array may contain non-utf8 data.
- * The return value is %NULL-terminated and should be freed using
- * g_strfreev().
- * containing the arguments (the argv)
+ * Peeks in the buffer, copying data of size @count into @buffer,
+ * offset @offset bytes.
*
- * Returns: (array length=argc) (transfer full): the string array
- * Since: 2.28
+ * Returns: a #gsize of the number of bytes peeked, or -1 on error.
*/
/**
- * g_application_command_line_get_cwd:
- * @cmdline: a #GApplicationCommandLine
+ * g_buffered_input_stream_peek_buffer:
+ * @stream: a #GBufferedInputStream
+ * @count: (out): a #gsize to get the number of bytes available in the buffer
*
- * 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.
+ * 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.
+ * read-only buffer
*
- * Returns: the current directory, or %NULL
- * Since: 2.28
+ * Returns: (array length=count) (element-type guint8) (transfer none):
*/
/**
- * g_application_command_line_get_environ:
- * @cmdline: a #GApplicationCommandLine
+ * g_buffered_input_stream_read_byte:
+ * @stream: a #GBufferedInputStream
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @error: location to store the error occuring, or %NULL to ignore
*
- * 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.
- * strings, or %NULL if they were not sent
+ * 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.
*
- * Returns: (array zero-terminated=1) (transfer none): the environment
- * Since: 2.28
+ * Returns: the byte read from the @stream, or -1 on end of stream or error.
*/
/**
- * g_application_command_line_get_exit_status:
- * @cmdline: a #GApplicationCommandLine
- *
- * Gets the exit status of @cmdline. See
- * g_application_command_line_set_exit_status() for more information.
+ * g_buffered_input_stream_set_buffer_size:
+ * @stream: a #GBufferedInputStream
+ * @size: a #gsize
*
- * Returns: the exit status
- * Since: 2.28
+ * Sets the size of the internal buffer of @stream to @size, or to the
+ * size of the contents of the buffer. The buffer can never be resized
+ * smaller than its current contents.
*/
/**
- * g_application_command_line_get_is_remote:
- * @cmdline: a #GApplicationCommandLine
+ * g_buffered_output_stream_get_auto_grow:
+ * @stream: a #GBufferedOutputStream.
*
- * Determines if @cmdline represents a remote invocation.
+ * Checks if the buffer automatically grows as data is added.
+ * %FALSE otherwise.
*
- * Returns: %TRUE if the invocation was remote
- * Since: 2.28
+ * Returns: %TRUE if the @stream's buffer automatically grows,
*/
/**
- * g_application_command_line_get_platform_data:
- * @cmdline: #GApplicationCommandLine
+ * g_buffered_output_stream_get_buffer_size:
+ * @stream: a #GBufferedOutputStream.
*
- * Gets the platform data associated with the invocation of @cmdline.
- * This is a #GVariant dictionary containing information about the
- * context in which the invocation occured. It typically contains
- * information like the current working directory and the startup
- * notification ID.
- * For local invocation, it will be %NULL.
+ * Gets the size of the buffer in the @stream.
*
- * Returns: the platform data, or %NULL
- * Since: 2.28
+ * Returns: the current size of the buffer.
*/
/**
- * g_application_command_line_getenv:
- * @cmdline: a #GApplicationCommandLine
- * @name: the environment variable to get
+ * g_buffered_output_stream_new:
+ * @base_stream: a #GOutputStream.
*
- * 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.
+ * Creates a new buffered output stream for a base stream.
*
- * Returns: the value of the variable, or %NULL if unset or unsent
- * Since: 2.28
+ * Returns: a #GOutputStream for the given @base_stream.
*/
/**
- * g_application_command_line_print:
- * @cmdline: a #GApplicationCommandLine
- * @format: a printf-style format string
- * @...: arguments, as per @format
+ * g_buffered_output_stream_new_sized:
+ * @base_stream: a #GOutputStream.
+ * @size: a #gsize.
*
- * 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.
+ * Creates a new buffered output stream with a given buffer size.
*
- * Since: 2.28
+ * Returns: a #GOutputStream with an internal buffer set to @size.
*/
/**
- * g_application_command_line_printerr:
- * @cmdline: a #GApplicationCommandLine
- * @format: a printf-style format string
- * @...: arguments, as per @format
+ * g_buffered_output_stream_set_auto_grow:
+ * @stream: a #GBufferedOutputStream.
+ * @auto_grow: a #gboolean.
*
- * 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.
+ * Sets whether or not the @stream's buffer should automatically grow.
+ * If @auto_grow is true, then each write will just make the buffer
+ * larger, and you must manually flush the buffer to actually write out
+ * the data to the underlying stream.
+ */
+
+
+/**
+ * g_buffered_output_stream_set_buffer_size:
+ * @stream: a #GBufferedOutputStream.
+ * @size: a #gsize.
*
- * Since: 2.28
+ * Sets the size of the internal buffer to @size.
*/
/**
- * g_application_command_line_set_exit_status:
- * @cmdline: a #GApplicationCommandLine
- * @exit_status: the exit status
+ * g_bus_get:
+ * @bus_type: A #GBusType.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: The data to pass to @callback.
*
- * 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
- * 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.
+ * 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 a asynchronous failable function. See g_bus_get_sync() for
+ * the synchronous version.
*
- * In the mainloop running (ie: because the use-count of the application
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * g_application_get_application_id:
- * @application: a #GApplication
- * @returns: the identifier for @application, owned by @application
+ * g_bus_get_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
+ * @error: Return location for error or %NULL.
*
- * Gets the unique identifier for @application.
+ * 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().
+ * Note that the returned #GDBusConnection object will (usually) have
+ * the #GDBusConnection:exit-on-close property set to %TRUE.
*
- * Since: 2.28
+ * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_application_get_flags:
- * @application: a #GApplication
- * @returns: the flags for @application
+ * g_bus_get_sync:
+ * @bus_type: A #GBusType.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Gets the flags for @application.
- * See #GApplicationFlags.
+ * 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().
+ * Note that the returned #GDBusConnection object will (usually) have
+ * the #GDBusConnection:exit-on-close property set to %TRUE.
*
- * Since: 2.28
+ * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_application_get_inactivity_timeout:
- * @application: a #GApplication
+ * g_bus_own_name:
+ * @bus_type: The type of bus to own a name on.
+ * @name: The well-known name to own.
+ * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
+ * @bus_acquired_handler: Handler to invoke when connected to the bus of type @bus_type or %NULL.
+ * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
+ * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
+ * @user_data: User data to pass to handlers.
+ * @user_data_free_func: Function for freeing @user_data or %NULL.
*
- * 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.
+ * Starts acquiring @name on the bus specified by @bus_type and calls
+ * acquired respectively lost. Callbacks will be invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this function from.
+ * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
+ * callbacks will be invoked after calling this function - there are three
+ * possible cases:
+ * <itemizedlist>
+ * <listitem><para>
+ * </para></listitem>
+ * <listitem><para>
+ * </para></listitem>
+ * <listitem><para>
+ * </para></listitem>
+ * </itemizedlist>
+ * 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 and export objects, see <xref linkend="gdbus-owning-names"/>.
+ * Simply register objects to be exported in @bus_acquired_handler and
+ * unregister the objects (if any) in @name_lost_handler.
+ * g_bus_unown_name() to stop owning the name.
*
- * Returns: the timeout, in milliseconds
- * Since: 2.28
+ * Returns: An identifier (never 0) that an be used with
+ * Since: 2.26
*/
/**
- * g_application_get_is_registered:
- * @application: a #GApplication
- * @returns: %TRUE if @application is registered
+ * g_bus_own_name_on_connection:
+ * @connection: A #GDBusConnection.
+ * @name: The well-known name to own.
+ * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
+ * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
+ * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
+ * @user_data: User data to pass to handlers.
+ * @user_data_free_func: Function for freeing @user_data or %NULL.
*
- * Checks if @application is registered.
- * An application is registered if g_application_register() has been
- * successfully called.
+ * Like g_bus_own_name() but takes a #GDBusConnection instead of a
+ * #GBusType.
+ * g_bus_unown_name() to stop owning the name.
*
- * Since: 2.28
+ * Returns: An identifier (never 0) that an be used with
+ * Since: 2.26
*/
/**
- * g_application_get_is_remote:
- * @application: a #GApplication
- * @returns: %TRUE if @application is remote
- *
- * 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().
+ * g_bus_own_name_on_connection_with_closures:
+ * @connection: A #GDBusConnection.
+ * @name: The well-known name to own.
+ * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
+ * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
+ * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
*
- * Since: 2.28
- */
-
-
-/**
- * g_application_hold:
- * @application: a #GApplication
+ * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
+ * easier binding in other languages.
+ * g_bus_unown_name() to stop owning the name.
*
- * 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().
+ * Returns: An identifier (never 0) that an be used with
+ * Rename to: g_bus_own_name_on_connection
+ * Since: 2.26
*/
/**
- * g_application_id_is_valid:
- * @application_id: a potential application identifier
- * @returns: %TRUE if @application_id is valid
+ * g_bus_own_name_with_closures:
+ * @bus_type: The type of bus to own a name on.
+ * @name: The well-known name to own.
+ * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
+ * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL.
+ * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
+ * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
*
- * Checks if @application_id is a valid application identifier.
- * A valid ID is required for calls to g_application_new() and
- * g_application_set_application_id().
- * For convenience, the restrictions on application identifiers are
- * reproduced here:
- * <itemizedlist>
- * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
- * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
- * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
- * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
- * <listitem>Application identifiers must not exceed 255 characters.</listitem>
- * </itemizedlist>
- */
-
-
-/**
- * g_application_new:
- * @application_id: the application id
- * @flags: the application flags
- * @returns: a new #GApplication instance
+ * Version of g_bus_own_name() using closures instead of callbacks for
+ * easier binding in other languages.
+ * g_bus_unown_name() to stop owning the name.
*
- * Creates a new #GApplication instance.
- * This function calls g_type_init() for you.
- * The application id must be valid. See g_application_id_is_valid().
+ * Returns: An identifier (never 0) that an be used with
+ * Rename to: g_bus_own_name
+ * Since: 2.26
*/
/**
- * g_application_open:
- * @application: a #GApplication
- * @files: (array length=n_files): an array of #GFiles to open
- * @n_files: the length of the @files array
- * @hint: a hint (or ""), but never %NULL
+ * g_bus_unown_name:
+ * @owner_id: An identifier obtained from g_bus_own_name()
*
- * Opens the given files.
- * In essence, this results in the #GApplication::open signal being emitted
- * in the primary instance.
- * intended to be used by applications that have multiple modes for
- * 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.
+ * Stops owning a name.
*
- * Opening files (eg: "view" vs "edit", etc). Unless you have a need
- * Since: 2.28
+ * Since: 2.26
*/
/**
- * g_application_register:
- * @application: a #GApplication
- * @cancellable: a #GCancellable, or %NULL
- * @error: a pointer to a NULL #GError, or %NULL
- * @returns: %TRUE if registration succeeded
- *
- * Attempts registration of the application.
- * This is the point at which the application discovers if it is the
- * primary instance or merely acting as a remote for an already-existing
- * primary instance. This is implemented by attempting to acquire the
- * application identifier as a unique bus name on the session bus using
- * GDBus.
- * Due to the internal architecture of GDBus, method calls can be
- * dispatched at any time (even if a main loop is not running). For
- * this reason, you must ensure that any object paths that you wish to
- * register are registered before calling this function.
- * 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.
- * 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.
- * instance is or is not the primary instance of the application. See
- * g_application_get_is_remote() for that.
+ * g_bus_unwatch_name:
+ * @watcher_id: An identifier obtained from g_bus_watch_name()
*
- * Note: the return value of this function is not an indicator that this
- * Since: 2.28
- */
-
-
-/**
- * g_application_release:
- * @application: a #GApplication
+ * Stops watching a name.
*
- * 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().
+ * Since: 2.26
*/
/**
- * g_application_run:
- * @application: a #GApplication
- * @argc: the argc from main() (or 0 if @argv is %NULL)
- * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
- * @returns: the exit status
+ * g_bus_watch_name:
+ * @bus_type: The type of bus to watch a name on.
+ * @name: The name (well-known or unique) to watch.
+ * @flags: Flags from the #GBusNameWatcherFlags enumeration.
+ * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
+ * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
+ * @user_data: User data to pass to handlers.
+ * @user_data_free_func: Function for freeing @user_data or %NULL.
*
- * 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.
- * First, the local_command_line() virtual function is invoked.
- * This function always runs on the local instance. It gets passed a pointer
- * to a %NULL-terminated copy of @argv and is expected to remove the arguments
- * that it handled (shifting up remaining arguments). See
- * <xref linkend="gapplication-example-cmdline2"/> for an example of
- * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
- * after setting <literal>argc = g_strv_length (argv);</literal>.
- * The last argument to local_command_line() is a pointer to the @status
- * variable which can used to set the exit status that is returned from
- * g_application_run().
- * If local_command_line() returns %TRUE, the command line is expected
- * to be completely handled, including possibly registering as the primary
- * instance, calling g_application_activate() or g_application_open(), etc.
- * If local_command_line() returns %FALSE then the application is registered
- * and the #GApplication::command-line signal is emitted in the primary
- * instance (which may or may not be this instance). The signal handler
- * gets passed a #GApplicationCommandline object that (among other things)
- * contains the remaining commandline arguments that have not been handled
- * by local_command_line().
- * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
- * flag set then the default implementation of local_command_line()
- * always returns %FALSE immediately, resulting in the commandline
- * always being handled in the primary instance.
- * Otherwise, the default implementation of local_command_line() tries
- * to do a couple of things that are probably reasonable for most
- * applications. First, g_application_register() is called to attempt
- * to register the application. If that works, then the command line
- * arguments are inspected. If no commandline arguments are given, then
- * g_application_activate() is called. If commandline arguments are
- * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
- * are assumed to be filenames and g_application_open() is called.
- * If you need to handle commandline arguments that are not filenames,
- * and you don't mind commandline handling to happen in the primary
- * instance, you should set %G_APPLICATION_HANDLED_COMMAND_LINE and
- * process the commandline arguments in your #GApplication::command-line
- * signal handler, either manually or using the #GOptionContext API.
- * If you are interested in doing more complicated local handling of the
- * commandline then you should implement your own #GApplication subclass
- * and override local_command_line(). In this case, you most likely want
- * to return %TRUE from your local_command_line() implementation to
- * suppress the default handling. See
- * <xref linkend="gapplication-example-cmdline2"/> for an example.
- * 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 mainloop is run until the use count falls to zero,
- * at which point 0 is returned.
- * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
- * around to provide its <emphasis>service</emphasis> to others).
+ * Starts watching @name on the bus specified by @bus_type and calls
+ * known to have a owner respectively known to lose its
+ * owner. Callbacks will be invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this function from.
+ * 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
+ * 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 wants
+ * to take action when a certain name exists, see <xref
+ * linkend="gdbus-watching-names"/>. Basically, the application
+ * should create object proxies in @name_appeared_handler and destroy
+ * them again (if any) in @name_vanished_handler.
+ * g_bus_unwatch_name() to stop watching the name.
*
- * Use count of zero is delayed for a while (ie: the instance stays
- * Since: 2.28
+ * Returns: An identifier (never 0) that an be used with
+ * Since: 2.26
*/
/**
- * g_application_set_action_group:
- * @application: a #GApplication
- * @action_group: (allow-none): a #GActionGroup, or %NULL
+ * g_bus_watch_name_on_connection:
+ * @connection: A #GDBusConnection.
+ * @name: The name (well-known or unique) to watch.
+ * @flags: Flags from the #GBusNameWatcherFlags enumeration.
+ * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
+ * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
+ * @user_data: User data to pass to handlers.
+ * @user_data_free_func: Function for freeing @user_data or %NULL.
*
- * Sets or unsets the group of actions associated with the application.
- * These actions are the actions that can be remotely invoked.
- * It is an error to call this function after the application has been
- * registered.
+ * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
+ * #GBusType.
+ * g_bus_unwatch_name() to stop watching the name.
*
- * Since: 2.28
+ * Returns: An identifier (never 0) that an be used with
+ * Since: 2.26
*/
/**
- * g_application_set_application_id:
- * @application: a #GApplication
- * @application_id: the identifier for @application
+ * g_bus_watch_name_on_connection_with_closures:
+ * @connection: A #GDBusConnection.
+ * @name: The name (well-known or unique) to watch.
+ * @flags: Flags from the #GBusNameWatcherFlags enumeration.
+ * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
+ * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
*
- * Sets the unique identifier for @application.
- * The application id can only be modified if @application has not yet
- * been registered.
- * The application id must be valid. See g_application_id_is_valid().
+ * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
+ * easier binding in other languages.
+ * g_bus_unwatch_name() to stop watching the name.
*
- * Since: 2.28
+ * Returns: An identifier (never 0) that an be used with
+ * Rename to: g_bus_watch_name_on_connection
+ * Since: 2.26
*/
/**
- * g_application_set_flags:
- * @application: a #GApplication
- * @flags: the flags for @application
+ * g_bus_watch_name_with_closures:
+ * @bus_type: The type of bus to watch a name on.
+ * @name: The name (well-known or unique) to watch.
+ * @flags: Flags from the #GBusNameWatcherFlags enumeration.
+ * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
+ * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
*
- * Sets the flags for @application.
- * The flags can only be modified if @application has not yet been
- * registered.
- * See #GApplicationFlags.
+ * Version of g_bus_watch_name() using closures instead of callbacks for
+ * easier binding in other languages.
+ * g_bus_unwatch_name() to stop watching the name.
*
- * Since: 2.28
+ * Returns: An identifier (never 0) that an be used with
+ * Rename to: g_bus_watch_name
+ * Since: 2.26
*/
/**
- * g_application_set_inactivity_timeout:
- * @application: a #GApplication
- * @inactivity_timeout: the timeout, in milliseconds
- *
- * Sets the current inactivity timeout for the application.
- * This is the amount of time (in milliseconds) after the last call to
- * g_application_release() before the application stops running.
- * 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.
+ * g_cancellable_cancel:
+ * @cancellable: a #GCancellable object.
*
- * Returns: the timeout, in milliseconds
- * Since: 2.28
+ * Will set @cancellable to cancelled, and will emit the
+ * #GCancellable::cancelled signal. (However, see the warning about
+ * race conditions in the documentation for that signal if you are
+ * planning to connect to it.)
+ * This function is thread-safe. In other words, you can safely call
+ * it from a thread other than the one running the operation that was
+ * passed the @cancellable.
+ * The convention within gio is that cancelling an asynchronous
+ * operation causes it to complete asynchronously. That is, if you
+ * cancel the operation from the same thread in which it is running,
+ * then the operation's #GAsyncReadyCallback will not be invoked until
+ * the application returns to the main loop.
*/
/**
- * g_async_initable_init_async:
- * @initable: a #GAsyncInitable.
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied
- * @user_data: the data to pass to callback function
+ * g_cancellable_connect:
+ * @cancellable: A #GCancellable.
+ * @callback: The #GCallback to connect.
+ * @data: Data to pass to @callback.
+ * @data_destroy_func: Free function for @data or %NULL.
*
- * 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.
- * 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.
- * If this function is not called, or returns with an error, then all
- * operations on the object should fail, generally returning the
- * error %G_IO_ERROR_NOT_INITIALIZED.
- * to this function with the same argument should return the same results.
- * Only the first call initializes the object; further calls return the result
- * of the first call. This is so that it's safe to implement the singleton
- * pattern in the GObject constructor function.
- * 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.
+ * 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.
+ * time of the connect if @cancellable is already cancelled,
+ * or when @cancellable is cancelled in some thread.
+ * disconnected, or immediately if the cancellable is already
+ * cancelled.
+ * See #GCancellable::cancelled for details on how to use this.
+ * been cancelled.
*
- * Implementations of this method must be idempotent: i.e. multiple calls
+ * Returns: The id of the signal handler or 0 if @cancellable has already
* Since: 2.22
*/
/**
- * g_async_initable_init_finish:
- * @initable: a #GAsyncInitable.
- * @res: a #GAsyncResult.
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * g_cancellable_disconnect:
+ * @cancellable: A #GCancellable or %NULL.
+ * @handler_id: Handler id of the handler to be disconnected, or %0.
*
- * Finishes asynchronous initialization and returns the result.
- * See g_async_initable_init_async().
- * will return %FALSE and set @error appropriately if present.
+ * 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.
*
- * Returns: %TRUE if successful. If an error has occurred, this function
* Since: 2.22
*/
/**
- * g_async_initable_new_async:
- * @object_type: a #GType supporting #GAsyncInitable.
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the initialization is finished
- * @user_data: the data to pass to callback function
- * @first_property_name: the name of the first property, or %NULL if no properties
- * @...: the value of the first property, followed by other property value pairs, and ended by %NULL.
+ * g_cancellable_get_current:
*
- * Helper function for constructing #GAsyncInitiable 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.
+ * Gets the top cancellable from the stack.
+ * if the stack is empty.
*
- * Since: 2.22
+ * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
*/
/**
- * g_async_initable_new_finish:
- * @initable: the #GAsyncInitable from the callback
- * @res: the #GAsyncResult.from the callback
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * g_cancellable_get_fd:
+ * @cancellable: a #GCancellable.
*
- * Finishes the async construction for the various g_async_initable_new calls,
- * returning the created object or %NULL on error.
- * g_object_unref().
+ * 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().
+ * is not supported, or on errors.
*
- * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with
- * Since: 2.22
+ * Returns: A valid file descriptor. %-1 if the file descriptor
*/
/**
- * g_async_initable_new_valist_async:
- * @object_type: a #GType supporting #GAsyncInitable.
- * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL.
- * @var_args: The var args list generated from @first_property_name.
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the initialization is finished
- * @user_data: the data to pass to callback function
+ * g_cancellable_is_cancelled:
+ * @cancellable: a #GCancellable or NULL.
*
- * Helper function for constructing #GAsyncInitiable 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.
+ * Checks if a cancellable job has been cancelled.
+ * FALSE if called with %NULL or if item is not cancelled.
+ *
+ * Returns: %TRUE if @cancellable is cancelled,
+ */
+
+
+/**
+ * g_cancellable_make_pollfd:
+ * @cancellable: a #GCancellable or %NULL
+ * @pollfd: a pointer to a #GPollFD
+ *
+ * Creates a #GPollFD corresponding to @cancellable; this can be passed
+ * to g_poll() and used to poll for cancellation. This is useful both
+ * for unix systems without a native poll and for portability to
+ * windows.
+ * When this function returns %TRUE, you should use
+ * g_cancellable_release_fd() to free up resources allocated for the
+ * 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().
+ * failure to prepare the cancellable.
*
+ * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
* Since: 2.22
*/
/**
- * g_async_initable_newv_async:
- * @object_type: a #GType supporting #GAsyncInitable.
- * @n_parameters: the number of parameters in @parameters
- * @parameters: the parameters to use to construct the object
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback to call when the initialization is finished
- * @user_data: the data to pass to callback function
+ * g_cancellable_new:
*
- * Helper function for constructing #GAsyncInitiable 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.
+ * 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, but not in multiple concurrent operations.
*
- * Since: 2.22
+ * Returns: a #GCancellable.
*/
/**
- * g_async_result_get_source_object:
- * @res: a #GAsyncResult
- *
- * Gets the source object from a #GAsyncResult.
- * or %NULL if there is none.
+ * g_cancellable_pop_current:
+ * @cancellable: a #GCancellable object
*
- * Returns: (transfer full): a new reference to the source object for the @res,
+ * Pops @cancellable off the cancellable stack (verifying that @cancellable
+ * is on the top of the stack).
*/
/**
- * g_async_result_get_user_data:
- * @res: a #GAsyncResult.
- *
- * Gets the user data from a #GAsyncResult.
+ * g_cancellable_push_current:
+ * @cancellable: a #GCancellable object
*
- * Returns: (transfer full): the user data for @res.
+ * Pushes @cancellable onto the cancellable stack. The current
+ * cancellable can then be recieved 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.
*/
/**
- * g_atomic_int_dec_and_test:
- * @atomic: a pointer to an integer
+ * g_cancellable_release_fd:
+ * @cancellable: a #GCancellable
*
- * Atomically decrements the integer pointed to by @atomic by 1.
- * after decrementing it
+ * 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.
*
- * Returns: %TRUE if the integer pointed to by @atomic is 0
- * Since: 2.4
+ * Since: 2.22
*/
/**
- * g_atomic_int_inc:
- * @atomic: a pointer to an integer.
- *
- * Atomically increments the integer pointed to by @atomic by 1.
+ * g_cancellable_reset:
+ * @cancellable: a #GCancellable object.
*
- * Since: 2.4
+ * Resets @cancellable to its uncancelled state.
*/
/**
- * g_buffered_input_stream_fill:
- * @stream: a #GBufferedInputStream
- * @count: the number of bytes that will be read from the stream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: location to store the error occuring, or %NULL to ignore
+ * g_cancellable_set_error_if_cancelled:
+ * @cancellable: a #GCancellable object.
+ * @error: #GError to append error state to.
*
- * 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().
- * or -1 on error.
+ * If the @cancellable is cancelled, sets the error to notify
+ * that the operation was cancelled.
*
- * Returns: the number of bytes read into @stream's buffer, up to @count,
+ * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not.
*/
/**
- * g_buffered_input_stream_fill_async:
- * @stream: a #GBufferedInputStream
- * @count: the number of bytes that will be read from the stream
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
- * @cancellable: (allow-none): optional #GCancellable object
- * @callback: (scope async): a #GAsyncReadyCallback
- * @user_data: (closure): a #gpointer
+ * g_cancellable_source_new: (skip)
+ * @cancellable: a #GCancellable, or %NULL
*
- * Reads data into @stream's buffer asynchronously, up to @count size.
- * 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.
+ * 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.
+ *
+ * Returns: (transfer full): the new #GSource.
+ * Since: 2.28
*/
/**
- * g_buffered_input_stream_fill_finish:
- * @stream: a #GBufferedInputStream
- * @result: a #GAsyncResult
- * @error: a #GError
+ * g_charset_converter_get_num_fallbacks:
+ * @converter: a #GCharsetConverter
*
- * Finishes an asynchronous read.
+ * Gets the number of fallbacks that @converter has applied so far.
*
- * Returns: a #gssize of the read stream, or %-1 on an error.
+ * Returns: the number of fallbacks that @converter has applied
+ * Since: 2.24
*/
/**
- * g_buffered_input_stream_get_available:
- * @stream: #GBufferedInputStream
+ * g_charset_converter_get_use_fallback:
+ * @converter: a #GCharsetConverter
*
- * Gets the size of the available data within the stream.
+ * Gets the #GCharsetConverter:use-fallback property.
*
- * Returns: size of the available stream.
+ * Returns: %TRUE if fallbacks are used by @converter
+ * Since: 2.24
*/
/**
- * g_buffered_input_stream_get_buffer_size:
- * @stream: a #GBufferedInputStream
+ * g_charset_converter_new:
+ * @to_charset: destination charset
+ * @from_charset: source charset
+ * @error: #GError for error reporting, or %NULL to ignore.
*
- * Gets the size of the input buffer.
+ * Creates a new #GCharsetConverter.
*
- * Returns: the current buffer size.
+ * Returns: a new #GCharsetConverter or %NULL on error.
+ * Since: 2.24
*/
/**
- * g_buffered_input_stream_new:
- * @base_stream: a #GInputStream
+ * g_charset_converter_set_use_fallback:
+ * @converter: a #GCharsetConverter
+ * @use_fallback: %TRUE to use fallbacks
*
- * Creates a new #GInputStream from the given @base_stream, with
- * a buffer set to the default size (4 kilobytes).
+ * Sets the #GCharsetConverter:use-fallback property.
*
- * Returns: a #GInputStream for the given @base_stream.
+ * Since: 2.24
*/
/**
- * g_buffered_input_stream_new_sized:
- * @base_stream: a #GInputStream
- * @size: a #gsize
+ * g_content_type_can_be_executable:
+ * @type: a content type string
*
- * Creates a new #GBufferedInputStream from the given @base_stream,
- * with a buffer set to @size.
+ * 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).
+ * can be executable, %FALSE otherwise.
*
- * Returns: a #GInputStream.
+ * Returns: %TRUE if the file type corresponds to a type that
*/
/**
- * g_buffered_input_stream_peek:
- * @stream: a #GBufferedInputStream
- * @buffer: a pointer to an allocated chunk of memory
- * @offset: a #gsize
- * @count: a #gsize
+ * g_content_type_equals:
+ * @type1: a content type string
+ * @type2: a content type string
*
- * Peeks in the buffer, copying data of size @count into @buffer,
- * offset @offset bytes.
+ * Compares two content types for equality.
+ * %FALSE otherwise.
*
- * Returns: a #gsize of the number of bytes peeked, or -1 on error.
+ * Returns: %TRUE if the two strings are identical or equivalent,
*/
/**
- * g_buffered_input_stream_peek_buffer:
- * @stream: a #GBufferedInputStream
- * @count: (out): a #gsize to get the number of bytes available in the buffer
+ * g_content_type_from_mime_type:
+ * @mime_type: a mime type string
*
- * 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.
- * read-only buffer
+ * Tries to find a content type based on the mime type name.
+ * or %NULL. Free with g_free()
*
- * Returns: (array length=count) (element-type guint8) (transfer none):
+ * Returns: (allow-none): Newly allocated string with content type
+ * Since: 2.18
*/
/**
- * g_buffered_input_stream_read_byte:
- * @stream: a #GBufferedInputStream
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: location to store the error occuring, or %NULL to ignore
+ * g_content_type_get_description:
+ * @type: a content type string
*
- * 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.
+ * Gets the human readable description of the content type.
+ * returned string with g_free()
*
- * Returns: the byte read from the @stream, or -1 on end of stream or error.
+ * Returns: a short description of the content type @type. Free the
*/
/**
- * g_buffered_input_stream_set_buffer_size:
- * @stream: a #GBufferedInputStream
- * @size: a #gsize
+ * g_content_type_get_icon:
+ * @type: a content type string
*
- * 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.
+ * Gets the icon for a content type.
+ * object with g_object_unref()
+ *
+ * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
*/
/**
- * g_buffered_output_stream_get_auto_grow:
- * @stream: a #GBufferedOutputStream.
+ * g_content_type_get_mime_type:
+ * @type: a content type string
*
- * Checks if the buffer automatically grows as data is added.
- * %FALSE otherwise.
+ * Gets the mime type for the content type, if one is registered.
+ * or %NULL if unknown.
*
- * Returns: %TRUE if the @stream's buffer automatically grows,
+ * Returns: (allow-none): the registered mime type for the given @type,
*/
/**
- * g_buffered_output_stream_get_buffer_size:
- * @stream: a #GBufferedOutputStream.
+ * g_content_type_guess:
+ * @filename: (allow-none): a string, or %NULL
+ * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
+ * @data_size: the size of @data
+ * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL
*
- * Gets the size of the buffer in the @stream.
+ * 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.
+ * given data. Free with g_free()
*
- * Returns: the current size of the buffer.
+ * Returns: a string indicating a guessed content type for the
*/
/**
- * g_buffered_output_stream_new:
- * @base_stream: a #GOutputStream.
+ * g_content_type_guess_for_tree:
+ * @root: the root of the tree to guess a type for
*
- * Creates a new buffered output stream for a base stream.
+ * Tries to guess the type of the tree with root @root, by
+ * looking at the files it contains. The result is an array
+ * of content types, with the best guess coming first.
+ * The types returned all have the form x-content/foo, e.g.
+ * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
+ * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec";>shared-mime-info</ulink>
+ * specification for more on x-content types.
+ * This function is useful in the implementation of
+ * g_mount_guess_content_type().
+ * array of zero or more content types, or %NULL. Free with g_strfreev()
*
- * Returns: a #GOutputStream for the given @base_stream.
+ * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
+ * Since: 2.18
*/
/**
- * g_buffered_output_stream_new_sized:
- * @base_stream: a #GOutputStream.
- * @size: a #gsize.
+ * g_content_type_is_a:
+ * @type: a content type string
+ * @supertype: a content type string
*
- * Creates a new buffered output stream with a given buffer size.
+ * Determines if @type is a subset of @supertype.
+ * %FALSE otherwise.
*
- * Returns: a #GOutputStream with an internal buffer set to @size.
+ * Returns: %TRUE if @type is a kind of @supertype,
*/
/**
- * g_buffered_output_stream_set_auto_grow:
- * @stream: a #GBufferedOutputStream.
- * @auto_grow: a #gboolean.
+ * g_content_type_is_unknown:
+ * @type: a content type string
*
- * 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.
+ * Checks if the content type is the generic "unknown" type.
+ * On UNIX this is the "application/octet-stream" mimetype,
+ * while on win32 it is "*".
+ *
+ * Returns: %TRUE if the type is the unknown type.
*/
/**
- * g_buffered_output_stream_set_buffer_size:
- * @stream: a #GBufferedOutputStream.
- * @size: a #gsize.
+ * g_content_types_get_registered:
*
- * Sets the size of the internal buffer to @size.
+ * Gets a list of strings containing all the registered content types
+ * known to the system. The list and its data should be freed using
+ * <programlisting>
+ * g_list_foreach (list, g_free, NULL);
+ * g_list_free (list);
+ * </programlisting>
+ *
+ * Returns: (element-type utf8) (transfer full): #GList of the registered content types
*/
/**
- * g_bus_get:
- * @bus_type: A #GBusType.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * g_converter_convert:
+ * @converter: a #GConverter.
+ * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert.
+ * @inbuf_size: the number of bytes in @inbuf
+ * @outbuf: a buffer to write converted data in.
+ * @outbuf_size: the number of bytes in @outbuf, must be at least one
+ * @flags: a #GConvertFlags controlling the conversion details
+ * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
+ * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
+ * @error: location to store the error occuring, or %NULL to ignore
*
- * 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 a asynchronous failable function. See g_bus_get_sync() for
- * the synchronous version.
+ * 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 availible 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.26
+ * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
+ * Since: 2.24
*/
/**
- * g_bus_get_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
- * @error: Return location for error or %NULL.
+ * g_converter_input_stream_get_converter:
+ * @converter_stream: a #GConverterInputStream
*
- * 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() and
- * g_dbus_connection_new_for_address().
- * Note that the returned #GDBusConnection object will (usually) have
- * the #GDBusConnection:exit-on-close property set to %TRUE.
+ * Gets the #GConverter that is used by @converter_stream.
*
- * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: (transfer none): the converter of the converter input stream
+ * Since: 2.24
*/
/**
- * g_bus_get_sync:
- * @bus_type: A #GBusType.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_converter_input_stream_new:
+ * @base_stream: a #GInputStream
+ * @converter: a #GConverter
*
- * 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().
- * Note that the returned #GDBusConnection object will (usually) have
- * the #GDBusConnection:exit-on-close property set to %TRUE.
+ * Creates a new converter input stream for the @base_stream.
*
- * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: a new #GInputStream.
*/
/**
- * g_bus_own_name:
- * @bus_type: The type of bus to own a name on.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
- * @bus_acquired_handler: Handler to invoke when connected to the bus of type @bus_type or %NULL.
- * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
- * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_converter_output_stream_get_converter:
+ * @converter_stream: a #GConverterOutputStream
*
- * Starts acquiring @name on the bus specified by @bus_type and calls
- * acquired respectively lost. Callbacks will be invoked in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this function from.
- * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
- * callbacks will be invoked after calling this function - there are three
- * possible cases:
- * <itemizedlist>
- * <listitem><para>
- * </para></listitem>
- * <listitem><para>
- * </para></listitem>
- * <listitem><para>
- * </para></listitem>
- * </itemizedlist>
- * 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 and export objects, see <xref linkend="gdbus-owning-names"/>.
- * Simply register objects to be exported in @bus_acquired_handler and
- * unregister the objects (if any) in @name_lost_handler.
- * g_bus_unown_name() to stop owning the name.
+ * Gets the #GConverter that is used by @converter_stream.
*
- * Returns: An identifier (never 0) that an be used with
- * Since: 2.26
+ * Returns: (transfer none): the converter of the converter output stream
+ * Since: 2.24
*/
/**
- * g_bus_own_name_on_connection:
- * @connection: A #GDBusConnection.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
- * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
- * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_converter_output_stream_new:
+ * @base_stream: a #GOutputStream
+ * @converter: a #GConverter
*
- * Like g_bus_own_name() but takes a #GDBusConnection instead of a
- * #GBusType.
- * g_bus_unown_name() to stop owning the name.
+ * Creates a new converter output stream for the @base_stream.
*
- * Returns: An identifier (never 0) that an be used with
- * Since: 2.26
+ * Returns: a new #GOutputStream.
*/
/**
- * g_bus_own_name_on_connection_with_closures:
- * @connection: A #GDBusConnection.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
- * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
- * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
- *
- * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
- * easier binding in other languages.
- * g_bus_unown_name() to stop owning the name.
+ * g_converter_reset:
+ * @converter: a #GConverter.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_own_name_on_connection
- * Since: 2.26
+ * 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
*/
/**
- * g_bus_own_name_with_closures:
- * @bus_type: The type of bus to own a name on.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
- * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL.
- * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
- * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
+ * g_credentials_get_native: (skip)
+ * @credentials: A #GCredentials.
+ * @native_type: The type of native credentials to get.
*
- * Version of g_bus_own_name() using closures instead of callbacks for
- * easier binding in other languages.
- * g_bus_unown_name() to stop owning the name.
+ * Gets a pointer to native credentials of type @native_type from
+ * It is a programming error (which will cause an warning to be
+ * logged) to use this method if there is no #GCredentials support for
+ * the OS or if @native_type isn't supported by the OS.
+ * operation there is no #GCredentials support for the OS or if
+ * data, it is owned by @credentials.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_own_name
+ * Returns: The pointer to native credentials or %NULL if the
* Since: 2.26
*/
/**
- * g_bus_unown_name:
- * @owner_id: An identifier obtained from g_bus_own_name()
+ * g_credentials_get_unix_user:
+ * @credentials: A #GCredentials
+ * @error: Return location for error or %NULL.
*
- * Stops owning a name.
+ * 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.
*
+ * Returns: The UNIX user identifier or -1 if @error is set.
* Since: 2.26
*/
/**
- * g_bus_unwatch_name:
- * @watcher_id: An identifier obtained from g_bus_watch_name()
+ * g_credentials_is_same_user:
+ * @credentials: A #GCredentials.
+ * @other_credentials: A #GCredentials.
+ * @error: Return location for error or %NULL.
*
- * Stops watching a name.
+ * Checks if @credentials and @other_credentials is the same user.
+ * This operation can fail if #GCredentials is not supported on the
+ * the OS.
+ * user, %FALSE otherwise or if @error is set.
*
+ * Returns: %TRUE if @credentials and @other_credentials has the same
* Since: 2.26
*/
/**
- * g_bus_watch_name:
- * @bus_type: The type of bus to watch a name on.
- * @name: The name (well-known or unique) to watch.
- * @flags: Flags from the #GBusNameWatcherFlags enumeration.
- * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
- * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_credentials_new:
*
- * Starts watching @name on the bus specified by @bus_type and calls
- * known to have a owner respectively known to lose its
- * owner. Callbacks will be invoked in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this function from.
- * 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
- * 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 wants
- * to take action when a certain name exists, see <xref
- * linkend="gdbus-watching-names"/>. Basically, the application
- * should create object proxies in @name_appeared_handler and destroy
- * them again (if any) in @name_vanished_handler.
- * g_bus_unwatch_name() to stop watching the name.
+ * Creates a new #GCredentials object with credentials matching the
+ * the current process.
*
- * Returns: An identifier (never 0) that an be used with
+ * Returns: A #GCredentials. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_bus_watch_name_on_connection:
- * @connection: A #GDBusConnection.
- * @name: The name (well-known or unique) to watch.
- * @flags: Flags from the #GBusNameWatcherFlags enumeration.
- * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
- * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: Function for freeing @user_data or %NULL.
+ * g_credentials_set_native:
+ * @credentials: A #GCredentials.
+ * @native_type: The type of native credentials to set.
+ * @native: A pointer to native credentials.
*
- * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
- * #GBusType.
- * g_bus_unwatch_name() to stop watching the name.
+ * Copies the native credentials of type @native_type from @native
+ * into @credentials.
+ * It is a programming error (which will cause an warning to be
+ * logged) to use this method if there is no #GCredentials support for
+ * the OS or if @native_type isn't supported by the OS.
*
- * Returns: An identifier (never 0) that an be used with
* Since: 2.26
*/
/**
- * g_bus_watch_name_on_connection_with_closures:
- * @connection: A #GDBusConnection.
- * @name: The name (well-known or unique) to watch.
- * @flags: Flags from the #GBusNameWatcherFlags enumeration.
- * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
- * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
+ * g_credentials_set_unix_user:
+ * @credentials: A #GCredentials.
+ * @uid: The UNIX user identifier to set.
+ * @error: Return location for error or %NULL.
*
- * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
- * easier binding in other languages.
- * g_bus_unwatch_name() to stop watching the name.
+ * 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.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_watch_name_on_connection
+ * Returns: %TRUE if @uid was set, %FALSE if error is set.
* Since: 2.26
*/
/**
- * g_bus_watch_name_with_closures:
- * @bus_type: The type of bus to watch a name on.
- * @name: The name (well-known or unique) to watch.
- * @flags: Flags from the #GBusNameWatcherFlags enumeration.
- * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
- * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
+ * g_credentials_to_string:
+ * @credentials: A #GCredentials object.
*
- * Version of g_bus_watch_name() using closures instead of callbacks for
- * easier binding in other languages.
- * g_bus_unwatch_name() to stop watching the name.
+ * Creates a human-readable textual representation of @credentials
+ * that can be used in logging and debug messages. The format of the
+ * returned string may change in future GLib release.
*
- * Returns: An identifier (never 0) that an be used with
- * Rename to: g_bus_watch_name
+ * Returns: A string that should be freed with g_free().
* Since: 2.26
*/
/**
- * g_cancellable_cancel:
- * @cancellable: a #GCancellable object.
+ * g_data_input_stream_get_byte_order:
+ * @stream: a given #GDataInputStream.
*
- * Will set @cancellable to cancelled, and will emit the
- * #GCancellable::cancelled signal. (However, see the warning about
- * race conditions in the documentation for that signal if you are
- * planning to connect to it.)
- * This function is thread-safe. In other words, you can safely call
- * it from a thread other than the one running the operation that was
- * passed the @cancellable.
- * The convention within gio is that cancelling an asynchronous
- * 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.
+ * Gets the byte order for the data input stream.
+ *
+ * Returns: the @stream's current #GDataStreamByteOrder.
*/
/**
- * g_cancellable_connect:
- * @cancellable: A #GCancellable.
- * @callback: The #GCallback to connect.
- * @data: Data to pass to @callback.
- * @data_destroy_func: Free function for @data or %NULL.
+ * g_data_input_stream_get_newline_type:
+ * @stream: a given #GDataInputStream.
*
- * 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.
- * time of the connect if @cancellable is already cancelled,
- * or when @cancellable is cancelled in some thread.
- * disconnected, or immediately if the cancellable is already
- * cancelled.
- * See #GCancellable::cancelled for details on how to use this.
- * been cancelled.
+ * Gets the current newline type for the @stream.
*
- * Returns: The id of the signal handler or 0 if @cancellable has already
- * Since: 2.22
+ * Returns: #GDataStreamNewlineType for the given @stream.
*/
/**
- * g_cancellable_disconnect:
- * @cancellable: A #GCancellable or %NULL.
- * @handler_id: Handler id of the handler to be disconnected, or %0.
+ * g_data_input_stream_new:
+ * @base_stream: a #GInputStream.
*
- * 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.
+ * Creates a new data input stream for the @base_stream.
*
- * Since: 2.22
+ * Returns: a new #GDataInputStream.
*/
/**
- * g_cancellable_get_current:
+ * g_data_input_stream_read_byte:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Gets the top cancellable from the stack.
- * if the stack is empty.
+ * Reads an unsigned 8-bit/1-byte value from @stream.
+ * if an error occurred.
*
- * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
+ * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
*/
/**
- * g_cancellable_get_fd:
- * @cancellable: a #GCancellable.
+ * g_data_input_stream_read_int16:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * 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().
- * is not supported, or on errors.
+ * 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().
+ * an error occurred.
*
- * Returns: A valid file descriptor. %-1 if the file descriptor
+ * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
*/
/**
- * g_cancellable_is_cancelled:
- * @cancellable: a #GCancellable or NULL.
+ * g_data_input_stream_read_int32:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Checks if a cancellable job has been cancelled.
- * FALSE if called with %NULL or if item is not cancelled.
+ * 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.
+ * an error occurred.
*
- * Returns: %TRUE if @cancellable is cancelled,
+ * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
*/
/**
- * g_cancellable_make_pollfd:
- * @cancellable: a #GCancellable or %NULL
- * @pollfd: a pointer to a #GPollFD
+ * g_data_input_stream_read_int64:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * 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
- * 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().
- * failure to prepare the cancellable.
+ * 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.
+ * an error occurred.
*
- * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
- * Since: 2.22
+ * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
*/
/**
- * g_cancellable_new:
+ * g_data_input_stream_read_line:
+ * @stream: a given #GDataInputStream.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * 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, but not in multiple concurrent operations.
+ * Reads a 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.
+ * (without the newlines). Set @length to a #gsize to get the
+ * length of the read line. On an error, it will return %NULL and
+ * still return %NULL, but @error won't be set.
*
- * Returns: a #GCancellable.
+ * Returns: (transfer full): a string with the line that was read in
*/
/**
- * g_cancellable_pop_current:
- * @cancellable: a #GCancellable object
+ * g_data_input_stream_read_line_async:
+ * @stream: a given #GDataInputStream.
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (scope async): callback to call when the request is satisfied.
+ * @user_data: (closure): the data to pass to callback function.
*
- * Pops @cancellable off the cancellable stack (verifying that @cancellable
- * is on the top of the stack).
+ * The asynchronous version of g_data_input_stream_read_line(). It is
+ * an error to have two outstanding calls to this function.
+ * When the operation is finished, @callback will be called. You
+ * can then call g_data_input_stream_read_line_finish() to get
+ * the result of the operation.
+ *
+ * Since: 2.20
*/
/**
- * g_cancellable_push_current:
- * @cancellable: a #GCancellable object
+ * g_data_input_stream_read_line_finish:
+ * @stream: a given #GDataInputStream.
+ * @result: the #GAsyncResult that was provided to the callback.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @error: #GError for error reporting.
*
- * Pushes @cancellable onto the cancellable stack. The current
- * cancellable can then be recieved 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.
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_line_async().
+ * (without the newlines). Set @length to a #gsize to get the
+ * length of the read line. On an error, it will return %NULL and
+ * still return %NULL, but @error won't be set.
+ *
+ * Returns: (transfer full): a string with the line that was read in
+ * Since: 2.20
*/
/**
- * g_cancellable_release_fd:
- * @cancellable: a #GCancellable
+ * g_data_input_stream_read_uint16:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * 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.
+ * 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().
+ * an error occurred.
*
- * Since: 2.22
+ * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
*/
/**
- * g_cancellable_reset:
- * @cancellable: a #GCancellable object.
+ * g_data_input_stream_read_uint32:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * Resets @cancellable to its uncancelled state.
+ * 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.
+ * an error occurred.
+ *
+ * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
*/
/**
- * g_cancellable_set_error_if_cancelled:
- * @cancellable: a #GCancellable object.
- * @error: #GError to append error state to.
+ * g_data_input_stream_read_uint64:
+ * @stream: a given #GDataInputStream.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * If the @cancellable is cancelled, sets the error to notify
- * that the operation was cancelled.
+ * 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.
+ * an error occurred.
*
- * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not.
+ * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
*/
/**
- * g_cancellable_source_new: (skip)
- * @cancellable: a #GCancellable, or %NULL
+ * g_data_input_stream_read_until:
+ * @stream: a given #GDataInputStream.
+ * @stop_chars: characters to terminate the read.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: #GError for error reporting.
*
- * 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.
+ * 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.
+ * before encountering any of the stop characters. Set @length to
+ * a #gsize to get the length of the string. This function will
+ * return %NULL on an error.
*
- * Returns: (transfer full): the new #GSource.
- * Since: 2.28
+ * Returns: (transfer full): a string with the data that was read
*/
/**
- * g_charset_converter_get_num_fallbacks:
- * @converter: a #GCharsetConverter
+ * g_data_input_stream_read_until_async:
+ * @stream: a given #GDataInputStream.
+ * @stop_chars: characters to terminate the read.
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (scope async): callback to call when the request is satisfied.
+ * @user_data: (closure): the data to pass to callback function.
*
- * Gets the number of fallbacks that @converter has applied so far.
+ * 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.
*
- * Returns: the number of fallbacks that @converter has applied
- * Since: 2.24
+ * Since: 2.20
*/
/**
- * g_charset_converter_get_use_fallback:
- * @converter: a #GCharsetConverter
+ * g_data_input_stream_read_until_finish:
+ * @stream: a given #GDataInputStream.
+ * @result: the #GAsyncResult that was provided to the callback.
+ * @length: (out): a #gsize to get the length of the data read in.
+ * @error: #GError for error reporting.
*
- * Gets the #GCharsetConverter:use-fallback property.
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_until_async().
+ * before encountering any of the stop characters. Set @length to
+ * a #gsize to get the length of the string. This function will
+ * return %NULL on an error.
*
- * Returns: %TRUE if fallbacks are used by @converter
- * Since: 2.24
+ * Since: 2.20
+ * Returns: (transfer full): a string with the data that was read
*/
/**
- * g_charset_converter_new:
- * @to_charset: destination charset
- * @from_charset: source charset
- * @error: #GError for error reporting, or %NULL to ignore.
+ * g_data_input_stream_read_upto:
+ * @stream: a #GDataInputStream
+ * @stop_chars: characters to terminate the read
+ * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
+ * @length: (out): a #gsize to get the length of the data read in
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @error: #GError for error reporting
*
- * Creates a new #GCharsetConverter.
+ * Reads a string from the data input stream, up to the first
+ * occurrence of any of the stop characters.
+ * In contrast to g_data_input_stream_read_until(), this function
+ * does <emphasis>not</emphasis> consume the stop character. You have
+ * to use g_data_input_stream_read_byte() to get it before calling
+ * g_data_input_stream_read_upto() again.
+ * Note that @stop_chars may contain '\0' if @stop_chars_len is
+ * specified.
+ * before encountering any of the stop characters. Set @length to
+ * a #gsize to get the length of the string. This function will
+ * return %NULL on an error
*
- * Returns: a new #GCharsetConverter or %NULL on error.
- * Since: 2.24
+ * Returns: (transfer full): a string with the data that was read
+ * Since: 2.26
*/
/**
- * g_charset_converter_set_use_fallback:
- * @converter: a #GCharsetConverter
- * @use_fallback: %TRUE to use fallbacks
+ * g_data_input_stream_read_upto_async:
+ * @stream: a #GDataInputStream
+ * @stop_chars: characters to terminate the read
+ * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
*
- * Sets the #GCharsetConverter:use-fallback property.
+ * The asynchronous version of g_data_input_stream_read_upto().
+ * It is an error to have two outstanding calls to this function.
+ * In contrast to g_data_input_stream_read_until(), this function
+ * does <emphasis>not</emphasis> consume the stop character. You have
+ * to use g_data_input_stream_read_byte() to get it before calling
+ * g_data_input_stream_read_upto() again.
+ * Note that @stop_chars may contain '\0' if @stop_chars_len is
+ * specified.
+ * 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.24
+ * Since: 2.26
*/
/**
- * g_content_type_can_be_executable:
- * @type: a content type string
+ * g_data_input_stream_read_upto_finish:
+ * @stream: a #GDataInputStream
+ * @result: the #GAsyncResult that was provided to the callback
+ * @length: (out): a #gsize to get the length of the data read in
+ * @error: #GError for error reporting
*
- * 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).
- * can be executable, %FALSE otherwise.
+ * Finish an asynchronous call started by
+ * g_data_input_stream_read_upto_async().
+ * Note that this function does <emphasis>not</emphasis> consume the
+ * stop character. You have to use g_data_input_stream_read_byte() to
+ * get it before calling g_data_input_stream_read_upto_async() again.
+ * before encountering any of the stop characters. Set @length to
+ * a #gsize to get the length of the string. This function will
+ * return %NULL on an error.
*
- * Returns: %TRUE if the file type corresponds to a type that
+ * Returns: (transfer full): a string with the data that was read
+ * Since: 2.24
*/
/**
- * g_content_type_equals:
- * @type1: a content type string
- * @type2: a content type string
- *
- * Compares two content types for equality.
- * %FALSE otherwise.
+ * g_data_input_stream_set_byte_order:
+ * @stream: a given #GDataInputStream.
+ * @order: a #GDataStreamByteOrder to set.
*
- * Returns: %TRUE if the two strings are identical or equivalent,
+ * This function sets the byte order for the given @stream. All subsequent
+ * reads from the @stream will be read in the given @order.
*/
/**
- * g_content_type_from_mime_type:
- * @mime_type: a mime type string
- *
- * Tries to find a content type based on the mime type name.
- * or %NULL. Free with g_free()
+ * g_data_input_stream_set_newline_type:
+ * @stream: a #GDataInputStream.
+ * @type: the type of new line return as #GDataStreamNewlineType.
*
- * Returns: (allow-none): Newly allocated string with content type
- * Since: 2.18
+ * 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 availible.
*/
/**
- * g_content_type_get_description:
- * @type: a content type string
+ * g_data_output_stream_get_byte_order:
+ * @stream: a #GDataOutputStream.
*
- * Gets the human readable description of the content type.
- * returned string with g_free()
+ * Gets the byte order for the stream.
*
- * Returns: a short description of the content type @type. Free the
+ * Returns: the #GDataStreamByteOrder for the @stream.
*/
/**
- * g_content_type_get_icon:
- * @type: a content type string
+ * g_data_output_stream_new:
+ * @base_stream: a #GOutputStream.
*
- * Gets the icon for a content type.
- * object with g_object_unref()
+ * Creates a new data output stream for @base_stream.
*
- * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
+ * Returns: #GDataOutputStream.
*/
/**
- * g_content_type_get_mime_type:
- * @type: a content type string
+ * g_data_output_stream_put_byte:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guchar.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Gets the mime type for the content type, if one is registered.
- * or %NULL if unknown.
+ * Puts a byte into the output stream.
*
- * Returns: (allow-none): the registered mime type for the given @type,
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_content_type_guess:
- * @filename: (allow-none): a string, or %NULL
- * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
- * @data_size: the size of @data
- * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL
+ * g_data_output_stream_put_int16:
+ * @stream: a #GDataOutputStream.
+ * @data: a #gint16.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * 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.
- * given data. Free with g_free()
+ * Puts a signed 16-bit integer into the output stream.
*
- * Returns: a string indicating a guessed content type for the
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_content_type_guess_for_tree:
- * @root: the root of the tree to guess a type for
+ * g_data_output_stream_put_int32:
+ * @stream: a #GDataOutputStream.
+ * @data: a #gint32.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Tries to guess the type of the tree with root @root, by
- * looking at the files it contains. The result is an array
- * of content types, with the best guess coming first.
- * The types returned all have the form x-content/foo, e.g.
- * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
- * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec";>shared-mime-info</ulink>
- * specification for more on x-content types.
- * This function is useful in the implementation of
- * g_mount_guess_content_type().
- * array of zero or more content types, or %NULL. Free with g_strfreev()
+ * Puts a signed 32-bit integer into the output stream.
*
- * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
- * Since: 2.18
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_content_type_is_a:
- * @type: a content type string
- * @supertype: a content type string
+ * g_data_output_stream_put_int64:
+ * @stream: a #GDataOutputStream.
+ * @data: a #gint64.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Determines if @type is a subset of @supertype.
- * %FALSE otherwise.
+ * Puts a signed 64-bit integer into the stream.
*
- * Returns: %TRUE if @type is a kind of @supertype,
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_content_type_is_unknown:
- * @type: a content type string
+ * g_data_output_stream_put_string:
+ * @stream: a #GDataOutputStream.
+ * @str: a string.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Checks if the content type is the generic "unknown" type.
- * On UNIX this is the "application/octet-stream" mimetype,
- * while on win32 it is "*".
+ * Puts a string into the output stream.
*
- * Returns: %TRUE if the type is the unknown type.
+ * Returns: %TRUE if @string was successfully added to the @stream.
*/
/**
- * g_content_types_get_registered:
+ * g_data_output_stream_put_uint16:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guint16.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Gets a list of strings containing all the registered content types
- * known to the system. The list and its data should be freed using
- * <programlisting>
- * g_list_foreach (list, g_free, NULL);
- * g_list_free (list);
- * </programlisting>
+ * Puts an unsigned 16-bit integer into the output stream.
*
- * Returns: (element-type utf8) (transfer full): #GList of the registered content types
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_converter_convert:
- * @converter: a #GConverter.
- * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert.
- * @inbuf_size: the number of bytes in @inbuf
- * @outbuf: a buffer to write converted data in.
- * @outbuf_size: the number of bytes in @outbuf, must be at least one
- * @flags: a #GConvertFlags controlling the conversion details
- * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
- * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
- * @error: location to store the error occuring, or %NULL to ignore
- *
- * This is the main operation used when converting data. It is to be called
- * multiple times in a loop, and each time it will do some work, i.e.
- * producing some output (in @outbuf) or consuming some input (from @inbuf) or
- * both. If its not possible to do any work an error is returned.
- * Note that a single call may not consume all input (or any input at all).
- * Also a call may produce output even if given no input, due to state stored
- * in the converter producing output.
- * If any data was either produced or consumed, and then an error happens, then
- * only the successful conversion is reported and the error is returned on the
- * next call.
- * A full conversion loop involves calling this method repeatedly, each time
- * giving it new input and space output space. When there is no more input
- * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
- * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
- * each time until all data is consumed and all output is produced, then
- * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
- * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
- * in a decompression converter where the end of data is detectable from the
- * data (and there might even be other data after the end of the compressed data).
- * When some data has successfully been converted @bytes_read and is set to
- * the number of bytes read from @inbuf, and @bytes_written is set to indicate
- * how many bytes was written to @outbuf. If there are more data to output
- * or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then
- * G_CONVERTER_CONVERTED is returned, and if no more data is to be output
- * then G_CONVERTER_FINISHED is returned.
- * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
- * Some errors need special handling:
- * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
- * to write the resulting converted data, the application should
- * call the function again with a larger @outbuf to continue.
- * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
- * input to fully determine what the conversion should produce,
- * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
- * example with an incomplete multibyte sequence when converting text,
- * or when a regexp matches up to the end of the input (and may match
- * further input). It may also happen when @inbuf_size is zero and
- * there is no more data to produce.
- * When this happens the application should read more input and then
- * call the function again. If further input shows that there is no
- * more data call the function again with the same data but with
- * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
- * to finish as e.g. in the regexp match case (or, to fail again with
- * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
- * input is actually partial).
- * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
- * converter object is in an invalid state where its not allowed
- * to call g_converter_convert() anymore. At this time you can only
- * free the object or call g_converter_reset() to reset it to the
- * initial state.
- * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
- * to try to write out all internal state to the output. The application
- * has to call the function multiple times with the flag set, and when
- * the availible 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).
+ * g_data_output_stream_put_uint32:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guint32.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
- * Since: 2.24
+ * Puts an unsigned 32-bit integer into the stream.
+ *
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_converter_input_stream_get_converter:
- * @converter_stream: a #GConverterInputStream
+ * g_data_output_stream_put_uint64:
+ * @stream: a #GDataOutputStream.
+ * @data: a #guint64.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
*
- * Gets the #GConverter that is used by @converter_stream.
+ * Puts an unsigned 64-bit integer into the stream.
*
- * Returns: (transfer none): the converter of the converter input stream
- * Since: 2.24
+ * Returns: %TRUE if @data was successfully added to the @stream.
*/
/**
- * g_converter_input_stream_new:
- * @base_stream: a #GInputStream
- * @converter: a #GConverter
- *
- * Creates a new converter input stream for the @base_stream.
+ * g_data_output_stream_set_byte_order:
+ * @stream: a #GDataOutputStream.
+ * @order: a %GDataStreamByteOrder.
*
- * Returns: a new #GInputStream.
+ * Sets the byte order of the data output stream to @order.
*/
/**
- * g_converter_output_stream_get_converter:
- * @converter_stream: a #GConverterOutputStream
+ * g_dbus_address_get_for_bus_sync:
+ * @bus_type: A #GBusType.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Gets the #GConverter that is used by @converter_stream.
+ * Synchronously looks up the D-Bus address for the well-known message
+ * bus instance specified by @bus_type. This may involve using various
+ * platform specific mechanisms.
*
- * Returns: (transfer none): the converter of the converter output stream
- * Since: 2.24
+ * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
+ * Since: 2.26
*/
/**
- * g_converter_output_stream_new:
- * @base_stream: a #GOutputStream
- * @converter: a #GConverter
+ * g_dbus_address_get_stream:
+ * @address: A valid D-Bus address.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: Data to pass to @callback.
*
- * Creates a new converter output stream for the @base_stream.
+ * 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.
+ * 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.
*
- * Returns: a new #GOutputStream.
+ * Since: 2.26
*/
/**
- * g_converter_reset:
- * @converter: a #GConverter.
+ * g_dbus_address_get_stream_finish:
+ * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
+ * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
+ * @error: Return location for error or %NULL.
*
- * 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.
+ * Finishes an operation started with g_dbus_address_get_stream().
*
- * Since: 2.24
+ * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
+ * Since: 2.26
*/
/**
- * g_credentials_get_native: (skip)
- * @credentials: A #GCredentials.
- * @native_type: The type of native credentials to get.
+ * g_dbus_address_get_stream_sync:
+ * @address: A valid D-Bus address.
+ * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Gets a pointer to native credentials of type @native_type from
- * It is a programming error (which will cause an warning to be
- * logged) to use this method if there is no #GCredentials support for
- * the OS or if @native_type isn't supported by the OS.
- * operation there is no #GCredentials support for the OS or if
- * data, it is owned by @credentials.
+ * 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.
+ * This is a synchronous failable function. See
+ * g_dbus_address_get_stream() for the asynchronous version.
*
- * Returns: The pointer to native credentials or %NULL if the
+ * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
* Since: 2.26
*/
/**
- * g_credentials_get_unix_user:
- * @credentials: A #GCredentials
- * @error: Return location for error or %NULL.
+ * g_dbus_annotation_info_lookup:
+ * @annotations: A %NULL-terminated array of annotations or %NULL.
+ * @name: The name of the annotation to look up.
*
- * 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.
+ * Looks up the value of an annotation.
+ * This cost of this function is O(n) in number of annotations.
*
- * Returns: The UNIX user identifier or -1 if @error is set.
+ * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
* Since: 2.26
*/
/**
- * g_credentials_is_same_user:
- * @credentials: A #GCredentials.
- * @other_credentials: A #GCredentials.
- * @error: Return location for error or %NULL.
+ * g_dbus_annotation_info_ref:
+ * @info: A #GDBusNodeInfo
*
- * Checks if @credentials and @other_credentials is the same user.
- * This operation can fail if #GCredentials is not supported on the
- * the OS.
- * user, %FALSE otherwise or if @error is set.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: %TRUE if @credentials and @other_credentials has the same
+ * Returns: The same @info.
* Since: 2.26
*/
/**
- * g_credentials_new:
+ * g_dbus_annotation_info_unref:
+ * @info: A #GDBusAnnotationInfo.
*
- * Creates a new #GCredentials object with credentials matching the
- * the current process.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: A #GCredentials. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_credentials_set_native:
- * @credentials: A #GCredentials.
- * @native_type: The type of native credentials to set.
- * @native: A pointer to native credentials.
+ * g_dbus_arg_info_ref:
+ * @info: A #GDBusArgInfo
*
- * Copies the native credentials of type @native_type from @native
- * into @credentials.
- * It is a programming error (which will cause an warning to be
- * logged) to use this method if there is no #GCredentials support for
- * the OS or if @native_type isn't supported by the OS.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
+ * Returns: The same @info.
* Since: 2.26
*/
/**
- * g_credentials_set_unix_user:
- * @credentials: A #GCredentials.
- * @uid: The UNIX user identifier to set.
- * @error: Return location for error or %NULL.
+ * g_dbus_arg_info_unref:
+ * @info: A #GDBusArgInfo.
*
- * 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.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: %TRUE if @uid was set, %FALSE if error is set.
* Since: 2.26
*/
/**
- * g_credentials_to_string:
- * @credentials: A #GCredentials object.
+ * g_dbus_auth_observer_authorize_authenticated_peer:
+ * @observer: A #GDBusAuthObserver.
+ * @stream: A #GIOStream for the #GDBusConnection.
+ * @credentials: Credentials received from the peer or %NULL.
*
- * 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.
+ * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
*
- * Returns: A string that should be freed with g_free().
+ * Returns: %TRUE if the peer is authorized, %FALSE if not.
* Since: 2.26
*/
/**
- * g_data_input_stream_get_byte_order:
- * @stream: a given #GDataInputStream.
+ * g_dbus_auth_observer_new:
*
- * Gets the byte order for the data input stream.
+ * Creates a new #GDBusAuthObserver object.
*
- * Returns: the @stream's current #GDataStreamByteOrder.
+ * Returns: A #GDBusAuthObserver. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_get_newline_type:
- * @stream: a given #GDataInputStream.
+ * g_dbus_connection_add_filter:
+ * @connection: A #GDBusConnection.
+ * @filter_function: A filter function.
+ * @user_data: User data to pass to @filter_function.
+ * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL.
*
- * Gets the current newline type for the @stream.
+ * Adds a message filter. Filters are handlers that are run on all
+ * incoming and outgoing messages, prior to standard dispatch. Filters
+ * are run in the order that they were added. The same handler can be
+ * added as a filter more than once, in which case it will be run more
+ * than once. Filters added during a filter callback won't be run on
+ * the message being processed. Filter functions are allowed to modify
+ * and even drop messages.
+ * Note that filters are run in a dedicated message handling thread so
+ * they can't block and, generally, can't do anything but signal a
+ * worker thread. Also note that filters are rarely needed - use API
+ * such as g_dbus_connection_send_message_with_reply(),
+ * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
+ * If a filter consumes an incoming message the message is not
+ * dispatched anywhere else - not even the standard dispatch machinery
+ * (that API such as g_dbus_connection_signal_subscribe() and
+ * g_dbus_connection_send_message_with_reply() relies on) will see the
+ * message. Similary, if a filter consumes an outgoing message, the
+ * message will not be sent to the other peer.
+ * g_dbus_connection_remove_filter().
*
- * Returns: #GDataStreamNewlineType for the given @stream.
+ * Returns: A filter identifier that can be used with
+ * Since: 2.26
*/
/**
- * g_data_input_stream_new:
- * @base_stream: a #GInputStream.
+ * g_dbus_connection_call:
+ * @connection: A #GDBusConnection.
+ * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
+ * @object_path: Path of remote object.
+ * @interface_name: D-Bus interface to invoke method on.
+ * @method_name: The name of the method to invoke.
+ * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
+ * @reply_type: (allow-none): The expected type of the reply, or %NULL.
+ * @flags: Flags from the #GDBusCallFlags enumeration.
+ * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation.
+ * @user_data: The data to pass to @callback.
*
- * Creates a new data input stream for the @base_stream.
+ * Asynchronously invokes the @method_name method on the
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
+ * not compatible with the D-Bus protocol, the operation fails with
+ * %G_IO_ERROR_INVALID_ARGUMENT.
+ * If @reply_type is non-%NULL then the reply will be checked for having this type and an
+ * error will be raised if it does not match. Said another way, if you give a @reply_type
+ * then any non-%NULL return value will be of this type.
+ * If the @parameters #GVariant is floating, it is consumed. This allows
+ * convenient 'inline' use of g_variant_new(), e.g.:
+ * |[
+ * g_dbus_connection_call (connection,
+ * "org.freedesktop.StringThings",
+ * "/org/freedesktop/StringThings",
+ * "org.freedesktop.StringThings",
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * NULL,
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * (GAsyncReadyCallback) two_strings_done,
+ * NULL);
+ * ]|
+ * This is an asynchronous method. When the operation is finished, @callback will be invoked
+ * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread you are calling this method from. You can then call
+ * g_dbus_connection_call_finish() to get the result of the operation.
+ * See g_dbus_connection_call_sync() for the synchronous version of this
+ * function.
*
- * Returns: a new #GDataInputStream.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_byte:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_call_finish:
+ * @connection: A #GDBusConnection.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call().
+ * @error: Return location for error or %NULL.
*
- * Reads an unsigned 8-bit/1-byte value from @stream.
- * if an error occurred.
+ * Finishes an operation started with g_dbus_connection_call().
+ * return values. Free with g_variant_unref().
*
- * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_int16:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_call_sync:
+ * @connection: A #GDBusConnection.
+ * @bus_name: A unique or well-known bus name.
+ * @object_path: Path of remote object.
+ * @interface_name: D-Bus interface to invoke method on.
+ * @method_name: The name of the method to invoke.
+ * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
+ * @reply_type: (allow-none): The expected type of the reply, or %NULL.
+ * @flags: Flags from the #GDBusCallFlags enumeration.
+ * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * 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().
- * an error occurred.
+ * Synchronously invokes the @method_name method on the
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
+ * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
+ * contains a value not compatible with the D-Bus protocol, the operation
+ * fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ * If @reply_type is non-%NULL then the reply will be checked for having
+ * this type and an error will be raised if it does not match. Said
+ * another way, if you give a @reply_type then any non-%NULL return
+ * value will be of this type.
+ * If the @parameters #GVariant is floating, it is consumed.
+ * This allows convenient 'inline' use of g_variant_new(), e.g.:
+ * |[
+ * g_dbus_connection_call_sync (connection,
+ * "org.freedesktop.StringThings",
+ * "/org/freedesktop/StringThings",
+ * "org.freedesktop.StringThings",
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * NULL,
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * &error);
+ * ]|
+ * The calling thread is blocked until a reply is received. See
+ * g_dbus_connection_call() for the asynchronous version of
+ * this method.
+ * return values. Free with g_variant_unref().
*
- * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_int32:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_close:
+ * @connection: A #GDBusConnection.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
+ * @user_data: The data to pass to @callback.
*
- * 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.
- * an error occurred.
+ * 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 <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread that @connection was constructed in.
+ * This is an asynchronous method. When the operation is finished,
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from. You can
+ * then call g_dbus_connection_close_finish() to get the result of the
+ * operation. See g_dbus_connection_close_sync() for the synchronous
+ * version.
*
- * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_int64:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_close_finish:
+ * @connection: A #GDBusConnection.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close().
+ * @error: Return location for error or %NULL.
*
- * 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.
- * an error occurred.
+ * Finishes an operation started with g_dbus_connection_close().
*
- * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line:
- * @stream: a given #GDataInputStream.
- * @length: (out): a #gsize to get the length of the data read in.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_close_sync:
+ * @connection: A #GDBusConnection.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Reads a 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.
- * (without the newlines). Set @length to a #gsize to get the
- * length of the read line. On an error, it will return %NULL and
- * still return %NULL, but @error won't be set.
+ * Synchronously closees @connection. The calling thread is blocked
+ * until this is done. See g_dbus_connection_close() for the
+ * asynchronous version of this method and more details about what it
+ * does.
*
- * Returns: (transfer full): a string with the line that was read in
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line_async:
- * @stream: a given #GDataInputStream.
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): callback to call when the request is satisfied.
- * @user_data: (closure): the data to pass to callback function.
+ * g_dbus_connection_emit_signal:
+ * @connection: A #GDBusConnection.
+ * @destination_bus_name: (allow-none): The unique bus name for the destination for the signal or %NULL to emit to all listeners.
+ * @object_path: Path of remote object.
+ * @interface_name: D-Bus interface to emit a signal on.
+ * @signal_name: The name of the signal to emit.
+ * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
+ * @error: Return location for error or %NULL.
*
- * 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.
+ * 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.
*
- * Since: 2.20
+ * Returns: %TRUE unless @error is set.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_line_finish:
- * @stream: a given #GDataInputStream.
- * @result: the #GAsyncResult that was provided to the callback.
- * @length: (out): a #gsize to get the length of the data read in.
- * @error: #GError for error reporting.
+ * g_dbus_connection_flush:
+ * @connection: A #GDBusConnection.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
+ * @user_data: The data to pass to @callback.
*
- * Finish an asynchronous call started by
- * g_data_input_stream_read_line_async().
- * (without the newlines). Set @length to a #gsize to get the
- * length of the read line. On an error, it will return %NULL and
- * still return %NULL, but @error won't be set.
+ * Asynchronously flushes @connection, that is, writes all queued
+ * outgoing message to the transport and then flushes the transport
+ * (using g_output_stream_flush_async()). This is useful in programs
+ * that wants to emit a D-Bus signal and then exit
+ * immediately. Without flushing the connection, there is no guarantee
+ * that the message has been sent to the networking buffers in the OS
+ * kernel.
+ * This is an asynchronous method. When the operation is finished,
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from. You can
+ * then call g_dbus_connection_flush_finish() to get the result of the
+ * operation. See g_dbus_connection_flush_sync() for the synchronous
+ * version.
*
- * Returns: (transfer full): a string with the line that was read in
- * Since: 2.20
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_uint16:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_flush_finish:
+ * @connection: A #GDBusConnection.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush().
+ * @error: Return location for error or %NULL.
*
- * 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().
- * an error occurred.
+ * Finishes an operation started with g_dbus_connection_flush().
*
- * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_uint32:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_flush_sync:
+ * @connection: A #GDBusConnection.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * 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.
- * an error occurred.
+ * Synchronously flushes @connection. The calling thread is blocked
+ * until this is done. See g_dbus_connection_flush() for the
+ * asynchronous version of this method and more details about what it
+ * does.
*
- * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_uint64:
- * @stream: a given #GDataInputStream.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_get_capabilities:
+ * @connection: A #GDBusConnection.
*
- * 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.
- * an error occurred.
+ * Gets the capabilities negotiated with the remote peer
+ *
+ * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
+ * Since: 2.26
+ */
+
+
+/**
+ * g_dbus_connection_get_exit_on_close:
+ * @connection: A #GDBusConnection.
*
- * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
+ * Gets whether the process is terminated when @connection is
+ * closed by the remote peer. See
+ * #GDBusConnection:exit-on-close for more details.
+ * closed by the remote peer.
+ *
+ * Returns: Whether the process is terminated when @connection is
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_until:
- * @stream: a given #GDataInputStream.
- * @stop_chars: characters to terminate the read.
- * @length: (out): a #gsize to get the length of the data read in.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: #GError for error reporting.
+ * g_dbus_connection_get_guid:
+ * @connection: A #GDBusConnection.
*
- * 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.
- * 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 GUID of the peer performing the role of server when
+ * authenticating. See #GDBusConnection:guid for more details.
*
- * Returns: (transfer full): a string with the data that was read
+ * Returns: The GUID. Do not free this string, it is owned by
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_until_async:
- * @stream: a given #GDataInputStream.
- * @stop_chars: characters to terminate the read.
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (scope async): callback to call when the request is satisfied.
- * @user_data: (closure): the data to pass to callback function.
+ * g_dbus_connection_get_peer_credentials:
+ * @connection: A #GDBusConnection.
*
- * 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.
+ * 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.
+ * this object, it is owned by @connection.
*
- * Since: 2.20
+ * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_until_finish:
- * @stream: a given #GDataInputStream.
- * @result: the #GAsyncResult that was provided to the callback.
- * @length: (out): a #gsize to get the length of the data read in.
- * @error: #GError for error reporting.
+ * g_dbus_connection_get_stream:
+ * @connection: a #GDBusConnection
*
- * Finish an asynchronous call started by
- * g_data_input_stream_read_until_async().
- * 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.
+ * Gets the underlying stream used for IO.
*
- * Since: 2.20
- * Returns: (transfer full): a string with the data that was read
+ * Returns: (transfer none): the stream used for IO
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_upto:
- * @stream: a #GDataInputStream
- * @stop_chars: characters to terminate the read
- * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
- * @length: (out): a #gsize to get the length of the data read in
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @error: #GError for error reporting
+ * g_dbus_connection_get_unique_name:
+ * @connection: A #GDBusConnection.
*
- * Reads a string from the data input stream, up to the first
- * occurrence of any of the stop characters.
- * In contrast to g_data_input_stream_read_until(), this function
- * does <emphasis>not</emphasis> consume the stop character. You have
- * to use g_data_input_stream_read_byte() to get it before calling
- * g_data_input_stream_read_upto() again.
- * Note that @stop_chars may contain '\0' if @stop_chars_len is
- * specified.
- * 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
+ * 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.
+ * bus connection. Do not free this string, it is owned by
*
- * Returns: (transfer full): a string with the data that was read
- * Since: 2.24
+ * Returns: The unique name or %NULL if @connection is not a message
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_upto_async:
- * @stream: a #GDataInputStream
- * @stop_chars: characters to terminate the read
- * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
- * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
- * @callback: (scope async): callback to call when the request is satisfied
- * @user_data: (closure): the data to pass to callback function
+ * g_dbus_connection_is_closed:
+ * @connection: A #GDBusConnection.
*
- * The asynchronous version of g_data_input_stream_read_upto().
- * It is an error to have two outstanding calls to this function.
- * In contrast to g_data_input_stream_read_until(), this function
- * does <emphasis>not</emphasis> consume the stop character. You have
- * to use g_data_input_stream_read_byte() to get it before calling
- * g_data_input_stream_read_upto() again.
- * Note that @stop_chars may contain '\0' if @stop_chars_len is
- * specified.
- * 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.
+ * Gets whether @connection is closed.
*
- * Since: 2.24
+ * Returns: %TRUE if the connection is closed, %FALSE otherwise.
+ * Since: 2.26
*/
/**
- * g_data_input_stream_read_upto_finish:
- * @stream: a #GDataInputStream
- * @result: the #GAsyncResult that was provided to the callback
- * @length: (out): a #gsize to get the length of the data read in
- * @error: #GError for error reporting
+ * g_dbus_connection_new:
+ * @stream: A #GIOStream.
+ * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
+ * @flags: Flags describing how to make the connection.
+ * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: The data to pass to @callback.
*
- * Finish an asynchronous call started by
- * g_data_input_stream_read_upto_async().
- * Note that this function does <emphasis>not</emphasis> consume the
- * stop character. You have to use g_data_input_stream_read_byte() to
- * get it before calling g_data_input_stream_read_upto_async() again.
- * 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.
+ * 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.
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_dbus_connection_new_finish() to get the result of the
+ * operation.
+ * This is a asynchronous failable constructor. See
+ * g_dbus_connection_new_sync() for the synchronous
+ * version.
*
- * Returns: (transfer full): a string with the data that was read
- * Since: 2.24
+ * Since: 2.26
*/
/**
- * g_data_input_stream_set_byte_order:
- * @stream: a given #GDataInputStream.
- * @order: a #GDataStreamByteOrder to set.
+ * g_dbus_connection_new_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
+ * @error: Return location for error or %NULL.
*
- * This function sets the byte order for the given @stream. All subsequent
- * reads from the @stream will be read in the given @order.
+ * Finishes an operation started with g_dbus_connection_new().
+ *
+ * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_input_stream_set_newline_type:
- * @stream: a #GDataInputStream.
- * @type: the type of new line return as #GDataStreamNewlineType.
+ * g_dbus_connection_new_for_address:
+ * @address: A D-Bus address.
+ * @flags: Flags describing how to make the connection.
+ * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: The data to pass to @callback.
*
- * 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 availible.
+ * Asynchronously connects and sets up a D-Bus client connection for
+ * exchanging D-Bus messages with an endpoint specified by @address
+ * which must be in the D-Bus address format.
+ * This constructor can only be used to initiate client-side
+ * connections - use g_dbus_connection_new() if you need to act as the
+ * server. In particular, @flags cannot contain the
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_dbus_connection_new_finish() to get the result of the
+ * operation.
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
+ * This is a asynchronous failable constructor. See
+ * g_dbus_connection_new_for_address_sync() for the synchronous
+ * version.
+ *
+ * Since: 2.26
*/
/**
- * g_data_output_stream_get_byte_order:
- * @stream: a #GDataOutputStream.
+ * g_dbus_connection_new_for_address_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
+ * @error: Return location for error or %NULL.
*
- * Gets the byte order for the stream.
+ * Finishes an operation started with g_dbus_connection_new_for_address().
*
- * Returns: the #GDataStreamByteOrder for the @stream.
+ * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_output_stream_new:
- * @base_stream: a #GOutputStream.
+ * g_dbus_connection_new_for_address_sync:
+ * @address: A D-Bus address.
+ * @flags: Flags describing how to make the connection.
+ * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Creates a new data output stream for @base_stream.
+ * 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.
+ * This constructor can only be used to initiate client-side
+ * connections - use g_dbus_connection_new_sync() if you need to act
+ * as the server. In particular, @flags cannot contain the
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
+ * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+ * This is a synchronous failable constructor. See
+ * g_dbus_connection_new_for_address() for the asynchronous version.
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
*
- * Returns: #GDataOutputStream.
+ * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_byte:
- * @stream: a #GDataOutputStream.
- * @data: a #guchar.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_new_sync:
+ * @stream: A #GIOStream.
+ * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
+ * @flags: Flags describing how to make the connection.
+ * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Puts a byte into the output stream.
+ * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
+ * with the end represented by @stream.
+ * If @stream is a #GSocketConnection, then the corresponding #GSocket
+ * will be put into non-blocking mode.
+ * If @observer is not %NULL it may be used to control the
+ * authentication process.
+ * This is a synchronous failable constructor. See
+ * g_dbus_connection_new() for the asynchronous version.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_int16:
- * @stream: a #GDataOutputStream.
- * @data: a #gint16.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_register_object:
+ * @connection: A #GDBusConnection.
+ * @object_path: The object path to register at.
+ * @interface_info: Introspection data for the interface.
+ * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL.
+ * @user_data: Data to pass to functions in @vtable.
+ * @user_data_free_func: Function to call when the object path is unregistered.
+ * @error: Return location for error or %NULL.
*
- * Puts a signed 16-bit integer into the output stream.
+ * Registers callbacks for exported objects at @object_path with the
+ * D-Bus interface that is described in @interface_info.
+ * Calls to functions in @vtable (and @user_data_free_func) will
+ * happen in the <link linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from.
+ * Note that all #GVariant values passed to functions in @vtable will match
+ * the signature given in @interface_info - if a remote caller passes
+ * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
+ * is returned to the remote caller.
+ * Additionally, if the remote caller attempts to invoke methods or
+ * access properties not mentioned in @interface_info the
+ * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
+ * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
+ * are returned to the caller.
+ * It is considered a programming error if the
+ * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
+ * #GVariant of incorrect type.
+ * If an existing callback is already registered at @object_path and
+ * GDBus automatically implements the standard D-Bus interfaces
+ * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
+ * and org.freedesktop.Peer, so you don't have to implement those for
+ * the objects you export. You <emphasis>can</emphasis> implement
+ * org.freedesktop.DBus.Properties yourself, e.g. to handle getting
+ * and setting of properties asynchronously.
+ * Note that the reference count on @interface_info will be
+ * incremented by 1 (unless allocated statically, e.g. if the
+ * reference count is -1, see g_dbus_interface_info_ref()) for as long
+ * as the object is exported. Also note that @vtable will be copied.
+ * See <xref linkend="gdbus-server"/> for an example of how to use this method.
+ * that can be used with g_dbus_connection_unregister_object() .
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Returns: 0 if @error is set, otherwise a registration id (never 0)
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_int32:
- * @stream: a #GDataOutputStream.
- * @data: a #gint32.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_register_subtree:
+ * @connection: A #GDBusConnection.
+ * @object_path: The object path to register the subtree at.
+ * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
+ * @flags: Flags used to fine tune the behavior of the subtree.
+ * @user_data: Data to pass to functions in @vtable.
+ * @user_data_free_func: Function to call when the subtree is unregistered.
+ * @error: Return location for error or %NULL.
*
- * Puts a signed 32-bit integer into the output stream.
+ * Registers a whole subtree of <quote>dynamic</quote> objects.
+ * The @enumerate and @introspection functions in @vtable are used to
+ * convey, to remote callers, what nodes exist in the subtree rooted
+ * by @object_path.
+ * When handling remote calls into any node in the subtree, first the
+ * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
+ * the @introspection function is used to check if the node supports the
+ * requested method. If so, the @dispatch function is used to determine
+ * where to dispatch the call. The collected #GDBusInterfaceVTable and
+ * #gpointer will be used to call into the interface vtable for processing
+ * the request.
+ * All calls into user-provided code will be invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from.
+ * If an existing subtree is already registered at @object_path or
+ * then @error is set to #G_IO_ERROR_EXISTS.
+ * Note that it is valid to register regular objects (using
+ * g_dbus_connection_register_object()) in a subtree registered with
+ * g_dbus_connection_register_subtree() - if so, the subtree handler
+ * is tried as the last resort. One way to think about a subtree
+ * handler is to consider it a <quote>fallback handler</quote>
+ * for object paths not registered via g_dbus_connection_register_object()
+ * or other bindings.
+ * Note that @vtable will be copied so you cannot change it after
+ * registration.
+ * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
+ * that can be used with g_dbus_connection_unregister_subtree() .
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_int64:
- * @stream: a #GDataOutputStream.
- * @data: a #gint64.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_remove_filter:
+ * @connection: a #GDBusConnection
+ * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
*
- * Puts a signed 64-bit integer into the stream.
+ * Removes a filter.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_string:
- * @stream: a #GDataOutputStream.
- * @str: a string.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_send_message:
+ * @connection: A #GDBusConnection.
+ * @message: A #GDBusMessage
+ * @flags: Flags affecting how the message is sent.
+ * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Puts a string into the output stream.
+ * Asynchronously sends @message to the peer represented by @connection.
+ * Unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+ * will be assigned by @connection and set on @message via
+ * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+ * serial number used will be written to this location prior to
+ * submitting the message to the underlying transport.
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
+ * Note that @message must be unlocked, unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ * transmission, %FALSE if @error is set.
*
- * Returns: %TRUE if @string was successfully added to the @stream.
+ * Returns: %TRUE if the message was well-formed and queued for
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_uint16:
- * @stream: a #GDataOutputStream.
- * @data: a #guint16.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_send_message_with_reply:
+ * @connection: A #GDBusConnection.
+ * @message: A #GDBusMessage.
+ * @flags: Flags affecting how the message is sent.
+ * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
+ * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
+ * @user_data: The data to pass to @callback.
*
- * Puts an unsigned 16-bit integer into the output stream.
+ * Asynchronously sends @message to the peer represented by @connection.
+ * Unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+ * will be assigned by @connection and set on @message via
+ * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+ * serial number used will be written to this location prior to
+ * submitting the message to the underlying transport.
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ * This is an asynchronous method. When the operation is finished, @callback will be invoked
+ * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread you are calling this method from. You can then call
+ * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
+ * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
+ * Note that @message must be unlocked, unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ * See <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_uint32:
- * @stream: a #GDataOutputStream.
- * @data: a #guint32.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_send_message_with_reply_finish:
+ * @connection: a #GDBusConnection
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
+ * @error: Return location for error or %NULL.
*
- * Puts an unsigned 32-bit integer into the stream.
+ * Finishes an operation started with g_dbus_connection_send_message_with_reply().
+ * Note that @error is only set if a local in-process error
+ * occured. 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 <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_put_uint64:
- * @stream: a #GDataOutputStream.
- * @data: a #guint64.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError, %NULL to ignore.
+ * g_dbus_connection_send_message_with_reply_sync:
+ * @connection: A #GDBusConnection.
+ * @message: A #GDBusMessage.
+ * @flags: Flags affecting how the message is sent.
+ * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
+ * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
*
- * Puts an unsigned 64-bit integer into the stream.
+ * Synchronously sends @message to the peer represented by @connection
+ * and blocks the calling thread until a reply is received or the
+ * timeout is reached. See g_dbus_connection_send_message_with_reply()
+ * for the asynchronous version of this method.
+ * Unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
+ * will be assigned by @connection and set on @message via
+ * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
+ * serial number used will be written to this location prior to
+ * submitting the message to the underlying transport.
+ * If @connection is closed then the operation will fail with
+ * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
+ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
+ * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ * Note that @error is only set if a local in-process error
+ * occured. 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 <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
+ * Note that @message must be unlocked, unless @flags contain the
+ * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
*
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
+ * Since: 2.26
*/
/**
- * g_data_output_stream_set_byte_order:
- * @stream: a #GDataOutputStream.
- * @order: a %GDataStreamByteOrder.
+ * g_dbus_connection_set_exit_on_close:
+ * @connection: A #GDBusConnection.
+ * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer.
*
- * Sets the byte order of the data output stream to @order.
+ * Sets whether the process should be terminated when @connection is
+ * closed by the remote peer. See #GDBusConnection:exit-on-close for
+ * more details.
+ * Note that this function should be used with care. Most modern UNIX
+ * desktops tie the notion of a user session the session bus, and expect
+ * all of a users applications to quit when their bus connection goes away.
+ * If you are setting @exit_on_close to %FALSE for the shared session
+ * bus connection, you should make sure that your application exits
+ * when the user session ends.
+ *
+ * Since: 2.26
*/
/**
- * g_dbus_address_get_for_bus_sync:
- * @bus_type: A #GBusType.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_connection_signal_subscribe:
+ * @connection: A #GDBusConnection.
+ * @sender: (allow-none): Sender name to match on (unique or well-known name) or %NULL to listen from all senders.
+ * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to match on all interfaces.
+ * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals.
+ * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths.
+ * @arg0: (allow-none): Contents of first string argument to match on or %NULL to match on all kinds of arguments.
+ * @flags: Flags describing how to subscribe to the signal (currently unused).
+ * @callback: Callback to invoke when there is a signal matching the requested data.
+ * @user_data: User data to pass to @callback.
+ * @user_data_free_func: Function to free @user_data with when subscription is removed or %NULL.
*
- * Synchronously looks up the D-Bus address for the well-known message
- * bus instance specified by @bus_type. This may involve using various
- * platform specific mechanisms.
+ * Subscribes to signals on @connection and invokes @callback with a
+ * whenever the signal is received. Note that @callback
+ * will be invoked in the <link
+ * linkend="g-main-context-push-thread-default">thread-default main
+ * loop</link> of the thread you are calling this method from.
+ * If @connection is not a message bus connection, @sender must be
+ * %NULL.
+ * 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.
*
- * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
+ * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
* Since: 2.26
*/
/**
- * g_dbus_address_get_stream:
- * @address: A valid D-Bus address.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: Data to pass to @callback.
+ * g_dbus_connection_signal_unsubscribe:
+ * @connection: A #GDBusConnection.
+ * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
*
- * 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.
- * 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.
+ * Unsubscribes from signals.
*
* Since: 2.26
*/
/**
- * g_dbus_address_get_stream_finish:
- * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
- * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
- * @error: Return location for error or %NULL.
+ * g_dbus_connection_start_message_processing:
+ * @connection: A #GDBusConnection.
*
- * Finishes an operation started with g_dbus_address_get_stream().
+ * If @connection was created with
+ * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
+ * starts processing messages. Does nothing on if @connection wasn't
+ * created with this flag or if the method has already been called.
*
- * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
* Since: 2.26
*/
/**
- * g_dbus_address_get_stream_sync:
- * @address: A valid D-Bus address.
- * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_connection_unregister_object:
+ * @connection: A #GDBusConnection.
+ * @registration_id: A registration id obtained from g_dbus_connection_register_object().
*
- * 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.
- * This is a synchronous failable function. See
- * g_dbus_address_get_stream() for the asynchronous version.
+ * Unregisters an object.
*
- * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
+ * Returns: %TRUE if the object was unregistered, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_annotation_info_lookup:
- * @annotations: A %NULL-terminated array of annotations or %NULL.
- * @name: The name of the annotation to look up.
+ * g_dbus_connection_unregister_subtree:
+ * @connection: A #GDBusConnection.
+ * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree().
*
- * Looks up the value of an annotation.
- * This cost of this function is O(n) in number of annotations.
+ * Unregisters a subtree.
*
- * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
+ * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_annotation_info_ref:
- * @info: A #GDBusNodeInfo
+ * g_dbus_error_encode_gerror:
+ * @error: A #GError.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Creates a D-Bus error name to use for @error. If @error matches
+ * a registered error (cf. g_dbus_error_register_error()), the corresponding
+ * D-Bus error name will be returned.
+ * Otherwise the a name of the form
+ * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
+ * will be used. This allows other GDBus applications to map the error
+ * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
+ * This function is typically only used in object mappings to put a
+ * #GError on the wire. Regular applications should not use it.
*
- * Returns: The same @info.
+ * Returns: A D-Bus error name (never %NULL). Free with g_free().
* Since: 2.26
*/
/**
- * g_dbus_annotation_info_unref:
- * @info: A #GDBusAnnotationInfo.
+ * g_dbus_error_get_remote_error:
+ * @error: A #GError.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Gets the D-Bus error name used for @error, if any.
+ * This function is guaranteed to return a D-Bus error name for all
+ * #GError<!-- -->s returned from functions handling remote method
+ * calls (e.g. g_dbus_connection_call_finish()) unless
+ * g_dbus_error_strip_remote_error() has been used on @error.
*
+ * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
* Since: 2.26
*/
/**
- * g_dbus_arg_info_ref:
- * @info: A #GDBusArgInfo
+ * g_dbus_error_is_remote_error:
+ * @error: A #GError.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * 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.
+ * %FALSE otherwise.
*
- * Returns: The same @info.
+ * Returns: %TRUE if @error represents an error from a remote peer,
* Since: 2.26
*/
/**
- * g_dbus_arg_info_unref:
- * @info: A #GDBusArgInfo.
+ * g_dbus_error_new_for_dbus_error:
+ * @dbus_error_name: D-Bus error name.
+ * @dbus_error_message: D-Bus error message.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Creates a #GError based on the contents of @dbus_error_name and
+ * Errors registered with g_dbus_error_register_error() will be looked
+ * up using @dbus_error_name and if a match is found, the error domain
+ * and code is used. Applications can use g_dbus_error_get_remote_error()
+ * to recover @dbus_error_name.
+ * If a match against a registered error is not found and the D-Bus
+ * error name is in a form as returned by g_dbus_error_encode_gerror()
+ * the error domain and code encoded in the name is used to
+ * create the #GError. Also, @dbus_error_name is added to the error message
+ * such that it can be recovered with g_dbus_error_get_remote_error().
+ * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
+ * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
+ * added to the error message such that it can be recovered with
+ * g_dbus_error_get_remote_error().
+ * In all three cases, @dbus_error_name can always be recovered from the
+ * returned #GError using the g_dbus_error_get_remote_error() function
+ * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
+ * This function is typically only used in object mappings to prepare
+ * #GError instances for applications. Regular applications should not use
+ * it.
*
+ * Returns: An allocated #GError. Free with g_error_free().
* Since: 2.26
*/
/**
- * g_dbus_auth_observer_authorize_authenticated_peer:
- * @observer: A #GDBusAuthObserver.
- * @stream: A #GIOStream for the #GDBusConnection.
- * @credentials: Credentials received from the peer or %NULL.
+ * g_dbus_error_register_error:
+ * @error_domain: A #GQuark for a error domain.
+ * @error_code: An error code.
+ * @dbus_error_name: A D-Bus error name.
*
- * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
+ * Creates an association to map between @dbus_error_name and
+ * #GError<!-- -->s specified by @error_domain and @error_code.
+ * This is typically done in the routine that returns the #GQuark for
+ * an error domain.
+ * exists.
*
- * Returns: %TRUE if the peer is authorized, %FALSE if not.
+ * Returns: %TRUE if the association was created, %FALSE if it already
* Since: 2.26
*/
/**
- * g_dbus_auth_observer_new:
+ * g_dbus_error_register_error_domain:
+ * @error_domain_quark_name: The error domain name.
+ * @quark_volatile: A pointer where to store the #GQuark.
+ * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
+ * @num_entries: Number of items to register.
*
- * Creates a new #GDBusAuthObserver object.
+ * Helper function for associating a #GError error domain with D-Bus error names.
*
- * Returns: A #GDBusAuthObserver. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_connection_add_filter:
- * @connection: A #GDBusConnection.
- * @filter_function: A filter function.
- * @user_data: User data to pass to @filter_function.
- * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL.
+ * g_dbus_error_set_dbus_error:
+ * @error: A pointer to a #GError or %NULL.
+ * @dbus_error_name: D-Bus error name.
+ * @dbus_error_message: D-Bus error message.
+ * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
+ * @...: Arguments for @format.
*
- * 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 - see the #GDBusMessageFilterResult
- * enumeration for details.
- * Note that filters are run in a dedicated message handling thread so
- * they can't block and, generally, can't do anything but signal a
- * worker thread. Also note that filters are rarely needed - use API
- * such as g_dbus_connection_send_message_with_reply(),
- * g_dbus_connection_signal_subscribe() or
- * g_dbus_connection_call() instead.
- * If a filter consumes an incoming message the message is not
- * dispatched anywhere else - not even the standard dispatch machinery
- * (that API such as g_dbus_connection_signal_subscribe() and
- * g_dbus_connection_send_message_with_reply() relies on) will see the
- * message. Similary, if a filter consumes an outgoing message, the
- * message will not be sent to the other peer.
- * g_dbus_connection_remove_filter().
+ * Does nothing if @error is %NULL. Otherwise sets * error to
+ * a new #GError created with g_dbus_error_new_for_dbus_error()
+ * with @dbus_error_message prepend with @format (unless %NULL).
*
- * Returns: A filter identifier that can be used with
* Since: 2.26
*/
/**
- * g_dbus_connection_call:
- * @connection: A #GDBusConnection.
- * @bus_name: A unique or well-known bus name or %NULL if @connection is not a message bus connection.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to invoke method on.
- * @method_name: The name of the method to invoke.
- * @parameters: A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
- * @reply_type: The expected type of the reply, or %NULL.
- * @flags: Flags from the #GDBusCallFlags enumeration.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
- * @user_data: The data to pass to @callback.
- *
- * Asynchronously invokes the @method_name method on the
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
- * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
- * not compatible with the D-Bus protocol, the operation fails with
- * %G_IO_ERROR_INVALID_ARGUMENT.
- * If @reply_type is non-%NULL then the reply will be checked for having this type and an
- * error will be raised if it does not match. Said another way, if you give a @reply_type
- * then any non-%NULL return value will be of this type.
- * If the @parameters #GVariant is floating, it is consumed. This allows
- * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
- * g_dbus_connection_call (connection,
- * "org.freedesktop.StringThings",
- * "/org/freedesktop/StringThings",
- * "org.freedesktop.StringThings",
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * NULL,
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * (GAsyncReadyCallback) two_strings_done,
- * NULL);
- * ]|
- * This is an asynchronous method. When the operation is finished, @callback will be invoked
- * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
- * of the thread you are calling this method from. You can then call
- * g_dbus_connection_call_finish() to get the result of the operation.
- * See g_dbus_connection_call_sync() for the synchronous version of this
- * function.
+ * g_dbus_error_set_dbus_error_valist:
+ * @error: A pointer to a #GError or %NULL.
+ * @dbus_error_name: D-Bus error name.
+ * @dbus_error_message: D-Bus error message.
+ * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
+ * @var_args: Arguments for @format.
+ *
+ * Like g_dbus_error_set_dbus_error() but intended for language bindings.
*
* Since: 2.26
*/
/**
- * g_dbus_connection_call_finish:
- * @connection: A #GDBusConnection.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call().
- * @error: Return location for error or %NULL.
+ * g_dbus_error_strip_remote_error:
+ * @error: A #GError.
*
- * Finishes an operation started with g_dbus_connection_call().
- * return values. Free with g_variant_unref().
+ * Looks for extra information in the error message used to recover
+ * the D-Bus error name and strips it if found. If stripped, the
+ * message field in @error will correspond exactly to what was
+ * received on the wire.
+ * This is typically used when presenting errors to the end user.
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %TRUE if information was stripped, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_call_sync:
- * @connection: A #GDBusConnection.
- * @bus_name: A unique or well-known bus name.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to invoke method on.
- * @method_name: The name of the method to invoke.
- * @parameters: A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
- * @reply_type: The expected type of the reply, or %NULL.
- * @flags: Flags from the #GDBusCallFlags enumeration.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_error_unregister_error:
+ * @error_domain: A #GQuark for a error domain.
+ * @error_code: An error code.
+ * @dbus_error_name: A D-Bus error name.
*
- * Synchronously invokes the @method_name method on the
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
- * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
- * contains a value not compatible with the D-Bus protocol, the operation
- * fails with %G_IO_ERROR_INVALID_ARGUMENT.
- * If @reply_type is non-%NULL then the reply will be checked for having
- * this type and an error will be raised if it does not match. Said
- * another way, if you give a @reply_type then any non-%NULL return
- * value will be of this type.
- * If the @parameters #GVariant is floating, it is consumed.
- * This allows convenient 'inline' use of g_variant_new(), e.g.:
- * |[
- * g_dbus_connection_call_sync (connection,
- * "org.freedesktop.StringThings",
- * "/org/freedesktop/StringThings",
- * "org.freedesktop.StringThings",
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * NULL,
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * &error);
- * ]|
- * The calling thread is blocked until a reply is received. See
- * g_dbus_connection_call() for the asynchronous version of
- * this method.
- * return values. Free with g_variant_unref().
+ * Destroys an association previously set up with g_dbus_error_register_error().
*
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
* Since: 2.26
*/
/**
- * g_dbus_connection_close:
- * @connection: A #GDBusConnection.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
- * @user_data: The data to pass to @callback.
+ * g_dbus_generate_guid:
*
- * 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread that @connection was constructed in.
- * This is an asynchronous method. When the operation is finished,
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this method from. You can
- * then call g_dbus_connection_close_finish() to get the result of the
- * operation. See g_dbus_connection_close_sync() for the synchronous
- * version.
+ * Generate a D-Bus GUID that can be used with
+ * e.g. g_dbus_connection_new().
+ * See the D-Bus specification regarding what strings are valid D-Bus
+ * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
*
+ * Returns: A valid D-Bus GUID. Free with g_free().
* Since: 2.26
*/
/**
- * g_dbus_connection_close_finish:
- * @connection: A #GDBusConnection.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close().
- * @error: Return location for error or %NULL.
+ * g_dbus_gvalue_to_gvariant:
+ * @gvalue: A #GValue to convert to a #GVariant.
+ * @type: A #GVariantType.
*
- * Finishes an operation started with g_dbus_connection_close().
+ * Converts a #GValue to a #GVariant of the type indicated by the @type parameter.
+ * The conversion is using the following rules:
+ * <table frame='all'>
+ * <title>#GValue / #GVariant conversion rules</title>
+ * <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ * <thead>
+ * <row>
+ * <entry>If the #GType for @gvalue is...</entry>
+ * <entry>... then @type must be</entry>
+ * </row>
+ * </thead>
+ * <tbody>
+ * <row>
+ * <entry>#G_TYPE_STRING</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link>, <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link> or <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_STRV</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link> or <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_BOOLEAN</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_UCHAR</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_INT</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_UINT</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_INT64</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_UINT64</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_INT</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-HANDLE:CAPS">'h'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_DOUBLE</entry>
+ * <entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry>
+ * </row>
+ * <row>
+ * <entry>#G_TYPE_VARIANT</entry>
+ * <entry>Any #GVariantType</entry>
+ * </row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
+ * is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will
+ * also fail for any #GType (including e.g. #G_TYPE_OBJECT and
+ * #G_TYPE_BOXED derived-types) not in the table above.
+ * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
+ * %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
+ * %NULL) for @type is returned (e.g. 0 for scalar types, the empty
+ * string for string types, <literal>'/'</literal> for object path
+ * types, the empty array for any array type and so on).
+ * See the g_dbus_gvariant_to_gvalue() function for how to convert a
+ * #GVariant to a #GValue.
+ * failure. Free with g_variant_unref().
+ *
+ * Returns: A #GVariant (never floating) of #GVariantType
+ * Since: 2.30
+ */
+
+
+/**
+ * g_dbus_gvariant_to_gvalue:
+ * @value: A #GVariant.
+ * @out_gvalue: Return location pointing to a zero-filled (uninitialized) #GValue.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
- * Since: 2.26
+ * 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.
+ * The conversion never fails - a valid #GValue is always returned in
+ *
+ * Since: 2.30
*/
/**
- * g_dbus_connection_close_sync:
- * @connection: A #GDBusConnection.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_get_info:
+ * @interface_: An exported D-Bus interface.
*
- * Synchronously closees @connection. The calling thread is blocked
- * until this is done. See g_dbus_connection_close() for the
- * asynchronous version of this method and more details about what it
- * does.
+ * Gets D-Bus introspection information for the D-Bus interface
+ * implemented by @interface_.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_emit_signal:
- * @connection: A #GDBusConnection.
- * @destination_bus_name: The unique bus name for the destination for the signal or %NULL to emit to all listeners.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to emit a signal on.
- * @signal_name: The name of the signal to emit.
- * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_get_object:
+ * @interface_: An exported D-Bus interface.
*
- * 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.
+ * Gets the #GDBusObject that @interface_ belongs to, if any.
+ * reference belongs to @interface_ and should not be freed.
+ *
+ * Returns: (transfer none): A #GDBusObject or %NULL. The returned
+ * Since: 2.30
+ */
+
+
+/**
+ * g_dbus_interface_info_cache_build:
+ * @info: A #GDBusInterfaceInfo.
+ *
+ * Builds a lookup-cache to speed up
+ * g_dbus_interface_info_lookup_method(),
+ * g_dbus_interface_info_lookup_signal() and
+ * g_dbus_interface_info_lookup_property().
+ * If this has already been called with @info, the existing cache is
+ * used and its use count is increased.
+ * Note that @info cannot be modified until
+ * g_dbus_interface_info_cache_release() is called.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_dbus_interface_info_cache_release:
+ * @info: A GDBusInterfaceInfo
+ *
+ * Decrements the usage count for the cache for @info built by
+ * g_dbus_interface_info_cache_build() (if any) and frees the
+ * resources used by the cache if the usage count drops to zero.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_dbus_interface_info_generate_xml:
+ * @info: A #GDBusNodeInfo
+ * @indent: Indentation level.
+ * @string_builder: A #GString to to append XML data to.
+ *
+ * Appends an XML representation of @info (and its children) to @string_builder.
+ * This function is typically used for generating introspection XML
+ * documents at run-time for handling the
+ * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
+ * method.
*
- * Returns: %TRUE unless @error is set.
* Since: 2.26
*/
/**
- * g_dbus_connection_flush:
- * @connection: A #GDBusConnection.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
- * @user_data: The data to pass to @callback.
+ * g_dbus_interface_info_lookup_method:
+ * @info: A #GDBusInterfaceInfo.
+ * @name: A D-Bus method name (typically in CamelCase)
*
- * Asynchronously flushes @connection, that is, writes all queued
- * outgoing message to the transport and then flushes the transport
- * (using g_output_stream_flush_async()). This is useful in programs
- * that wants to emit a D-Bus signal and then exit
- * immediately. Without flushing the connection, there is no guarantee
- * that the message has been sent to the networking buffers in the OS
- * kernel.
- * This is an asynchronous method. When the operation is finished,
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this method from. You can
- * then call g_dbus_connection_flush_finish() to get the result of the
- * operation. See g_dbus_connection_flush_sync() for the synchronous
- * version.
+ * Looks up information about a method.
+ * This cost of this function is O(n) in number of methods unless
+ * g_dbus_interface_info_cache_build() has been used on @info.
*
+ * Returns: A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
/**
- * g_dbus_connection_flush_finish:
- * @connection: A #GDBusConnection.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush().
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_info_lookup_property:
+ * @info: A #GDBusInterfaceInfo.
+ * @name: A D-Bus property name (typically in CamelCase).
*
- * Finishes an operation started with g_dbus_connection_flush().
+ * Looks up information about a property.
+ * This cost of this function is O(n) in number of properties unless
+ * g_dbus_interface_info_cache_build() has been used on @info.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
/**
- * g_dbus_connection_flush_sync:
- * @connection: A #GDBusConnection.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_info_lookup_signal:
+ * @info: A #GDBusInterfaceInfo.
+ * @name: A D-Bus signal name (typically in CamelCase)
*
- * 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.
+ * Looks up information about a signal.
+ * This cost of this function is O(n) in number of signals unless
+ * g_dbus_interface_info_cache_build() has been used on @info.
*
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
/**
- * g_dbus_connection_get_capabilities:
- * @connection: A #GDBusConnection.
+ * g_dbus_interface_info_ref:
+ * @info: A #GDBusInterfaceInfo
*
- * Gets the capabilities negotiated with the remote peer
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
+ * Returns: The same @info.
* Since: 2.26
*/
/**
- * g_dbus_connection_get_exit_on_close:
- * @connection: A #GDBusConnection.
+ * g_dbus_interface_info_unref:
+ * @info: A #GDBusInterfaceInfo.
*
- * Gets whether the process is terminated when @connection is
- * closed by the remote peer. See
- * #GDBusConnection:exit-on-close for more details.
- * closed by the remote peer.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: Whether the process is terminated when @connection is
* Since: 2.26
*/
/**
- * g_dbus_connection_get_guid:
- * @connection: A #GDBusConnection.
+ * g_dbus_interface_set_object:
+ * @interface_: An exported D-Bus interface.
+ * @object: A #GDBusObject or %NULL.
*
- * The GUID of the peer performing the role of server when
- * authenticating. See #GDBusConnection:guid for more details.
+ * Sets the #GDBusObject for @interface_ to @object.
+ * Note that @interface_ will hold a weak reference to @object.
*
- * Returns: The GUID. Do not free this string, it is owned by
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_peer_credentials:
- * @connection: A #GDBusConnection.
+ * g_dbus_interface_skeleton_export:
+ * @interface_: The D-Bus interface to export.
+ * @connection: A #GDBusConnection to export @interface_ on.
+ * @object_path: The path to export the interface at.
+ * @error: Return location for error or %NULL.
*
- * 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.
- * this object, it is owned by @connection.
+ * Exports @interface_ at @object_path on @connection.
+ * Use g_dbus_interface_skeleton_unexport() to unexport the object.
*
- * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
- * Since: 2.26
+ * Returns: %TRUE if the interface was exported, other %FALSE with
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_stream:
- * @connection: a #GDBusConnection
+ * g_dbus_interface_skeleton_flush:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Gets the underlying stream used for IO.
+ * 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
+ * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
+ * signal later (e.g. in an idle handler). This technique is useful
+ * for collapsing multiple property changes into one.
*
- * Returns: (transfer none): the stream used for IO
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_get_unique_name:
- * @connection: A #GDBusConnection.
+ * g_dbus_interface_skeleton_get_connection:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * 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.
- * bus connection. Do not free this string, it is owned by
+ * Gets the connection that @interface_ is exported on, if any.
+ * not exported anywhere. Do not free, the object belongs to @interface_.
*
- * Returns: The unique name or %NULL if @connection is not a message
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
+ * Since: 2.30
*/
/**
- * g_dbus_connection_is_closed:
- * @connection: A #GDBusConnection.
+ * g_dbus_interface_skeleton_get_flags:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Gets whether @connection is closed.
+ * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
+ * of @interface_
*
- * Returns: %TRUE if the connection is closed, %FALSE otherwise.
- * Since: 2.26
+ * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_new:
- * @stream: A #GIOStream.
- * @guid: The GUID to use if a authenticating as a server or %NULL.
- * @flags: Flags describing how to make the connection.
- * @observer: A #GDBusAuthObserver or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * g_dbus_interface_skeleton_get_info:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
- * with the end represented by @stream.
- * If @observer is not %NULL it may be used to control the
- * authentication process.
- * When the operation is finished, @callback will be invoked. You can
- * then call g_dbus_connection_new_finish() to get the result of the
- * operation.
- * This is a asynchronous failable constructor. See
- * g_dbus_connection_new_sync() for the synchronous
- * version.
+ * Gets D-Bus introspection information for the D-Bus interface
+ * implemented by @interface_.
*
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
+ * Since: 2.30
*/
/**
- * g_dbus_connection_new_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_skeleton_get_object_path:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Finishes an operation started with g_dbus_connection_new().
+ * Gets the object path that @interface_ is exported on, if any.
+ * anywhere. Do not free, the string belongs to @interface_.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
+ * Since: 2.30
*/
/**
- * g_dbus_connection_new_for_address:
- * @address: A D-Bus address.
- * @flags: Flags describing how to make the connection.
- * @observer: A #GDBusAuthObserver or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * g_dbus_interface_skeleton_get_properties:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Asynchronously connects and sets up a D-Bus client connection for
- * exchanging D-Bus messages with an endpoint specified by @address
- * which must be in the D-Bus address format.
- * This constructor can only be used to initiate client-side
- * connections - use g_dbus_connection_new() if you need to act as the
- * server. In particular, @flags cannot contain the
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
- * When the operation is finished, @callback will be invoked. You can
- * then call g_dbus_connection_new_finish() to get the result of the
- * operation.
- * If @observer is not %NULL it may be used to control the
- * authentication process.
- * This is a asynchronous failable constructor. See
- * g_dbus_connection_new_for_address_sync() for the synchronous
- * version.
+ * Gets all D-Bus properties for @interface_.
*
- * Since: 2.26
+ * Returns: A new, floating, #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_connection_new_for_address_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_skeleton_get_vtable: (skip)
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Finishes an operation started with g_dbus_connection_new_for_address().
+ * Gets the interface vtable for the D-Bus interface implemented by
+ * itself to be passed as @user_data.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Returns: A #GDBusInterfaceVTable (never %NULL).
+ * Since: 2.30
*/
/**
- * g_dbus_connection_new_for_address_sync:
- * @address: A D-Bus address.
- * @flags: Flags describing how to make the connection.
- * @observer: A #GDBusAuthObserver or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_skeleton_set_flags:
+ * @interface_: A #GDBusInterfaceSkeleton.
+ * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
*
- * 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.
- * This constructor can only be used to initiate client-side
- * connections - use g_dbus_connection_new_sync() if you need to act
- * as the server. In particular, @flags cannot contain the
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
- * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
- * This is a synchronous failable constructor. See
- * g_dbus_connection_new_for_address() for the asynchronous version.
- * If @observer is not %NULL it may be used to control the
- * authentication process.
+ * Sets flags describing what the behavior of @skeleton should be.
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_new_sync:
- * @stream: A #GIOStream.
- * @guid: The GUID to use if a authenticating as a server or %NULL.
- * @flags: Flags describing how to make the connection.
- * @observer: A #GDBusAuthObserver or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_interface_skeleton_unexport:
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
- * with the end represented by @stream.
- * 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.
+ * Stops exporting an interface previously exported with
+ * g_dbus_interface_skeleton_export().
*
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_connection_register_object:
- * @connection: A #GDBusConnection.
- * @object_path: The object path to register at.
- * @interface_info: Introspection data for the interface.
- * @vtable: A #GDBusInterfaceVTable to call into or %NULL.
- * @user_data: Data to pass to functions in @vtable.
- * @user_data_free_func: Function to call when the object path is unregistered.
- * @error: Return location for error or %NULL.
+ * g_dbus_is_address:
+ * @string: A string.
*
- * Registers callbacks for exported objects at @object_path with the
- * D-Bus interface that is described in @interface_info.
- * Calls to functions in @vtable (and @user_data_free_func) will
- * happen in the <link linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this method from.
- * Note that all #GVariant values passed to functions in @vtable will match
- * the signature given in @interface_info - if a remote caller passes
- * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
- * is returned to the remote caller.
- * Additionally, if the remote caller attempts to invoke methods or
- * access properties not mentioned in @interface_info the
- * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
- * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
- * are returned to the caller.
- * It is considered a programming error if the
- * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
- * #GVariant of incorrect type.
- * If an existing callback is already registered at @object_path and
- * GDBus automatically implements the standard D-Bus interfaces
- * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
- * and org.freedesktop.Peer, so you don't have to implement those for
- * the objects you export. You <emphasis>can</emphasis> implement
- * org.freedesktop.DBus.Properties yourself, e.g. to handle getting
- * and setting of properties asynchronously.
- * Note that the reference count on @interface_info will be
- * incremented by 1 (unless allocated statically, e.g. if the
- * reference count is -1, see g_dbus_interface_info_ref()) for as long
- * as the object is exported. Also note that @vtable will be copied.
- * See <xref linkend="gdbus-server"/> for an example of how to use this method.
- * that can be used with g_dbus_connection_unregister_object() .
+ * Checks if @string is a D-Bus address.
+ * This doesn't check if @string is actually supported by #GDBusServer
+ * or #GDBusConnection - use g_dbus_is_supported_address() to do more
+ * checks.
*
- * Returns: 0 if @error is set, otherwise a registration id (never 0)
+ * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_register_subtree:
- * @connection: A #GDBusConnection.
- * @object_path: The object path to register the subtree at.
- * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
- * @flags: Flags used to fine tune the behavior of the subtree.
- * @user_data: Data to pass to functions in @vtable.
- * @user_data_free_func: Function to call when the subtree is unregistered.
- * @error: Return location for error or %NULL.
+ * g_dbus_is_guid:
+ * @string: The string to check.
*
- * Registers a whole subtree of <quote>dynamic</quote> objects.
- * The @enumerate and @introspection functions in @vtable are used to
- * convey, to remote callers, what nodes exist in the subtree rooted
- * by @object_path.
- * When handling remote calls into any node in the subtree, first the
- * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
- * the @introspection function is used to check if the node supports the
- * requested method. If so, the @dispatch function is used to determine
- * where to dispatch the call. The collected #GDBusInterfaceVTable and
- * #gpointer will be used to call into the interface vtable for processing
- * the request.
- * All calls into user-provided code will be invoked in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this method from.
- * If an existing subtree is already registered at @object_path or
- * then @error is set to #G_IO_ERROR_EXISTS.
- * Note that it is valid to register regular objects (using
- * g_dbus_connection_register_object()) in a subtree registered with
- * g_dbus_connection_register_subtree() - if so, the subtree handler
- * is tried as the last resort. One way to think about a subtree
- * handler is to consider it a <quote>fallback handler</quote>
- * for object paths not registered via g_dbus_connection_register_object()
- * or other bindings.
- * Note that @vtable will be copied so you cannot change it after
- * registration.
- * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
- * that can be used with g_dbus_connection_unregister_subtree() .
+ * Checks if @string is a D-Bus GUID.
+ * See the D-Bus specification regarding what strings are valid D-Bus
+ * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
*
- * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
+ * Returns: %TRUE if @string is a guid, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_remove_filter:
- * @connection: a #GDBusConnection
- * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
+ * g_dbus_is_interface_name:
+ * @string: The string to check.
*
- * Removes a filter.
+ * Checks if @string is a valid D-Bus interface name.
*
+ * Returns: %TRUE if valid, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_send_message:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage
- * @flags: Flags affecting how the message is sent.
- * @out_serial: Return location for serial number assigned to @message when sending it or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_is_member_name:
+ * @string: The string to check.
*
- * Asynchronously sends @message to the peer represented by @connection.
- * Unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
- * will be assigned by @connection and set on @message via
- * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
- * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @message is not well-formed,
- * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
- * See <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> for an example of how to use this
- * low-level API to send and receive UNIX file descriptors.
- * Note that @message must be unlocked, unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
- * transmission, %FALSE if @error is set.
+ * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
*
- * Returns: %TRUE if the message was well-formed and queued for
+ * Returns: %TRUE if valid, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_send_message_with_reply:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage.
- * @flags: Flags affecting how the message is sent.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
- * @out_serial: Return location for serial number assigned to @message when sending it or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
- * @user_data: The data to pass to @callback.
+ * g_dbus_is_name:
+ * @string: The string to check.
*
- * Asynchronously sends @message to the peer represented by @connection.
- * Unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
- * will be assigned by @connection and set on @message via
- * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
- * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
- * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
- * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
- * This is an asynchronous method. When the operation is finished, @callback will be invoked
- * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
- * of the thread you are calling this method from. You can then call
- * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
- * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
- * Note that @message must be unlocked, unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
- * See <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> for an example of how to use this
- * low-level API to send and receive UNIX file descriptors.
+ * Checks if @string is a valid D-Bus bus name (either unique or well-known).
*
+ * Returns: %TRUE if valid, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_send_message_with_reply_finish:
- * @connection: a #GDBusConnection
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
+ * g_dbus_is_supported_address:
+ * @string: A string.
* @error: Return location for error or %NULL.
*
- * Finishes an operation started with g_dbus_connection_send_message_with_reply().
- * Note that @error is only set if a local in-process error
- * occured. 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> for an example of how to use this
- * low-level API to send and receive UNIX file descriptors.
+ * Like g_dbus_is_address() but also checks if the library suppors the
+ * transports in @string and that key/value pairs for each transport
+ * are valid.
+ * supported by this library, %FALSE if @error is set.
*
- * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
+ * Returns: %TRUE if @string is a valid D-Bus address that is
* Since: 2.26
*/
/**
- * g_dbus_connection_send_message_with_reply_sync:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage.
- * @flags: Flags affecting how the message is sent.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
- * @out_serial: Return location for serial number assigned to @message when sending it or %NULL.
- * @cancellable: A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * g_dbus_is_unique_name:
+ * @string: The string to check.
*
- * Synchronously sends @message to the peer represented by @connection
- * and blocks the calling thread until a reply is received or the
- * timeout is reached. See g_dbus_connection_send_message_with_reply()
- * for the asynchronous version of this method.
- * Unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
- * will be assigned by @connection and set on @message via
- * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
- * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
- * If @connection is closed then the operation will fail with
- * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
- * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
- * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
- * Note that @error is only set if a local in-process error
- * occured. 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> for an example of how to use this
- * low-level API to send and receive UNIX file descriptors.
- * Note that @message must be unlocked, unless @flags contain the
- * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ * Checks if @string is a valid D-Bus unique bus name.
*
- * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
+ * Returns: %TRUE if valid, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_connection_set_exit_on_close:
- * @connection: A #GDBusConnection.
- * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer.
+ * g_dbus_message_bytes_needed:
+ * @blob: A blob represent a binary D-Bus message.
+ * @blob_len: The length of @blob (must be at least 16).
+ * @error: Return location for error or %NULL.
*
- * Sets whether the process should be terminated when @connection is
- * closed by the remote peer. See #GDBusConnection:exit-on-close for
- * more details.
+ * Utility function to calculate how many bytes are needed to
+ * completely deserialize the D-Bus message stored at @blob.
+ * determine the size).
*
+ * Returns: Number of bytes needed or -1 if @error is set (e.g. if
* Since: 2.26
*/
/**
- * g_dbus_connection_signal_subscribe:
- * @connection: A #GDBusConnection.
- * @sender: Sender name to match on (unique or well-known name) or %NULL to listen from all senders.
- * @interface_name: D-Bus interface name to match on or %NULL to match on all interfaces.
- * @member: D-Bus signal name to match on or %NULL to match on all signals.
- * @object_path: Object path to match on or %NULL to match on all object paths.
- * @arg0: Contents of first string argument to match on or %NULL to match on all kinds of arguments.
- * @flags: Flags describing how to subscribe to the signal (currently unused).
- * @callback: Callback to invoke when there is a signal matching the requested data.
- * @user_data: User data to pass to @callback.
- * @user_data_free_func: Function to free @user_data with when subscription is removed or %NULL.
+ * g_dbus_message_copy:
+ * @message: A #GDBusMessage.
+ * @error: Return location for error or %NULL.
*
- * Subscribes to signals on @connection and invokes @callback with a
- * whenever the signal is received. Note that @callback
- * will be invoked in the <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> of the thread you are calling this method from.
- * If @connection is not a message bus connection, @sender must be
- * %NULL.
- * 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.
+ * 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.
+ * Free with g_object_unref().
*
- * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
+ * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
* Since: 2.26
*/
/**
- * g_dbus_connection_signal_unsubscribe:
- * @connection: A #GDBusConnection.
- * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
+ * g_dbus_message_get_arg0:
+ * @message: A #GDBusMessage.
*
- * Unsubscribes from signals.
+ * Convenience to get the first item in the body of @message.
*
+ * Returns: The string item or %NULL if the first item in the body of
* Since: 2.26
*/
/**
- * g_dbus_connection_start_message_processing:
- * @connection: A #GDBusConnection.
+ * g_dbus_message_get_body:
+ * @message: A #GDBusMessage.
*
- * If @connection was created with
- * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
- * starts processing messages. Does nothing on if @connection wasn't
- * created with this flag or if the method has already been called.
+ * Gets the body of a message.
*
+ * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
* Since: 2.26
*/
/**
- * g_dbus_connection_unregister_object:
- * @connection: A #GDBusConnection.
- * @registration_id: A registration id obtained from g_dbus_connection_register_object().
+ * g_dbus_message_get_byte_order:
+ * @message: A #GDBusMessage.
*
- * Unregisters an object.
+ * Gets the byte order of @message.
*
- * Returns: %TRUE if the object was unregistered, %FALSE otherwise.
- * Since: 2.26
+ * Returns: The byte order.
*/
/**
- * g_dbus_connection_unregister_subtree:
- * @connection: A #GDBusConnection.
- * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree().
+ * g_dbus_message_get_destination:
+ * @message: A #GDBusMessage.
*
- * Unregisters a subtree.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
*
- * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_error_encode_gerror:
- * @error: A #GError.
+ * g_dbus_message_get_error_name:
+ * @message: A #GDBusMessage.
*
- * Creates a D-Bus error name to use for @error. If @error matches
- * a registered error (cf. g_dbus_error_register_error()), the corresponding
- * D-Bus error name will be returned.
- * Otherwise the a name of the form
- * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
- * will be used. This allows other GDBus applications to map the error
- * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
- * This function is typically only used in object mappings to put a
- * #GError on the wire. Regular applications should not use it.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
*
- * Returns: A D-Bus error name (never %NULL). Free with g_free().
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_error_get_remote_error:
- * @error: A #GError.
+ * g_dbus_message_get_flags:
+ * @message: A #GDBusMessage.
*
- * Gets the D-Bus error name used for @error, if any.
- * This function is guaranteed to return a D-Bus error name for all
- * #GError<!-- -->s returned from functions handling remote method
- * calls (e.g. g_dbus_connection_call_finish()) unless
- * g_dbus_error_strip_remote_error() has been used on @error.
+ * Gets the flags for @message.
*
- * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
+ * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
* Since: 2.26
*/
/**
- * g_dbus_error_is_remote_error:
- * @error: A #GError.
+ * g_dbus_message_get_header:
+ * @message: A #GDBusMessage.
+ * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
*
- * 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.
- * %FALSE otherwise.
+ * Gets a header field on @message.
+ * otherwise. Do not free, it is owned by @message.
*
- * Returns: %TRUE if @error represents an error from a remote peer,
+ * Returns: A #GVariant with the value if the header was found, %NULL
* Since: 2.26
*/
/**
- * g_dbus_error_new_for_dbus_error:
- * @dbus_error_name: D-Bus error name.
- * @dbus_error_message: D-Bus error message.
+ * g_dbus_message_get_header_fields:
+ * @message: A #GDBusMessage.
*
- * Creates a #GError based on the contents of @dbus_error_name and
- * 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.
+ * Gets an array of all header fields on @message that are set.
+ * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a
+ * #guchar. Free with g_free().
*
- * Returns: An allocated #GError. Free with g_error_free().
+ * Returns: An array of header fields terminated by
* Since: 2.26
*/
/**
- * g_dbus_error_register_error:
- * @error_domain: A #GQuark for a error domain.
- * @error_code: An error code.
- * @dbus_error_name: A D-Bus error name.
+ * g_dbus_message_get_interface:
+ * @message: A #GDBusMessage.
*
- * Creates an association to map between @dbus_error_name and
- * #GError<!-- -->s specified by @error_domain and @error_code.
- * This is typically done in the routine that returns the #GQuark for
- * an error domain.
- * exists.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
*
- * Returns: %TRUE if the association was created, %FALSE if it already
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_error_register_error_domain:
- * @error_domain_quark_name: The error domain name.
- * @quark_volatile: A pointer where to store the #GQuark.
- * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
- * @num_entries: Number of items to register.
+ * g_dbus_message_get_locked:
+ * @message: A #GDBusMessage.
*
- * Helper function for associating a #GError error domain with D-Bus error names.
+ * Checks whether @message is locked. To monitor changes to this
+ * value, conncet to the #GObject::notify signal to listen for changes
+ * on the #GDBusMessage:locked property.
*
+ * Returns: %TRUE if @message is locked, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_error_set_dbus_error:
- * @error: A pointer to a #GError or %NULL.
- * @dbus_error_name: D-Bus error name.
- * @dbus_error_message: D-Bus error message.
- * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
- * @...: Arguments for @format.
+ * g_dbus_message_get_member:
+ * @message: A #GDBusMessage.
*
- * 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).
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
*
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_error_set_dbus_error_valist:
- * @error: A pointer to a #GError or %NULL.
- * @dbus_error_name: D-Bus error name.
- * @dbus_error_message: D-Bus error message.
- * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
- * @var_args: Arguments for @format.
+ * g_dbus_message_get_message_type:
+ * @message: A #GDBusMessage.
*
- * Like g_dbus_error_set_dbus_error() but intended for language bindings.
+ * Gets the type of @message.
*
+ * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
* Since: 2.26
*/
/**
- * g_dbus_error_strip_remote_error:
- * @error: A #GError.
+ * g_dbus_message_get_num_unix_fds:
+ * @message: A #GDBusMessage.
*
- * 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.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
*
- * Returns: %TRUE if information was stripped, %FALSE otherwise.
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_error_unregister_error:
- * @error_domain: A #GQuark for a error domain.
- * @error_code: An error code.
- * @dbus_error_name: A D-Bus error name.
+ * g_dbus_message_get_path:
+ * @message: A #GDBusMessage.
*
- * Destroys an association previously set up with g_dbus_error_register_error().
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
*
- * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_generate_guid:
+ * g_dbus_message_get_reply_serial:
+ * @message: A #GDBusMessage.
*
- * Generate a D-Bus GUID that can be used with
- * e.g. g_dbus_connection_new().
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
*
- * Returns: A valid D-Bus GUID. Free with g_free().
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_interface_info_cache_build:
- * @info: A #GDBusInterfaceInfo.
+ * g_dbus_message_get_sender:
+ * @message: A #GDBusMessage.
*
- * 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.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
*
- * Since: 2.30
+ * Returns: The value.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_info_cache_release:
- * @info: A GDBusInterfaceInfo
+ * g_dbus_message_get_serial:
+ * @message: A #GDBusMessage.
*
- * 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.
+ * Gets the serial for @message.
*
- * Since: 2.30
+ * Returns: A #guint32.
+ * Since: 2.26
*/
/**
- * g_dbus_interface_info_generate_xml:
- * @info: A #GDBusNodeInfo
- * @indent: Indentation level.
- * @string_builder: A #GString to to append XML data to.
+ * g_dbus_message_get_signature:
+ * @message: A #GDBusMessage.
*
- * Appends an XML representation of @info (and its children) to @string_builder.
- * This function is typically used for generating introspection XML
- * documents at run-time for handling the
- * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
- * method.
+ * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
*
+ * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_interface_info_lookup_method:
- * @info: A #GDBusInterfaceInfo.
- * @name: A D-Bus method name (typically in CamelCase)
+ * g_dbus_message_get_unix_fd_list:
+ * @message: A #GDBusMessage.
*
- * Looks up information about a method.
- * This cost of this function is O(n) in number of methods unless
- * g_dbus_interface_info_cache_build() has been used on @info.
+ * Gets the UNIX file descriptors associated with @message, if any.
+ * This method is only available on UNIX.
+ * associated. Do not free, this object is owned by @message.
*
- * Returns: A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
* Since: 2.26
*/
/**
- * g_dbus_interface_info_lookup_property:
- * @info: A #GDBusInterfaceInfo.
- * @name: A D-Bus property name (typically in CamelCase).
+ * g_dbus_message_lock:
+ * @message: A #GDBusMessage.
*
- * Looks up information about a property.
- * This cost of this function is O(n) in number of properties unless
- * g_dbus_interface_info_cache_build() has been used on @info.
+ * If @message is locked, does nothing. Otherwise locks the message.
*
- * Returns: A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
/**
- * g_dbus_interface_info_lookup_signal:
- * @info: A #GDBusInterfaceInfo.
- * @name: A D-Bus signal name (typically in CamelCase)
+ * g_dbus_message_new:
*
- * Looks up information about a signal.
- * This cost of this function is O(n) in number of signals unless
- * g_dbus_interface_info_cache_build() has been used on @info.
+ * Creates a new empty #GDBusMessage.
*
- * Returns: A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Returns: A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_interface_info_ref:
- * @info: A #GDBusInterfaceInfo
+ * g_dbus_message_new_from_blob:
+ * @blob: A blob represent a binary D-Bus message.
+ * @blob_len: The length of @blob.
+ * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
+ * @error: Return location for error or %NULL.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Creates a new #GDBusMessage from the data stored at @blob. The byte
+ * order that the message was in can be retrieved using
+ * g_dbus_message_get_byte_order().
+ * g_object_unref().
*
- * Returns: The same @info.
+ * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
* Since: 2.26
*/
/**
- * g_dbus_interface_info_unref:
- * @info: A #GDBusInterfaceInfo.
+ * g_dbus_message_new_method_call:
+ * @name: A valid D-Bus name or %NULL.
+ * @path: A valid object path.
+ * @interface_: A valid D-Bus interface name or %NULL.
+ * @method: A valid method name.
*
- * If @info is statically allocated, does nothing. Otherwise decreases
- * the reference count of @info. When its reference count drops to 0,
- * the memory used is freed.
+ * Creates a new #GDBusMessage for a method call.
*
+ * Returns: A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_is_address:
- * @string: A string.
+ * g_dbus_message_new_method_error:
+ * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
+ * @error_name: A valid D-Bus error name.
+ * @error_message_format: The D-Bus error message in a printf() format.
+ * @...: Arguments for @error_message_format.
*
- * Checks if @string is a D-Bus address.
- * This doesn't check if @string is actually supported by #GDBusServer
- * or #GDBusConnection - use g_dbus_is_supported_address() to do more
- * checks.
+ * Creates a new #GDBusMessage that is an error reply to @method_call_message.
*
- * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
+ * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_is_guid:
- * @string: The string to check.
+ * g_dbus_message_new_method_error_literal:
+ * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
+ * @error_name: A valid D-Bus error name.
+ * @error_message: The D-Bus error message.
*
- * Checks if @string is a D-Bus GUID.
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * Creates a new #GDBusMessage that is an error reply to @method_call_message.
*
- * Returns: %TRUE if @string is a guid, %FALSE otherwise.
+ * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_is_interface_name:
- * @string: The string to check.
+ * g_dbus_message_new_method_error_valist:
+ * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
+ * @error_name: A valid D-Bus error name.
+ * @error_message_format: The D-Bus error message in a printf() format.
+ * @var_args: Arguments for @error_message_format.
*
- * Checks if @string is a valid D-Bus interface name.
+ * Like g_dbus_message_new_method_error() but intended for language bindings.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
+ * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_is_member_name:
- * @string: The string to check.
+ * g_dbus_message_new_method_reply:
+ * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
*
- * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
+ * Creates a new #GDBusMessage that is a reply to @method_call_message.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
+ * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_is_name:
- * @string: The string to check.
+ * g_dbus_message_new_signal:
+ * @path: A valid object path.
+ * @interface_: A valid D-Bus interface name.
+ * @signal: A valid signal name.
*
- * Checks if @string is a valid D-Bus bus name (either unique or well-known).
+ * Creates a new #GDBusMessage for a signal emission.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
+ * Returns: A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_is_supported_address:
- * @string: A string.
- * @error: Return location for error or %NULL.
+ * g_dbus_message_print:
+ * @message: A #GDBusMessage.
+ * @indent: Indentation level.
*
- * Like g_dbus_is_address() but also checks if the library suppors the
- * transports in @string and that key/value pairs for each transport
- * are valid.
- * supported by this library, %FALSE if @error is set.
+ * 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:
+ * <programlisting>
+ * Headers:
+ * path -> objectpath '/org/gtk/GDBus/TestObject'
+ * interface -> 'org.gtk.GDBus.TestInterface'
+ * member -> 'GimmeStdout'
+ * destination -> ':1.146'
+ * UNIX File Descriptors:
+ * (none)
+ * </programlisting>
+ * or
+ * <programlisting>
+ * Headers:
+ * reply-serial -> uint32 4
+ * destination -> ':1.159'
+ * sender -> ':1.146'
+ * num-unix-fds -> uint32 1
+ * UNIX File Descriptors:
+ * </programlisting>
*
- * Returns: %TRUE if @string is a valid D-Bus address that is
+ * Type: method-return
+ * Flags: no-reply-expected
+ * Version: 0
+ * Serial: 477
+ * Body: ()
+ * Fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
+ * Returns: A string that should be freed with g_free().
* Since: 2.26
*/
/**
- * g_dbus_is_unique_name:
- * @string: The string to check.
+ * g_dbus_message_set_body:
+ * @message: A #GDBusMessage.
+ * @body: Either %NULL or a #GVariant that is a tuple.
*
- * Checks if @string is a valid D-Bus unique bus name.
+ * Sets the body @message. As a side-effect the
+ * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
+ * type string of @body (or cleared if @body is %NULL).
+ * If @body is floating, @message assumes ownership of @body.
*
- * Returns: %TRUE if valid, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_message_bytes_needed:
- * @blob: A blob represent a binary D-Bus message.
- * @blob_len: The length of @blob (must be at least 16).
- * @error: Return location for error or %NULL.
+ * g_dbus_message_set_byte_order:
+ * @message: A #GDBusMessage.
+ * @byte_order: The byte order.
*
- * Utility function to calculate how many bytes are needed to
- * completely deserialize the D-Bus message stored at @blob.
- * determine the size).
+ * Sets the byte order of @message.
+ */
+
+
+/**
+ * g_dbus_message_set_destination:
+ * @message: A #GDBusMessage.
+ * @value: The value to set.
+ *
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
*
- * Returns: Number of bytes needed or -1 if @error is set (e.g. if
* Since: 2.26
*/
/**
- * g_dbus_message_copy:
+ * g_dbus_message_set_error_name:
* @message: A #GDBusMessage.
- * @error: Return location for error or %NULL.
+ * @value: The value to set.
*
- * 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.
- * g_object_unref().
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
*
- * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with
* Since: 2.26
*/
/**
- * g_dbus_message_get_arg0:
+ * g_dbus_message_set_flags:
* @message: A #GDBusMessage.
+ * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
*
- * Convenience to get the first item in the body of @message.
+ * Sets the flags to set on @message.
*
- * Returns: The string item or %NULL if the first item in the body of
* Since: 2.26
*/
/**
- * g_dbus_message_get_body:
+ * g_dbus_message_set_header:
* @message: A #GDBusMessage.
+ * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+ * @value: A #GVariant to set the header field or %NULL to clear the header field.
*
- * Gets the body of a message.
+ * Sets a header field on @message.
+ * If @value is floating, @message assumes ownership of @value.
*
- * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
* Since: 2.26
*/
/**
- * g_dbus_message_get_byte_order:
+ * g_dbus_message_set_interface:
* @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Gets the byte order of @message.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
*
- * Returns: The byte order.
+ * Since: 2.26
*/
/**
- * g_dbus_message_get_destination:
+ * g_dbus_message_set_member:
* @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
*
- * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_message_get_error_name:
+ * g_dbus_message_set_message_type:
* @message: A #GDBusMessage.
+ * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+ * Sets @message to be of @type.
*
- * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_message_get_flags:
+ * g_dbus_message_set_num_unix_fds:
* @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Gets the flags for @message.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
*
- * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
* Since: 2.26
*/
/**
- * g_dbus_message_get_header:
+ * g_dbus_message_set_path:
* @message: A #GDBusMessage.
- * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
+ * @value: The value to set.
*
- * Gets a header field on @message.
- * otherwise. Do not free, it is owned by @message.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
*
- * Returns: A #GVariant with the value if the header was found, %NULL
* Since: 2.26
*/
/**
- * g_dbus_message_get_header_fields:
+ * g_dbus_message_set_reply_serial:
* @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Gets an array of all header fields on @message that are set.
- * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a
- * #guchar. Free with g_free().
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
*
- * Returns: An array of header fields terminated by
* Since: 2.26
*/
/**
- * g_dbus_message_get_interface:
+ * g_dbus_message_set_sender:
* @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
*
- * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_message_get_locked:
+ * g_dbus_message_set_serial:
* @message: A #GDBusMessage.
+ * @serial: A #guint32.
*
- * Checks whether @message is locked. To monitor changes to this
- * value, conncet to the #GObject::notify signal to listen for changes
- * on the #GDBusMessage:locked property.
+ * Sets the serial for @message.
*
- * Returns: %TRUE if @message is locked, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_message_get_member:
+ * g_dbus_message_set_signature:
* @message: A #GDBusMessage.
+ * @value: The value to set.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+ * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
*
- * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_message_get_message_type:
+ * g_dbus_message_set_unix_fd_list:
* @message: A #GDBusMessage.
+ * @fd_list: (allow-none): A #GUnixFDList or %NULL.
*
- * Gets the type of @message.
+ * 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
+ * This method is only available on UNIX.
*
- * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
* Since: 2.26
*/
/**
- * g_dbus_message_get_num_unix_fds:
+ * g_dbus_message_to_blob:
* @message: A #GDBusMessage.
+ * @out_size: Return location for size of generated blob.
+ * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
+ * @error: Return location for error.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+ * Serializes @message to a blob. The byte order returned by
+ * g_dbus_message_get_byte_order() will be used.
+ * generated by @message or %NULL if @error is set. Free with g_free().
*
- * Returns: The value.
+ * Returns: A pointer to a valid binary D-Bus message of @out_size bytes
* Since: 2.26
*/
/**
- * g_dbus_message_get_path:
+ * g_dbus_message_to_gerror:
* @message: A #GDBusMessage.
+ * @error: The #GError to set.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+ * 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.
*
- * Returns: The value.
+ * Returns: %TRUE if @error was set, %FALSE otherwise.
* Since: 2.26
*/
/**
- * g_dbus_message_get_reply_serial:
- * @message: A #GDBusMessage.
+ * g_dbus_method_info_ref:
+ * @info: A #GDBusMethodInfo
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
- * Returns: The value.
+ * Returns: The same @info.
* Since: 2.26
*/
/**
- * g_dbus_message_get_sender:
- * @message: A #GDBusMessage.
+ * g_dbus_method_info_unref:
+ * @info: A #GDBusMethodInfo.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
- * Returns: The value.
* Since: 2.26
*/
/**
- * g_dbus_message_get_serial:
- * @message: A #GDBusMessage.
+ * g_dbus_method_invocation_get_connection:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Gets the serial for @message.
+ * Gets the #GDBusConnection the method was invoked on.
*
- * Returns: A #guint32.
+ * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_get_signature:
- * @message: A #GDBusMessage.
+ * g_dbus_method_invocation_get_interface_name:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+ * Gets the name of the D-Bus interface the method was invoked on.
*
- * Returns: The value.
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_get_unix_fd_list:
- * @message: A #GDBusMessage.
+ * g_dbus_method_invocation_get_message:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Gets the UNIX file descriptors associated with @message, if any.
- * This method is only available on UNIX.
- * associated. Do not free, this object is owned by @message.
+ * 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 <xref linkend="gdbus-server"/> and <xref
+ * linkend="gdbus-unix-fd-client"/> for an example of how to use this
+ * low-level API to send and receive UNIX file descriptors.
*
- * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
+ * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_lock:
- * @message: A #GDBusMessage.
+ * g_dbus_method_invocation_get_method_info:
+ * @invocation: A #GDBusMethodInvocation.
*
- * If @message is locked, does nothing. Otherwise locks the message.
+ * Gets information about the method call, if any.
*
+ * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_new:
+ * g_dbus_method_invocation_get_method_name:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Creates a new empty #GDBusMessage.
+ * Gets the name of the method that was invoked.
*
- * Returns: A #GDBusMessage. Free with g_object_unref().
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_new_from_blob:
- * @blob: A blob represent a binary D-Bus message.
- * @blob_len: The length of @blob.
- * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
- * @error: Return location for error or %NULL.
+ * g_dbus_method_invocation_get_object_path:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Creates a new #GDBusMessage from the data stored at @blob. The byte
- * order that the message was in can be retrieved using
- * g_dbus_message_get_byte_order().
- * g_object_unref().
+ * Gets the object path the method was invoked on.
*
- * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_new_method_call:
- * @name: A valid D-Bus name or %NULL.
- * @path: A valid object path.
- * @interface_: A valid D-Bus interface name or %NULL.
- * @method: A valid method name.
+ * g_dbus_method_invocation_get_parameters:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Creates a new #GDBusMessage for a method call.
+ * Gets the parameters of the method invocation. If there are no input
+ * parameters then this will return a GVariant with 0 children rather than NULL.
*
- * Returns: A #GDBusMessage. Free with g_object_unref().
+ * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_new_method_error:
- * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
- * @error_name: A valid D-Bus error name.
- * @error_message_format: The D-Bus error message in a printf() format.
- * @...: Arguments for @error_message_format.
+ * g_dbus_method_invocation_get_sender:
+ * @invocation: A #GDBusMethodInvocation.
*
- * Creates a new #GDBusMessage that is an error reply to @method_call_message.
+ * Gets the bus name that invoked the method.
*
- * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
+ * Returns: A string. Do not free, it is owned by @invocation.
* Since: 2.26
*/
/**
- * g_dbus_message_new_method_error_literal:
- * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
- * @error_name: A valid D-Bus error name.
- * @error_message: The D-Bus error message.
+ * g_dbus_method_invocation_get_user_data: (skip)
+ * @invocation: A #GDBusMethodInvocation.
*
- * Creates a new #GDBusMessage that is an error reply to @method_call_message.
+ * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
*
- * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
+ * Returns: A #gpointer.
* Since: 2.26
*/
/**
- * g_dbus_message_new_method_error_valist:
- * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
+ * g_dbus_method_invocation_return_dbus_error:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
* @error_name: A valid D-Bus error name.
- * @error_message_format: The D-Bus error message in a printf() format.
- * @var_args: Arguments for @error_message_format.
+ * @error_message: A valid D-Bus error message.
*
- * Like g_dbus_message_new_method_error() but intended for language bindings.
+ * Finishes handling a D-Bus method call by returning an error.
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_message_new_method_reply:
- * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
+ * g_dbus_method_invocation_return_error:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @domain: A #GQuark for the #GError error domain.
+ * @code: The error code.
+ * @format: printf()-style format.
+ * @...: Parameters for @format.
*
- * Creates a new #GDBusMessage that is a reply to @method_call_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
+ * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
+ * used. This provides transparent mapping of #GError between
+ * applications using GDBus.
+ * If you are writing an application intended to be portable,
+ * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
+ * or use g_dbus_method_invocation_return_dbus_error().
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_message_new_signal:
- * @path: A valid object path.
- * @interface_: A valid D-Bus interface name.
- * @signal: A valid signal name.
+ * g_dbus_method_invocation_return_error_literal:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @domain: A #GQuark for the #GError error domain.
+ * @code: The error code.
+ * @message: The error message.
*
- * Creates a new #GDBusMessage for a signal emission.
+ * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Returns: A #GDBusMessage. Free with g_object_unref().
* Since: 2.26
*/
/**
- * g_dbus_message_print:
- * @message: A #GDBusMessage.
- * @indent: Indentation level.
+ * g_dbus_method_invocation_return_error_valist:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @domain: A #GQuark for the #GError error domain.
+ * @code: The error code.
+ * @format: printf()-style format.
+ * @var_args: #va_list of parameters for @format.
*
- * 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:
- * <programlisting>
- * Headers:
- * path -> objectpath '/org/gtk/GDBus/TestObject'
- * interface -> 'org.gtk.GDBus.TestInterface'
- * member -> 'GimmeStdout'
- * destination -> ':1.146'
- * UNIX File Descriptors:
- * (none)
- * </programlisting>
- * or
- * <programlisting>
- * Headers:
- * reply-serial -> uint32 4
- * destination -> ':1.159'
- * sender -> ':1.146'
- * num-unix-fds -> uint32 1
- * UNIX File Descriptors:
- * </programlisting>
+ * Like g_dbus_method_invocation_return_error() but intended for
+ * language bindings.
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Type: method-return
- * Flags: no-reply-expected
- * Version: 0
- * Serial: 477
- * Body: ()
- * Fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
- * Returns: A string that should be freed with g_free().
* Since: 2.26
*/
/**
- * g_dbus_message_set_body:
- * @message: A #GDBusMessage.
- * @body: Either %NULL or a #GVariant that is a tuple.
+ * g_dbus_method_invocation_return_gerror:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @error: A #GError.
*
- * 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.
+ * Like g_dbus_method_invocation_return_error() but takes a #GError
+ * instead of the error domain, error code and message.
+ * This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
*/
/**
- * g_dbus_message_set_byte_order:
- * @message: A #GDBusMessage.
- * @byte_order: The byte order.
- *
- * Sets the byte order of @message.
- */
-
-
-/**
- * g_dbus_message_set_destination:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_method_invocation_return_value:
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
+ * Finishes handling a D-Bus method call by returning @parameters.
+ * If the @parameters GVariant is floating, it is consumed.
+ * It is an error if @parameters is not of the right format.
+ * This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
*/
/**
- * g_dbus_message_set_error_name:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_method_invocation_take_error: (skip)
+ * @invocation: (transfer full): A #GDBusMethodInvocation.
+ * @error: (transfer full): A #GError.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
+ * Like g_dbus_method_invocation_return_gerror() but takes ownership
+ * of @error so the caller does not need to free it.
+ * This method will free @invocation, you cannot use it afterwards.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_flags:
- * @message: A #GDBusMessage.
- * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
+ * g_dbus_node_info_generate_xml:
+ * @info: A #GDBusNodeInfo.
+ * @indent: Indentation level.
+ * @string_builder: A #GString to to append XML data to.
*
- * Sets the flags to set on @message.
+ * Appends an XML representation of @info (and its children) to @string_builder.
+ * This function is typically used for generating introspection XML documents at run-time for
+ * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
*
* Since: 2.26
*/
/**
- * g_dbus_message_set_header:
- * @message: A #GDBusMessage.
- * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
- * @value: A #GVariant to set the header field or %NULL to clear the header field.
+ * g_dbus_node_info_lookup_interface:
+ * @info: A #GDBusNodeInfo.
+ * @name: A D-Bus interface name.
*
- * Sets a header field on @message.
- * If @value is floating, @message assumes ownership of @value.
+ * Looks up information about an interface.
+ * This cost of this function is O(n) in number of interfaces.
*
+ * Returns: A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
/**
- * g_dbus_message_set_interface:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_node_info_new_for_xml:
+ * @xml_data: Valid D-Bus introspection XML.
+ * @error: Return location for error.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
+ * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
+ * with g_dbus_node_info_unref().
*
+ * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
* Since: 2.26
*/
/**
- * g_dbus_message_set_member:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_node_info_ref:
+ * @info: A #GDBusNodeInfo
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
+ * If @info is statically allocated does nothing. Otherwise increases
+ * the reference count.
*
+ * Returns: The same @info.
* Since: 2.26
*/
/**
- * g_dbus_message_set_message_type:
- * @message: A #GDBusMessage.
- * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
+ * g_dbus_node_info_unref:
+ * @info: A #GDBusNodeInfo.
*
- * Sets @message to be of @type.
+ * If @info is statically allocated, does nothing. Otherwise decreases
+ * the reference count of @info. When its reference count drops to 0,
+ * the memory used is freed.
*
* Since: 2.26
*/
/**
- * g_dbus_message_set_num_unix_fds:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_object_get_interface:
+ * @object: A #GDBusObject.
+ * @interface_name: A D-Bus interface name.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
+ * Gets the D-Bus interface with name @interface_name associated with
+ * #GDBusInterface that must be freed with g_object_unref().
*
- * Since: 2.26
+ * Returns: (transfer full): %NULL if not found, otherwise a
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_path:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_object_get_interfaces:
+ * @object: A #GDBusObject.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
+ * Gets the D-Bus interfaces associated with @object.
+ * The returned list must be freed by g_list_free() after each element has been freed
+ * with g_object_unref().
*
- * Since: 2.26
+ * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_reply_serial:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_object_get_object_path:
+ * @object: A #GDBusObject.
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
+ * Gets the object path for @object.
*
- * Since: 2.26
+ * Returns: A string owned by @object. Do not free.
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_sender:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_object_manager_client_get_connection:
+ * @manager: A #GDBusObjectManagerClient
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
+ * Gets the #GDBusConnection used by @manager.
+ * the object belongs to @manager.
*
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusConnection object. Do not free,
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_serial:
- * @message: A #GDBusMessage.
- * @serial: A #guint32.
+ * g_dbus_object_manager_client_get_flags:
+ * @manager: A #GDBusObjectManagerClient
*
- * Sets the serial for @message.
+ * Gets the flags that @manager was constructed with.
+ * enumeration.
*
- * Since: 2.26
+ * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_signature:
- * @message: A #GDBusMessage.
- * @value: The value to set.
+ * g_dbus_object_manager_client_get_name:
+ * @manager: A #GDBusObjectManagerClient
*
- * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
+ * Gets the name that @manager is for.
+ * belongs to @manager.
*
- * Since: 2.26
+ * Returns: A unique or well-known name. Do not free, the string
+ * Since: 2.30
*/
/**
- * g_dbus_message_set_unix_fd_list:
- * @message: A #GDBusMessage.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
+ * g_dbus_object_manager_client_get_name_owner:
+ * @manager: A #GDBusObjectManagerClient.
*
- * 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
- * This method is only available on UNIX.
+ * 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.
+ * g_free().
*
- * Since: 2.26
+ * Returns: The name owner or %NULL if no name owner exists. Free with
+ * Since: 2.30
*/
/**
- * g_dbus_message_to_blob:
- * @message: A #GDBusMessage.
- * @out_size: Return location for size of generated blob.
- * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
- * @error: Return location for error.
+ * g_dbus_object_manager_client_new:
+ * @connection: A #GDBusConnection.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @object_path: The object path of the control object.
+ * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+ * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
+ * @cancellable: A #GCancellable or %NULL
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: The data to pass to @callback.
*
- * Serializes @message to a blob. The byte order returned by
- * g_dbus_message_get_byte_order() will be used.
- * generated by @message or %NULL if @error is set. 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
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread you are calling this method from. You can
+ * then call g_dbus_object_manager_client_new_finish() to get the result. See
+ * g_dbus_object_manager_client_new_sync() for the synchronous version.
*
- * Returns: A pointer to a valid binary D-Bus message of @out_size bytes
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_message_to_gerror:
- * @message: A #GDBusMessage.
- * @error: The #GError to set.
+ * g_dbus_object_manager_client_new_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
+ * @error: Return location for error or %NULL.
*
- * 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.
+ * Finishes an operation started with g_dbus_object_manager_client_new().
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
*
- * Returns: %TRUE if @error was set, %FALSE otherwise.
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Since: 2.30
*/
/**
- * g_dbus_method_info_ref:
- * @info: A #GDBusMethodInfo
- *
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * g_dbus_object_manager_client_new_for_bus:
+ * @bus_type: A #GBusType.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @object_path: The object path of the control object.
+ * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+ * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
+ * @cancellable: A #GCancellable or %NULL
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: The data to pass to @callback.
*
- * Returns: The same @info.
- * Since: 2.26
+ * 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
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread you are calling this method from. You can
+ * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
+ * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
+ *
+ * Since: 2.30
*/
/**
- * g_dbus_method_info_unref:
- * @info: A #GDBusMethodInfo.
+ * g_dbus_object_manager_client_new_for_bus_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
+ * @error: Return location for error or %NULL.
*
- * 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.
+ * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
*
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_connection:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_client_new_for_bus_sync:
+ * @bus_type: A #GBusType.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @object_path: The object path of the control object.
+ * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+ * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
+ * @cancellable: A #GCancellable or %NULL
+ * @error: Return location for error or %NULL.
*
- * Gets the #GDBusConnection the method was invoked on.
+ * 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.
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
*
- * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_interface_name:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_client_new_sync:
+ * @connection: A #GDBusConnection.
+ * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
+ * @name: The owner of the control object (unique or well-known name).
+ * @object_path: The object path of the control object.
+ * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
+ * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
+ * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
+ * @cancellable: A #GCancellable or %NULL
+ * @error: Return location for error or %NULL.
*
- * Gets the name of the D-Bus interface the method was invoked on.
+ * 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.
+ * #GDBusObjectManagerClient object or %NULL if @error is set. Free
+ * with g_object_unref().
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_message:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_get_interface:
+ * @manager: A #GDBusObjectManager.
+ * @object_path: Object path to lookup.
+ * @interface_name: D-Bus interface name to lookup.
*
- * 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> for an example of how to use this
- * low-level API to send and receive UNIX file descriptors.
+ * Gets the interface proxy for @interface_name at @object_path, if
+ * any.
+ * with g_object_unref().
*
- * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_method_info:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_get_object:
+ * @manager: A #GDBusObjectManager.
+ * @object_path: Object path to lookup.
*
- * Gets information about the method call, if any.
+ * Gets the #GDBusObjectProxy at @object_path, if any.
+ * g_object_unref().
*
- * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: (transfer full): A #GDBusObject or %NULL. Free with
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_method_name:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_get_object_path:
+ * @manager: A #GDBusObjectManager.
*
- * Gets the name of the method that was invoked.
+ * Gets the object path that @manager is for.
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: A string owned by @manager. Do not free.
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_object_path:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_get_objects:
+ * @manager: A #GDBusObjectManager.
*
- * Gets the object path the method was invoked on.
+ * Gets all #GDBusObject objects known to @manager.
+ * #GDBusObject objects. The returned list should be freed with
+ * g_list_free() after each element has been freed with
+ * g_object_unref().
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Returns: (transfer full) (element-type GDBusObject): A list of
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_parameters:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_server_export:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object: A #GDBusObjectSkeleton.
*
- * Gets the parameters of the method invocation.
+ * 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.
*
- * Returns: A #GVariant. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_sender:
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_server_export_uniquely:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object: An object.
*
- * Gets the bus name that invoked the method.
+ * Like g_dbus_object_manager_server_export() but appends a string of
+ * the form <literal>_N</literal> (with N being a natural number) to
+ * already exists. As such, the #GDBusObjectProxy:object-path property
+ * of @object may be modified.
*
- * Returns: A string. Do not free, it is owned by @invocation.
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_get_user_data: (skip)
- * @invocation: A #GDBusMethodInvocation.
+ * g_dbus_object_manager_server_get_connection:
+ * @manager: A #GDBusObjectManagerServer
*
- * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
+ * Gets the #GDBusConnection used by @manager.
+ * be freed with g_object_unref().
*
- * Returns: A #gpointer.
- * Since: 2.26
+ * Returns: (transfer full): A #GDBusConnection object or %NULL if
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_return_dbus_error:
- * @invocation: A #GDBusMethodInvocation.
- * @error_name: A valid D-Bus error name.
- * @error_message: A valid D-Bus error message.
+ * g_dbus_object_manager_server_new:
+ * @object_path: The object path to export the manager object at.
*
- * Finishes handling a D-Bus method call by returning an error.
- * This method will free @invocation, you cannot use it afterwards.
+ * 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 <ulink
+ * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager";>InterfacesAdded</ulink>
+ * signals being emitted.
*
- * Since: 2.26
+ * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_return_error:
- * @invocation: A #GDBusMethodInvocation.
- * @domain: A #GQuark for the #GError error domain.
- * @code: The error code.
- * @format: printf()-style format.
- * @...: Parameters for @format.
- *
- * Finishes handling a D-Bus method call by returning an error.
- * See g_dbus_error_encode_gerror() for details about what error name
- * will be returned on the wire. In a nutshell, if the given error is
- * registered using g_dbus_error_register_error() the name given
- * during registration is used. Otherwise, a name of the form
- * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
- * used. This provides transparent mapping of #GError between
- * applications using GDBus.
- * If you are writing an application intended to be portable,
- * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
- * or use g_dbus_method_invocation_return_dbus_error().
- * This method will free @invocation, you cannot use it afterwards.
+ * g_dbus_object_manager_server_set_connection:
+ * @manager: A #GDBusObjectManagerServer.
+ * @connection: (allow-none): A #GDBusConnection or %NULL.
*
- * Since: 2.26
+ * Exports all objects managed by @manager on @connection. If
*/
/**
- * g_dbus_method_invocation_return_error_literal:
- * @invocation: A #GDBusMethodInvocation.
- * @domain: A #GQuark for the #GError error domain.
- * @code: The error code.
- * @message: The error message.
+ * g_dbus_object_manager_server_unexport:
+ * @manager: A #GDBusObjectManagerServer.
+ * @object_path: An object path.
*
- * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
- * This method will free @invocation, you cannot use it afterwards.
+ * 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.26
+ * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_return_error_valist:
- * @invocation: A #GDBusMethodInvocation.
- * @domain: A #GQuark for the #GError error domain.
- * @code: The error code.
- * @format: printf()-style format.
- * @var_args: #va_list of parameters for @format.
+ * g_dbus_object_proxy_get_connection:
+ * @proxy: a #GDBusObjectProxy
*
- * Like g_dbus_method_invocation_return_error() but intended for
- * language bindings.
- * This method will free @invocation, you cannot use it afterwards.
+ * Gets the connection that @proxy is for.
+ * object is owned by @proxy.
*
- * Since: 2.26
+ * Returns: (transfer none): A #GDBusConnection. Do not free, the
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_return_gerror:
- * @invocation: A #GDBusMethodInvocation.
- * @error: A #GError.
+ * g_dbus_object_proxy_new:
+ * @connection: a #GDBusConnection
+ * @object_path: the object path
*
- * Like g_dbus_method_invocation_return_error() but takes a #GError
- * instead of the error domain, error code and message.
- * This method will free @invocation, you cannot use it afterwards.
+ * Creates a new #GDBusObjectProxy for the given connection and
+ * object path.
*
- * Since: 2.26
+ * Returns: a new #GDBusObjectProxy
+ * Since: 2.30
*/
/**
- * g_dbus_method_invocation_return_value:
- * @invocation: A #GDBusMethodInvocation.
- * @parameters: A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
+ * g_dbus_object_skeleton_add_interface:
+ * @object: A #GDBusObjectSkeleton.
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Finishes handling a D-Bus method call by returning @parameters.
- * If the @parameters GVariant is floating, it is consumed.
- * It is an error if @parameters is not of the right format.
- * This method will free @invocation, you cannot use it afterwards.
+ * 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.26
+ * Since: 2.30
*/
/**
- * g_dbus_node_info_generate_xml:
- * @info: A #GDBusNodeInfo.
- * @indent: Indentation level.
- * @string_builder: A #GString to to append XML data to.
+ * g_dbus_object_skeleton_flush:
+ * @object: A #GDBusObjectSkeleton.
*
- * Appends an XML representation of @info (and its children) to @string_builder.
- * This function is typically used for generating introspection XML documents at run-time for
- * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
+ * This method simply calls g_dbus_interface_skeleton_flush() on all
+ * interfaces belonging to @object. See that method for when flushing
+ * is useful.
*
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_node_info_lookup_interface:
- * @info: A #GDBusNodeInfo.
- * @name: A D-Bus interface name.
+ * g_dbus_object_skeleton_new:
+ * @object_path: An object path.
*
- * Looks up information about an interface.
- * This cost of this function is O(n) in number of interfaces.
+ * Creates a new #GDBusObjectSkeleton.
*
- * Returns: A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
- * Since: 2.26
+ * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
+ * Since: 2.30
*/
/**
- * g_dbus_node_info_new_for_xml:
- * @xml_data: Valid D-Bus introspection XML.
- * @error: Return location for error.
+ * g_dbus_object_skeleton_remove_interface:
+ * @object: A #GDBusObjectSkeleton.
+ * @interface_: A #GDBusInterfaceSkeleton.
*
- * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
- * with g_dbus_node_info_unref().
+ * Removes @interface_ from @object.
*
- * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_node_info_ref:
- * @info: A #GDBusNodeInfo
+ * g_dbus_object_skeleton_remove_interface_by_name:
+ * @object: A #GDBusObjectSkeleton.
+ * @interface_name: A D-Bus interface name.
*
- * If @info is statically allocated does nothing. Otherwise increases
- * the reference count.
+ * Removes the #GDBusInterface with @interface_name from @object.
+ * If no D-Bus interface of the given interface exists, this function
+ * does nothing.
*
- * Returns: The same @info.
- * Since: 2.26
+ * Since: 2.30
*/
/**
- * g_dbus_node_info_unref:
- * @info: A #GDBusNodeInfo.
+ * g_dbus_object_skeleton_set_object_path:
+ * @object: A #GDBusObjectSkeleton.
+ * @object_path: A valid D-Bus object path.
*
- * 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.
+ * Sets the object path for @object.
*
- * Since: 2.26
+ * Since: 2.30
*/
@@ -18551,8 +19949,8 @@
* &data);
* ]|
* This is an asynchronous method. When the operation is finished,
- * <link linkend="g-main-context-push-thread-default">thread-default
- * main loop</link> of the thread you are calling this method from.
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * of the thread you are calling this method from.
* You can then call g_dbus_proxy_call_finish() to get the result of
* the operation. See g_dbus_proxy_call_sync() for the synchronous
* version of this method.
@@ -19060,6 +20458,17 @@
/**
+ * g_desktop_app_info_get_categories:
+ * @info: a #GDesktopAppInfo
+ *
+ * Gets the categories from the desktop file.
+ * i.e. no attempt is made to split it by ';' or validate it.
+ *
+ * Returns: The unparsed Categories key from the desktop file;
+ */
+
+
+/**
* g_desktop_app_info_get_filename:
* @info: a #GDesktopAppInfo
*
@@ -19073,6 +20482,16 @@
/**
+ * g_desktop_app_info_get_generic_name:
+ * @info: a #GDesktopAppInfo
+ *
+ * Gets the generic name from the destkop file.
+ *
+ * Returns: The value of the GenericName key
+ */
+
+
+/**
* g_desktop_app_info_get_is_hidden:
* @info: a #GDesktopAppInfo.
*
@@ -19093,7 +20512,7 @@
* @user_setup_data: (closure user_setup): User data for @user_setup
* @pid_callback: (scope call): Callback for child processes
* @pid_callback_data: (closure pid_callback): User data for @callback
- * @error: a #GError
+ * @error: return location for a #GError, or %NULL
*
* This function performs the equivalent of g_app_info_launch_uris(),
* but is intended primarily for operating system components that
@@ -19105,6 +20524,8 @@
* This guarantee allows additional control over the exact environment
* of the child processes, which is provided via a setup function
* semantics of the @setup function.
+ *
+ * Returns: %TRUE on successful launch, %FALSE otherwise.
*/
@@ -20288,7 +21709,7 @@
*
* Get the #GFile container which is being enumerated.
*
- * Returns: (transfer full): the #GFile which is being enumerated.
+ * Returns: (transfer none): the #GFile which is being enumerated.
* Since: 2.18
*/
@@ -21217,7 +22638,7 @@
/**
* g_file_info_set_content_type:
* @info: a #GFileInfo.
- * @content_type: a content type. See #GContentType.
+ * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>.
*
* Sets the content type attribute for a given #GFileInfo.
* See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
@@ -23178,7 +24599,7 @@
* (such as <literal>/path/to/my icon.png</literal>) without escaping
* if the #GFile for @icon is a native file. If the file is not
* native, the returned string is the result of g_file_get_uri()
- * (such as <literal>sftp://path/to/my%%20icon.png</literal>).
+ * (such as <literal>sftp://path/to/my%20icon.png</literal>).
* </para></listitem>
* <listitem><para>
* If @icon is a #GThemedIcon with exactly one name, the encoding is
@@ -23194,6 +24615,18 @@
/**
+ * g_inet_address_equal:
+ * @address: A #GInetAddress.
+ * @other_address: Another #GInetAddress.
+ *
+ * Checks if two #GInetAddress instances are equal, e.g. the same address.
+ *
+ * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
+ * Since: 2.30
+ */
+
+
+/**
* g_inet_address_get_family:
* @address: a #GInetAddress
*
@@ -26147,7 +27580,7 @@
/**
* g_proxy_connect_finish:
* @proxy: a #GProxy
- * @result: a #GAsyncRetult
+ * @result: a #GAsyncResult
* @error: return #GError
*
* See g_proxy_connect().
@@ -26399,9 +27832,11 @@
* the textual form of an IP address (in which case this just becomes
* a wrapper around g_inet_address_new_from_string()).
* On success, g_resolver_lookup_by_name() will return a #GList of
- * #GInetAddress, sorted in order of preference. (That is, you should
- * attempt to connect to the first address first, then the second if
- * the first fails, etc.)
+ * #GInetAddress, sorted in order of preference and guaranteed to not
+ * contain duplicates. That is, if using the result to connect to
+ * 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.
* If @cancellable is non-%NULL, it can be used to cancel the
@@ -27102,6 +28537,22 @@
/**
+ * g_settings_get_uint:
+ * @settings: a #GSettings object
+ * @key: the key to get the value for
+ * @returns: an unsigned integer
+ *
+ * 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
+ */
+
+
+/**
* g_settings_get_value:
* @settings: a #GSettings object
* @key: the key to get the value for
@@ -27223,8 +28674,8 @@
* @returns: a new #GSettings object
*
* Creates a new #GSettings object with a given schema and backend.
- * Creating settings objects with an different backend allows accessing settings
- * from a database other than the usual one. For example, it may make
+ * 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.
@@ -27443,6 +28894,23 @@
/**
+ * g_settings_set_uint:
+ * @settings: a #GSettings object
+ * @key: the name of the key to set
+ * @value: the value to set it to
+ * @returns: %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
+ */
+
+
+/**
* g_settings_set_value:
* @settings: a #GSettings object
* @key: the name of the key to set
@@ -28150,7 +29618,7 @@
* 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 find a #GProxy instance to handle handshaking. The
+ * 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
@@ -28171,14 +29639,14 @@
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Tries to resolve the @connectable and make a network connection to it..
+ * 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 the address that the
+ * The socket created will be the same family as the address that the
* 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().
@@ -28192,7 +29660,7 @@
/**
* g_socket_client_connect_async:
- * @client: a #GTcpClient
+ * @client: a #GSocketClient
* @connectable: a #GSocketConnectable specifying the remote address.
* @cancellable: (allow-none): a #GCancellable, or %NULL
* @callback: (scope async): a #GAsyncReadyCallback
@@ -28211,7 +29679,7 @@
* g_socket_client_connect_finish:
* @client: a #GSocketClient.
* @result: a #GAsyncResult.
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an async connect operation. See g_socket_client_connect_async()
*
@@ -28238,7 +29706,7 @@
* 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 overide if necessary) and
+ * them to give the hostname, and a port override if necessary) and
* 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
@@ -28257,7 +29725,7 @@
/**
* g_socket_client_connect_to_host_async:
- * @client: a #GTcpClient
+ * @client: a #GSocketClient
* @host_and_port: the name and optionally the port of the host to connect to
* @default_port: the default port to connect to
* @cancellable: (allow-none): a #GCancellable, or %NULL
@@ -28277,7 +29745,7 @@
* g_socket_client_connect_to_host_finish:
* @client: a #GSocketClient.
* @result: a #GAsyncResult.
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an async connect operation. See g_socket_client_connect_to_host_async()
*
@@ -28329,7 +29797,7 @@
* g_socket_client_connect_to_service_finish:
* @client: a #GSocketClient.
* @result: a #GAsyncResult.
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an async connect operation. See g_socket_client_connect_to_service_async()
*
@@ -28389,7 +29857,7 @@
* g_socket_client_connect_to_uri_finish:
* @client: a #GSocketClient.
* @result: a #GAsyncResult.
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
*
@@ -28428,7 +29896,7 @@
* Gets the local address of the socket client.
* See g_socket_client_set_local_address() for details.
*
- * Returns: (transfer none): a #GSocketAddres or %NULL. don't free
+ * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
* Since: 2.22
*/
@@ -28542,7 +30010,7 @@
* 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 the the local
+ * 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.
*
@@ -28778,7 +30246,7 @@
* @protocol_id: a protocol id
*
* Looks up the #GType to be used when creating socket connections on
- * sockets with the specified @family,@type and @protocol_id.
+ * sockets with the specified @family, @type and @protocol_id.
* If no type is registered, the #GSocketConnection base type is returned.
*
* Returns: a #GType
@@ -28794,7 +30262,7 @@
* @protocol: a protocol id
*
* Looks up the #GType to be used when creating socket connections on
- * sockets with the specified @family,@type and @protocol.
+ * sockets with the specified @family, @type and @protocol.
* If no type is registered, the #GSocketConnection base type is returned.
*
* Since: 2.22
@@ -29165,7 +30633,7 @@
* @listener: a #GSocketListener
* @result: a #GAsyncResult.
* @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an async accept operation. See g_socket_listener_accept_async()
*
@@ -29219,7 +30687,7 @@
* @listener: a #GSocketListener
* @result: a #GAsyncResult.
* @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an async accept operation. See g_socket_listener_accept_socket_async()
*
@@ -29243,13 +30711,13 @@
* 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 determinstic behaviour, see
+ * connections. For more deterministic behavior, see
* g_socket_listener_add_inet_port().
* 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 occured at. This
+ * be set to the address that the binding actually occurred at. This
* is helpful for determining the port number that was used for when
* requested, belongs to the caller and must be freed.
*
@@ -29263,10 +30731,10 @@
* g_socket_listener_add_any_inet_port:
* @listener: a #GSocketListener
* @source_object: (allow-none): Optional #GObject identifying this source
- * @error: a #GError location to store the error occuring, or %NULL to ignore.
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Listens for TCP connections on any available port number for both
- * IPv6 and IPv4 (if each are available).
+ * 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.
* to accept to identify this particular source, which is
@@ -29413,14 +30881,16 @@
* 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 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
+ * 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.
+ * the peer, or -1 on error
*
- * Returns: Number of bytes read, or -1 on error
+ * Returns: Number of bytes read, or 0 if the connection was closed by
* Since: 2.22
*/
@@ -29438,8 +30908,9 @@
* If @address is non-%NULL then @address will be set equal to the
* source address of the received packet.
* See g_socket_receive() for additional information.
+ * the peer, or -1 on error
*
- * Returns: Number of bytes read, or -1 on error
+ * Returns: Number of bytes read, or 0 if the connection was closed by
* Since: 2.22
*/
@@ -29489,14 +30960,16 @@
* 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 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.
+ * 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.
+ * the peer, or -1 on error
*
* In @messages (ie: not including the %NULL terminator).
- * Returns: Number of bytes read, or -1 on error
+ * Returns: Number of bytes read, or 0 if the connection was closed by
* Since: 2.22
*/
@@ -29513,8 +30986,9 @@
* 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.
+ * the peer, or -1 on error
*
- * Returns: Number of bytes read, or -1 on error
+ * Returns: Number of bytes read, or 0 if the connection was closed by
* Since: 2.26
*/
@@ -29664,7 +31138,7 @@
* Starts the service, i.e. start accepting connections
* from the added sockets when the mainloop runs.
* This call is threadsafe, so it may be called from a thread
- * handling an incomming client request.
+ * handling an incoming client request.
*
* Since: 2.22
*/
@@ -29677,7 +31151,7 @@
* Stops the service, i.e. stops accepting connections
* from the added sockets when the mainloop runs.
* This call is threadsafe, so it may be called from a thread
- * handling an incomming client request.
+ * handling an incoming client request.
*
* Since: 2.22
*/
@@ -29920,7 +31394,7 @@
* @graceful_disconnect: Whether to do graceful disconnects or not
*
* This enabled graceful disconnects on close. A graceful disconnect
- * means that we signal the recieving end that the connection is terminated
+ * 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.
@@ -30040,7 +31514,7 @@
* @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit
*
* Creates a new #GThreadedSocketService with no listeners. Listeners
- * must be added with g_socket_service_add_listeners().
+ * must be added with one of the #GSocketListener "add" methods.
*
* Returns: a new #GSocketService.
* Since: 2.22
@@ -30048,6 +31522,23 @@
/**
+ * g_time_zone_monitor_get:
+ *
+ * Gets the singleton instance of the #GTimeZoneMonitor class, creating
+ * it if required.
+ * You should call g_object_unref() on the result when you no longer
+ * need it. Be aware, though, that this will not destroy the instance,
+ * so if you connected to the changed signal, you are required to
+ * disconnect from it for yourself.
+ * There is only one instance of #GTimeZoneMonitor and it dispatches its
+ * signals via the default #GMainContext. There is no way to create an
+ * instance that will dispatch signals using a different context.
+ *
+ * Returns: a reference to the #GTimeZoneMonitor.
+ */
+
+
+/**
* g_tls_backend_get_certificate_type:
* @backend: the #GTlsBackend
*
@@ -30379,7 +31870,7 @@
* @conn: a #GTlsConnection
*
* Gets @conn rehandshaking mode. See
- * g_tls_connection_set_rehandshake() for details.
+ * g_tls_connection_set_rehandshake_mode() for details.
*
* Returns: @conn's rehandshaking mode
* Since: 2.28
@@ -30695,7 +32186,7 @@
* @error: Return location for error or %NULL.
*
* Passes the credentials of the current user the receiving side
- * of the connection. The recieving end has to call
+ * 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
@@ -30716,8 +32207,8 @@
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @error: (allow-none): #GError for error reporting, or %NULL to ignore.
*
- * Passes a file descriptor to the recieving side of the
- * connection. The recieving end has to call g_unix_connection_receive_fd()
+ * 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
@@ -30742,7 +32233,7 @@
/**
* g_unix_credentials_message_is_supported:
*
- * Checks if passing a #GCredential on a #GSocket is supported on this platform.
+ * Checks if passing #GCredentials on a #GSocket is supported on this platform.
*
* Returns: %TRUE if supported, %FALSE otherwise
* Since: 2.26
@@ -31314,7 +32805,7 @@
* 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_mounts_points_changed_since().
+ * g_unix_mount_points_changed_since().
* a #GList of the UNIX mountpoints.
*
* Returns: (element-type GUnixMountPoint) (transfer full):
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index cbc588d..9b4b35c 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -145,8 +145,8 @@
* GBoxedCopyFunc:
* @boxed: The boxed structure to be copied.
*
- * This function is provided by the user and should produce a copy of the passed
- * in boxed structure.
+ * This function is provided by the user and should produce a copy
+ * of the passed in boxed structure.
*
* Returns: The newly created copy of the boxed structure.
*/
@@ -415,6 +415,16 @@
/**
+ * GDebugKey:
+ * @key: the string
+ * @value: the flag
+ *
+ * Associates a string with a bit flag.
+ * Used in g_parse_debug_string().
+ */
+
+
+/**
* GEnumClass:
* @g_type_class: the parent class
* @minimum: the smallest possible value.
@@ -462,6 +472,16 @@
/**
+ * GFreeFunc:
+ * @data: a data pointer
+ *
+ * Declares a type of function which takes an arbitrary
+ * data pointer argument and has no return value. It is
+ * not currently used in GLib or GTK+.
+ */
+
+
+/**
* GIconv:
*
* The <structname>GIConv</structname> struct wraps an
@@ -1393,6 +1413,7 @@
* @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions.
* @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code.
* @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
+ * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30.
*
* The signal flags are used to specify a signal's behaviour, the overall
* signal description outlines how especially the RUN flags control the
@@ -1461,6 +1482,25 @@
/**
+ * GSourceDummyMarshal:
+ *
+ * This is just a placeholder for #GClosureMarshal,
+ * which cannot be used here for dependency reasons.
+ */
+
+
+/**
+ * GSourceFunc:
+ * @data: data passed to the function, set when the source was created with one of the above functions
+ *
+ * Specifies the type of function passed to g_timeout_add(),
+ * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
+ *
+ * Returns: %FALSE if the source should be removed
+ */
+
+
+/**
* GSourceFuncs:
* @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the
* @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
@@ -1798,7 +1838,7 @@
* @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i
' needs to be used, and for collection of floats 'd'.
* @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_p
ointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour i
s undefined.
* @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
- * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
+ * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
*
* The #GTypeValueTable provides the functions required by the #GValue implementation,
* to serve as a container for values of a type.
@@ -1835,7 +1875,7 @@
* to functions within a #GTypeValueTable structure, or implementations of
* the g_value_*() API. That is, code portions which implement new fundamental
* types.
- * #GValue users can not make any assumptions about how data is stored
+ * #GValue users cannot make any assumptions about how data is stored
* within the 2 element @data union, and the @g_type member should
* only be accessed through the G_VALUE_TYPE() macro.
*
@@ -1867,12 +1907,21 @@
*
* A type in the GVariant type system.
* Two types may not be compared by value; use g_variant_type_equal() or
- * g_variant_type_is_subtype(). May be copied using
+ * g_variant_type_is_subtype_of(). May be copied using
* g_variant_type_copy() and freed using g_variant_type_free().
*/
/**
+ * GVoidFunc:
+ *
+ * Declares a type of function which takes no arguments
+ * and has no return value. It is used to specify the type
+ * function passed to g_atexit().
+ */
+
+
+/**
* GWeakNotify:
* @data: data that was provided when the weak reference was established
* @where_the_object_was: the object being finalized
@@ -3628,7 +3677,7 @@
* G_TYPE_IS_ABSTRACT:
* @type: A #GType value.
*
- * Checks if @type is an abstract type. An abstract type can not be
+ * Checks if @type is an abstract type. An abstract type cannot be
* instantiated and is normally used as an abstract base class for
* derived classes.
*
@@ -4086,7 +4135,7 @@
* g_object_set (obj, "authors", authors, NULL);
* gchar *writers[];
* g_object_get (obj, "authors", &writers, NULL);
- * // do something with writers
+ * /* do something with writers */
* g_strfreev (writers);
* ]|
*
@@ -4155,6 +4204,15 @@
/**
+ * G_TYPE_VARIANT_BUILDER:
+ *
+ * The #GType for a boxed type holding a #GVariantBuilder.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* G_TYPE_VARIANT_TYPE:
*
* The #GType for a boxed type holding a #GVariantType.
@@ -4266,7 +4324,8 @@
* G_VALUE_HOLDS_BOXED:
* @value: a valid #GValue structure
*
- * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED.
+ * Checks whether the given #GValue can hold values derived
+ * from type %G_TYPE_BOXED.
*
* Returns: %TRUE on success.
*/
@@ -4467,6 +4526,15 @@
/**
+ * G_VALUE_NOCOPY_CONTENTS:
+ *
+ * If passed to G_VALUE_COLLECT(), allocated data won't be copied
+ * but used verbatim. This does not affect ref-counted types like
+ * objects. For more details, see the #GValueTable documentation.
+ */
+
+
+/**
* G_VALUE_TYPE:
* @value: A #GValue structure.
*
@@ -4586,8 +4654,8 @@
*
* The type of a 32bit signed integer value, that by convention, is used
* as an index into an array of file descriptors that are sent alongside
- * a DBus message.
- * If you are not interacting with DBus, then there is no reason to make
+ * a D-Bus message.
+ * If you are not interacting with D-Bus, then there is no reason to make
* use of this type.
*/
@@ -4625,11 +4693,11 @@
/**
* G_VARIANT_TYPE_OBJECT_PATH:
*
- * The type of a DBus object reference. These are strings of a
+ * The type of a D-Bus object reference. These are strings of a
* specific format used to identify objects at a given destination on
* the bus.
- * If you are not interacting with DBus, then there is no reason to make
- * use of this type. If you are, then the DBus specification contains a
+ * If you are not interacting with D-Bus, then there is no reason to make
+ * use of this type. If you are, then the D-Bus specification contains a
* precise description of valid object paths.
*/
@@ -4637,10 +4705,10 @@
/**
* G_VARIANT_TYPE_SIGNATURE:
*
- * The type of a DBus type signature. These are strings of a specific
- * format used as type signatures for DBus methods and messages.
- * If you are not interacting with DBus, then there is no reason to make
- * use of this type. If you are, then the DBus specification contains a
+ * The type of a D-Bus type signature. These are strings of a specific
+ * format used as type signatures for D-Bus methods and messages.
+ * If you are not interacting with D-Bus, then there is no reason to make
+ * use of this type. If you are, then the D-Bus specification contains a
* precise description of valid signature strings.
*/
@@ -4701,6 +4769,16 @@
/**
+ * G_VARIANT_TYPE_VARDICT:
+ *
+ * The type of a dictionary mapping strings to variants (the ubiquitous
+ * "a{sv}" type).
+ *
+ * Since: 2.30
+ */
+
+
+/**
* G_VARIANT_TYPE_VARIANT:
*
* The type of a box that contains any other value (including another
@@ -4998,7 +5076,7 @@
* types and interface implementations are in use, the module is kept
* loaded. When the types and interfaces are gone, the module may be
* unloaded. If the types and interfaces become used again, the module
- * will be reloaded. Note that the last unref can not happen in module
+ * will be reloaded. Note that the last unref cannot happen in module
* code, since that would lead to the caller's code being unloaded before
* g_object_unref() returns to it.
* Keeping track of whether the module should be loaded or not is done by
@@ -5092,14 +5170,14 @@
* support. Signals are described in detail in <xref
* linkend="gobject-Signals"/>.
* <para id="floating-ref">
- * #GInitiallyUnowned is derived from #GObject. The only difference between
- * the two is that the initial reference of a #GInitiallyUnowned is flagged
+ * GInitiallyUnowned is derived from GObject. The only difference between
+ * the two is that the initial reference of a GInitiallyUnowned is flagged
* as a <firstterm>floating</firstterm> reference.
* This means that it is not specifically claimed to be "owned" by
* any code portion. The main motivation for providing floating references is
* C convenience. In particular, it allows code to be written as:
* |[
- * container = create_container();
+ * container = create_container ();
* container_add_child (container, create_child());
* ]|
* If <function>container_add_child()</function> will g_object_ref_sink() the
@@ -5109,8 +5187,8 @@
* reference leaks, it would have to be written as:
* |[
* Child *child;
- * container = create_container();
- * child = create_child();
+ * container = create_container ();
+ * child = create_child ();
* container_add_child (container, child);
* g_object_unref (child);
* ]|
@@ -5121,22 +5199,22 @@
* a new reference.
* Since floating references are useful almost exclusively for C convenience,
* language bindings that provide automated reference and memory ownership
- * maintenance (such as smart pointers or garbage collection) therefore don't
- * need to expose floating references in their API.
+ * maintenance (such as smart pointers or garbage collection) should not
+ * expose floating references in their API.
* </para>
* Some object implementations may need to save an objects floating state
- * across certain code portions (an example is #GtkMenu), to achive this, the
- * following sequence can be used:
+ * across certain code portions (an example is #GtkMenu), to achieve this,
+ * the following sequence can be used:
* |[
- * // save floating state
+ * /* save floating state */
* gboolean was_floating = g_object_is_floating (object);
* g_object_ref_sink (object);
- * // protected code portion
+ * /* protected code portion */
* ...;
- * // restore floating state
+ * /* restore floating state */
* if (was_floating)
* g_object_force_floating (object);
- * g_obejct_unref (object); // release previously acquired reference
+ * g_object_unref (object); /* release previously acquired reference */
* ]|
*/
@@ -5289,28 +5367,6 @@
/**
- * g_atomic_int_dec_and_test:
- * @atomic: a pointer to an integer
- *
- * Atomically decrements the integer pointed to by @atomic by 1.
- * after decrementing it
- *
- * Returns: %TRUE if the integer pointed to by @atomic is 0
- * Since: 2.4
- */
-
-
-/**
- * g_atomic_int_inc:
- * @atomic: a pointer to an integer.
- *
- * Atomically increments the integer pointed to by @atomic by 1.
- *
- * Since: 2.4
- */
-
-
-/**
* g_binding_get_flags:
* @binding: a #GBinding
*
@@ -5722,6 +5778,22 @@
/**
+ * g_cclosure_marshal_generic:
+ * @closure: A #GClosure.
+ * @return_gvalue: A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value.
+ * @n_param_values: The length of the @param_values array.
+ * @param_values: An array of #GValue<!-- -->s holding the arguments on which to invoke the callback of closure.
+ * @invocation_hint: The invocation hint given as the last argument to g_closure_invoke().
+ * @marshal_data: Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal()
+ *
+ * A generic marshaller function implemented via <ulink
+ * url="http://sourceware.org/libffi/";>libffi</ulink>.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* g_cclosure_new: (skip)
* @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func
@@ -6780,10 +6852,10 @@
*
* This function is intended for #GObject implementations to re-enforce a
* <link linkend="floating-ref">floating</link> object reference.
- * Doing this is seldomly required, all
* #GInitiallyUnowned<!-- -->s are created with a floating reference which
* usually just needs to be sunken by calling g_object_ref_sink().
*
+ * Doing this is seldomly required: all
* Since: 2.10
*/
@@ -6950,7 +7022,7 @@
* g_object_is_floating:
* @object: (type GObject.Object): a #GObject
*
- * Checks wether @object has a <link linkend="floating-ref">floating</link>
+ * Checks whether @object has a <link linkend="floating-ref">floating</link>
* reference.
*
* Since: 2.10
@@ -9246,6 +9318,9 @@
*
* Obtains data which has previously been attached to @type
* with g_type_set_qdata().
+ * Note that this does not take subtyping into account; data
+ * attached to one type with g_type_set_qdata() cannot
+ * be retrieved from a subtype using g_type_get_qdata().
*
* Returns: (transfer none): the data, or %NULL if no data was found
*/
@@ -9780,7 +9855,7 @@
/**
* g_value_array_remove:
* @value_array: #GValueArray to remove an element from
- * @index_: position of value to remove, must be < value_array->n_values
+ * @index_: position of value to remove, which must be less than <code>value_array-><link linkend="GValueArray.n-values">n_values</link></code>
*
* Remove the value at position @index_ from @value_array.
*
@@ -9843,7 +9918,8 @@
* @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT
*
* Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing
- * its reference count.
+ * its reference count. If the contents of the #GValue are %NULL, then
+ * %NULL will be returned.
* should be unreferenced when no longer needed.
*
* Returns: (type GObject.Object) (transfer full): object content of @value,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
